• Home
• com.googlecode.ez-vcard
• ez-vcard
• 0.12.1
• source code
• VCard.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

ezvcard.VCard Maven / Gradle / Ivy

package ezvcard;

import java.io.IOException;
import java.io.OutputStream;
import java.io.Writer;
import java.nio.file.Path;
import java.time.Instant;
import java.time.LocalDate;
import java.time.temporal.Temporal;
import java.util.AbstractList;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Set;

import javax.xml.transform.TransformerException;

import ezvcard.io.html.HCardPage;
import ezvcard.io.json.JCardWriter;
import ezvcard.io.text.VCardWriter;
import ezvcard.io.xml.XCardWriter;
import ezvcard.parameter.EmailType;
import ezvcard.parameter.TelephoneType;
import ezvcard.parameter.VCardParameters;
import ezvcard.property.Address;
import ezvcard.property.Agent;
import ezvcard.property.Anniversary;
import ezvcard.property.Birthday;
import ezvcard.property.Birthplace;
import ezvcard.property.CalendarRequestUri;
import ezvcard.property.CalendarUri;
import ezvcard.property.Categories;
import ezvcard.property.Classification;
import ezvcard.property.ClientPidMap;
import ezvcard.property.Deathdate;
import ezvcard.property.Deathplace;
import ezvcard.property.Email;
import ezvcard.property.Expertise;
import ezvcard.property.FormattedName;
import ezvcard.property.FreeBusyUrl;
import ezvcard.property.Gender;
import ezvcard.property.Geo;
import ezvcard.property.HasAltId;
import ezvcard.property.Hobby;
import ezvcard.property.Impp;
import ezvcard.property.Interest;
import ezvcard.property.Key;
import ezvcard.property.Kind;
import ezvcard.property.Label;
import ezvcard.property.Language;
import ezvcard.property.Logo;
import ezvcard.property.Mailer;
import ezvcard.property.Member;
import ezvcard.property.Nickname;
import ezvcard.property.Note;
import ezvcard.property.OrgDirectory;
import ezvcard.property.Organization;
import ezvcard.property.Photo;
import ezvcard.property.ProductId;
import ezvcard.property.Profile;
import ezvcard.property.RawProperty;
import ezvcard.property.Related;
import ezvcard.property.Revision;
import ezvcard.property.Role;
import ezvcard.property.SortString;
import ezvcard.property.Sound;
import ezvcard.property.Source;
import ezvcard.property.SourceDisplayText;
import ezvcard.property.StructuredName;
import ezvcard.property.Telephone;
import ezvcard.property.Timezone;
import ezvcard.property.Title;
import ezvcard.property.Uid;
import ezvcard.property.Url;
import ezvcard.property.VCardProperty;
import ezvcard.property.Xml;
import ezvcard.util.ListMultimap;
import ezvcard.util.StringUtils;

/*
 Copyright (c) 2012-2023, Michael Angstadt
 All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met: 

 1. Redistributions of source code must retain the above copyright notice, this
 list of conditions and the following disclaimer. 
 2. Redistributions in binary form must reproduce the above copyright notice,
 this list of conditions and the following disclaimer in the documentation
 and/or other materials provided with the distribution. 

 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 The views and conclusions contained in the software and documentation are those
 of the authors and should not be interpreted as representing official policies, 
 either expressed or implied, of the FreeBSD Project.
 */

/**
 * Represents a vCard.
 * @author Michael Angstadt
 */
public class VCard implements Iterable {
	private VCardVersion version;
	private final ListMultimap, VCardProperty> properties = new ListMultimap<>();

	/**
	 * Creates a new vCard set to version 3.0.
	 */
	public VCard() {
		this(VCardVersion.V3_0);
	}

	/**
	 * Creates a new vCard.
	 * @param version the version to assign to the vCard
	 */
	public VCard(VCardVersion version) {
		this.version = version;
	}

	/**
	 * Creates a deep copy of the given vCard.
	 * @param original the vCard to copy
	 */
	public VCard(VCard original) {
		version = original.version;
		for (VCardProperty property : original.getProperties()) {
			addProperty(property.copy());
		}
	}

	/**
	 * 

	 * Marshals this vCard to its text representation.
	 * 
	 * 

	 * The vCard will be marshalled to whatever vCard version is assigned to
	 * this object (see {@link #setVersion(VCardVersion)}). If no version is
	 * set, then it will be marshalled to 3.0.
	 * 
	 * 

	 * Use the {@link VCardWriter} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @return the vCard string
	 * @see VCardWriter
	 * @see vCard 2.1
	 * @see RFC 2426 (3.0)
	 * @see RFC 6350 (4.0)
	 */
	public String write() {
		return Ezvcard.write(this).go();
	}

