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

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

Direct Known Subclasses:

AttachmentMarshaller, DateOrDateTimePropertyMarshaller, DateTimePropertyMarshaller, DurationPropertyMarshaller, FreeBusyMarshaller, GeoMarshaller, IntegerPropertyMarshaller, ListPropertyMarshaller, RawPropertyMarshaller, RecurrenceDatesMarshaller, RecurrenceRuleMarshaller, 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.
static class	ICalPropertyMarshaller.Result<T> Represents the result of a marshal or unmarshal operation.
protected static class	ICalPropertyMarshaller.Splitter Factory class for splitting strings.

Field Summary

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

Constructor Summary

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

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

Method Summary

protected abstract T	_parseText(String value, ICalParameters parameters, List<String> warnings) Unmarshals a property's value.
protected T	_parseXml(XCalElement element, ICalParameters parameters, List<String> warnings) Unmarshals a property's value from an XML document (xCal).
protected void	_prepareParameters(T property, ICalParameters copy) Sanitizes a property's parameters (called before the property is written).
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).
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.
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 String[][]	parseComponent(String str) Parses a component value.
protected static String[]	parseList(String str) Parses a comma-separated list of values.
ICalPropertyMarshaller.Result<T>	parseText(String value, ICalParameters parameters) Unmarshals a property's value.
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.Splitter	split(String string, String delimiter) Splits a string by a delimiter.
protected static String	unescape(String text) Unescapes all special characters that are escaped with a backslash, as well as escaped newlines.
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

qname

protected final QName qname

Constructor Detail

ICalPropertyMarshaller

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

Creates a new marshaller.

Parameters:

clazz - the property class

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

ICalPropertyMarshaller

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

Creates a new marshaller.

Parameters:

clazz - the property class

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

qname - the XML element name and namespace (used for xCal documents)

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

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

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

parseText

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

Unmarshals a property's value.

Parameters:

value - the value

parameters - the property's parameters

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

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

_prepareParameters

protected void _prepareParameters(T property,
                                  ICalParameters copy)

Sanitizes a property's parameters (called before the property is written). This should be overridden by child classes when required.

Parameters:

property - the property

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

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

Parameters:

property - the property

element - the XML element

Throws:

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

_parseText

protected abstract T _parseText(String value,
                                ICalParameters parameters,
                                List<String> warnings)

Unmarshals a property's value.

Parameters:

value - the value

parameters - the property's parameters

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's value from an XML document (xCal).

Parameters:

element - the property's XML element

parameters - the property's parameters

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 escaped by ICalWriter)

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.

Parameters:

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

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

Returns:

the factory object

parseList

protected static String[] parseList(String str)

Parses a comma-separated list of values.

Parameters:

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

Returns:

the parsed values

parseComponent

protected static String[][] parseComponent(String str)

Parses a component value.

Parameters:

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

Returns:

the parsed values

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