biweekly.io.scribe.property

Class ICalPropertyScribe<T extends ICalProperty>

java.lang.Object

biweekly.io.scribe.property.ICalPropertyScribe<T>

Type Parameters:

T - the property class

Direct Known Subclasses:

AttachmentScribe, AttendeeScribe, DateOrDateTimePropertyScribe, DateTimePropertyScribe, DaylightScribe, DurationPropertyScribe, FreeBusyScribe, GeoScribe, IntegerPropertyScribe, ListPropertyScribe, OrganizerScribe, RawPropertyScribe, RecurrenceDatesScribe, RecurrencePropertyScribe, RequestStatusScribe, TextPropertyScribe, TriggerScribe, UtcOffsetPropertyScribe, VCalAlarmPropertyScribe, VersionScribe, XmlScribe

public abstract class ICalPropertyScribe<T extends ICalProperty>
extends Object

Base class for iCalendar property scribes.

Author:

Michael Angstadt

Nested Class Summary

Nested Classes

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

Field Summary

Fields

Modifier and Type	Field and Description
protected Class<T>	clazz
protected String	propertyName
protected QName	qname

Constructor Summary

Constructors

Constructor and Description
ICalPropertyScribe(Class<T> clazz, String propertyName) Creates a new scribe.
ICalPropertyScribe(Class<T> clazz, String propertyName, ICalDataType defaultDataType) Creates a new scribe.
ICalPropertyScribe(Class<T> clazz, String propertyName, ICalDataType defaultDataType, QName qname) Creates a new scribe.

Method Summary

Methods

Modifier and Type	Method and Description
protected ICalDataType	_dataType(T property, ICalVersion version) Determines the data type of a property instance.
protected ICalDataType	_defaultDataType(ICalVersion version) Determines the default data type of this property.
protected T	_parseJson(JCalValue value, ICalDataType dataType, ICalParameters parameters, ParseContext context) Unmarshals a property from a JSON data stream (jCal).
protected abstract T	_parseText(String value, ICalDataType dataType, ICalParameters parameters, ParseContext context) Unmarshals a property from a plain-text iCalendar data stream.
protected T	_parseXml(XCalElement element, ICalParameters parameters, ParseContext context) Unmarshals a property from an XML document (xCal).
protected ICalParameters	_prepareParameters(T property, WriteContext context) Sanitizes a property's parameters before the property is written.
protected JCalValue	_writeJson(T property, WriteContext context) Marshals a property's value to a JSON data stream (jCal).
protected abstract String	_writeText(T property, WriteContext context) Marshals a property's value to a string.
protected void	_writeXml(T property, XCalElement element, WriteContext context) Marshals a property's value to an XML element (xCal).
ICalDataType	dataType(T property, ICalVersion version) Determines the data type of a property instance.
protected static ICalPropertyScribe.DateWriter	date(Date date) Formats a date as a string.
protected static ICalPropertyScribe.DateWriter	date(Date date, ICalProperty property, WriteContext context)
protected static ICalPropertyScribe.DateWriter	date(ICalDate date) Formats a date as a string.
protected static ICalPropertyScribe.DateWriter	date(ICalDate date, ICalProperty property, WriteContext context)
protected static ICalPropertyScribe.DateParser	date(String value) Parses a date string.
ICalDataType	defaultDataType(ICalVersion version) Determines the default data type of this property.
protected static String	escape(String text) Escapes all special characters within a iCalendar 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 xCal documents.
Set<ICalVersion>	getSupportedVersions() Gets the iCalendar versions that support this property.
protected static ICalParameters	handleTzidParameter(ICalProperty property, boolean hasTime, WriteContext context) Adds a TZID parameter to a property's parameter list if necessary.
protected static boolean	isInObservance(WriteContext context) Determines if the property is within an observance component.
protected static <T> String	list(Collection<T> values) Writes a comma-separated list of values.
protected static <T> String	list(Collection<T> values, ICalPropertyScribe.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.
T	parseJson(JCalValue value, ICalDataType dataType, ICalParameters parameters, ParseContext context) Unmarshals a property's value from a JSON data stream (jCal).
T	parseText(String value, ICalDataType dataType, ICalParameters parameters, ParseContext context) Unmarshals a property from a plain-text iCalendar data stream.
T	parseXml(Element element, ICalParameters parameters, ParseContext context) Unmarshals a property's value from an XML document (xCal).
ICalParameters	prepareParameters(T property, WriteContext context) Sanitizes a property's parameters before the property is written.
protected static ICalPropertyScribe.SemiStructuredIterator	semistructured(String value) Parses a list of values that are delimited by semicolons.
protected static ICalPropertyScribe.SemiStructuredIterator	semistructured(String value, boolean nullEmpties) Parses a list of values that are delimited by semicolons.
protected static ICalPropertyScribe.Splitter	splitter(char delimiter) Splits a string by a delimiter, taking escaped characters into account.
protected static ICalPropertyScribe.StructuredIterator	structured(JCalValue value) Provides an iterator for a jCard structured value.
protected static String	structured(Object... values) Writes a structured value.
protected static ICalPropertyScribe.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, WriteContext context) Marshals a property's value to a JSON data stream (jCal).
String	writeText(T property, WriteContext context) Marshals a property's value to a string.
void	writeXml(T property, Element element, WriteContext context) 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

qname

protected final QName qname

Constructor Detail

ICalPropertyScribe

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

Creates a new scribe.

Parameters:

clazz - the property class

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

ICalPropertyScribe

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

Creates a new scribe.

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

ICalPropertyScribe

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

Creates a new scribe.

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

getSupportedVersions

