ezvcard.types
Class VCardType

java.lang.Object
  ezvcard.types.VCardType

All Implemented Interfaces:

Comparable<VCardType>

Direct Known Subclasses:

AgentType, BinaryType, BirthplaceType, ClientPidMapType, DateOrTimeType, DeathplaceType, GenderType, GeoType, RawType, StructuredNameType, TextListType, TextType, TimestampType, TimezoneType, TypeParameterType

public abstract class VCardType
extends Object
implements Comparable<VCardType>

Represents a vCard key/value pair entry (called a "type" or "property").

Author:

Michael Angstadt

Field Summary

protected String	group The group that this type belongs to or null if it doesn't belong to a group.
protected VCardSubTypes	subTypes The list of attributes that are associated with this type (called "sub types" or "parameters").
protected String	typeName The name of the type.

Constructor Summary

VCardType(String typeName)

Method Summary

int	compareTo(VCardType that) Sorts by PREF parameter ascending.
protected void	doMarshalSubTypes(VCardSubTypes subTypes, VCardVersion version, List<String> warnings, CompatibilityMode compatibilityMode, VCard vcard) Gets the sub types that will be sent over the wire.
protected abstract void	doMarshalText(StringBuilder value, VCardVersion version, List<String> warnings, CompatibilityMode compatibilityMode) Converts this type object to a string for sending over the wire.
protected void	doMarshalXml(XCardElement parent, List<String> warnings, CompatibilityMode compatibilityMode) Marshals this type for inclusion in an xCard (XML document).
protected void	doUnmarshalHtml(HCardElement element, List<String> warnings) Unmarshals the type from an hCard (HTML document).
protected abstract void	doUnmarshalText(String value, VCardVersion version, List<String> warnings, CompatibilityMode compatibilityMode) Unmarshals the type value from off the wire.
protected void	doUnmarshalXml(XCardElement element, List<String> warnings, CompatibilityMode compatibilityMode) Unmarshals the type from an xCard (XML document).
String	getGroup() Gets this type's group.
QName	getQName() Gets the qualified name (XML namespace and local part) for marshalling the type to an XML document (xCard).
VCardSubTypes	getSubTypes() Gets all sub types (a.k.a "parameters") associated with this type.
VCardVersion[]	getSupportedVersions() Gets the vCard versions that support this type.
String	getTypeName() Gets the name of this type.
VCardSubTypes	marshalSubTypes(VCardVersion version, List<String> warnings, CompatibilityMode compatibilityMode, VCard vcard) Gets the Sub Types to send over the wire.
String	marshalText(VCardVersion version, List<String> warnings, CompatibilityMode compatibilityMode) Converts this type object to a string for sending over the wire.
void	marshalXml(Element parent, VCardVersion version, List<String> warnings, CompatibilityMode compatibilityMode) Marshals this type for inclusion in an xCard (XML document).
void	setGroup(String group) Sets this type's group.
void	unmarshalHtml(Element element, List<String> warnings) Unmarshals the type from an hCard (HTML document).
void	unmarshalText(VCardSubTypes subTypes, String value, VCardVersion version, List<String> warnings, CompatibilityMode compatibilityMode) Unmarshals the type value from off the wire.
void	unmarshalXml(VCardSubTypes subTypes, Element element, VCardVersion version, List<String> warnings, CompatibilityMode compatibilityMode) Unmarshals the type from an xCard (XML document).

Methods inherited from class java.lang.Object

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

Field Detail

typeName

protected final String typeName

The name of the type.

group

protected String group

The group that this type belongs to or null if it doesn't belong to a group.

subTypes

protected VCardSubTypes subTypes

The list of attributes that are associated with this type (called "sub types" or "parameters").

Constructor Detail

VCardType

public VCardType(String typeName)

Parameters:

typeName - the type name (e.g. "ADR")

Method Detail

getTypeName

public String getTypeName()

Gets the name of this type.

Returns:

the type name (e.g. "ADR")

getSupportedVersions

public VCardVersion[] getSupportedVersions()

Gets the vCard versions that support this type.

Returns:

the vCard versions that support this type.

marshalText

public final String marshalText(VCardVersion version,
                                List<String> warnings,
                                CompatibilityMode compatibilityMode)

Converts this type object to a string for sending over the wire. It is NOT responsible for folding.

Parameters:

version - the version vCard that is being generated

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the marshalling process

