ezvcard.io.scribe
Class VCardPropertyScribe<T extends VCardProperty>

java.lang.Object
  ezvcard.io.scribe.VCardPropertyScribe<T>

Type Parameters:

T - the property class

Direct Known Subclasses:

AddressScribe, AgentScribe, BinaryPropertyScribe, BirthplaceScribe, ClientPidMapScribe, DateOrTimePropertyScribe, DeathplaceScribe, GenderScribe, GeoScribe, ImppScribe, ListPropertyScribe, OrganizationScribe, RawPropertyScribe, RelatedScribe, RevisionScribe, SimplePropertyScribe, StructuredNameScribe, TelephoneScribe, TimezoneScribe, XmlScribe

public abstract class VCardPropertyScribe<T extends VCardProperty>
extends Object

Base class for vCard property marshallers.

Author:

Michael Angstadt

Nested Class Summary

protected static class	VCardPropertyScribe.DateWriter Factory class for writing dates.
static class	VCardPropertyScribe.Result<T extends VCardProperty> Represents the result of an unmarshal operation.
protected static class	VCardPropertyScribe.SemiStructuredIterator Iterates over the fields in a semi-structured value (a structured value whose components cannot be multi-valued).
protected static class	VCardPropertyScribe.Splitter Factory class for splitting strings.
protected static class	VCardPropertyScribe.StructuredIterator Iterates over the fields in a structured value.

Field Summary

protected Class<T>	clazz
protected String	propertyName
protected QName	qname

Constructor Summary

VCardPropertyScribe(Class<T> clazz, String propertyName)
Creates a new marshaller.

VCardPropertyScribe(Class<T> clazz, String propertyName, QName qname)
Creates a new marshaller.

Method Summary

protected VCardDataType	_dataType(T property, VCardVersion version) Determines the data type of a property instance.
protected abstract VCardDataType	_defaultDataType(VCardVersion version) Determines the property's default data type.
protected T	_parseHtml(HCardElement element, List<String> warnings) Unmarshals the property from an hCard (HTML document).
protected T	_parseJson(JCardValue value, VCardDataType dataType, VCardParameters parameters, List<String> warnings) Unmarshals a property from a JSON data stream (jCard).
protected abstract T	_parseText(String value, VCardDataType dataType, VCardVersion version, VCardParameters parameters, List<String> warnings) Unmarshals a property from a plain-text vCard.
protected T	_parseXml(XCardElement element, VCardParameters parameters, List<String> warnings) 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 abstract String	_writeText(T property, VCardVersion version) Marshals a property's value to a string.
protected void	_writeXml(T property, XCardElement element) Marshals a property's value to an XML element (xCard).
VCardDataType	dataType(T property, VCardVersion version) Determines the data type of a property instance.
protected static VCardPropertyScribe.DateWriter	date(Date date) Formats a Date object as a string.
protected static Date	date(String value) Parses a date string.
VCardDataType	defaultDataType(VCardVersion version) Determines the property's default data type.
static String	escape(String text) Escapes all special characters within a vCard value.
Class<T>	getPropertyClass() Gets the property class.
String	getPropertyName() Gets the property name.
QName	getQName() Gets this property's local name and namespace for xCard documents.
protected static void	handlePrefParam(VCardProperty property, VCardParameters copy, VCardVersion version, VCard vcard) Utility method for switching between the "PREF" and "TYPE=PREF" parameters, depending on the target vCard version.
protected static <T> String	list(Collection<T> values) Writes a comma-separated list of values.
protected static String	list(Object... values) Writes a comma-separated list of values.
protected static List<String>	list(String value) Parses a comma-separated list of values.
protected static CannotParseException	missingXmlElements(String... elements) Creates a CannotParseException, indicating that the XML elements that the parser expected to find are missing from the property's XML element.
protected static CannotParseException	missingXmlElements(VCardDataType... dataTypes) Creates a CannotParseException, indicating that the XML elements that the parser expected to find are missing from the property's XML element.
VCardPropertyScribe.Result<T>	parseHtml(Element element) Unmarshals the property from an HTML document (hCard).
VCardPropertyScribe.Result<T>	parseJson(JCardValue value, VCardDataType dataType, VCardParameters parameters) Unmarshals a property's value from a JSON data stream (jCard).
VCardPropertyScribe.Result<T>	parseText(String value, VCardDataType dataType, VCardVersion version, VCardParameters parameters) Unmarshals a property from a plain-text vCard.
VCardPropertyScribe.Result<T>	parseXml(Element element, VCardParameters parameters) Unmarshals a property's value from an XML document (xCard).
VCardParameters	prepareParameters(T property, VCardVersion version, VCard vcard) Sanitizes a property's parameters (called before the property is written).
protected static VCardPropertyScribe.SemiStructuredIterator	semistructured(String value) Parses a list of values that are delimited by semicolons.
protected static VCardPropertyScribe.SemiStructuredIterator	semistructured(String value, int limit) Parses a list of values that are delimited by semicolons.
protected static VCardPropertyScribe.Splitter	split(String string, String delimiter) Splits a string by a delimiter.
protected static VCardPropertyScribe.StructuredIterator	structured(JCardValue value) Provides an iterator for a jCard structured value.
protected static String	structured(Object... values) Writes a structured value.
protected static VCardPropertyScribe.StructuredIterator	structured(String value) Parses a structured value.
static String	unescape(String text) Unescapes all special characters that are escaped with a backslash, as well as escaped newlines.
JCardValue	writeJson(T property) Marshals a property's value to a JSON data stream (jCard).
String	writeText(T property, VCardVersion version) Marshals a property's value to a string.
void	writeXml(T property, Element element) Marshals a property's value to an XML element (xCard).

