ezvcard.io.scribe

Class BinaryPropertyScribe<T extends BinaryProperty<U>,U extends MediaTypeParameter>

java.lang.Object

ezvcard.io.scribe.VCardPropertyScribe<T>

ezvcard.io.scribe.BinaryPropertyScribe<T,U>

Type Parameters:

T - the property class

U - the media type class

Direct Known Subclasses:

ImagePropertyScribe, KeyScribe, SoundScribe

public abstract class BinaryPropertyScribe<T extends BinaryProperty<U>,U extends MediaTypeParameter>
extends VCardPropertyScribe<T>

Marshals properties that have binary data.

Author:

Michael Angstadt

Nested Class Summary

Nested classes/interfaces inherited from class ezvcard.io.scribe.VCardPropertyScribe

VCardPropertyScribe.DateWriter

Field Summary

Fields inherited from class ezvcard.io.scribe.VCardPropertyScribe

clazz, propertyName, qname

Constructor Summary

Constructors

Constructor and Description
BinaryPropertyScribe(Class<T> clazz, String propertyName)

Method Summary

Modifier and Type	Method and Description
protected VCardDataType	_dataType(T property, VCardVersion version) Determines the data type of a property instance.
protected VCardDataType	_defaultDataType(VCardVersion version) Determines the property's default data type.
protected abstract U	_mediaTypeFromFileExtension(String extension) Searches for a MediaTypeParameter object, given a file extension.
protected abstract U	_mediaTypeFromMediaTypeParameter(String mediaType) Builds a MediaTypeParameter object based on the value of the MEDIATYPE parameter or data URI of 4.0 vCards.
protected abstract U	_mediaTypeFromTypeParameter(String type) Builds a MediaTypeParameter object based on the value of the TYPE parameter in 2.1/3.0 vCards.
protected abstract T	_newInstance(byte[] data, U contentType) Creates a new instance of the property object from binary data.
protected abstract T	_newInstance(String uri, U contentType) Creates a new instance of the property object from a URI.
protected T	_parseHtml(HCardElement element, ParseContext context) Unmarshals the property from an hCard (HTML document).
protected T	_parseJson(JCardValue value, VCardDataType dataType, VCardParameters parameters, ParseContext context) Unmarshals a property from a JSON data stream (jCard).
protected T	_parseText(String value, VCardDataType dataType, VCardParameters parameters, ParseContext context) Unmarshals a property from a plain-text vCard.
protected T	_parseXml(XCardElement element, VCardParameters parameters, ParseContext context) Unmarshals a property from an XML document (xCard).
protected void	_prepareParameters(T property, VCardParameters copy, VCardVersion version, VCard vcard) Sanitizes a property's parameters before the property is written.
protected JCardValue	_writeJson(T property) Marshals a property's value to a JSON data stream (jCard).
protected String	_writeText(T property, WriteContext context) Marshals a property's value to a string.
protected void	_writeXml(T property, XCardElement parent) Marshals a property's value to an XML element (xCard).
protected T	cannotUnmarshalValue(String value, VCardVersion version, U contentType) Called if the unmarshalling code cannot determine how to unmarshal the value.
protected static String	getFileExtension(String url) Gets the file extension from a URL.
protected T	parse(String value, VCardDataType dataType, VCardParameters parameters, VCardVersion version) Parses the property.
protected T	parseAsDataUri(String value) Attempts to parse the given string as a data URI.
protected U	parseContentTypeFromParameters(VCardParameters parameters, VCardVersion version) Tries to determine a property value's content type by looking at the property's parameters.
protected U	parseContentTypeFromValueAndParameters(String value, VCardParameters parameters, VCardVersion version) Tries to determine a property value's content type by looking at the property's parameters and value.

Methods inherited from class ezvcard.io.scribe.VCardPropertyScribe

dataType, date, date, defaultDataType, escape, getPropertyClass, getPropertyName, getQName, handlePrefParam, missingXmlElements, missingXmlElements, parseHtml, parseJson, parseText, parseXml, prepareParameters, writeJson, writeText, writeXml

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BinaryPropertyScribe

public BinaryPropertyScribe(Class<T> clazz,
                            String propertyName)

Method Detail

_defaultDataType

protected VCardDataType _defaultDataType(VCardVersion version)

Description copied from class: VCardPropertyScribe

Determines the property's default data type.

When writing a plain-text vCard, if the data type of a property instance (as determined by the VCardPropertyScribe.dataType(T, ezvcard.VCardVersion) method) matches the default data type, then a VALUE parameter will *not* be written.

When parsing a plain-text vCard, if a property has no VALUE parameter, then the property's default data type will be passed into the VCardPropertyScribe.parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.io.ParseContext) method.

Specified by:

_defaultDataType in class VCardPropertyScribe<T extends BinaryProperty<U>>

Parameters:

version - the vCard version

Returns:

the default data type or null if unknown

_dataType

protected VCardDataType _dataType(T property,
                                  VCardVersion version)

Description copied from class: VCardPropertyScribe

Determines the data type of a property instance.