public Set<ICalVersion> getSupportedVersions()

Gets the iCalendar versions that support this property. This method returns all iCalendar versions unless overridden by the child scribe.

Returns:

the iCalendar versions

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. "DTSTART")

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,
                               WriteContext context)

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

Parameters:

property - the property to write

context - the context

Returns:

the sanitized parameters

defaultDataType

public final ICalDataType defaultDataType(ICalVersion version)

Determines the default data type of this property.

Parameters:

version - the version of the iCalendar object being generated

Returns:

the data type or null if unknown

dataType

public final ICalDataType dataType(T property,
                    ICalVersion version)

Determines the data type of a property instance.

Parameters:

property - the property

version - the version of the iCalendar object being generated

Returns:

the data type or null if unknown

writeText

public final String writeText(T property,
               WriteContext context)

Marshals a property's value to a string.

Parameters:

property - the property

context - the context

Throws:

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

writeXml

public final void writeXml(T property,
            Element element,
            WriteContext context)

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

Parameters:

property - the property

element - the property's XML element

context - the context

Throws:

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

writeJson

public final JCalValue writeJson(T property,
                  WriteContext context)

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

Parameters:

property - the property

context - the context

Returns:

the marshalled value

Throws:

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

parseText

public final T parseText(String value,
          ICalDataType dataType,
          ICalParameters parameters,
          ParseContext context)

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

context - the parse context

Returns:

the unmarshalled property

Throws:

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

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

parseXml

public final T parseXml(Element element,
         ICalParameters parameters,
         ParseContext context)

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

Parameters:

element - the property's XML element

parameters - the property's parameters

context - the context

Returns:

the unmarshalled property

Throws:

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

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

parseJson

public final T parseJson(JCalValue value,
          ICalDataType dataType,
          ICalParameters parameters,
          ParseContext context)

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

context - the context

Returns:

the unmarshalled property

Throws:

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

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

_prepareParameters

protected ICalParameters _prepareParameters(T property,
                                WriteContext context)

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 returns the property's parameters unmodified.

Parameters:

property - the property to write

context - the context

Returns:

the sanitized parameters (this should be a *copy* of the property's parameters if modifications were made)

_defaultDataType

protected ICalDataType _defaultDataType(ICalVersion version)

Determines the default data type of this property.

This method should be overridden by child classes if a property's default data type changes depending the iCalendar version. The default implementation of this method returns the data type that was passed into the ICalPropertyScribe(Class, String, ICalDataType) constructor. Null is returned if this constructor was not invoked.

Parameters:

version - the version of the iCalendar object being generated

Returns:

the data type or null if unknown

_dataType

protected ICalDataType _dataType(T property,
                     ICalVersion 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 returns the property's default data type.

Parameters:

property - the property

version - the version of the iCalendar object being generated

Returns:

the data type or null if unknown

_writeText

protected abstract String _writeText(T property,
                WriteContext context)

Marshals a property's value to a string.

Parameters:

property - the property

context - the write context

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,
             WriteContext context)

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, biweekly.ICalVersion) method), and the child element's text content will be set to the property's marshalled plain-text value (retrieved using the writeText(T, biweekly.io.WriteContext) method).

Parameters:

property - the property

element - the property's XML element

context - the context

Throws:

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

_writeJson

protected JCalValue _writeJson(T property,
                   WriteContext context)

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, biweekly.io.WriteContext) method).

Parameters:

property - the property

context - the context

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,
           ParseContext context)

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.

context - the parse context

Returns:

the unmarshalled property object

Throws:

CannotParseException - if the scribe 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,
          ParseContext context)

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, biweekly.io.ParseContext) 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, biweekly.io.ParseContext) 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.

context - the context

Returns:

the unmarshalled property object

Throws:

CannotParseException - if the scribe 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,
           ParseContext context)

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, biweekly.io.ParseContext) 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.

context - the context

Returns:

the unmarshalled property object

Throws:

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

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

isInObservance

protected static boolean isInObservance(WriteContext context)

Determines if the property is within an observance component.

Parameters:

context - the write context

Returns:

true if the property is within an observance, false if not

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

splitter

protected static ICalPropertyScribe.Splitter splitter(char delimiter)

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

Parameters:

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,
              ICalPropertyScribe.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 ICalPropertyScribe.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 ICalPropertyScribe.SemiStructuredIterator semistructured(String value,
                                                       boolean nullEmpties)

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")

nullEmpties - true to treat empty elements as null, false to treat them as empty strings

Returns:

the parsed values

structured

protected static ICalPropertyScribe.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 ICalPropertyScribe.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 ICalPropertyScribe.DateParser date(String value)

Parses a date string.

Parameters:

value - the date string

Returns:

the factory object

date

protected static ICalPropertyScribe.DateWriter date(Date date)

Formats a date as a string.

Parameters:

date - the date

Returns:

the factory object

date

protected static ICalPropertyScribe.DateWriter date(ICalDate date)

Formats a date as a string.

Parameters:

date - the date

Returns:

the factory object

date

protected static ICalPropertyScribe.DateWriter date(Date date,
                                 ICalProperty property,
                                 WriteContext context)

date

protected static ICalPropertyScribe.DateWriter date(ICalDate date,
                                 ICalProperty property,
                                 WriteContext context)

handleTzidParameter

protected static ICalParameters handleTzidParameter(ICalProperty property,
                                 boolean hasTime,
                                 WriteContext context)

Adds a TZID parameter to a property's parameter list if necessary.

Parameters:

property - the property

hasTime - true if the property value has a time component, false if not

context - the write context

Returns:

the property's new set of parameters

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.