Getting started

This quick start guide will show you the basics of how to read and write vCards using ez-vcard. If you are familiar with Java programming and a programming idiom called method chaining, it should be fairly intuitive once you see some examples. The Javadocs are also a good source of information.

In this guide, we will be using the Ezvcard class. This class contains a collection of static factory methods that use method chaining to simplify the reading/writing process. For more control over the reading/writing process, you can use the VCardReader and VCardWriter classes.

Reading vCard data

To parse a vCard, start by calling the Ezvcard.parse() method. This method is overloaded to take a String, File, InputStream, or Reader as an argument.

Then, you can optionally call additional methods which allow you to customize the parsing process. For example, caretDecoding(false) can be called to disable a certain kind of encoding scheme that only some vCard producers support.

Finally, call the first() or all() methods to execute the parsing operation.

The parsed data of each vCard is returned in a VCard object. This object is essentially a DTO, containing mostly getter/setter methods.

String str =
"BEGIN:VCARD\r\n" +
"VERSION:4.0\r\n" +
"N:Doe;Jonathan;;Mr;\r\n" +
"FN:John Doe\r\n" +
"END:VCARD\r\n";

//parse the first vCard from the data stream
VCard vcard = Ezvcard.parse(str).first();

//or parse all vCards from the data stream 
//List<VCard> vcards = Ezvcard.parse(str).all();

String fullName = vcard.getFormattedName().getValue();
String lastName = vcard.getStructuredName().getFamily();

Writing vCard data

To write a vCard, simply create a new instance of the VCard class, and populate it with data. Then, pass it into the Ezvcard.write() method.

Then, you can optionally call additional methods which allow you to customize the writing process. For example, version() can be called to specify what version of the vCard standard the written data should adhere to (it defaults to 3.0, one of the most commonly-used versions).

Finally, call the go() method to execute the write operation. This method is overloaded to take a File, OutputStream, or Writer as an argument. The no-argument version will return the serialized vCard as a String.

VCard vcard = new VCard();

StructuredName n = new StructuredName();
n.setFamily("Doe");
n.setGiven("Jonathan");
n.getPrefixes().add("Mr");
vcard.setStructuredName(n);

vcard.setFormattedName("John Doe");

Ezvcard.write(vcard).version(VCardVersion.V4_0).go(System.out);

The above code produces the following output:

BEGIN:VCARD
VERSION:4.0
PRODID:ez-vcard 0.9.10
N:Doe;Jonathan;;Mr;
FN:John Doe
END:VCARD

Note that, by default, if a property is not supported by the version you are writing the vCard as, it will be excluded from the serialized output. To disable this, call versionStrict(false).

Validating a VCard object

To help ensure that data within a VCard Java object properly adheres to the vCard specifications, the validate() method can be called. This method returns a list of warnings, alerting the developer to such things as a property not being supported by a specific vCard version.

Note that the presence of validation warnings will not prevent the VCard object from being properly written to a data stream. Syntactically-correct vCard data will still be produced. However, the consuming application may have trouble interpreting some of the data, due to the presence of these warnings.

And, as mentioned above, if a property is not supported by the version you are writing the vCard as, it will be excluded from the serialized output. To disable this, call versionStrict(false) when writing the vCard.

VCard vcard = new VCard();

vcard.setGender(Gender.male());

TelUri uri = new TelUri.Builder("+1-800-555-1234").extension("123").build();
Telephone tel = new Telephone(uri);
tel.getTypes().add(TelephoneType.TEXT);
vcard.addTelephoneNumber(tel);

ValidationWarnings warnings = vcard.validate(VCardVersion.V2_1);
System.out.println(warnings.toString());

The above code produces the following output:

W00: A StructuredName property is required for vCard versions 2.1 and 3.0.
[Gender] | W02: Property is not supported in this vCard version.  Supported versions are: [4.0]
[Telephone] | W19: Tel URIs are only supported by vCard version 4.0.  ez-vcard will convert the URI to a string, but some of the data in the URI may be lost.
[Telephone] | W09: TYPE parameter value ("text") is not supported by this property in this vCard version.