ezvcard.parameter
Class VCardParameters

java.lang.Object
  ezvcard.util.ListMultimap<String,String>
      ezvcard.parameter.VCardParameters

All Implemented Interfaces:

Iterable<Map.Entry<String,List<String>>>

public class VCardParameters
extends ListMultimap<String,String>

Holds the parameters (aka "sub types") of a vCard property.

Author:

Michael Angstadt

Field Summary

static String	ALTID
static String	CALSCALE
static String	CHARSET
static String	ENCODING
static String	GEO
static String	INDEX
static String	LABEL
static String	LANGUAGE
static String	LEVEL
static String	MEDIATYPE
static String	PID
static String	PREF
static String	SORT_AS
static String	TYPE
static String	TZ
static String	VALUE

Constructor Summary

VCardParameters()
Creates a list of parameters.

VCardParameters(VCardParameters orig)
Creates a copy of an existing parameter list.

Method Summary

void	addPid(int localId) Adds a PID parameter value.
void	addPid(int localId, int clientPidMapRef) Adds a PID parameter value.
void	addType(String type) Adds a TYPE parameter.
String	getAltId() Gets the ALTID parameter value.
Calscale	getCalscale() Gets the type of calendar that is used for a date or date-time property value.
String	getCharset() Gets the CHARSET parameter.
Encoding	getEncoding() Gets the ENCODING parameter.
double[]	getGeo() Gets the GEO parameter value.
Integer	getIndex() Gets the sorted position of this property when it is grouped together with other properties of the same type.
String	getLabel() Gets the LABEL parameter.
String	getLanguage() Gets the LANGUAGE parameter.
String	getLevel() Gets the LEVEL parameter.
String	getMediaType() Gets the MEDIATYPE parameter.
List<Integer[]>	getPids() Gets all PID parameter values.
Integer	getPref() Gets the preference value.
List<String>	getSortAs() Gets the SORT-AS parameter value(s).
String	getTimezone() Gets the TZ parameter.
String	getType() Gets the first TYPE parameter.
Set<String>	getTypes() Gets all TYPE parameters.
VCardDataType	getValue() Gets the VALUE parameter.
void	removePids() Removes all PID values.
void	removeType(String type) Removes a TYPE parameter.
void	removeTypes() Removes all TYPE parameters.
void	removeValue() Removes the VALUE parameter.
protected String	sanitizeKey(String key) Modifies a given key before it is used to interact with the internal map.
void	setAltId(String altId) Sets the ALTID parameter value.
void	setCalscale(Calscale value) Sets the type of calendar that is used for a date or date-time property value.
void	setCharset(String charset) Sets the CHARSET parameter.
void	setEncoding(Encoding encoding) Sets the ENCODING parameter.
void	setGeo(double latitude, double longitude) Sets the GEO parameter value.
void	setIndex(Integer index) Sets the sorted position of this property when it is grouped together with other properties of the same type.
void	setLabel(String label) Sets the LABEL parameter.
void	setLanguage(String language) Sets the LANGUAGE parameter.
void	setLevel(String level) Sets the LEVEL parameter.
void	setMediaType(String mediaType) Sets the MEDIATYPE parameter.
void	setPref(Integer pref) Sets the preference value.
void	setSortAs(String... names) Sets the SORT-AS parameter value(s).
void	setTimezone(String tz) Sets the TZ parameter.
void	setType(String type) Sets the TYPE parameter.
void	setValue(VCardDataType value) Sets the VALUE parameter.
List<Warning>	validate(VCardVersion version) Checks this parameters list for data consistency problems or deviations from the spec.

Methods inherited from class ezvcard.util.ListMultimap

clear, containsKey, equals, first, get, getMap, hashCode, isEmpty, iterator, keySet, put, putAll, remove, removeAll, replace, replace, size, toString, values

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ALTID

public static final String ALTID

See Also:

Constant Field Values

CALSCALE

public static final String CALSCALE

See Also:

Constant Field Values

CHARSET

public static final String CHARSET

See Also:

Constant Field Values

ENCODING

public static final String ENCODING

See Also:

Constant Field Values

GEO

public static final String GEO

See Also:

Constant Field Values

INDEX

public static final String INDEX

See Also:

Constant Field Values

LABEL

public static final String LABEL

See Also:

Constant Field Values

LANGUAGE

public static final String LANGUAGE

See Also:

Constant Field Values

LEVEL

public static final String LEVEL

See Also:

Constant Field Values

MEDIATYPE

public static final String MEDIATYPE

See Also:

Constant Field Values