This method should be overridden by child classes if a property's data type changes depending on its value. The default implementation of this method calls VCardPropertyScribe._defaultDataType(ezvcard.VCardVersion).

Overrides:

_dataType in class VCardPropertyScribe<T extends BinaryProperty<U>>

Parameters:

property - the property

version - the version of the vCard that is being generated

Returns:

the data type or null if unknown

_prepareParameters

protected void _prepareParameters(T property,
                                  VCardParameters copy,
                                  VCardVersion version,
                                  VCard vcard)

Description copied from class: VCardPropertyScribe

Sanitizes a property's parameters before the property is written.

This method should be overridden by child classes that wish to tweak the property's parameters before the property is written. The default implementation of this method does nothing.

Overrides:

_prepareParameters in class VCardPropertyScribe<T extends BinaryProperty<U>>

Parameters:

property - the property

copy - the list of parameters to make modifications to (it is a copy of the property's parameters)

version - the version of the vCard that is being generated

vcard - the vCard that the property belongs to

_writeText

protected String _writeText(T property,
                            WriteContext context)

Description copied from class: VCardPropertyScribe

Marshals a property's value to a string.

Specified by:

_writeText in class VCardPropertyScribe<T extends BinaryProperty<U>>

Parameters:

property - the property

context - contains information about the vCard being written, such as the target version

Returns:

the marshalled value

_parseText

protected T _parseText(String value,
                       VCardDataType dataType,
                       VCardParameters parameters,
                       ParseContext context)

Description copied from class: VCardPropertyScribe

Unmarshals a property from a plain-text vCard.

Specified by:

_parseText in class VCardPropertyScribe<T extends BinaryProperty<U>>

Parameters:

value - the value as read off the wire

dataType - the data type of the property value. The property's VALUE parameter is used to determine the data type. If the property has no VALUE parameter, then this parameter will be set to the property's default datatype, as determined by the VCardPropertyScribe.defaultDataType(ezvcard.VCardVersion) method. Note that the VALUE parameter is removed from the property's parameter list after it has been read.

parameters - the parsed parameters. These parameters will be assigned to the property object once this method returns. Therefore, do not assign any parameters to the property object itself whilst inside of this method, or else they will be overwritten.

context - the parse context

Returns:

the unmarshalled property object

_writeXml

protected void _writeXml(T property,
                         XCardElement parent)

Description copied from class: VCardPropertyScribe

Marshals a property's value to an XML element (xCard).

This method should be overridden by child classes that wish to support xCard. The default implementation of this method will append one child element to the property's XML element. The child element's name will be that of the property's data type (retrieved using the VCardPropertyScribe.dataType(T, ezvcard.VCardVersion) method), and the child element's text content will be set to the property's marshalled plain-text value (retrieved using the VCardPropertyScribe.writeText(T, ezvcard.io.text.WriteContext) method).

Overrides:

_writeXml in class VCardPropertyScribe<T extends BinaryProperty<U>>

Parameters:

property - the property

parent - the property's XML element

_parseXml

protected T _parseXml(XCardElement element,
                      VCardParameters parameters,
                      ParseContext context)

Description copied from class: VCardPropertyScribe

Unmarshals a property from an XML document (xCard).

This method should be overridden by child classes that wish to support xCard. The default implementation of this method will find the first child element with the xCard namespace. The element's name will be used as the property's data type and its text content (escaped for inclusion in a text-based vCard, e.g. escaping comma characters) will be passed into the VCardPropertyScribe._parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.io.ParseContext) method. If no such child element is found, then the parent element's text content will be passed into VCardPropertyScribe._parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.io.ParseContext) and the data type will be null.

Overrides:

_parseXml in class VCardPropertyScribe<T extends BinaryProperty<U>>

Parameters:

element - the property's XML element

parameters - the parsed parameters. These parameters will be assigned to the property object once this method returns. Therefore, do not assign any parameters to the property object itself whilst inside of this method, or else they will be overwritten.

context - the parse context

Returns:

the unmarshalled property object

_parseHtml

protected T _parseHtml(HCardElement element,
                       ParseContext context)

Description copied from class: VCardPropertyScribe

Unmarshals the property from an hCard (HTML document).

This method should be overridden by child classes that wish to support hCard. The default implementation of this method will retrieve the HTML element's hCard value (as described in HCardElement.value()), and pass it into the VCardPropertyScribe._parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.io.ParseContext) method.

Overrides:

_parseHtml in class VCardPropertyScribe<T extends BinaryProperty<U>>

Parameters:

element - the property's HTML element

context - the parse context

Returns:

the unmarshalled property object

_writeJson

protected JCardValue _writeJson(T property)

Description copied from class: VCardPropertyScribe

Marshals a property's value to a JSON data stream (jCard).

This method should be overridden by child classes that wish to support jCard. The default implementation of this method will create a jCard property that has a single JSON string value (generated by the VCardPropertyScribe.writeText(T, ezvcard.io.text.WriteContext) method).

Overrides:

_writeJson in class VCardPropertyScribe<T extends BinaryProperty<U>>

Parameters:

property - the property

Returns:

the marshalled value

_parseJson