compatibilityMode - allows the programmer to customize the marshalling process depending on the expected consumer of the vCard

Returns:

the string for sending over the wire

Throws:

SkipMeException - if this type should NOT be marshalled into the vCard

EmbeddedVCardException - if the value of this type is an embedded vCard (i.e. the AGENT type)

doMarshalText

protected abstract void doMarshalText(StringBuilder value,
                                      VCardVersion version,
                                      List<String> warnings,
                                      CompatibilityMode compatibilityMode)

Converts this type object to a string for sending over the wire. It is NOT responsible for folding.

Parameters:

value - the buffer to add the marshalled value to

version - the version vCard that is being generated

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the marshalling process

compatibilityMode - allows the programmer to customize the marshalling process depending on the expected consumer of the vCard

Throws:

SkipMeException - if this type should NOT be marshalled into the vCard

EmbeddedVCardException - if the value of this type is an embedded vCard (i.e. the AGENT type)

marshalXml

public final void marshalXml(Element parent,
                             VCardVersion version,
                             List<String> warnings,
                             CompatibilityMode compatibilityMode)

Marshals this type for inclusion in an xCard (XML document).

Parameters:

parent - the XML element that the type's value will be inserted into. For example, this would be the "<fn>" element for the "FN" type.

version - the version vCard that is being generated

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the marshalling process

compatibilityMode - allows the programmer to customize the marshalling process depending on the expected consumer of the vCard

Throws:

SkipMeException - if this type should NOT be marshalled into the vCard

doMarshalXml

protected void doMarshalXml(XCardElement parent,
                            List<String> warnings,
                            CompatibilityMode compatibilityMode)

Marshals this type for inclusion in an xCard (XML document). All child classes SHOULD override this, but are not required to.

Parameters:

parent - the XML element that the type's value will be inserted into. For example, this would be the "<fn>" element for the "FN" type.

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the marshalling process

compatibilityMode - allows the programmer to customize the marshalling process depending on the expected consumer of the vCard

Throws:

SkipMeException - if this type should NOT be marshalled into the vCard

marshalSubTypes

public final VCardSubTypes marshalSubTypes(VCardVersion version,
                                           List<String> warnings,
                                           CompatibilityMode compatibilityMode,
                                           VCard vcard)

Gets the Sub Types to send over the wire.

Parameters:

version - the version vCard that is being generated

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the marshalling process

compatibilityMode - allows the programmer to customize the marshalling process depending on the expected consumer of the vCard

vcard - the vCard that is being marshalled

Returns:

the sub types that will be sent

doMarshalSubTypes

protected void doMarshalSubTypes(VCardSubTypes subTypes,
                                 VCardVersion version,
                                 List<String> warnings,
                                 CompatibilityMode compatibilityMode,
                                 VCard vcard)

Gets the sub types that will be sent over the wire.

If this method is NOT overridden, then the type's sub types will be sent over the wire as-is. In other words, whatever is in the subTypes field will be sent. Child classes can override this method in order to modify the sub types before they are marshalled.

Parameters:

subTypes - the sub types that will be marshalled into the vCard. This object is a copy of the subTypes field, so any modifications done to this object will not effect the state of the field.

version - the version vCard that is being generated

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the marshalling process

compatibilityMode - allows the programmer to customize the marshalling process depending on the expected consumer of the vCard

vcard - the VCard object that is being marshalled

unmarshalText

public final void unmarshalText(VCardSubTypes subTypes,
                                String value,
                                VCardVersion version,
                                List<String> warnings,
                                CompatibilityMode compatibilityMode)

Unmarshals the type value from off the wire.

Parameters:

subTypes - the sub types that were parsed

value - the unfolded value from off the wire. If the wire value is in "quoted-printable" encoding, it will be decoded.

version - the version of the vCard that is being read or null if the VERSION type has not been parsed yet (v3.0 and v4.0 require that the VERSION type be at the top of the vCard, but v2.1 has no such requirement)

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the unmarshalling process

compatibilityMode - allows the programmer to customize the unmarshalling process depending on where the vCard came from

Throws:

SkipMeException - if this type should NOT be added to the VCard object

EmbeddedVCardException - if the value of this type is an embedded vCard (i.e. the AGENT type)

doUnmarshalText

protected abstract void doUnmarshalText(String value,
                                        VCardVersion version,
                                        List<String> warnings,
                                        CompatibilityMode compatibilityMode)