PID

public static final String PID

See Also:

Constant Field Values

PREF

public static final String PREF

See Also:

Constant Field Values

SORT_AS

public static final String SORT_AS

See Also:

Constant Field Values

TYPE

public static final String TYPE

See Also:

Constant Field Values

TZ

public static final String TZ

See Also:

Constant Field Values

VALUE

public static final String VALUE

See Also:

Constant Field Values

Constructor Detail

VCardParameters

public VCardParameters()

Creates a list of parameters.

VCardParameters

public VCardParameters(VCardParameters orig)

Creates a copy of an existing parameter list.

Parameters:

orig - the object to copy

Method Detail

getEncoding

public Encoding getEncoding()

Gets the ENCODING parameter. This is used when the property value is encoded in a form other than plain text.

Supported versions: 2.1, 3.0

Returns:

the encoding or null if not found

setEncoding

public void setEncoding(Encoding encoding)

Sets the ENCODING parameter. This is used when the property value is encoded in a form other than plain text.

Supported versions: 2.1, 3.0

Parameters:

encoding - the encoding or null to remove

getValue

public VCardDataType getValue()

Gets the VALUE parameter. This defines what kind of data type the property has, such as "text" or "URI". Only used in text-based vCards.

Supported versions: 2.1, 3.0, 4.0

Returns:

the value or null if not found

setValue

public void setValue(VCardDataType value)

Sets the VALUE parameter. This defines what kind of data type the property has, such as "text" or "URI". Only used in text-based vCards.

Supported versions: 2.1, 3.0, 4.0

Parameters:

value - the value or null to remove

removeValue

public void removeValue()

Removes the VALUE parameter. This defines what kind of data type the property has, such as "text" or "URI". Only used in text-based vCards.

Supported versions: 2.1, 3.0, 4.0

getCharset

public String getCharset()

Gets the CHARSET parameter.

Supported versions: 2.1

Returns:

the value or null if not found

setCharset

public void setCharset(String charset)

Sets the CHARSET parameter.

Supported versions: 2.1

Parameters:

charset - the value or null to remove

getLanguage

public String getLanguage()

Gets the LANGUAGE parameter.

Supported versions: 2.1, 3.0, 4.0

Returns:

the language (e.g. "en-US") or null if not set

See Also:

RFC 5646

setLanguage

public void setLanguage(String language)

Sets the LANGUAGE parameter.

Supported versions: 2.1, 3.0, 4.0

Parameters:

language - the language (e.g "en-US") or null to remove

See Also:

RFC 5646

getLabel

public String getLabel()

Gets the LABEL parameter.

Supported versions: 4.0

Returns:

the address label or null if not set

setLabel

public void setLabel(String label)

Sets the LABEL parameter.

Supported versions: 4.0

Parameters:

label - the address label or null to remove

getTimezone

public String getTimezone()

Gets the TZ parameter.

Supported versions: 4.0

Returns:

the timezone (e.g. "America/New_York") or null if not set

setTimezone

public void setTimezone(String tz)

Sets the TZ parameter.

Supported versions: 4.0

Parameters:

tz - the timezone (e.g. "America/New_York") or null to remove

getTypes

public Set<String> getTypes()

Gets all TYPE parameters.

Supported versions: 2.1, 3.0, 4.0

Returns:

the values or empty set if not found

addType

public void addType(String type)

Adds a TYPE parameter.

Supported versions: 2.1, 3.0, 4.0

Parameters:

type - the value

getType

public String getType()

Gets the first TYPE parameter.

Supported versions: 2.1, 3.0, 4.0

Returns:

the value or null if not found.

setType

public void setType(String type)

Sets the TYPE parameter.

Supported versions: 2.1, 3.0, 4.0

Parameters:

type - the value or null to remove

removeType

public void removeType(String type)

Removes a TYPE parameter.

Supported versions: 2.1, 3.0, 4.0

Parameters:

type - the value to remove

removeTypes

public void removeTypes()

Removes all TYPE parameters.

Supported versions: 2.1, 3.0, 4.0

getPref

public Integer getPref()

Gets the preference value. The lower the number, the more preferred this property instance is compared with other properties in the same vCard of the same type. If a property doesn't have a preference value, then it is considered the least preferred.

In the vCard below, the address on the second row is the most preferred because it has the lowest PREF value.

 ADR;TYPE=work;PREF=2:
 ADR;TYPE=work;PREF=1:
 ADR;TYPE=home:
 

Preference values must be numeric and must be between 1 and 100.

Supported versions: 4.0

Returns:

the preference value or null if it doesn't exist or null if it couldn't be parsed into a number

Throws:

IllegalStateException - if the parameter value is malformed and cannot be parsed

setPref

public void setPref(Integer pref)

Sets the preference value. The lower the number, the more preferred this property instance is compared with other properties in the same vCard of the same type. If a property doesn't have a preference value, then it is considered the least preferred.

In the vCard below, the address on the second row is the most preferred because it has the lowest PREF value.

 ADR;TYPE=work;PREF=2:
 ADR;TYPE=work;PREF=1:
 ADR;TYPE=home:
 

Preference values must be numeric and must be between 1 and 100.

Supported versions: 4.0

Parameters:

pref - the preference value or null to remove

Throws:

IllegalArgumentException - if the value is not between 1 and 100

getAltId

public String getAltId()

Gets the ALTID parameter value. This is used to specify alternative representations of the same type.

For example, a vCard may contain multiple NOTE properties that each have the same ALTID. This means that each NOTE contains a different representation of the same information. In the example below, the first three NOTEs have the same ALTID. They each contain the same message, but each is written in a different language. The other NOTEs have different (or absent) ALTIDs, which means they are not associated with the top three.

 NOTE;ALTID=1;LANGUAGE=en: Hello world!
 NOTE;ALTID=1;LANGUAGE=fr: Bonjour tout le monde!
 NOTE;ALTID=1;LANGUAGE=es: �Hola, mundo!
 NOTE;ALTID=2;LANGUAGE=de: Meine Lieblingsfarbe ist blau.
 NOTE;ALTID=2;LANGUAGE=en: My favorite color is blue.
 NOTE: This vCard will self-destruct in 5 seconds.
 

Supported versions: 4.0

Returns:

the ALTID or null if it doesn't exist

setAltId

public void setAltId(String altId)

Sets the ALTID parameter value. This is used to specify alternative representations of the same type.

For example, a vCard may contain multiple NOTE properties that each have the same ALTID. This means that each NOTE contains a different representation of the same information. In the example below, the first three NOTEs have the same ALTID. They each contain the same message, but each is written in a different language. The other NOTEs have different (or absent) ALTIDs, which means they are not associated with the top three.

 NOTE;ALTID=1;LANGUAGE=en: Hello world!
 NOTE;ALTID=1;LANGUAGE=fr: Bonjour tout le monde!
 NOTE;ALTID=1;LANGUAGE=es: �Hola, mundo!
 NOTE;ALTID=2;LANGUAGE=de: Meine Lieblingsfarbe ist blau.
 NOTE;ALTID=2;LANGUAGE=en: My favorite color is blue.
 NOTE: This vCard will self-destruct in 5 seconds.
 

Supported versions: 4.0

Parameters:

altId - the ALTID or null to remove

getGeo

public double[] getGeo()

Gets the GEO parameter value. This is used to associate global positioning information with a vCard property. It can be used with the Address property.

Supported versions: 4.0

Returns:

the latitude (index 0) and longitude (index 1) or null if not present or null if the parameter value was in an incorrect format

Throws:

IllegalStateException - if the parameter value is malformed and cannot be parsed

setGeo

public void setGeo(double latitude,
                   double longitude)

Sets the GEO parameter value. This is used to associate global positioning information with a vCard property. It can be used with the Address property.

Supported versions: 4.0

Parameters:

latitude - the latitude

longitude - the longitude

getSortAs

public List<String> getSortAs()

Gets the SORT-AS parameter value(s). This contains typically two string values which the vCard should be sorted by (family and given names). This is useful if the person's last name (defined in the N property) starts with characters that should be ignored during sorting. It can be used with the StructuredName and Organization properties.

Supported versions: 4.0

Returns:

the name(s) (e.g. { "Aboville", "Christine" } if the family name is "d'Aboville" and the given name is "Christine") or empty list of the parameter doesn't exist

setSortAs

public void setSortAs(String... names)

Sets the SORT-AS parameter value(s). This is useful with the N property when the person's last name starts with characters that should be ignored during sorting. It can be used with the StructuredName and Organization properties.

Supported versions: 4.0

Parameters:

names - the names in the order they should be sorted in (e.g. ["Aboville", "Christine"] if the family name is "d'Aboville" and the given name is "Christine") or empty parameter list to remove

getCalscale

public Calscale getCalscale()

Gets the type of calendar that is used for a date or date-time property value.

Supported versions: 4.0

Returns:

the type of calendar or null if not found

setCalscale

public void setCalscale(Calscale value)