Methods inherited from class java.lang.Object

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

Field Detail

clazz

protected final Class<T extends VCardProperty> clazz

propertyName

protected final String propertyName

qname

protected final QName qname

Constructor Detail

VCardPropertyScribe

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

Creates a new marshaller.

Parameters:

clazz - the property class

propertyName - the property name (e.g. "FN")

VCardPropertyScribe

public VCardPropertyScribe(Class<T> clazz,
                           String propertyName,
                           QName qname)

Creates a new marshaller.

Parameters:

clazz - the property class

propertyName - the property name (e.g. "FN")

qname - the XML element name and namespace to use for xCard documents (by default, the XML element name is set to the lower-cased property name, and the element namespace is set to the xCard namespace)

Method Detail

getPropertyClass

public Class<T> getPropertyClass()

Gets the property class.

Returns:

the property class

getPropertyName

public String getPropertyName()

Gets the property name.

Returns:

the property name (e.g. "FN")

getQName

public QName getQName()

Gets this property's local name and namespace for xCard documents.

Returns:

the XML local name and namespace

prepareParameters

public final VCardParameters prepareParameters(T property,
                                               VCardVersion version,
                                               VCard vcard)

Sanitizes a property's parameters (called before the property is written). Note that a copy of the parameters is returned so that the property object does not get modified.

Parameters:

property - the property

version - the version of the vCard that is being generated

vcard - the vCard that the property belongs to

Returns:

the sanitized parameters

defaultDataType

public final VCardDataType defaultDataType(VCardVersion version)

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 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 parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.VCardVersion, ezvcard.parameter.VCardParameters) method.

Parameters:

version - the vCard version

Returns:

the default data type or null if unknown

dataType

public final VCardDataType dataType(T property,
                                    VCardVersion version)

Determines the data type of a property instance.

Parameters:

property - the property

version - the version of the vCard that is being generated

Returns:

the data type or null if unknown

writeText

public final String writeText(T property,
                              VCardVersion version)

Marshals a property's value to a string.

Parameters:

property - the property

version - the version of the vCard that is being generated

Returns:

the marshalled value

Throws:

SkipMeException - if the property should not be written to the data stream

writeXml

public final void writeXml(T property,
                           Element element)

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

Parameters:

property - the property

element - the property's XML element.

Throws:

SkipMeException - if the property should not be written to the data stream

writeJson

public final JCardValue writeJson(T property)

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

Parameters:

property - the property

Returns:

the marshalled value

Throws:

SkipMeException - if the property should not be written to the data stream

parseText

public final VCardPropertyScribe.Result<T> parseText(String value,
                                                     VCardDataType dataType,
                                                     VCardVersion version,
                                                     VCardParameters parameters)

Unmarshals a property from a plain-text vCard.

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 defaultDataType(ezvcard.VCardVersion) method. Note that the VALUE parameter is removed from the property's parameter list after it has been read.

version - the version of the vCard that is being parsed

parameters - the parsed parameters

Returns:

the unmarshalled property and its warnings

Throws:

CannotParseException - if the marshaller could not parse the property's value

SkipMeException - if the property should not be added to the final VCard object

EmbeddedVCardException - if the property value is an embedded vCard (i.e. the AGENT property)

parseXml

public final VCardPropertyScribe.Result<T> parseXml(Element element,
                                                    VCardParameters parameters)

Unmarshals a property's value from an XML document (xCard).

Parameters:

element - the property's XML element

parameters - the parsed parameters

Returns:

the unmarshalled property and its warnings

Throws:

CannotParseException - if the marshaller could not parse the property's value

SkipMeException - if the property should not be added to the final VCard object

parseHtml

public final VCardPropertyScribe.Result<T> parseHtml(Element element)

Unmarshals the property from an HTML document (hCard).

Parameters:

element - the property's HTML element

Returns:

the unmarshalled property and its warnings

Throws:

CannotParseException - if the property value could not be parsed

SkipMeException - if this type should NOT be added to the VCard object

EmbeddedVCardException - if the property value is an embedded vCard (i.e. the AGENT property)

parseJson

public final VCardPropertyScribe.Result<T> parseJson(JCardValue value,
                                                     VCardDataType dataType,
                                                     VCardParameters parameters)

Unmarshals a property's value from a JSON data stream (jCard).

Parameters:

value - the property's JSON value

dataType - the data type

parameters - the parsed parameters

Returns:

the unmarshalled property and its warnings

Throws:

CannotParseException - if the marshaller could not parse the property's value

SkipMeException - if the property should not be added to the final VCard object

_prepareParameters

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

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.

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

_defaultDataType

protected abstract VCardDataType _defaultDataType(VCardVersion version)

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 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 parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.VCardVersion, ezvcard.parameter.VCardParameters) method.

Parameters:

version - the vCard version

Returns:

the default data type or null if unknown

_dataType

protected VCardDataType _dataType(T property,
                                  VCardVersion version)

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 _defaultDataType(ezvcard.VCardVersion).

Parameters:

property - the property

version - the version of the vCard that is being generated

Returns:

the data type or null if unknown

_writeText

protected abstract String _writeText(T property,
                                     VCardVersion version)

Marshals a property's value to a string.

Parameters:

property - the property

version - the version of the vCard that is being generated

Returns:

the marshalled value

Throws:

SkipMeException - if the property should not be written to the data stream

_writeXml

protected void _writeXml(T property,
                         XCardElement element)

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 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 writeText(T, ezvcard.VCardVersion) method).

Parameters:

property - the property

element - the property's XML element

Throws:

SkipMeException - if the property should not be written to the data stream

_writeJson

protected JCardValue _writeJson(T property)

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 writeText(T, ezvcard.VCardVersion) method).

Parameters:

property - the property

Returns:

the marshalled value

Throws:

SkipMeException - if the property should not be written to the data stream

_parseText

protected abstract T _parseText(String value,
                                VCardDataType dataType,
                                VCardVersion version,
                                VCardParameters parameters,
                                List<String> warnings)

Unmarshals a property from a plain-text vCard.

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 defaultDataType(ezvcard.VCardVersion) method. Note that the VALUE parameter is removed from the property's parameter list after it has been read.

version - the version of the vCard that is being parsed

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.

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the unmarshalling process

Returns:

the unmarshalled property object

Throws:

CannotParseException - if the marshaller could not parse the property's value

SkipMeException - if the property should not be added to the final VCard object

_parseXml

protected T _parseXml(XCardElement element,
                      VCardParameters parameters,
                      List<String> warnings)

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 will be passed into the _parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.VCardVersion, ezvcard.parameter.VCardParameters, java.util.List) method. If no such child element is found, then the parent element's text content will be passed into _parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.VCardVersion, ezvcard.parameter.VCardParameters, java.util.List) and the data type will be null.

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.

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the unmarshalling process

Returns:

the unmarshalled property object

Throws:

CannotParseException - if the marshaller could not parse the property's value

SkipMeException - if the property should not be added to the final VCard object

_parseHtml

protected T _parseHtml(HCardElement element,
                       List<String> warnings)

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 _parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.VCardVersion, ezvcard.parameter.VCardParameters, java.util.List) method.

Parameters:

element - the property's HTML element

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the unmarshalling process

Throws:

CannotParseException - if the property value could not be parsed

SkipMeException - if this property should NOT be added to the VCard object

