T
- the property classpublic abstract class VCardPropertyScribe<T extends VCardProperty> extends Object
Modifier and Type | Class and Description |
---|---|
protected static class |
VCardPropertyScribe.DateWriter
A helper class for writing date values.
|
static class |
VCardPropertyScribe.Result<T extends VCardProperty>
Represents the result of an unmarshal operation.
|
protected static class |
VCardPropertyScribe.SemiStructuredIterator
Iterates over the items in a "semi-structured" property value.
|
protected static class |
VCardPropertyScribe.Splitter
A helper class for splitting strings.
|
protected static class |
VCardPropertyScribe.StructuredIterator
Iterates over the items in a "structured" property value.
|
Modifier and Type | Field and Description |
---|---|
protected Class<T> |
clazz |
protected String |
propertyName |
protected QName |
qname |
Constructor and Description |
---|
VCardPropertyScribe(Class<T> clazz,
String propertyName)
Creates a new marshaller.
|
VCardPropertyScribe(Class<T> clazz,
String propertyName,
QName qname)
Creates a new marshaller.
|
Modifier and Type | Method and Description |
---|---|
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 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 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)
A utility method for switching between the "PREF" and "TYPE=PREF"
parameters when marshalling a property (version 4.0 vCards use "PREF=1",
while version 3.0 vCards use "TYPE=PREF").
|
protected static <T> String |
list(Collection<T> values)
Generates a "list" property value.
|
protected static String |
list(Object... values)
Generates a "list" property value.
|
protected static List<String> |
list(String value)
Parses a "list" property value.
|
protected static CannotParseException |
missingXmlElements(String... elements)
Creates a
CannotParseException to indicate that a scribe could
not find the necessary XML elements required in order to successfully
parse a property (xCards only). |
protected static CannotParseException |
missingXmlElements(VCardDataType... dataTypes)
Creates a
CannotParseException to indicate that a scribe could
not find the necessary XML elements required in order to successfully
parse a property (xCards only). |
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 "semi-structured" property value (a "structured" property value
whose items cannot be multi-valued).
|
protected static VCardPropertyScribe.SemiStructuredIterator |
semistructured(String value,
int limit)
Parses a "semi-structured" property value (a "structured" property value
whose items cannot be multi-valued).
|
protected static VCardPropertyScribe.Splitter |
splitter(char delimiter)
Creates a string splitter (takes escaped characters into account).
|
protected static String |
structured(Object... values)
Writes a "structured" property value.
|
protected static VCardPropertyScribe.StructuredIterator |
structured(String value)
Parses a "structured" property value.
|
static String |
unescape(String text)
Unescapes all special characters that are escaped with a backslash, as
well as escaped newlines.
|
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).
|
protected final Class<T extends VCardProperty> clazz
protected final String propertyName
protected final QName qname
public VCardPropertyScribe(Class<T> clazz, String propertyName)
clazz
- the property classpropertyName
- the property name (e.g. "FN")public VCardPropertyScribe(Class<T> clazz, String propertyName, QName qname)
clazz
- the property classpropertyName
- 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)public Class<T> getPropertyClass()
public String getPropertyName()
public QName getQName()
public final VCardParameters prepareParameters(T property, VCardVersion version, VCard vcard)
property
- the propertyversion
- the version of the vCard that is being generatedvcard
- the vCard that the property belongs topublic 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, org.opencrx.application.uses.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, org.opencrx.application.uses.ezvcard.VCardDataType, org.opencrx.application.uses.ezvcard.VCardVersion, org.opencrx.application.uses.ezvcard.parameter.VCardParameters)
method.
version
- the vCard versionpublic final VCardDataType dataType(T property, VCardVersion version)
property
- the propertyversion
- the version of the vCard that is being generatedpublic final String writeText(T property, VCardVersion version)
property
- the propertyversion
- the version of the vCard that is being generatedSkipMeException
- if the property should not be written to the data
streampublic final void writeXml(T property, Element element)
property
- the propertyelement
- the property's XML element.SkipMeException
- if the property should not be written to the data
streampublic final VCardPropertyScribe.Result<T> parseText(String value, VCardDataType dataType, VCardVersion version, VCardParameters parameters)
value
- the value as read off the wiredataType
- 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(org.opencrx.application.uses.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 parsedparameters
- the parsed parametersCannotParseException
- if the marshaller could not parse the
property's valueSkipMeException
- if the property should not be added to the final
VCard
objectEmbeddedVCardException
- if the property value is an embedded vCard
(i.e. the AGENT property)public final VCardPropertyScribe.Result<T> parseXml(Element element, VCardParameters parameters)
element
- the property's XML elementparameters
- the parsed parametersCannotParseException
- if the marshaller could not parse the
property's valueSkipMeException
- if the property should not be added to the final
VCard
objectprotected 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.
property
- the propertycopy
- 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 generatedvcard
- the vCard that the property belongs toprotected 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, org.opencrx.application.uses.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, org.opencrx.application.uses.ezvcard.VCardDataType, org.opencrx.application.uses.ezvcard.VCardVersion, org.opencrx.application.uses.ezvcard.parameter.VCardParameters)
method.
version
- the vCard versionprotected 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(org.opencrx.application.uses.ezvcard.VCardVersion)
.
property
- the propertyversion
- the version of the vCard that is being generatedprotected abstract String _writeText(T property, VCardVersion version)
property
- the propertyversion
- the version of the vCard that is being generatedSkipMeException
- if the property should not be written to the data
streamprotected 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, org.opencrx.application.uses.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, org.opencrx.application.uses.ezvcard.VCardVersion)
method).
property
- the propertyelement
- the property's XML elementSkipMeException
- if the property should not be written to the data
streamprotected abstract T _parseText(String value, VCardDataType dataType, VCardVersion version, VCardParameters parameters, List<String> warnings)
value
- the value as read off the wiredataType
- 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(org.opencrx.application.uses.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 parsedparameters
- 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 processCannotParseException
- if the marshaller could not parse the
property's valueSkipMeException
- if the property should not be added to the final
VCard
objectprotected 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, org.opencrx.application.uses.ezvcard.VCardDataType, org.opencrx.application.uses.ezvcard.VCardVersion, org.opencrx.application.uses.ezvcard.parameter.VCardParameters, java.util.List<java.lang.String>)
method. If no such child element is found, then the
parent element's text content will be passed into _parseText(java.lang.String, org.opencrx.application.uses.ezvcard.VCardDataType, org.opencrx.application.uses.ezvcard.VCardVersion, org.opencrx.application.uses.ezvcard.parameter.VCardParameters, java.util.List<java.lang.String>)
and
the data type will be null.
element
- the property's XML elementparameters
- 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 processCannotParseException
- if the marshaller could not parse the
property's valueSkipMeException
- if the property should not be added to the final
VCard
objectpublic static String unescape(String text)
text
- the text to unescapepublic static String escape(String text)
Escapes all special characters within a vCard value. These characters are:
\
),
);
)
Newlines are not escaped by this method. They are escaped when the vCard
is serialized (in the VCardRawWriter
class).
text
- the text to escapeprotected static VCardPropertyScribe.Splitter splitter(char delimiter)
delimiter
- the delimiter character (e.g. ',')protected static List<String> list(String value)
Categories
.value
- the string to parse (e.g. "one,two,three\,four")protected static String list(Object... values)
Categories
.values
- the values to write (the toString()
method is
invoked on each object, null objects are ignored, e.g. ["one", "two",
"three,four"])protected static <T> String list(Collection<T> values)
Categories
).values
- the values to write (the toString()
method is
invoked on each object, null objects are ignored, e.g. ["one", "two",
"three,four"])protected static VCardPropertyScribe.SemiStructuredIterator semistructured(String value)
Organization
.value
- the string to parse (e.g. "one;two;three\;four,five")protected static VCardPropertyScribe.SemiStructuredIterator semistructured(String value, int limit)
Organization
.value
- the string to parse (e.g. "one;two;three\;four,five")limit
- the max number of items to parse (see
String.split(String, int)
)protected static VCardPropertyScribe.StructuredIterator structured(String value)
StructuredName
.value
- the string to parse (e.g. "one;two,three;four\,five\;six")protected static String structured(Object... values)
Writes a "structured" property value. This is used in plain-text vCards
to marshal properties such as StructuredName
.
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.
values
- the values to writeprotected static Date date(String value)
value
- the date stringIllegalArgumentException
- if the date cannot be parsedprotected static VCardPropertyScribe.DateWriter date(Date date)
Date
object as a string.date
- the dateprotected static CannotParseException missingXmlElements(VCardDataType... dataTypes)
CannotParseException
to indicate that a scribe could
not find the necessary XML elements required in order to successfully
parse a property (xCards only).dataTypes
- the expected data types (null for "unknown")protected static CannotParseException missingXmlElements(String... elements)
CannotParseException
to indicate that a scribe could
not find the necessary XML elements required in order to successfully
parse a property (xCards only).elements
- the names of the expected XML elements.protected static void handlePrefParam(VCardProperty property, VCardParameters copy, VCardVersion version, VCard vcard)
_prepareParameters(T, org.opencrx.application.uses.ezvcard.parameter.VCardParameters, org.opencrx.application.uses.ezvcard.VCardVersion, org.opencrx.application.uses.ezvcard.VCard)
method.property
- the property that is being marshalledcopy
- the parameters that are being marshalledversion
- the vCard versionvcard
- the vCard that's being marshalledThis software is published under the BSD license. Copyright © 2003-${build.year}, CRIXP AG, Switzerland, All rights reserved. Use is subject to license terms.