Sets the type of calendar that is used for a date or date-time property value.

Supported versions: 4.0

Parameters:

value - the type of calendar or null to remove

getPids

public List<Integer[]> getPids()

Gets all PID parameter values. PIDs can exist on any property where multiple instances are allowed (such as EMAIL or ADR, but not N because only 1 instance of N is allowed).

When used in conjunction with the CLIENTPIDMAP property, it allows an individual property instance to be uniquely identifiable. This feature is made use of when two different versions of the same vCard have to be merged together (called "synchronizing").

Supported versions: 4.0

Returns:

the PID values or empty set if there are none. Index 0 is the local ID and index 1 is the ID used to reference the CLIENTPIDMAP property. Index 0 will never be null, but index 1 may be null.

Throws:

IllegalStateException - if the parameter value is malformed and cannot be parsed

addPid

public void addPid(int localId)

Adds a PID parameter value. PIDs can exist on any property where multiple instances are allowed (such as EMAIL or ADR, but not N because only 1 instance of N is allowed).

When used in conjunction with the CLIENTPIDMAP property, it allows an individual property instance to be uniquely identifiable. This feature is made use of when two different versions of the same vCard have to be merged together (called "synchronizing").

Supported versions: 4.0

Parameters:

localId - the local ID

addPid

public void addPid(int localId,
                   int clientPidMapRef)

Adds a PID parameter value. PIDs can exist on any property where multiple instances are allowed (such as EMAIL or ADR, but not N because only 1 instance of N is allowed).

When used in conjunction with the CLIENTPIDMAP property, it allows an individual property instance to be uniquely identifiable. This feature is made use of when two different versions of the same vCard have to be merged together (called "synchronizing").

Supported versions: 4.0

Parameters:

localId - the local ID

clientPidMapRef - the ID used to reference the property's globally unique identifier in the CLIENTPIDMAP property.

removePids

public void removePids()

Removes all PID values.

Supported versions: 4.0

getMediaType

public String getMediaType()

Gets the MEDIATYPE parameter. This is used in properties that have a URL as a value, such as PHOTO and SOUND. It defines the content type of the referenced resource.

Supported versions: 4.0

Returns:

the media type (e.g. "image/jpeg") or null if it doesn't exist

setMediaType

public void setMediaType(String mediaType)

Sets the MEDIATYPE parameter. This is used in properties that have a URL as a value, such as PHOTO and SOUND. It defines the content type of the referenced resource.

Supported versions: 4.0

Parameters:

mediaType - the media type (e.g. "image/jpeg") or null to remove

getLevel

public String getLevel()

Gets the LEVEL parameter. This is used to define the level of skill or level of interest the person has towards something.

Supported versions: 4.0

Returns:

the level (e.g. "beginner") or null if not found

See Also:

RFC 6715

setLevel

public void setLevel(String level)

Sets the LEVEL parameter. This is used to define the level of skill or level of interest the person has towards something.

Supported versions: 4.0

Parameters:

level - the level (e.g. "beginner") or null to remove

See Also:

RFC 6715

getIndex

public Integer getIndex()

Gets the sorted position of this property when it is grouped together with other properties of the same type. Properties with low index values are put at the beginning of the sorted list and properties with high index values are put at the end of the list.

Supported versions: 4.0

Returns:

the INDEX value or null if it doesn't exist or null if it couldn't be parsed into a number

Throws:

IllegalStateException - if the parameter value is malformed and cannot be parsed

See Also:

RFC 6715

setIndex

public void setIndex(Integer index)

Sets the sorted position of this property when it is grouped together with other properties of the same type. Properties with low index values are put at the beginning of the sorted list and properties with high index values are put at the end of the list.

Supported versions: 4.0

Parameters:

index - the INDEX value (must be greater than 0) or null to remove

Throws:

IllegalArgumentException - if the value is not greater than 0

See Also:

RFC 6715

validate

public List<Warning> validate(VCardVersion version)

Checks this parameters list for data consistency problems or deviations from the spec. These problems will not prevent the vCard from being written to a data stream, but may prevent it from being parsed correctly by the consuming application.

Parameters:

version - the vCard version to validate against

Returns:

a list of warnings or an empty list if no problems were found

sanitizeKey

protected String sanitizeKey(String key)

Description copied from class: ListMultimap

Modifies a given key before it is used to interact with the internal map. This method is meant to be overridden by child classes if necessary.

Overrides:

sanitizeKey in class ListMultimap<String,String>

Parameters:

key - the key

Returns:

the modified key (by default, the key is returned as-is)