	/**
	 * 

	 * Marshals this vCard to its text representation.
	 * 
	 * 

	 * The vCard will be marshalled to whatever vCard version is assigned to
	 * this object (see {@link #setVersion(VCardVersion)}). If no version is
	 * set, then it will be marshalled to 3.0.
	 * 
	 * 

	 * Use the {@link VCardWriter} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @param file the file to write the vCard to
	 * @throws IOException if there's a problem writing to the file
	 * @see VCardWriter
	 * @see vCard 2.1
	 * @see RFC 2426 (3.0)
	 * @see RFC 6350 (4.0)
	 */
	public void write(Path file) throws IOException {
		Ezvcard.write(this).go(file);
	}

	/**
	 * 

	 * Marshals this vCard to its text representation.
	 * 
	 * 

	 * The vCard will be marshalled to whatever vCard version is assigned to
	 * this object (see {@link #setVersion(VCardVersion)}). If no version is
	 * set, then it will be marshalled to 3.0.
	 * 
	 * 

	 * Use the {@link VCardWriter} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @param out the output stream to write the vCard to
	 * @see VCardWriter
	 * @throws IOException if there's a problem writing to the output stream
	 * @see vCard 2.1
	 * @see RFC 2426 (3.0)
	 * @see RFC 6350 (4.0)
	 */
	public void write(OutputStream out) throws IOException {
		Ezvcard.write(this).go(out);
	}

	/**
	 * 

	 * Marshals this vCard to its text representation.
	 * 
	 * 

	 * The vCard will be marshalled to whatever vCard version is assigned to
	 * this object (see {@link #setVersion(VCardVersion)}). If no version is
	 * set, then it will be marshalled to 3.0.
	 * 
	 * 

	 * Use the {@link VCardWriter} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @param writer the writer to write the vCard to
	 * @throws IOException if there's a problem writing to the writer
	 * @see VCardWriter
	 * @see vCard 2.1
	 * @see RFC 2426 (3.0)
	 * @see RFC 6350 (4.0)
	 */
	public void write(Writer writer) throws IOException {
		Ezvcard.write(this).go(writer);
	}

	/**
	 * 

	 * Marshals this vCard to its XML representation (xCard).
	 * 
	 * 

	 * Use the {@link XCardWriter} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @return the vCard XML document
	 * @see XCardWriter
	 * @see RFC 6351
	 */
	public String writeXml() {
		return Ezvcard.writeXml(this).indent(2).go();
	}

	/**
	 * 

	 * Marshals this vCard to its XML representation (xCard).
	 * 
	 * 

	 * Use the {@link XCardWriter} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @param file the file to write to
	 * @throws IOException if there's a problem writing to the file
	 * @throws TransformerException if there's a problem writing the vCard
	 * @see XCardWriter
	 * @see RFC 6351
	 */
	public void writeXml(Path file) throws IOException, TransformerException {
		Ezvcard.writeXml(this).indent(2).go(file);
	}

	/**
	 * 

	 * Marshals this vCard to its XML representation (xCard).
	 * 
	 * 

	 * Use the {@link XCardWriter} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @param out the output stream to write the vCard to
	 * @throws TransformerException if there's a problem writing to the output
	 * stream
	 * @see XCardWriter
	 * @see RFC 6351
	 */
	public void writeXml(OutputStream out) throws TransformerException {
		Ezvcard.writeXml(this).indent(2).go(out);
	}

	/**
	 * 

	 * Marshals this vCard to its XML representation (xCard).
	 * 
	 * 

	 * Use the {@link XCardWriter} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @param writer the writer to write the vCard to
	 * @throws TransformerException if there's a problem writing to the writer
	 * @see XCardWriter
	 * @see RFC 6351
	 */
	public void writeXml(Writer writer) throws TransformerException {
		Ezvcard.writeXml(this).indent(2).go(writer);
	}

	/**
	 * 

	 * Marshals this vCard to a basic HTML page (hCard).
	 * 
	 * 

	 * Use the {@link HCardPage} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @return the HTML page
	 * @see HCardPage
	 * @see hCard 1.0
	 */
	public String writeHtml() {
		return Ezvcard.writeHtml(this).go();
	}

