biweekly.io.scribe.property

Class DateOrDateTimePropertyScribe<T extends DateOrDateTimeProperty>

java.lang.Object

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

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

Type Parameters:

T - the property class

Direct Known Subclasses:

DateDueScribe, DateEndScribe, DateStartScribe, RecurrenceIdScribe

public abstract class DateOrDateTimePropertyScribe<T extends DateOrDateTimeProperty>
extends ICalPropertyScribe<T>

Marshals properties that have either "date" or "date-time" values.

Author:

Michael Angstadt

Nested Class Summary

Nested classes/interfaces inherited from class biweekly.io.scribe.property.ICalPropertyScribe

ICalPropertyScribe.DateParser, ICalPropertyScribe.DateWriter, ICalPropertyScribe.ListCallback<T>, ICalPropertyScribe.Result<T>, ICalPropertyScribe.SemiStructuredIterator, ICalPropertyScribe.Splitter, ICalPropertyScribe.StructuredIterator

Field Summary

Fields inherited from class biweekly.io.scribe.property.ICalPropertyScribe

clazz, propertyName, qname

Constructor Summary

Constructors

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

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 T	_parseJson(JCalValue value, ICalDataType dataType, ICalParameters parameters, ParseContext context) Unmarshals a property from a JSON data stream (jCal).
protected 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 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).
protected abstract T	newInstance(ICalDate date)

Methods inherited from class biweekly.io.scribe.property.ICalPropertyScribe

_defaultDataType, dataType, date, date, date, date, date, defaultDataType, escape, getPropertyClass, getPropertyName, getQName, getSupportedVersions, handleTzidParameter, isInObservance, list, list, list, list, missingXmlElements, missingXmlElements, object, object, parseJson, parseText, parseXml, prepareParameters, semistructured, semistructured, splitter, structured, structured, structured, unescape, writeJson, writeText, writeXml

Methods inherited from class java.lang.Object

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

Constructor Detail

DateOrDateTimePropertyScribe

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

Method Detail

_prepareParameters

protected ICalParameters _prepareParameters(T property,
                                WriteContext context)

Description copied from class: ICalPropertyScribe

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.

Overrides:

_prepareParameters in class ICalPropertyScribe<T extends DateOrDateTimeProperty>

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)

_dataType

protected ICalDataType _dataType(T property,
                     ICalVersion version)

Description copied from class: ICalPropertyScribe

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.

Overrides:

_dataType in class ICalPropertyScribe<T extends DateOrDateTimeProperty>

Parameters:

property - the property

version - the version of the iCalendar object being generated

Returns:

the data type or null if unknown

_writeText

protected String _writeText(T property,
                WriteContext context)

Description copied from class: ICalPropertyScribe

Marshals a property's value to a string.

Specified by:

_writeText in class ICalPropertyScribe<T extends DateOrDateTimeProperty>

Parameters:

property - the property

context - the write context

Returns:

the marshalled value

_parseText

protected T _parseText(String value,
           ICalDataType dataType,
           ICalParameters parameters,
           ParseContext context)

Description copied from class: ICalPropertyScribe

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

Specified by:

_parseText in class ICalPropertyScribe<T extends DateOrDateTimeProperty>

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

_writeXml

protected void _writeXml(T property,
             XCalElement element,
             WriteContext context)

Description copied from class: ICalPropertyScribe

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 ICalPropertyScribe.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 ICalPropertyScribe.writeText(T, biweekly.io.WriteContext) method).

Overrides:

_writeXml in class ICalPropertyScribe<T extends DateOrDateTimeProperty>

Parameters:

property - the property

element - the property's XML element

context - the context

_parseXml

protected T _parseXml(XCalElement element,
          ICalParameters parameters,
          ParseContext context)

Description copied from class: ICalPropertyScribe

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 ICalPropertyScribe._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 ICalPropertyScribe._parseText(java.lang.String, biweekly.ICalDataType, biweekly.parameter.ICalParameters, biweekly.io.ParseContext) and the data type will be null.

Overrides:

_parseXml in class ICalPropertyScribe<T extends DateOrDateTimeProperty>

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

_writeJson

protected JCalValue _writeJson(T property,
                   WriteContext context)

Description copied from class: ICalPropertyScribe

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 ICalPropertyScribe.writeText(T, biweekly.io.WriteContext) method).

Overrides:

_writeJson in class ICalPropertyScribe<T extends DateOrDateTimeProperty>

Parameters:

property - the property

context - the context

Returns:

the marshalled value

_parseJson

protected T _parseJson(JCalValue value,
           ICalDataType dataType,
           ICalParameters parameters,
           ParseContext context)

Description copied from class: ICalPropertyScribe

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

Overrides:

_parseJson in class ICalPropertyScribe<T extends DateOrDateTimeProperty>

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

newInstance

protected abstract T newInstance(ICalDate date)