T - the property classU - the media type classpublic abstract class BinaryPropertyScribe<T extends BinaryProperty<U>,U extends MediaTypeParameter> extends VCardPropertyScribe<T>
VCardPropertyScribe.DateWriterclazz, propertyName, qname| Constructor and Description |
|---|
BinaryPropertyScribe(Class<T> clazz,
String propertyName) |
| Modifier and Type | Method and Description |
|---|---|
protected VCardDataType |
_dataType(T property,
VCardVersion version)
Determines the data type of a property instance.
|
protected VCardDataType |
_defaultDataType(VCardVersion version)
Determines the property's default data type.
|
protected abstract U |
_mediaTypeFromFileExtension(String extension)
Searches for a
MediaTypeParameter object, given a file extension. |
protected abstract U |
_mediaTypeFromMediaTypeParameter(String mediaType)
Builds a
MediaTypeParameter object based on the value of the
MEDIATYPE parameter or data URI of 4.0 vCards. |
protected abstract U |
_mediaTypeFromTypeParameter(String type)
Builds a
MediaTypeParameter object based on the value of the TYPE
parameter in 2.1/3.0 vCards. |
protected abstract T |
_newInstance(byte[] data,
U contentType)
Creates a new instance of the property object from binary data.
|
protected abstract T |
_newInstance(String uri,
U contentType)
Creates a new instance of the property object from a URI.
|
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 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 String |
_writeText(T property,
WriteContext context)
Marshals a property's value to a string.
|
protected void |
_writeXml(T property,
XCardElement parent)
Marshals a property's value to an XML element (xCard).
|
protected T |
cannotUnmarshalValue(String value,
VCardVersion version,
U contentType)
Called if the unmarshalling code cannot determine how to unmarshal the
value.
|
protected static String |
getFileExtension(String url)
Gets the file extension from a URL.
|
protected T |
parse(String value,
VCardDataType dataType,
VCardParameters parameters,
VCardVersion version)
Parses the property.
|
protected U |
parseContentTypeFromParameters(VCardParameters parameters,
VCardVersion version)
Tries to determine a property value's content type by looking at the
property's parameters.
|
protected U |
parseContentTypeFromValueAndParameters(String value,
VCardParameters parameters,
VCardVersion version)
Tries to determine a property value's content type by looking at the
property's parameters and value.
|
dataType, date, date, defaultDataType, escape, getPropertyClass, getPropertyName, getQName, handlePrefParam, missingXmlElements, missingXmlElements, parseHtml, parseJson, parseText, parseXml, prepareParameters, writeJson, writeText, writeXmlpublic BinaryPropertyScribe(Class<T> clazz, String propertyName)
protected VCardDataType _defaultDataType(VCardVersion version)
VCardPropertyScribeDetermines the property's default data type.
When writing a plain-text vCard, if the data type of a property instance
(as determined by the VCardPropertyScribe.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
VCardPropertyScribe.parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.io.ParseContext) method.
_defaultDataType in class VCardPropertyScribe<T extends BinaryProperty<U>>version - the vCard versionprotected VCardDataType _dataType(T property, VCardVersion version)
VCardPropertyScribeDetermines 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 VCardPropertyScribe._defaultDataType(ezvcard.VCardVersion).
_dataType in class VCardPropertyScribe<T extends BinaryProperty<U>>property - the propertyversion - the version of the vCard that is being generatedprotected void _prepareParameters(T property, VCardParameters copy, VCardVersion version, VCard vcard)
VCardPropertyScribeSanitizes 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.
_prepareParameters in class VCardPropertyScribe<T extends BinaryProperty<U>>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 String _writeText(T property, WriteContext context)
VCardPropertyScribe_writeText in class VCardPropertyScribe<T extends BinaryProperty<U>>property - the propertycontext - contains information about the vCard being written, such
as the target versionprotected T _parseText(String value, VCardDataType dataType, VCardParameters parameters, ParseContext context)
VCardPropertyScribe_parseText in class VCardPropertyScribe<T extends BinaryProperty<U>>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 VCardPropertyScribe.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 contextprotected void _writeXml(T property, XCardElement parent)
VCardPropertyScribeMarshals 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 VCardPropertyScribe.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
VCardPropertyScribe.writeText(T, ezvcard.io.text.WriteContext) method).
_writeXml in class VCardPropertyScribe<T extends BinaryProperty<U>>property - the propertyparent - the property's XML elementprotected T _parseXml(XCardElement element, VCardParameters parameters, ParseContext context)
VCardPropertyScribeUnmarshals 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 VCardPropertyScribe._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
VCardPropertyScribe._parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.io.ParseContext) and the data type will be null.
_parseXml in class VCardPropertyScribe<T extends BinaryProperty<U>>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 contextprotected T _parseHtml(HCardElement element, ParseContext context)
VCardPropertyScribeUnmarshals 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 VCardPropertyScribe._parseText(java.lang.String, ezvcard.VCardDataType, ezvcard.parameter.VCardParameters, ezvcard.io.ParseContext) method.
_parseHtml in class VCardPropertyScribe<T extends BinaryProperty<U>>element - the property's HTML elementcontext - the parse contextprotected JCardValue _writeJson(T property)
VCardPropertyScribeMarshals 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
VCardPropertyScribe.writeText(T, ezvcard.io.text.WriteContext) method).
_writeJson in class VCardPropertyScribe<T extends BinaryProperty<U>>property - the propertyprotected T _parseJson(JCardValue value, VCardDataType dataType, VCardParameters parameters, ParseContext context)
VCardPropertyScribeUnmarshals 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 VCardPropertyScribe._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.
_parseJson in class VCardPropertyScribe<T extends BinaryProperty<U>>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 contextprotected T cannotUnmarshalValue(String value, VCardVersion version, U contentType)
value - the valueversion - the version of the vCardcontentType - the content type of the resource of null if unknownprotected abstract U _mediaTypeFromMediaTypeParameter(String mediaType)
MediaTypeParameter object based on the value of the
MEDIATYPE parameter or data URI of 4.0 vCards.mediaType - the media type string (e.g. "image/jpeg")protected abstract U _mediaTypeFromTypeParameter(String type)
MediaTypeParameter object based on the value of the TYPE
parameter in 2.1/3.0 vCards.type - the TYPE value (e.g. "JPEG")protected abstract U _mediaTypeFromFileExtension(String extension)
MediaTypeParameter object, given a file extension.extension - the file extension (e.g. "jpg")protected abstract T _newInstance(String uri, U contentType)
uri - the URIcontentType - the content type or null if unknownprotected abstract T _newInstance(byte[] data, U contentType)
data - the datacontentType - the content type or null if unknownprotected U parseContentTypeFromParameters(VCardParameters parameters, VCardVersion version)
parameters - the parametersversion - the vCard versionprotected U parseContentTypeFromValueAndParameters(String value, VCardParameters parameters, VCardVersion version)
value - the property valueparameters - the property parametersversion - the vCard versionprotected T parse(String value, VCardDataType dataType, VCardParameters parameters, VCardVersion version)
value - the property valuedataType - the data typeparameters - the property parametersversion - the vCard versionprotected static String getFileExtension(String url)
url - the URLCopyright © 2012–2023 Michael Angstadt. All rights reserved.