	/**
	 * 

	 * Marshals this vCard to a basic HTML page (hCard).
	 * 
	 * 

	 * Use the {@link HCardPage} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @param file the file to write to
	 * @throws IOException if there's a problem writing to the file
	 * @see HCardPage
	 * @see hCard 1.0
	 */
	public void writeHtml(Path file) throws IOException {
		Ezvcard.writeHtml(this).go(file);
	}

	/**
	 * 

	 * Marshals this vCard to a basic HTML page (hCard).
	 * 
	 * 

	 * Use the {@link HCardPage} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @param out the output stream to write to
	 * @throws IOException if there's a problem writing to the output stream
	 * @see HCardPage
	 * @see hCard 1.0
	 */
	public void writeHtml(OutputStream out) throws IOException {
		Ezvcard.writeHtml(this).go(out);
	}

	/**
	 * 

	 * Marshals this vCard to a basic HTML page (hCard).
	 * 
	 * 

	 * Use the {@link HCardPage} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @param writer the writer to write to
	 * @throws IOException if there's a problem writing to the writer
	 * @see HCardPage
	 * @see hCard 1.0
	 */
	public void writeHtml(Writer writer) throws IOException {
		Ezvcard.writeHtml(this).go(writer);
	}

	/**
	 * 

	 * Marshals this vCard to its JSON representation (jCard).
	 * 
	 * 

	 * Use the {@link JCardWriter} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @return the JSON string
	 * @see JCardWriter
	 * @see RFC 7095
	 */
	public String writeJson() {
		return Ezvcard.writeJson(this).go();
	}

	/**
	 * 

	 * Marshals this vCard to its JSON representation (jCard).
	 * 
	 * 

	 * Use the {@link JCardWriter} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @param file the file to write the vCard to
	 * @throws IOException if there's a problem writing to the file
	 * @see JCardWriter
	 * @see RFC 7095
	 */
	public void writeJson(Path file) throws IOException {
		Ezvcard.writeJson(this).go(file);
	}

	/**
	 * 

	 * Marshals this vCard to its JSON representation (jCard).
	 * 
	 * 

	 * Use the {@link JCardWriter} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @param out the output stream to write the vCard to
	 * @see JCardWriter
	 * @throws IOException if there's a problem writing to the output stream
	 * @see RFC 7095
	 */
	public void writeJson(OutputStream out) throws IOException {
		Ezvcard.writeJson(this).go(out);
	}

	/**
	 * 

	 * Marshals this vCard to its JSON representation (jCard).
	 * 
	 * 

	 * Use the {@link JCardWriter} class for more control over the marshalling
	 * process and to write multiple vCards to the same stream.
	 * 
	 * @param writer the writer to write the vCard to
	 * @throws IOException if there's a problem writing to the writer
	 * @see JCardWriter
	 * @see RFC 7095
	 */
	public void writeJson(Writer writer) throws IOException {
		Ezvcard.writeJson(this).go(writer);
	}

	/**
	 * Gets the version attached to this vCard.
	 * @return the vCard version
	 */
	public VCardVersion getVersion() {
		return version;
	}

	/**
	 * 

	 * Sets the version of this vCard.
	 * 
	 * 

	 * When marshalling a vCard with the {@link VCardWriter} class, use the
	 * {@link VCardWriter#setTargetVersion setTargetVersion} method to define
	 * what version the vCard should be marshalled as. {@link VCardWriter}
	 * does not look at the version that is set on the VCard object.
	 * 
	 * @param version the vCard version
	 */
	public void setVersion(VCardVersion version) {
		this.version = version;
	}

	/**
	 * 

	 * Gets the type of entity this vCard represents.
	 * 
	 * 

	 * Property name: {@code KIND}

	 * Supported versions: {@code 4.0}
	 * 
	 * @return the kind property or null if not set
	 * @see RFC 6350
	 * p.25
	 */
	public Kind getKind() {
		return getProperty(Kind.class);
	}

	/**
	 * 

	 * Sets the type of entity this vCard represents.
	 * 
	 * 

	 * Property name: {@code KIND}

	 * Supported versions: {@code 4.0}
	 * 
	 * @param kind the kind property or null to remove
	 * @see RFC 6350
	 * p.25
	 */
	public void setKind(Kind kind) {
		setProperty(Kind.class, kind);
	}

	/**
	 * 

	 * Gets the gender of the person.
	 * 
	 * 

	 * Property name: {@code GENDER}

	 * Supported versions: {@code 4.0}
	 * 
	 * @return the gender property or null if not set
	 * @see RFC 6350
	 * p.32
	 */
	public Gender getGender() {
		return getProperty(Gender.class);
	}

