public class VCardParameters extends ListMultimap<String,String>
Modifier and Type | Class and Description |
---|---|
class |
VCardParameters.EnumParameterList<T extends VCardParameter>
A list that converts the raw string values of a parameter to the
appropriate
VCardParameter object that some parameters use. |
class |
VCardParameters.TypeParameterList<T extends VCardParameter>
A list that converts the raw string values of a TYPE parameter to the
appropriate
VCardParameter object that some parameters use. |
class |
VCardParameters.VCardParameterList<T>
A list that converts the raw string values of a parameter to another kind
of value (for example, Integers).
|
Modifier and Type | Field and Description |
---|---|
static String |
ALTID
Used to specify that the property value is an alternative representation
of another property value.
|
static String |
CALSCALE
Defines the type of calendar that is used in a date or date-time property
value (for example, "gregorian").
|
static String |
CHARSET
Defines the character set that the property value is encoded in (for
example, "UTF-8").
|
static String |
ENCODING
This parameter is used when the property value is encoded in a form other
than plain text (for example, "base64").
|
static String |
GEO
Used to associate global positioning information with the property.
|
static String |
INDEX
Defines the sorted position of this property when it is grouped together
with other properties of the same type.
|
static String |
LABEL
Used by the
Address property to define a mailing label for the
address. |
static String |
LANGUAGE
Defines the language that the property value is written in (for example,
"en" for English").
|
static String |
LEVEL
Used to define the skill or interest level the person has towards the
topic defined by the property (for example, "beginner").
|
static String |
MEDIATYPE
|
static String |
PID
Defines a property ID.
|
static String |
PREF
Defines the preference value.
|
static String |
SORT_AS
This parameter defines how the vCard should be sorted amongst other
vCards.
|
static String |
TYPE
The meaning of this parameter varies depending on the property.
|
static String |
TZ
Used to associate timezone information with an
Address property
(for example, "America/New_York" to indicate that an address adheres to
that timezone). |
static String |
VALUE
Defines the data type of the property value (for example, "date" if the
property value is a date without a time component).
|
Constructor and Description |
---|
VCardParameters()
Creates a list of parameters.
|
VCardParameters(Map<String,List<String>> map)
Creates a parameter list that is backed by the given map.
|
VCardParameters(VCardParameters orig)
Creates a copy of an existing parameter list.
|
Modifier and Type | Method and Description |
---|---|
void |
addPid(Pid pid)
Adds a PID (property ID) parameter value.
|
void |
addType(String type)
Adds a TYPE parameter value.
|
boolean |
equals(Object obj)
Determines whether the given object is logically equivalent to this list
of vCard parameters.
|
String |
getAltId()
Gets the ALTID parameter value.
|
Calscale |
getCalscale()
Gets the CALSCALE (calendar scale) parameter value.
|
String |
getCharset()
Gets the CHARSET (character set) parameter value.
|
Encoding |
getEncoding()
Gets the ENCODING parameter value.
|
GeoUri |
getGeo()
Gets the GEO parameter value.
|
Integer |
getIndex()
Gets the INDEX parameter value.
|
String |
getLabel()
Gets the LABEL parameter value.
|
String |
getLanguage()
Gets the LANGUAGE parameter value.
|
String |
getLevel()
Gets the LEVEL parameter value.
|
String |
getMediaType()
Gets the MEDIATYPE parameter value.
|
List<Pid> |
getPids()
Gets the PID (property ID) parameter values.
|
Integer |
getPref()
Gets the PREF (preference) parameter value.
|
List<String> |
getSortAs()
Gets the SORT-AS parameter values.
|
String |
getTimezone()
Gets the TZ (timezone) parameter value.
|
String |
getType()
Gets the first TYPE parameter value.
|
List<String> |
getTypes()
Gets the TYPE parameter values.
|
VCardDataType |
getValue()
Gets the VALUE parameter value.
|
int |
hashCode() |
void |
removePid(Pid pid)
Removes a PID (property ID) parameter value.
|
void |
removePids()
Removes all PID (property ID) parameter values.
|
void |
removeType(String type)
Removes a TYPE parameter value.
|
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 calscale)
Sets the CALSCALE (calendar scale) parameter value.
|
void |
setCharset(String charset)
Sets the CHARSET (character set) parameter value.
|
void |
setEncoding(Encoding encoding)
Sets the ENCODING parameter value.
|
void |
setGeo(GeoUri uri)
Sets the GEO parameter value.
|
void |
setIndex(Integer index)
Sets the INDEX parameter value.
|
void |
setLabel(String label)
Sets the LABEL parameter value.
|
void |
setLanguage(String language)
Sets the LANGUAGE parameter value.
|
void |
setLevel(String level)
Sets the LEVEL parameter value.
|
void |
setMediaType(String mediaType)
Sets the MEDIATYPE parameter value.
|
void |
setPref(Integer pref)
Sets the PREF (preference) parameter value.
|
void |
setSortAs(String... sortStrings)
Sets the SORT-AS parameter values.
|
void |
setTimezone(String timezone)
Sets the TZ (timezone) parameter value.
|
void |
setType(String type)
Sets the TYPE parameter value.
|
void |
setValue(VCardDataType dataType)
Sets the VALUE parameter value.
|
List<ValidationWarning> |
validate(VCardVersion version)
Checks the parameters for data consistency problems or deviations from
the specification.
|
asMap, clear, containsKey, first, get, getMap, isEmpty, iterator, keySet, put, putAll, remove, removeAll, replace, replace, size, toString, values
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
forEach, spliterator
public static final String ALTID
Used to specify that the property value is an alternative representation of another property value.
In the example below, the first three Note
properties have the
same ALTID. This means that they each contain the same value, but in
different forms. In this case, each property value is written in a
different language. The other Note
properties in the example have
different (or absent) ALTID values, 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
public static final String CALSCALE
Defines the type of calendar that is used in a date or date-time property value (for example, "gregorian").
Supported versions: 4.0
public static final String CHARSET
Defines the character set that the property value is encoded in (for example, "UTF-8"). Typically, this is only used in 2.1 vCards when the property value is encoded in quoted-printable encoding.
Supported versions: 2.1
public static final String ENCODING
This parameter is used when the property value is encoded in a form other than plain text (for example, "base64").
Supported versions: 2.1, 3.0
public static final String GEO
Used to associate global positioning information with the property. It
can be used with the Address
property.
Supported versions: 4.0
public static final String INDEX
Defines 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. Properties with high INDEX values are put at the end of the list.
Supported versions: 4.0
public static final String LABEL
Used by the Address
property to define a mailing label for the
address.
Supported versions: 4.0
public static final String LANGUAGE
Defines the language that the property value is written in (for example, "en" for English").
Supported versions: 2.1, 3.0, 4.0
public static final String LEVEL
Used to define the skill or interest level the person has towards the topic defined by the property (for example, "beginner"). Its value varies depending on the property.
Supported versions: 4.0
public static final String MEDIATYPE
Used in properties that have a URL as a value, such as Photo
and
Sound
. It defines the content type of the referenced resource
(for example, "image/png" for a PNG image).
Supported versions: 4.0
public static final String PID
Defines a property ID. PIDs can exist on any property where multiple
instances are allowed (such as Email
or Address
, but not
StructuredName
because only 1 instance of this property is
allowed per vCard).
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
public static final String PREF
Defines the preference value. The lower this number is, the more "preferred" the property instance is compared with other properties 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:;;1600 Amphitheatre Parkway;Mountain View;CA;94043 ADR;TYPE=work;PREF=1:;;One Microsoft Way;Redmond;WA;98052 ADR;TYPE=home:;;123 Maple St;Hometown;KS;12345
Supported versions: 4.0
public static final String SORT_AS
This parameter defines how the vCard should be sorted amongst other
vCards. For example, this can be used if the person's last name (defined
in the StructuredName
property) starts with characters that
should be ignored during sorting (such as "d'Aboville").
This parameter can be used with the StructuredName
and
Organization
properties. 2.1 and 3.0 vCards should use the
SortString
property instead.
This parameter can be multi-valued. The first value is the primary sort keyword (such as the person's last name), the second value is the secondary sort keyword (such as the person's first name), etc.
Supported versions: 4.0
public static final String TYPE
The meaning of this parameter varies depending on the property.
Supported versions: 2.1, 3.0, 4.0
public static final String TZ
Used to associate timezone information with an Address
property
(for example, "America/New_York" to indicate that an address adheres to
that timezone).
Supported versions: 4.0
public static final String VALUE
Defines the data type of the property value (for example, "date" if the property value is a date without a time component). It is used if the property accepts multiple values that have different data types.
Supported versions: 2.1, 3.0, 4.0
public VCardParameters()
public VCardParameters(VCardParameters orig)
orig
- the object to copypublic VCardParameters(Map<String,List<String>> map)
Creates a parameter list that is backed by the given map. Any changes made to the given map will effect the parameter list and vice versa.
Care must be taken to ensure that the given map's keys are all in uppercase.
To avoid problems, it is highly recommended that the given map NOT be
modified by anything other than this VCardParameters
class after
being passed into this constructor.
map
- the mappublic String getAltId()
Gets the ALTID parameter value.
This parameter is used to specify that the property value is an alternative representation of another property value.
In the example below, the first three Note
properties have the
same ALTID. This means that they each contain the same value, but in
different forms. In this case, each property value is written in a
different language. The other Note
properties in the example have
different (or absent) ALTID values, 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
public void setAltId(String altId)
Sets the ALTID parameter value.
This parameter is used to specify that the property value is an alternative representation of another property value.
In the example below, the first three Note
properties have the
same ALTID. This means that they each contain the same value, but in
different forms. In this case, each property value is written in a
different language. The other Note
properties in the example have
different (or absent) ALTID values, 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
altId
- the ALTID or null to removepublic Calscale getCalscale()
Gets the CALSCALE (calendar scale) parameter value.
This parameter defines the type of calendar that is used in a date or date-time property value (for example, "gregorian").
Supported versions: 4.0
public void setCalscale(Calscale calscale)
Sets the CALSCALE (calendar scale) parameter value.
This parameter defines the type of calendar that is used in a date or date-time property value (for example, "gregorian").
Supported versions: 4.0
calscale
- the type of calendar or null to removepublic String getCharset()
Gets the CHARSET (character set) parameter value.
This parameter defines the character set that the property value is encoded in (for example, "UTF-8"). Typically, this is only used in 2.1 vCards when the property value is encoded in quoted-printable encoding.
Supported versions: 2.1
public void setCharset(String charset)
Sets the CHARSET (character set) parameter value.
This parameter defines the character set that the property value is encoded in (for example, "UTF-8"). Typically, this is only used in 2.1 vCards when the property value is encoded in quoted-printable encoding.
Supported versions: 2.1
charset
- the character set or null to removepublic Encoding getEncoding()
Gets the ENCODING parameter value.
This parameter is used when the property value is encoded in a form other than plain text (for example, "base64").
Supported versions: 2.1, 3.0
public void setEncoding(Encoding encoding)
Sets the ENCODING parameter value.
This parameter is used when the property value is encoded in a form other than plain text (for example, "base64").
Supported versions: 2.1, 3.0
encoding
- the encoding or null to removepublic GeoUri getGeo()
Gets the GEO parameter value.
This parameter is used to associate global positioning information with
the property. It can be used with the Address
property.
Supported versions: 4.0
IllegalStateException
- if the parameter value is malformed and
cannot be parsed into a geo URI. If this happens, you may use the
get()
method to retrieve its raw value.public void setGeo(GeoUri uri)
Sets the GEO parameter value.
This parameter is used to associate global positioning information with
the property. It can be used with the Address
property.
Supported versions: 4.0
uri
- the geo URI or null to removepublic Integer getIndex()
Gets the INDEX parameter value.
This parameter defines 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. Properties with high INDEX values are put at the end of the list.
Supported versions: 4.0
IllegalStateException
- if the parameter value cannot be parsed as
an integer. If this happens, you may use the
get()
method to retrieve its raw value.public void setIndex(Integer index)
Sets the INDEX parameter value.
This parameter defines 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. Properties with high INDEX values are put at the end of the list.
Supported versions: 4.0
index
- the index or null to removepublic String getLabel()
Gets the LABEL parameter value.
This parameter is used by the Address
property to define a
mailing label for the address.
Supported versions: 4.0
public void setLabel(String label)
Sets the LABEL parameter value.
This parameter is used by the Address
property to define a
mailing label for the address.
Supported versions: 4.0
label
- the label or null to removepublic String getLanguage()
Gets the LANGUAGE parameter value.
This parameter defines the language that the property value is written in (for example, "en" for English").
Supported versions: 2.1, 3.0, 4.0
public void setLanguage(String language)
Sets the LANGUAGE parameter value.
This parameter defines the language that the property value is written in (for example, "en" for English").
Supported versions: 2.1, 3.0, 4.0
language
- the language or null to removepublic String getLevel()
Gets the LEVEL parameter value.
This parameter is used to define the skill or interest level the person has towards the topic defined by the property (for example, "beginner"). Its value varies depending on the property.
Supported versions: 4.0
public void setLevel(String level)
Sets the LEVEL parameter value.
This parameter is used to define the skill or interest level the person has towards the topic defined by the property (for example, "beginner"). Its value varies depending on the property.
Supported versions: 4.0
level
- the level or null to removepublic String getMediaType()
Gets the MEDIATYPE parameter value.
This parameter 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 (for example, "image/png" for a PNG image).
Supported versions: 4.0
public void setMediaType(String mediaType)
Sets the MEDIATYPE parameter value.
This parameter 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 (for example, "image/png" for a PNG image).
Supported versions: 4.0
mediaType
- the media type or null to removepublic List<Pid> getPids()
Gets the PID (property ID) parameter values.
PIDs can exist on any property where multiple instances are allowed (such
as Email
or Address
, but not StructuredName
because only 1 instance of this property is allowed per vCard).
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").
Changes to the returned list will update the VCardParameters
object, and vice versa.
Supported versions: 4.0
IllegalStateException
- if one or more parameter values cannot be
parsed as PIDs. If this happens, you may use the
get()
method to retrieve the raw values.public void addPid(Pid pid)
Adds a PID (property ID) parameter value.
PIDs can exist on any property where multiple instances are allowed (such
as Email
or Address
, but not StructuredName
because only 1 instance of this property is allowed per vCard).
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
pid
- the PID to addpublic void removePid(Pid pid)
Removes a PID (property ID) parameter value.
PIDs can exist on any property where multiple instances are allowed (such
as Email
or Address
, but not StructuredName
because only 1 instance of this property is allowed per vCard).
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
pid
- the PID to removepublic void removePids()
Removes all PID (property ID) parameter values.
PIDs can exist on any property where multiple instances are allowed (such
as Email
or Address
, but not StructuredName
because only 1 instance of this property is allowed per vCard).
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
public Integer getPref()
Gets the PREF (preference) parameter value.
The lower this number is, the more "preferred" the property instance is compared with other properties 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:;;1600 Amphitheatre Parkway;Mountain View;CA;94043 ADR;TYPE=work;PREF=1:;;One Microsoft Way;Redmond;WA;98052 ADR;TYPE=home:;;123 Maple St;Hometown;KS;12345
Supported versions: 4.0
IllegalStateException
- if the parameter value cannot be parsed as
an integer. If this happens, you may use the
get()
method to retrieve its raw value.public void setPref(Integer pref)
Sets the PREF (preference) parameter value.
The lower this number is, the more "preferred" the property instance is compared with other properties 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:;;1600 Amphitheatre Parkway;Mountain View;CA;94043 ADR;TYPE=work;PREF=1:;;One Microsoft Way;Redmond;WA;98052 ADR;TYPE=home:;;123 Maple St;Hometown;KS;12345
Supported versions: 4.0
pref
- the preference value or null to removepublic List<String> getSortAs()
Gets the SORT-AS parameter values.
This parameter defines how the vCard should be sorted amongst other
vCards. For example, this can be used if the person's last name (defined
in the StructuredName
property) starts with characters that
should be ignored during sorting (such as "d'Aboville").
This parameter can be used with the StructuredName
and
Organization
properties. 2.1 and 3.0 vCards should use the
SortString
property instead.
This parameter can be multi-valued. The first value is the primary sort keyword (such as the person's last name), the second value is the secondary sort keyword (such as the person's first name), etc.
Changes to the returned list will update the VCardParameters
object, and vice versa.
Supported versions: 4.0
public void setSortAs(String... sortStrings)
Sets the SORT-AS parameter values.
This parameter defines how the vCard should be sorted amongst other
vCards. For example, this can be used if the person's last name (defined
in the StructuredName
property) starts with characters that
should be ignored during sorting (such as "d'Aboville").
This parameter can be used with the StructuredName
and
Organization
properties. 2.1 and 3.0 vCards should use the
SortString
property instead.
This parameter can be multi-valued. The first value is the primary sort keyword (such as the person's last name), the second value is the secondary sort keyword (such as the person's first name), etc.
Supported versions: 4.0
sortStrings
- the sort strings or an empty parameter list to removepublic List<String> getTypes()
Gets the TYPE parameter values.
The meaning of this parameter varies depending on the property.
Changes to the returned list will update the VCardParameters
object, and vice versa.
Supported versions: 2.1, 3.0, 4.0
public String getType()
Gets the first TYPE parameter value.
The meaning of this parameter varies depending on the property.
Supported versions: 2.1, 3.0, 4.0
public void addType(String type)
Adds a TYPE parameter value.
The meaning of this parameter varies depending on the property.
Supported versions: 2.1, 3.0, 4.0
type
- the type to addpublic void removeType(String type)
Removes a TYPE parameter value.
The meaning of this parameter varies depending on the property.
Supported versions: 2.1, 3.0, 4.0
type
- the type to removepublic void setType(String type)
Sets the TYPE parameter value.
The meaning of this parameter varies depending on the property.
Supported versions: 2.1, 3.0, 4.0
type
- the type or null to removepublic String getTimezone()
Gets the TZ (timezone) parameter value.
This parameter is used to associate timezone information with an
Address
property (for example, "America/New_York" to indicate
that an address adheres to that timezone).
Supported versions: 4.0
public void setTimezone(String timezone)
Sets the TZ (timezone) parameter value.
This parameter is used to associate timezone information with an
Address
property (for example, "America/New_York" to indicate
that an address adheres to that timezone).
Supported versions: 4.0
timezone
- the timezone or null to removepublic VCardDataType getValue()
Gets the VALUE parameter value.
This parameter defines the data type of the property value (for example, "date" if the property value is a date without a time component). It is used if the property accepts multiple values that have different data types.
Supported versions: 2.1, 3.0, 4.0
public void setValue(VCardDataType dataType)
Sets the VALUE parameter value.
This parameter defines the data type of the property value (for example, "date" if the property value is a date without a time component). It is used if the property accepts multiple values that have different data types.
Supported versions: 2.1, 3.0, 4.0
dataType
- the data type or null to removepublic List<ValidationWarning> validate(VCardVersion version)
Checks the parameters for data consistency problems or deviations from the specification.
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.
*With a few exceptions: One thing this method does is check for illegal characters. There are certain characters that will break the vCard syntax if written (such as a newline character in a parameter name). If one of these characters is present, it WILL prevent the vCard from being written.
version
- the vCard version to validate againstprotected String sanitizeKey(String key)
ListMultimap
sanitizeKey
in class ListMultimap<String,String>
key
- the keypublic int hashCode()
hashCode
in class ListMultimap<String,String>
public boolean equals(Object obj)
Determines whether the given object is logically equivalent to this list of vCard parameters.
vCard parameters are case-insensitive. Also, the order in which they are defined does not matter.
equals
in class ListMultimap<String,String>
obj
- the object to compare toCopyright © 2012–2023 Michael Angstadt. All rights reserved.