biweekly.property.marshaller
Class ICalPropertyMarshaller<T extends ICalProperty>

java.lang.Object
  biweekly.property.marshaller.ICalPropertyMarshaller<T>

Type Parameters:

T - the property class

Direct Known Subclasses:

AttachmentMarshaller, DateOrDateTimePropertyMarshaller, DateTimePropertyMarshaller, DurationPropertyMarshaller, FreeBusyMarshaller, GeoMarshaller, IntegerPropertyMarshaller, ListPropertyMarshaller, RawPropertyMarshaller, RecurrenceDatesMarshaller, RecurrencePropertyMarshaller, RequestStatusMarshaller, TextPropertyMarshaller, TriggerMarshaller, UtcOffsetPropertyMarshaller, VersionMarshaller, XmlMarshaller

public abstract class ICalPropertyMarshaller<T extends ICalProperty>
extends Object

Base class for iCalendar property marshallers.

Author:

Michael Angstadt

Nested Class Summary

protected static class	ICalPropertyMarshaller.DateParser Factory class for parsing dates.
protected static class	ICalPropertyMarshaller.DateWriter Factory class for writing dates.
protected static interface	ICalPropertyMarshaller.ListCallback<T> Callback function used in conjunction with the list method
static class	ICalPropertyMarshaller.Result<T extends ICalProperty> Represents the result of an unmarshal operation.
protected static class	ICalPropertyMarshaller.SemiStructuredIterator Iterates over the fields in a semi-structured value (a structured value whose components cannot be multi-valued).
protected static class	ICalPropertyMarshaller.Splitter Factory class for splitting strings.
protected static class	ICalPropertyMarshaller.StructuredIterator Iterates over the fields in a structured value.

Field Summary

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

Constructor Summary

ICalPropertyMarshaller(Class<T> clazz, String propertyName, ICalDataType defaultDataType)
Creates a new marshaller.

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

Method Summary