	/**
	 * 

	 * Sets the gender of the person.
	 * 
	 * 

	 * Property name: {@code GENDER}

	 * Supported versions: {@code 4.0}
	 * 
	 * @param gender the gender property or null to remove
	 * @see RFC 6350
	 * p.32
	 */
	public void setGender(Gender gender) {
		setProperty(Gender.class, gender);
	}

	/**
	 * 

	 * Gets the members of the group that this vCard represents.
	 * 
	 * 

	 * Note: If a vCard has any {@link Member} properties, then it must also
	 * have a {@link Kind} property whose value is set to "group".
	 * 
	 * 

	 * Property name: {@code MEMBER}

	 * Supported versions: {@code 4.0}
	 * 
	 * @return the members properties (any changes made this list will affect
	 * the {@link VCard} object and vice versa)
	 * @see RFC 6350
	 * p.41
	 */
	public List getMembers() {
		return getProperties(Member.class);
	}

	/**
	 * 

	 * Adds a member to the group that this vCard represents.
	 * 
	 * 

	 * Note: If a vCard has any {@link Member} properties, then it must also
	 * have a {@link Kind} property whose value is set to "group".
	 * 
	 * 

	 * Property name: {@code MEMBER}

	 * Supported versions: {@code 4.0}
	 * 
	 * @param member the member property to add
	 * @see RFC 6350
	 * p.41
	 */
	public void addMember(Member member) {
		addProperty(member);
	}

	/**
	 * 

	 * Adds a member to the group that this vCard represents.
	 * 
	 * 

	 * Note: If a vCard has any {@link Member} properties, then it must also
	 * have a {@link Kind} property whose value is set to "group".
	 * 
	 * 

	 * Property name: {@code MEMBER}

	 * Supported versions: {@code 4.0}
	 * 
	 * @param altRepresentations the alternative representations of the same
	 * value. These properties contain the same information, but in different
	 * forms (such as different languages). See {@link VCardParameters#getAltId
	 * this description of the ALTID parameter} for more information. Note that
	 * this method automatically assigns an appropriate ALTID parameter to each
	 * property.
	 * @see RFC 6350
	 * p.41
	 */
	public void addMemberAlt(Member... altRepresentations) {
		addPropertyAlt(Member.class, altRepresentations);
	}

	/**
	 * 

	 * Gets the profile property. This property simply identifies the vCard as a
	 * vCard.
	 * 
	 * 

	 * Property name: {@code PROFILE}

	 * Supported versions: {@code 3.0}
	 * 
	 * @return the profile property or null if not set
	 * @see RFC 2426 p.5
	 */
	public Profile getProfile() {
		return getProperty(Profile.class);
	}

	/**
	 * 

	 * Sets the profile property. This property simply identifies the vCard as a
	 * vCard.
	 * 
	 * 

	 * Property name: {@code PROFILE}

	 * Supported versions: {@code 3.0}
	 * 
	 * @see RFC 2426 p.5
	 * @param profile the profile property or null to remove
	 */
	public void setProfile(Profile profile) {
		setProperty(Profile.class, profile);
	}

	/**
	 * 

	 * Gets the classification of the vCard, which describes the sensitivity of
	 * the information in the vCard.
	 * 
	 * 

	 * Property name: {@code CLASS}

	 * Supported versions: {@code 3.0}
	 * 
	 * @return the classification property or null if not set
	 * @see RFC 2426
	 * p.26
	 */
	public Classification getClassification() {
		return getProperty(Classification.class);
	}

	/**
	 * 

	 * Sets the classification of the vCard, which describes the sensitivity of
	 * the information in the vCard.
	 * 
	 * 

	 * Property name: {@code CLASS}

	 * Supported versions: {@code 3.0}
	 * 
	 * @param classification the classification property or null to remove
	 * @see RFC 2426
	 * p.26
	 */
	public void setClassification(Classification classification) {
		setProperty(Classification.class, classification);
	}

	/**
	 * 

	 * Sets the classification of the vCard, which describes the sensitivity of
	 * the information in the vCard.
	 * 
	 * 

	 * Supported versions: {@code 3.0}

	 * Property name: {@code CLASS}
	 * 
	 * @param classification the classification (e.g. "PUBLIC", "PRIVATE",
	 * "CONFIDENTIAL") or null to remove
	 * @return the property object that was created
	 * @see RFC 2426
	 * p.26
	 */
	public Classification setClassification(String classification) {
		Classification type = (classification == null) ? null : new Classification(classification);
		setClassification(type);
		return type;
	}