EmbeddedVCardException - if the value of this property is an embedded vCard (i.e. the AGENT property)

_parseJson

protected T _parseJson(JCardValue value,
                       VCardDataType dataType,
                       VCardParameters parameters,
                       List<String> warnings)

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 _parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.VCardVersion, ezvcard.parameter.VCardParameters, java.util.List) 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.

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.

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the unmarshalling process

Returns:

the unmarshalled property object

Throws:

CannotParseException - if the marshaller could not parse the property's value

SkipMeException - if the property should not be added to the final VCard object

unescape

public static String unescape(String text)

Unescapes all special characters that are escaped with a backslash, as well as escaped newlines.

Parameters:

text - the text to unescape

Returns:

the unescaped text

escape

public static String escape(String text)

Escapes all special characters within a vCard value. These characters are:

• backslashes (\)
• commas (,)
• semi-colons (;)

Newlines are not escaped by this method. They are escaped when the vCard is serialized (in the VCardRawWriter class).

Parameters:

text - the text to escape

Returns:

the escaped text

split

protected static VCardPropertyScribe.Splitter split(String string,
                                                    String delimiter)

Splits a string by a delimiter.

Parameters:

string - the string to split (e.g. "one,two,three")

delimiter - the delimiter (e.g. ",")

Returns:

the factory object

list

protected static List<String> list(String value)

Parses a comma-separated list of values.

Parameters:

value - the string to parse (e.g. "one,two,th\,ree")

Returns:

the parsed values

list

protected static String list(Object... values)

Writes a comma-separated list of values.

Parameters:

values - the values to write

Returns:

the list

list

protected static <T> String list(Collection<T> values)

Writes a comma-separated list of values.

Parameters:

values - the values to write

Returns:

the list

semistructured

protected static VCardPropertyScribe.SemiStructuredIterator semistructured(String value)

Parses a list of values that are delimited by semicolons. Unlike structured value components, semi-structured components cannot be multi-valued.

Parameters:

value - the string to parse (e.g. "one;two;three")

Returns:

the parsed values

semistructured

protected static VCardPropertyScribe.SemiStructuredIterator semistructured(String value,
                                                                           int limit)

Parses a list of values that are delimited by semicolons. Unlike structured value components, semi-structured components cannot be multi-valued.

Parameters:

value - the string to parse (e.g. "one;two;three")

limit - the max number of components to parse

Returns:

the parsed values

structured

protected static VCardPropertyScribe.StructuredIterator structured(String value)

Parses a structured value.

Parameters:

value - the string to parse (e.g. "one;two,three;four")

Returns:

the parsed values

structured

protected static VCardPropertyScribe.StructuredIterator structured(JCardValue value)

Provides an iterator for a jCard structured value.

Parameters:

value - the jCard value

Returns:

the parsed values

structured

protected static String structured(Object... values)

Writes a structured value.

This method accepts a list of Object instances. Collection objects will be treated as multi-valued components. Null objects will be treated as empty components. All other objects will have their toString() method invoked to generate the string value.

Parameters:

values - the values to write

Returns:

the structured value string

date

protected static Date date(String value)

Parses a date string.

Parameters:

value - the date string

Returns:

the factory object

date

protected static VCardPropertyScribe.DateWriter date(Date date)

Formats a Date object as a string.

Parameters:

date - the date

Returns:

the factory object

missingXmlElements

protected static CannotParseException missingXmlElements(VCardDataType... dataTypes)

Creates a CannotParseException, indicating that the XML elements that the parser expected to find are missing from the property's XML element.

Parameters:

dataTypes - the expected data types (null for "unknown")

missingXmlElements

protected static CannotParseException missingXmlElements(String... elements)

Creates a CannotParseException, indicating that the XML elements that the parser expected to find are missing from the property's XML element.

Parameters:

elements - the names of the expected XML elements.

handlePrefParam

protected static void handlePrefParam(VCardProperty property,
                                      VCardParameters copy,
                                      VCardVersion version,
                                      VCard vcard)

Utility method for switching between the "PREF" and "TYPE=PREF" parameters, depending on the target vCard version. Meant to be called from a scribe's _prepareParameters(T, ezvcard.parameter.VCardParameters, ezvcard.VCardVersion, ezvcard.VCard) method.

Parameters:

property - the property that's being marshalled

copy - the parameters that are being marshalled

version - the vCard version

vcard - the vCard that's being marshalled