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.
|
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 scribe.
|
VCardPropertyScribe(Class<T> clazz,
String propertyName,
QName qname)
Creates a new scribe.
|
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 T |
_parseHtml(HCardElement element,
ParseContext context)
Unmarshals the property from an hCard (HTML document).
|
protected T |
_parseJson(JCardValue value,
VCardDataType dataType,
VCardParameters parameters,
ParseContext context)
Unmarshals a property from a JSON data stream (jCard).
|
protected abstract T |
_parseText(String value,
VCardDataType dataType,
VCardParameters parameters,
ParseContext context)
Unmarshals a property from a plain-text vCard.
|
protected T |
_parseXml(XCardElement element,
VCardParameters parameters,
ParseContext context)
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 JCardValue |
_writeJson(T property)
Marshals a property's value to a JSON data stream (jCard).
|
protected abstract String |
_writeText(T property,
WriteContext context)
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 Temporal |
date(String value)
Parses a date string.
|
protected static VCardPropertyScribe.DateWriter |
date(Temporal date)
Formats a
Temporal object as a string. |
VCardDataType |
defaultDataType(VCardVersion version)
Determines the property's default data type.
|
protected static String |
escape(String value,
WriteContext context)
Escapes special characters in a property value for writing to a
plain-text output stream.
|
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 parameters,
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 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). |
T |
parseHtml(HCardElement element,
ParseContext context)
Unmarshals the property from an HTML document (hCard).
|
T |
parseJson(JCardValue value,
VCardDataType dataType,
VCardParameters parameters,
ParseContext context)
Unmarshals a property's value from a JSON data stream (jCard).
|
T |
parseText(String value,
VCardDataType dataType,
VCardParameters parameters,
ParseContext context)
Unmarshals a property from a plain-text vCard.
|
T |
parseXml(Element element,
VCardParameters parameters,
ParseContext context)
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).
|
JCardValue |
writeJson(T property)
Marshals a property's value to a JSON data stream (jCard).
|
String |
writeText(T property,
WriteContext context)
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
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, 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, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.io.ParseContext)
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, WriteContext context)
property
- the propertycontext
- contains information about the vCard being written, such
as the target versionSkipMeException
- 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 JCardValue writeJson(T property)
property
- the propertySkipMeException
- if the property should not be written to the data
streampublic final T parseText(String value, VCardDataType dataType, VCardParameters parameters, ParseContext context)
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(ezvcard.VCardVersion)
method.
Note that the VALUE parameter is removed from the property's parameter
list after it has been read.parameters
- the parsed parameterscontext
- the parse contextCannotParseException
- 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 T parseXml(Element element, VCardParameters parameters, ParseContext context)
element
- the property's XML elementparameters
- the parsed parameterscontext
- the parse contextCannotParseException
- if the marshaller could not parse the
property's valueSkipMeException
- if the property should not be added to the final
VCard
objectpublic final T parseHtml(HCardElement element, ParseContext context)
element
- the property's HTML elementcontext
- the parse contextCannotParseException
- if the property value could not be parsedSkipMeException
- if this type should NOT be added to the
VCard
objectEmbeddedVCardException
- if the property value is an embedded vCard
(i.e. the AGENT property)public final T parseJson(JCardValue value, VCardDataType dataType, VCardParameters parameters, ParseContext context)
value
- the property's JSON valuedataType
- the data typeparameters
- the parsed parameterscontext
- the parse contextCannotParseException
- 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, 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, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.io.ParseContext)
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(ezvcard.VCardVersion)
.
property
- the propertyversion
- the version of the vCard that is being generatedprotected abstract String _writeText(T property, WriteContext context)
property
- the propertycontext
- contains information about the vCard being written, such
as the target versionSkipMeException
- 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, 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, ezvcard.io.text.WriteContext)
method).
property
- the propertyelement
- the property's XML elementSkipMeException
- if the property should not be written to the data
streamprotected JCardValue _writeJson(T property)
Marshals a property's value to a JSON data stream (jCard).
This method should be overridden by child classes that wish to support
jCard. The default implementation of this method will create a jCard
property that has a single JSON string value (generated by the
writeText(T, ezvcard.io.text.WriteContext)
method).
property
- the propertySkipMeException
- if the property should not be written to the data
streamprotected abstract T _parseText(String value, VCardDataType dataType, VCardParameters parameters, ParseContext context)
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(ezvcard.VCardVersion)
method.
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 contextCannotParseException
- 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, ParseContext context)
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 (escaped for inclusion
in a text-based vCard, e.g. escaping comma characters) will be passed
into the _parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.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, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.io.ParseContext)
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.context
- the parse contextCannotParseException
- if the marshaller could not parse the
property's valueSkipMeException
- if the property should not be added to the final
VCard
objectprotected T _parseHtml(HCardElement element, ParseContext context)
Unmarshals the property from an hCard (HTML document).
This method should be overridden by child classes that wish to support
hCard. The default implementation of this method will retrieve the HTML
element's hCard value (as described in HCardElement.value()
), and
pass it into the _parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.io.ParseContext)
method.
element
- the property's HTML elementcontext
- the parse contextCannotParseException
- if the property value could not be parsedSkipMeException
- if this property should NOT be added to the
VCard
objectEmbeddedVCardException
- if the value of this property is an
embedded vCard (i.e. the AGENT property)protected T _parseJson(JCardValue value, VCardDataType dataType, VCardParameters parameters, ParseContext context)
Unmarshals a property from a JSON data stream (jCard).
This method should be overridden by child classes that wish to support
jCard. The default implementation of this method will convert the jCard
property value to a string and pass it into the _parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.io.ParseContext)
method.
The following paragraphs describe the way in which this method's default implementation converts a jCard value to a string:
If the jCard 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 vCard.
["x-foo", {}, "text", "the;value"] --> "the\;value"
["x-foo", {}, "text", 2] --> "2"
If the jCard 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 vCard.
["x-foo", {}, "text", "one", "two,three"] -->
"one,two\,three"
If the jCard 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 jCard value starts with a JSON object, then it is converted to an
empty string (JSON objects are not supported by this method).
["x-foo", , "text", {"one": 1}] --> ""}
For all other cases, behavior is undefined.
value
- the property's JSON valuedataType
- the data typeparameters
- 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 contextCannotParseException
- if the marshaller could not parse the
property's valueSkipMeException
- if the property should not be added to the final
VCard
objectprotected static Temporal date(String value)
value
- the date stringIllegalArgumentException
- if the date cannot be parsedprotected static VCardPropertyScribe.DateWriter date(Temporal date)
Temporal
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 parameters, VCardVersion version, VCard vcard)
_prepareParameters(T, ezvcard.parameter.VCardParameters, ezvcard.VCardVersion, ezvcard.VCard)
method.property
- the property that is being marshalledparameters
- the parameters that are being marshalled (this should
be a copy of the property's parameters so that changes can be made to
them without affecting the original object)version
- the vCard version that the vCard is being marshalled tovcard
- the vCard that's being marshalledprotected static String escape(String value, WriteContext context)
Escapes special characters in a property value for writing to a plain-text output stream.
If the target version is 2.1, then the value will be returned unchanged. 2.1 only requires special characters to be escaped within properties that make use of those special characters.
value
- the value to escapecontext
- the write contextCopyright © 2012–2023 Michael Angstadt. All rights reserved.