	/**
	 * 

	 * Gets the URIs that can be used to retrieve the most up-to-date version of
	 * the person's vCard.
	 * 
	 * 

	 * Property name: {@code SOURCE} Supported versions:
	 * {@code 3.0, 4.0}
	 * 
	 * @return the source properties (any changes made this list will affect the
	 * {@link VCard} object and vice versa)
	 * @see RFC 6350
	 * p.24
	 * @see RFC 2426 p.5
	 */
	public List getSources() {
		return getProperties(Source.class);
	}

	/**
	 * 

	 * Adds a URI that can be used to retrieve the most up-to-date version of
	 * the person's vCard.
	 * 
	 * 

	 * Property name: {@code SOURCE} Supported versions:
	 * {@code 3.0, 4.0}
	 * 
	 * @param source the source property
	 * @see RFC 6350
	 * p.24
	 * @see RFC 2426 p.5
	 */
	public void addSource(Source source) {
		addProperty(source);
	}

	/**
	 * 

	 * Adds a URI that can be used to retrieve the most up-to-date version of
	 * the person's vCard.
	 * 
	 * 

	 * Property name: {@code SOURCE}

	 * Supported versions: {@code 3.0, 4.0}
	 * 
	 * @param source the source URI (e.g. "http://example.com/vcard.vcf")
	 * @return the property object that was created
	 * @see RFC 6350
	 * p.24
	 * @see RFC 2426 p.5
	 */
	public Source addSource(String source) {
		Source type = new Source(source);
		addSource(type);
		return type;
	}

	/**
	 * 

	 * Adds a URI that can be used to retrieve the most up-to-date version of
	 * the person's vCard.
	 * 
	 * 

	 * Property name: {@code SOURCE}

	 * Supported versions: {@code 4.0*}

	 * * Only 4.0 supports alternative representations
	 * 
	 * @param altRepresentations the alternative representations of the same
	 * value. These properties contain the same information, but in different
	 * forms (such as different languages). See {@link VCardParameters#getAltId
	 * this description of the ALTID parameter} for more information. Note that
	 * this method automatically assigns an appropriate ALTID parameter to each
	 * property.
	 * @see RFC 6350
	 * p.24
	 */
	public void addSourceAlt(Source... altRepresentations) {
		addPropertyAlt(Source.class, altRepresentations);
	}

	/**
	 * 

	 * Gets a textual representation of the {@link Source} property.
	 * 
	 * 

	 * Property name: {@code NAME}

	 * Supported versions: {@code 3.0}
	 * 
	 * @return the property or null if not set
	 * @see RFC 2426 p.5
	 */
	public SourceDisplayText getSourceDisplayText() {
		return getProperty(SourceDisplayText.class);
	}

	/**
	 * 

	 * Sets a textual representation of the {@link Source} property.
	 * 
	 * 

	 * Property name: {@code NAME}

	 * Supported versions: {@code 3.0}
	 * 
	 * @param sourceDisplayText the property null to remove
	 * @see RFC 2426 p.5
	 */
	public void setSourceDisplayText(SourceDisplayText sourceDisplayText) {
		setProperty(SourceDisplayText.class, sourceDisplayText);
	}

	/**
	 * 

	 * Sets a textual representation of the {@link Source} property.
	 * 
	 * 

	 * Property name: {@code NAME}

	 * Supported versions: {@code 3.0}
	 * 
	 * @param sourceDisplayText a textual representation of the vCard source or
	 * null to remove
	 * @return the property object that was created
	 * @see RFC 2426 p.5
	 */
	public SourceDisplayText setSourceDisplayText(String sourceDisplayText) {
		SourceDisplayText type = (sourceDisplayText == null) ? null : new SourceDisplayText(sourceDisplayText);
		setSourceDisplayText(type);
		return type;
	}

	/**
	 * 

	 * Gets all instances of the {@link FormattedName} property.
	 * 
	 * 

	 * Version 4.0 vCards may have multiple instances if alternative
	 * representations are defined (see
	 * {@link #addFormattedNameAlt(FormattedName...) addFormattedNameAlt}) or if
	 * properties with different TYPE parameters are defined.
	 * 
	 * 

	 * Property name: {@code FN}

	 * Supported versions: {@code 4.0*}

	 * * Only 4.0 supports multiple instances
	 * 
	 * @return the formatted name properties (any changes made this list will
	 * affect the {@link VCard} object and vice versa)
	 * @see RFC 6350
	 * p.28
	 * @see RFC 2426 p.8
	 * @see vCard 2.1 p.9
	 */
	public List getFormattedNames() {
		return getProperties(FormattedName.class);
	}