protected T _parseJson(JCardValue value,
                       VCardDataType dataType,
                       VCardParameters parameters,
                       ParseContext context)

Description copied from class: VCardPropertyScribe

Unmarshals a property from a JSON data stream (jCard).

This method should be overridden by child classes that wish to support jCard. The default implementation of this method will convert the jCard property value to a string and pass it into the VCardPropertyScribe._parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.io.ParseContext) method.

The following paragraphs describe the way in which this method's default implementation converts a jCard value to a string:

If the jCard value consists of a single, non-array, non-object value, then the value is converted to a string. Special characters (backslashes, commas, and semicolons) are escaped in order to simulate what the value might look like in a plain-text vCard.
["x-foo", {}, "text", "the;value"] --> "the\;value"
["x-foo", {}, "text", 2] --> "2"

If the jCard value consists of multiple, non-array, non-object values, then all the values are appended together in a single string, separated by commas. Special characters (backslashes, commas, and semicolons) are escaped for each value in order to prevent commas from being treated as delimiters, and to simulate what the value might look like in a plain-text vCard.
["x-foo", {}, "text", "one", "two,three"] --> "one,two\,three"

If the jCard value is a single array, then this array is treated as a "structured value", and converted its plain-text representation. Special characters (backslashes, commas, and semicolons) are escaped for each value in order to prevent commas and semicolons from being treated as delimiters.
["x-foo", {}, "text", ["one", ["two", "three"], "four;five"]] --> "one;two,three;four\;five"

If the jCard value starts with a JSON object, then it is converted to an empty string (JSON objects are not supported by this method).
["x-foo", , "text", {"one": 1}] --> ""}

For all other cases, behavior is undefined.

Overrides:

_parseJson in class VCardPropertyScribe<T extends BinaryProperty<U>>

Parameters:

value - the property's JSON value

dataType - the data type

parameters - the parsed parameters. These parameters will be assigned to the property object once this method returns. Therefore, do not assign any parameters to the property object itself whilst inside of this method, or else they will be overwritten.

context - the parse context

Returns:

the unmarshalled property object

cannotUnmarshalValue

protected T cannotUnmarshalValue(String value,
                                 VCardVersion version,
                                 U contentType)

Called if the unmarshalling code cannot determine how to unmarshal the value.

Parameters:

value - the value

version - the version of the vCard

contentType - the content type of the resource of null if unknown

Returns:

the unmarshalled property object or null if it cannot be unmarshalled

_mediaTypeFromMediaTypeParameter

protected abstract U _mediaTypeFromMediaTypeParameter(String mediaType)

Builds a MediaTypeParameter object based on the value of the MEDIATYPE parameter or data URI of 4.0 vCards.

Parameters:

mediaType - the media type string (e.g. "image/jpeg")

Returns:

the media type object

_mediaTypeFromTypeParameter

protected abstract U _mediaTypeFromTypeParameter(String type)

Builds a MediaTypeParameter object based on the value of the TYPE parameter in 2.1/3.0 vCards.

Parameters:

type - the TYPE value (e.g. "JPEG")

Returns:

the media type object

_mediaTypeFromFileExtension

protected abstract U _mediaTypeFromFileExtension(String extension)

Searches for a MediaTypeParameter object, given a file extension.

Parameters:

extension - the file extension (e.g. "jpg")

Returns:

the media type object or null if not found

_newInstance

protected abstract T _newInstance(String uri,
                                  U contentType)

Creates a new instance of the property object from a URI.

Parameters:

uri - the URI

contentType - the content type or null if unknown

Returns:

the property object

_newInstance

protected abstract T _newInstance(byte[] data,
                                  U contentType)

Creates a new instance of the property object from binary data.

Parameters:

data - the data

contentType - the content type or null if unknown

Returns:

the property object

parseContentTypeFromParameters

protected U parseContentTypeFromParameters(VCardParameters parameters,
                                           VCardVersion version)

Tries to determine a property value's content type by looking at the property's parameters.

Parameters:

parameters - the parameters

version - the vCard version

Returns:

the content type or null if it can't be found

parseContentTypeFromValueAndParameters

protected U parseContentTypeFromValueAndParameters(String value,
                                                   VCardParameters parameters,
                                                   VCardVersion version)

Tries to determine a property value's content type by looking at the property's parameters and value.

Parameters:

value - the property value

parameters - the property parameters

version - the vCard version

Returns:

the content type or null if it can't be found

parse

protected T parse(String value,
                  VCardDataType dataType,
                  VCardParameters parameters,
                  VCardVersion version)

Parses the property.

Parameters:

value - the property value

dataType - the data type

parameters - the property parameters

version - the vCard version

Returns:

the parsed property

parseAsDataUri

protected T parseAsDataUri(String value)
                    throws IllegalArgumentException

Attempts to parse the given string as a data URI.

Parameters:

value - the string to parse

Returns:

the data URI

Throws:

IllegalArgumentException - if the given value is not a valid data URI

getFileExtension

protected static String getFileExtension(String url)

Gets the file extension from a URL.

Parameters:

url - the URL

Returns:

the file extension (e.g. "jpg") or null if not found