Unmarshals the type value from off the wire.

Parameters:

value - the unfolded value from off the wire. If the wire value is in the "quoted-printable" encoding, it will be decoded.

version - the version of the vCard that is being read or null if the VERSION type has not been parsed yet (v3.0 and v4.0 require that the VERSION type be at the top of the vCard, but v2.1 has no such requirement)

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the unmarshalling process

compatibilityMode - allows you to customize the unmarshalling process depending on where the vCard came from

Throws:

SkipMeException - if this type should NOT be added to the VCard object

EmbeddedVCardException - if the value of this type is an embedded vCard (i.e. the AGENT type)

unmarshalXml

public final void unmarshalXml(VCardSubTypes subTypes,
                               Element element,
                               VCardVersion version,
                               List<String> warnings,
                               CompatibilityMode compatibilityMode)

Unmarshals the type from an xCard (XML document).

Parameters:

subTypes - the sub types that were parsed

element - the XML element that contains the type data. For example, this would be the "<fn>" element for the "FN" type. This object will NOT include the "<parameters>" child element (it is removed after being unmarshalled into a VCardSubTypes object).

version - the version of the xCard

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the unmarshalling process

compatibilityMode - allows the programmer to customize the unmarshalling process depending on where the vCard came from

Throws:

SkipMeException - if this type should NOT be added to the VCard object

UnsupportedOperationException - if the type class does not support xCard parsing

doUnmarshalXml

protected void doUnmarshalXml(XCardElement element,
                              List<String> warnings,
                              CompatibilityMode compatibilityMode)

Unmarshals the type from an xCard (XML document).

Parameters:

element - the XML element that contains the type data. For example, this would be the "<fn>" element for the "FN" type. This object will NOT include the "<parameters>" child element (it is removed after being unmarshalled into a VCardSubTypes object).

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the unmarshalling process

compatibilityMode - allows the programmer to customize the unmarshalling process depending on where the vCard came from

Throws:

SkipMeException - if this type should NOT be added to the VCard object

UnsupportedOperationException - if the type class does not support xCard parsing

unmarshalHtml

public final void unmarshalHtml(Element element,
                                List<String> warnings)

Unmarshals the type from an hCard (HTML document).

Parameters:

element - the HTML element that contains the type data.

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the unmarshalling process

Throws:

SkipMeException - if this type should NOT be added to the VCard object

EmbeddedVCardException - if the value of this type is an embedded vCard (i.e. the AGENT type)

UnsupportedOperationException - if the type class does not support hCard parsing

doUnmarshalHtml

protected void doUnmarshalHtml(HCardElement element,
                               List<String> warnings)

Unmarshals the type from an hCard (HTML document).

Parameters:

element - the HTML element that contains the type data.

warnings - allows the programmer to alert the user to any note-worthy (but non-critical) issues that occurred during the unmarshalling process

Throws:

SkipMeException - if this type should NOT be added to the VCard object

EmbeddedVCardException - if the value of this type is an embedded vCard (i.e. the AGENT type)

getQName

public QName getQName()

Gets the qualified name (XML namespace and local part) for marshalling the type to an XML document (xCard).

Extended type classes should override this method. By default, this method returns null, which instructs the marshallers to assign the following qualified name to the type:

Namespace: xCard namespace
Local part: a lower-cased version of the type name

Returns:

the XML qualified name or null to use the default qualified name

getSubTypes

public VCardSubTypes getSubTypes()

Gets all sub types (a.k.a "parameters") associated with this type. This method can be used to retrieve any extended, standard, or non-standard sub type.

Ideally, this method should NOT be used to retrieve the values of standard sub types because the type class should contain getter/setter methods for each standard sub type. For example, instead of calling NoteType.getSubTypes().getLanguage() to retrieve the "LANGUAGE" sub type of a NOTE, the NoteType.getLanguage() method should be called instead.

Returns:

the type's sub types

getGroup

public String getGroup()

Gets this type's group.

Returns:

the group or null if it does not belong to a group

setGroup

public void setGroup(String group)

Sets this type's group.

Parameters:

group - the group or null to remove the type's group

compareTo

public int compareTo(VCardType that)

Sorts by PREF parameter ascending. Types that do not have a PREF parameter are pushed to the end of the list.

Specified by:

compareTo in interface Comparable<VCardType>