	/**
	 * 

	 * Gets the person's full name.
	 * 
	 * 

	 * Property name: {@code FN}

	 * Supported versions: {@code 2.1, 3.0, 4.0}
	 * 
	 * @return the first formatted name property or null if not set
	 * @see RFC 6350
	 * p.28
	 * @see RFC 2426 p.8
	 * @see vCard 2.1 p.9
	 */
	public FormattedName getFormattedName() {
		return getProperty(FormattedName.class);
	}

	/**
	 * 

	 * Sets the person's full name.
	 * 
	 * 

	 * Property name: {@code FN}

	 * Supported versions: {@code 4.0*}

	 * * Only 4.0 supports alternative representations
	 * 
	 * @param altRepresentations the alternative representations of the same
	 * value. These properties contain the same information, but in different
	 * forms (such as different languages). See {@link VCardParameters#getAltId
	 * this description of the ALTID parameter} for more information. Note that
	 * this method automatically assigns an appropriate ALTID parameter to each
	 * property.
	 * @see RFC 6350
	 * p.28
	 * @see RFC 2426 p.8
	 * @see vCard 2.1 p.9
	 */
	public void setFormattedNameAlt(FormattedName... altRepresentations) {
		setPropertyAlt(FormattedName.class, altRepresentations);
	}

	/**
	 * 

	 * Adds a version of the person's full name.
	 * 
	 * 

	 * Property name: {@code FN}

	 * Supported versions: {@code 4.0*}

	 * * Only 4.0 supports alternative representations
	 * 
	 * @param altRepresentations the alternative representations of the same
	 * value. These properties contain the same information, but in different
	 * forms (such as different languages). See {@link VCardParameters#getAltId
	 * this description of the ALTID parameter} for more information. Note that
	 * this method automatically assigns an appropriate ALTID parameter to each
	 * property.
	 * @see RFC 6350
	 * p.28
	 * @see RFC 2426 p.8
	 * @see vCard 2.1 p.9
	 */
	public void addFormattedNameAlt(FormattedName... altRepresentations) {
		addPropertyAlt(FormattedName.class, altRepresentations);
	}

	/**
	 * 

	 * Sets the person's full name.
	 * 
	 * 

	 * Property name: {@code FN}

	 * Supported versions: {@code 2.1, 3.0, 4.0}
	 * 
	 * @param formattedName the formatted name property or null to remove
	 * @see RFC 6350
	 * p.28
	 * @see RFC 2426 p.8
	 * @see vCard 2.1 p.9
	 */
	public void setFormattedName(FormattedName formattedName) {
		setProperty(FormattedName.class, formattedName);
	}

	/**
	 * 

	 * Adds a version of the person's full name.
	 * 
	 * 

	 * Property name: {@code FN}

	 * Supported versions: {@code 4.0*}

	 * * Only 4.0 supports multiple instances
	 * 
	 * @param formattedName the formatted name property to add
	 * @see RFC 6350
	 * p.28
	 * @see RFC 2426 p.8
	 * @see vCard 2.1 p.9
	 */
	public void addFormattedName(FormattedName formattedName) {
		addProperty(formattedName);
	}

	/**
	 * 

	 * Sets the person's full name.
	 * 
	 * 

	 * Property name: {@code FN}

	 * Supported versions: {@code 2.1, 3.0, 4.0}
	 * 
	 * @param formattedName the formatted name (e.g. "John Doe") or null to
	 * remove
	 * @return the property object that was created
	 * @see RFC 6350
	 * p.28
	 * @see RFC 2426 p.8
	 * @see vCard 2.1 p.9
	 */
	public FormattedName setFormattedName(String formattedName) {
		FormattedName type = (formattedName == null) ? null : new FormattedName(formattedName);
		setFormattedName(type);
		return type;
	}

	/**
	 * 

	 * Gets all structured name properties.
	 * 
	 * 

	 * Version 4.0 vCards may have multiple instances if alternative
	 * representations are defined (see
	 * {@link #setStructuredNameAlt(StructuredName...) setStructuredNameAlt}) or
	 * if properties with different TYPE parameters are defined.
	 * 
	 * 

	 * Property name: {@code N}

	 * Supported versions: {@code 4.0*}

	 * * Only 4.0 supports alternative representations
	 * 
	 * @return the structured name properties (any changes made this list will
	 * affect the {@link VCard} object and vice versa)
	 * @see RFC 6350
	 * p.29
	 * @see RFC 2426 p.9
	 * @see vCard 2.1 p.9
	 */
	public List getStructuredNames() {
		return getProperties(StructuredName.class);
	}

