ezvcard
Class VCardSubTypes

java.lang.Object
  ezvcard.VCardSubTypes

public class VCardSubTypes
extends Object

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

Author:

Michael Angstadt

Constructor Summary

VCardSubTypes()

VCardSubTypes(VCardSubTypes orig)
Copy constructor.

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 sub type
List<String>	get(String name) Gets the values of a Sub Type
String	getAltId() Gets the ALTID parameter value.
CalscaleParameter	getCalscale() Gets the CALSCALE parameter value.
String	getCharset() Gets the CHARSET sub type.
EncodingParameter	getEncoding() Gets the ENCODING sub type.
String	getFirst(String name) Gets the first value of a Sub Type.
double[]	getGeo() Gets the GEO parameter value.
Integer	getIndex() Gets the INDEX parameter.
String	getLanguage() Gets the LANGUAGE sub type.
String	getLevel() Gets the LEVEL parameter.
String	getMediaType() Gets the MEDIATYPE parameter.
ListMultimap<String,String>	getMultimap() Gets the object used to store the Sub Types.
Set<String>	getNames() Gets the names of all the Sub Types.
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	getType() Gets the first TYPE sub type.
Set<String>	getTypes() Gets all TYPE sub types.
ValueParameter	getValue() Gets the VALUE sub type.
void	put(String name, String value) Adds a value to a Sub Type.
void	remove(String name, String value) Removes a value from a Sub Type.
List<String>	removeAll(String name) Removes a Sub Type.
void	removePids() Removes all PID values.
void	removeType(String type) Removes a TYPE sub type.
List<String>	replace(String name, String value) Adds a value to a Sub Type, replacing all existing values that the Sub Type has.
void	setAltId(String altId) Sets the ALTID parameter value.
void	setCalscale(CalscaleParameter value) Gets the CALSCALE parameter value.
void	setCharset(String charset) Sets the CHARSET sub type
void	setEncoding(EncodingParameter encoding) Sets the ENCODING sub type.
void	setGeo(double latitude, double longitude) Sets the GEO parameter value.
void	setIndex(Integer index) Sets the INDEX parameter.
void	setLanguage(String language) Sets the LANGUAGE sub type.
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	setType(String type) Sets the TYPE sub type.
void	setValue(ValueParameter value) Sets the VALUE sub type.

Methods inherited from class java.lang.Object

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

Constructor Detail

VCardSubTypes

public VCardSubTypes()

VCardSubTypes

public VCardSubTypes(VCardSubTypes orig)

Copy constructor.

Parameters:

orig - the object to copy

Method Detail

put

public void put(String name,
                String value)

Adds a value to a Sub Type.

Parameters:

name - the Sub Type name

value - the value to add

replace

public List<String> replace(String name,
                            String value)

Adds a value to a Sub Type, replacing all existing values that the Sub Type has.

Parameters:

name - the Sub Type name

value - the values to replace all existing values with

Returns:

the values of the Sub Type that were replaced

removeAll

public List<String> removeAll(String name)

Removes a Sub Type.

Parameters:

name - the Sub Type name

Returns:

the values of the Sub Type that were removed

remove

public void remove(String name,
                   String value)

Removes a value from a Sub Type.

Parameters:

name - the Sub Type name

value - the value to remove

get

public List<String> get(String name)

Gets the values of a Sub Type

Parameters:

name - the Sub Type name

Returns:

the values or an empty list if the Sub Type doesn't exist

getFirst

public String getFirst(String name)

Gets the first value of a Sub Type.

Parameters:

name - the Sub Type name

Returns:

the first value or null if the Sub Type doesn't exist

getNames

public Set<String> getNames()

Gets the names of all the Sub Types.

Returns:

the names of all the Sub Types or an empty set if there are no Sub Types

getMultimap

public ListMultimap<String,String> getMultimap()

Gets the object used to store the Sub Types.

Returns:

the object used to store the Sub Types

getEncoding

public EncodingParameter getEncoding()

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

vCard versions: 2.1, 3.0

Returns:

the encoding or null if not found

setEncoding

public void setEncoding(EncodingParameter encoding)

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

vCard versions: 2.1, 3.0

Parameters:

encoding - the encoding or null to remove

getValue

public ValueParameter getValue()

Gets the VALUE sub type. This defines what kind of value the type has, such as "text" or "URI".

vCard versions: 2.1, 3.0, 4.0

Returns:

the value or null if not found

setValue

public void setValue(ValueParameter value)

Sets the VALUE sub type. This defines what kind of value the type has, such as "text" or "URI".

vCard versions: 2.1, 3.0, 4.0

Parameters:

value - the value or null to remove

getCharset

public String getCharset()

Gets the CHARSET sub type.

vCard versions: 2.1

Returns:

the value or null if not found

setCharset

public void setCharset(String charset)

Sets the CHARSET sub type

vCard versions: 2.1

Parameters:

charset - the value or null to remove

getLanguage

public String getLanguage()

Gets the LANGUAGE sub type.

vCard 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 sub type.

vCard versions: 2.1, 3.0, 4.0

Parameters:

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

See Also:

RFC 5646

getTypes

public Set<String> getTypes()

Gets all TYPE sub types.

vCard 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 sub type

vCard versions: 2.1, 3.0, 4.0

Parameters:

type - the value

getType

public String getType()

Gets the first TYPE sub type.

vCard versions: 2.1, 3.0, 4.0

Returns:

the value or null if not found.

setType

public void setType(String type)

Sets the TYPE sub type.

vCard versions: 2.1, 3.0, 4.0

Parameters:

type - the value or null to remove

removeType

public void removeType(String type)

Removes a TYPE sub type.

vCard versions: 2.1, 3.0, 4.0

Parameters:

type - the value to remove

getPref

public Integer getPref()

Gets the preference value. The lower the number, the more preferred this type is compared to other types in the vCard with the same name. If a type 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.

vCard 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

setPref

public void setPref(Integer pref)

Sets the preference value. The lower the number, the more preferred this type is compared to other types in the vCard with the same name. If a type 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.

vCard 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 types 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.
 

vCard 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 types 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.
 

vCard 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 type. It can be used with the ADR type.

vCard 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

setGeo

public void setGeo(double latitude,
                   double longitude)

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

vCard 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 N and ORG types.

vCard 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 N and ORG types.

vCard 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 CalscaleParameter getCalscale()

Gets the CALSCALE parameter value. This defines the type of calendar that is used.

vCard versions: 4.0

Returns:

the type of calendar or null if not found

setCalscale

public void setCalscale(CalscaleParameter value)

Gets the CALSCALE parameter value. This is used with date/time types and defines the type of calendar that is used.

vCard 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").

vCard 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.

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").

vCard 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").

vCard 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.

vCard 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.

vCard 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.

vCard 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.

vCard 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.

vCard versions: 4.0

Parameters:

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

See Also:

RFC 6715

getIndex

public Integer getIndex()

Gets the INDEX parameter. When present, it specifies the order in which a collection of multi-valued property instances should be sorted. Properties with low INDEX values are put at the beginning of the sorted list.

vCard 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

See Also:

RFC 6715

setIndex

public void setIndex(Integer index)

Sets the INDEX parameter. When present, it specifies the order in which a collection of multi-valued property instances should be sorted. Properties with low INDEX values are put at the beginning of the sorted list.

vCard 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