protected ICalDataType	_dataType(T property) Determines the data type of a property instance.
protected T	_parseJson(JCalValue value, ICalDataType dataType, ICalParameters parameters, List<String> warnings) /**
protected abstract T	_parseText(String value, ICalDataType dataType, ICalParameters parameters, List<String> warnings) Unmarshals a property from a plain-text iCalendar data stream.
protected T	_parseXml(XCalElement element, ICalParameters parameters, List<String> warnings) Unmarshals a property from an XML document (xCal).
protected void	_prepareParameters(T property, ICalParameters copy) Sanitizes a property's parameters before the property is written.
protected JCalValue	_writeJson(T property) Marshals a property's value to a JSON data stream (jCal).
protected abstract String	_writeText(T property) Marshals a property's value to a string.
protected void	_writeXml(T property, XCalElement element) Marshals a property's value to an XML element (xCal).
ICalDataType	dataType(T property) Determines the data type of a property instance.
protected static ICalPropertyMarshaller.DateWriter	date(Date date) Formats a Date object as a string.
protected static ICalPropertyMarshaller.DateParser	date(String value) Parses a date string.
protected static String	escape(String text) Escapes all special characters within a iCalendar value.
ICalDataType	getDefaultDataType() Gets the property's default data type.
Class<T>	getPropertyClass() Gets the property class.
String	getPropertyName() Gets the property name.
QName	getQName() Gets this property's local name and namespace for xCal documents.
protected static <T> String	list(Collection<T> values) Writes a comma-separated list of values.
protected static <T> String	list(Collection<T> values, ICalPropertyMarshaller.ListCallback<T> callback) 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(ICalDataType... dataTypes) 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(String... elements) Creates a CannotParseException, indicating that the XML elements that the parser expected to find are missing from property's XML element.
protected static <T> String	object(Map<String,List<T>> value) Writes an object property value to a string.
protected static ListMultimap<String,String>	object(String value) Parses an object property value.
ICalPropertyMarshaller.Result<T>	parseJson(JCalValue value, ICalDataType dataType, ICalParameters parameters) Unmarshals a property's value from a JSON data stream (jCal).
ICalPropertyMarshaller.Result<T>	parseText(String value, ICalDataType dataType, ICalParameters parameters) Unmarshals a property from a plain-text iCalendar data stream.
ICalPropertyMarshaller.Result<T>	parseXml(Element element, ICalParameters parameters) Unmarshals a property's value from an XML document (xCal).
ICalParameters	prepareParameters(T property) Sanitizes a property's parameters (called before the property is written).
protected static ICalPropertyMarshaller.SemiStructuredIterator	semistructured(String value) Parses a list of values that are delimited by semicolons.
protected static ICalPropertyMarshaller.SemiStructuredIterator	semistructured(String value, int limit) Parses a list of values that are delimited by semicolons.
protected static ICalPropertyMarshaller.Splitter	split(String string, String delimiter) Splits a string by a delimiter, taking escaped characters into account.
protected static ICalPropertyMarshaller.StructuredIterator	structured(JCalValue value) Provides an iterator for a jCard structured value.
protected static String	structured(Object... values) Writes a structured value.
protected static ICalPropertyMarshaller.StructuredIterator	structured(String value) Parses a structured value.
protected static String	unescape(String text) Unescapes all special characters that are escaped with a backslash, as well as escaped newlines.
JCalValue	writeJson(T property) Marshals a property's value to a JSON data stream (jCal).
String	writeText(T property) Marshals a property's value to a string.
void	writeXml(T property, Element element) Marshals a property's value to an XML element (xCal).

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 ICalProperty> clazz

propertyName

protected final String propertyName

defaultDataType

protected final ICalDataType defaultDataType

qname

protected final QName qname

Constructor Detail

ICalPropertyMarshaller

public ICalPropertyMarshaller(Class<T> clazz,
                              String propertyName,
                              ICalDataType defaultDataType)

Creates a new marshaller.

Parameters:

clazz - the property class

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

defaultDataType - the property's default data type (e.g. "text") or null if unknown

ICalPropertyMarshaller

public ICalPropertyMarshaller(Class<T> clazz,
                              String propertyName,
                              ICalDataType defaultDataType,
                              QName qname)

Creates a new marshaller.

Parameters:

clazz - the property class

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

defaultDataType - the property's default data type (e.g. "text") or null if unknown

qname - the XML element name and namespace to use for xCal documents (by default, the XML element name is set to the lower-cased property name, and the element namespace is set to the xCal 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. "VERSION")

getDefaultDataType

public ICalDataType getDefaultDataType()

Gets the property's default data type.

Returns:

the default data type (e.g. "text") or null if unknown

getQName

public QName getQName()

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

Returns:

the XML local name and namespace

prepareParameters

public final ICalParameters prepareParameters(T property)

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

Returns:

the sanitized parameters

dataType

public final ICalDataType dataType(T property)

Determines the data type of a property instance.

Parameters:

property - the property

Returns:

the data type or null if unknown

writeText

public final String writeText(T property)

Marshals a property's value to a string.

Parameters:

property - the property

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 (xCal).

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 JCalValue writeJson(T property)

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

Parameters:

property - the property

Returns:

the marshalled value

Throws:

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

parseText

public final ICalPropertyMarshaller.Result<T> parseText(String value,
                                                        ICalDataType dataType,
                                                        ICalParameters parameters)

Unmarshals a property from a plain-text iCalendar data stream.

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

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 ICalendar object

parseXml

public final ICalPropertyMarshaller.Result<T> parseXml(Element element,
                                                       ICalParameters parameters)

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

Parameters:

element - the property's XML element

parameters - the property's 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 ICalendar object

parseJson

public final ICalPropertyMarshaller.Result<T> parseJson(JCalValue value,
                                                        ICalDataType dataType,
                                                        ICalParameters parameters)

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

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 ICalendar object

_prepareParameters

protected void _prepareParameters(T property,
                                  ICalParameters copy)

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)

_dataType

protected ICalDataType _dataType(T property)

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 returns the property's default data type.

Parameters:

property - the property

Returns:

the data type or null if unknown

_writeText

protected abstract String _writeText(T property)

Marshals a property's value to a string.

Parameters:

property - the property

Returns:

the marshalled value

Throws:

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

_writeXml

protected void _writeXml(T property,
                         XCalElement element)

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

This method should be overridden by child classes that wish to support xCal. 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) method), and the child element's text content will be set to the property's marshalled plain-text value (retrieved using the writeText(T) 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 JCalValue _writeJson(T property)

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

This method should be overridden by child classes that wish to support jCal. The default implementation of this method will create a jCard property that has a single JSON string value (generated by the writeText(T) 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,
                                ICalDataType dataType,
                                ICalParameters parameters,
                                List<String> warnings)

Unmarshals a property from a plain-text iCalendar data stream.

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. 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.

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 ICalendar object

_parseXml

protected T _parseXml(XCalElement element,
                      ICalParameters parameters,
                      List<String> warnings)

Unmarshals a property from an XML document (xCal).

This method should be overridden by child classes that wish to support xCal. The default implementation of this method will find the first child element with the xCal 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, biweekly.ICalDataType, biweekly.parameter.ICalParameters, 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, biweekly.ICalDataType, biweekly.parameter.ICalParameters, 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 ICalendar object

_parseJson

protected T _parseJson(JCalValue value,
                       ICalDataType dataType,
                       ICalParameters parameters,
                       List<String> warnings)

/**

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

This method should be overridden by child classes that wish to support jCal. The default implementation of this method will convert the jCal property value to a string and pass it into the _parseText(java.lang.String, biweekly.ICalDataType, biweekly.parameter.ICalParameters, java.util.List) method.

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

If the jCal 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 iCalendar object.
["x-foo", {}, "text", "the;value"] --> "the\;value"
["x-foo", {}, "text", 2] --> "2"

If the jCal 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 iCalendar object.
["x-foo", {}, "text", "one", "two,three"] --> "one,two\,three"

If the jCal 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 jCal value starts with a JSON object, then the object is converted to a format identical to the one used in the RRULE and EXRULE properties. Special characters (backslashes, commas, semicolons, and equal signs) are escaped for each value in order to preserve the syntax of the string value.
["x-foo", {}, "text", {"one": 1, "two": [2, 2.5]}] --> "ONE=1;TWO=2,2.5"

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 ICalendar object

unescape

protected 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

protected static String escape(String text)

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

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

Newlines are not escaped by this method. They are escaped when the iCalendar object is serialized (in the ICalRawWriter class).

Parameters:

text - the text to escape

Returns:

the escaped text

split

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

Splits a string by a delimiter, taking escaped characters into account.

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

list

protected static <T> String list(Collection<T> values,
                                 ICalPropertyMarshaller.ListCallback<T> callback)

Writes a comma-separated list of values.

Parameters:

values - the values to write

callback - callback function used for converting each value to a string

Returns:

the list

semistructured

protected static ICalPropertyMarshaller.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 ICalPropertyMarshaller.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 ICalPropertyMarshaller.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 ICalPropertyMarshaller.StructuredIterator structured(JCalValue 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

object

protected static <T> String object(Map<String,List<T>> value)

Writes an object property value to a string.

Parameters:

value - the value

Returns:

the string

object

protected static ListMultimap<String,String> object(String value)

Parses an object property value.

Parameters:

value - the value to parse

Returns:

the parsed value

date

protected static ICalPropertyMarshaller.DateParser date(String value)

Parses a date string.

Parameters:

value - the date string

Returns:

the factory object

date

protected static ICalPropertyMarshaller.DateWriter date(Date date)

Formats a Date object as a string.

Parameters:

date - the date

Returns:

the factory object

missingXmlElements

protected static CannotParseException missingXmlElements(ICalDataType... 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 property's XML element.

Parameters:

elements - the names of the expected XML elements.