	/**
	 * 

	 * Gets the individual components of the person's name.
	 * 
	 * 

	 * Property name: {@code N}

	 * Supported versions: {@code 2.1, 3.0, 4.0}
	 * 
	 * @return the first structured name property or null if not set
	 * @see RFC 6350
	 * p.29
	 * @see RFC 2426 p.9
	 * @see vCard 2.1 p.9
	 */
	public StructuredName getStructuredName() {
		return getProperty(StructuredName.class);
	}

	/**
	 * 

	 * Sets the individual components of the person's name.
	 * 
	 * 

	 * Property name: {@code N}

	 * Supported versions: {@code 4.0*}

	 * * Only 4.0 supports alternative representations
	 * 
	 * @param altRepresentations the alternative representations of the same
	 * value. These properties contain the same information, but in different
	 * forms (such as different languages). See {@link VCardParameters#getAltId
	 * this description of the ALTID parameter} for more information. Note that
	 * this method automatically assigns an appropriate ALTID parameter to each
	 * property.
	 * @see RFC 6350
	 * p.29
	 * @see RFC 2426 p.9
	 * @see vCard 2.1 p.9
	 */
	public void setStructuredNameAlt(StructuredName... altRepresentations) {
		setPropertyAlt(StructuredName.class, altRepresentations);
	}

	/**
	 * Sets the individual components of the person's name.
	 * 

	 * Property name: {@code N}

	 * Supported versions: {@code 2.1, 3.0, 4.0}
	 * 
	 * @param structuredName the structured name property or null to remove
	 */
	public void setStructuredName(StructuredName structuredName) {
		setProperty(StructuredName.class, structuredName);
	}

	/**
	 * 

	 * Gets all instances of the {@link Nickname} property.
	 * 
	 * 

	 * Version 4.0 vCards may have multiple instances if alternative
	 * representations are defined (see {@link #setNicknameAlt(Nickname...)
	 * setNicknameAlt}) or if properties with different TYPE parameters are
	 * defined.
	 * 
	 * 

	 * Property name: {@code NICKNAME}

	 * Supported versions: {@code 3.0, 4.0}
	 * 
	 * @return the nickname properties (any changes made this list will affect
	 * the {@link VCard} object and vice versa)
	 * @see RFC 6350
	 * p.29
	 * @see RFC 2426 p.9
	 */
	public List getNicknames() {
		return getProperties(Nickname.class);
	}

	/**
	 * 

	 * Gets the person's nicknames.
	 * 
	 * 

	 * Property name: {@code NICKNAME}

	 * Supported versions: {@code 3.0, 4.0}
	 * 
	 * @return the nickname property (may contain multiple values) or null if
	 * not set
	 * @see RFC 6350
	 * p.29
	 * @see RFC 2426 p.9
	 */
	public Nickname getNickname() {
		return getProperty(Nickname.class);
	}

	/**
	 * 

	 * Sets the person's nicknames.
	 * 
	 * 

	 * Property name: {@code NICKNAME}

	 * Supported versions: {@code 4.0*}

	 * * Only 4.0 supports alternative representations
	 * 
	 * @param altRepresentations the alternative representations of the same
	 * value. These properties contain the same information, but in different
	 * forms (such as different languages). See {@link VCardParameters#getAltId
	 * this description of the ALTID parameter} for more information. Note that
	 * this method automatically assigns an appropriate ALTID parameter to each
	 * property.
	 * @see RFC 6350
	 * p.29
	 * @see RFC 2426 p.9
	 */
	public void setNicknameAlt(Nickname... altRepresentations) {
		setPropertyAlt(Nickname.class, altRepresentations);
	}

	/**
	 * 

	 * Adds a collection of nicknames for the person.
	 * 
	 * 

	 * Property name: {@code NICKNAME}

	 * Supported versions: {@code 4.0*}

	 * * Only 4.0 supports alternative representations
	 * 
	 * @param altRepresentations the alternative representations of the same
	 * value. These properties contain the same information, but in different
	 * forms (such as different languages). See {@link VCardParameters#getAltId
	 * this description of the ALTID parameter} for more information. Note that
	 * this method automatically assigns an appropriate ALTID parameter to each
	 * property.
	 * @see RFC 6350
	 * p.29
	 * @see RFC 2426 p.9
	 */
	public void addNicknameAlt(Nickname... altRepresentations) {
		addPropertyAlt(Nickname.class, altRepresentations);
	}

	/**
	 * 

	 * Sets the person's nicknames.
	 * 
	 * 

	 * Property name: {@code NICKNAME}

	 * Supported versions: {@code 3.0, 4.0}
	 * 
	 * @param nickname the nickname property (may contain multiple values) or
	 * null to remove
	 * @see RFC 6350
	 * p.29
	 * @see RFC 2426 p.9
	 */
	public void setNickname(Nickname nickname) {
		setProperty(Nickname.class, nickname);
	}

	/**
	 * 

	 * Adds a set of nicknames for the person.
	 * 
	 * 

	 * Note that only version 4.0 vCards support multiple instances of this
	 * property.
	 * 
	 * 

	 * Property name: {@code NICKNAME}

	 * Supported versions: {@code 4.0*}

	 * * Only 4.0 supports multiple instances
	 * 
	 * @param nickname the nickname property (may contain multiple values)
	 * @see RFC 6350
	 * p.29
	 * @see RFC 2426 p.9
	 */
	public void addNickname(Nickname nickname) {
		addProperty(nickname);
	}

	/**
	 * 

	 * Sets the person's nicknames.
	 * 
	 * 

	 * Property name: {@code NICKNAME}

	 * Supported versions: {@code 3.0, 4.0}
	 * 
	 * @param nicknames the nicknames (e.g. "John", "Jon")
	 * @return the property object that was created
	 * @see RFC 6350
	 * p.29
	 * @see RFC 2426 p.9
	 */
	public Nickname setNickname(String... nicknames) {
		Nickname property = null;
		if (nicknames != null && nicknames.length > 0 && nicknames[0] != null) {
			property = new Nickname();
			property.getValues().addAll(Arrays.asList(nicknames));
		}
		setNickname(property);
		return property;
	}

	/**
	 * 

	 * Gets the string that should be used to sort the vCard. This typically set
	 * to the person's family name (last name).
	 * 
	 * 

	 * For 4.0 vCards, this information is stored in the
	 * {@link StructuredName#getSortAs} and/or {@link Organization#getSortAs}
	 * methods.
	 * 
	 * 

	 * Property name: {@code SORT-STRING}

	 * Supported versions: {@code 3.0}
	 * 
	 * @return the sort string property or null if not set
	 * @see RFC 2426
	 * p.22
	 */
	public SortString getSortString() {
		return getProperty(SortString.class);
	}

	/**
	 * 

	 * Sets the string that should be used to sort the vCard. This typically set
	 * to the person's family name (last name).
	 * 
	 * 

	 * For 4.0 vCards, this information is stored in the
	 * {@link StructuredName#getSortAs} and/or {@link Organization#getSortAs}
	 * methods.
	 * 
	 * 

	 * Property name: {@code SORT-STRING}

	 * Supported versions: {@code 3.0}
	 * 
	 * @param sortString the sort string property or null to remove
	 * @see RFC 2426
	 * p.22
	 */
	public void setSortString(SortString sortString) {
		setProperty(SortString.class, sortString);
	}

	/**
	 * 

	 * Sets the string that should be used to sort the vCard. This typically set
	 * to the person's family name (last name).
	 * 
	 * 

	 * For 4.0 vCards, this information is stored in the
	 * {@link StructuredName#getSortAs} and/or {@link Organization#getSortAs}
	 * methods.
	 * 
	 * 

	 * Property name: {@code SORT-STRING}

	 * Supported versions: {@code 3.0}
	 * 
	 * @param sortString the sort string (e.g. "Armour" if the person's last
	 * name is "d'Armour") or null to remove
	 * @return the property object that was created
	 * @see RFC 2426
	 * p.22
	 */
	public SortString setSortString(String sortString) {
		SortString type = (sortString == null) ? null : new SortString(sortString);
		setSortString(type);
		return type;
	}

	/**
	 * 

	 * Gets the titles associated with the person.
	 * 
	 * 

	 * Property name: {@code TITLE}

	 * Supported versions: {@code 2.1, 3.0, 4.0}
	 * 
	 * @return the title properties (any changes made this list will affect the
	 * {@link VCard} object and vice versa)
	 * @see RFC 6350
	 * p.39
	 * @see RFC 2426
	 * p.17
	 * @see vCard 2.1 p.17
	 */
	public List