Plain text

vCard data is most commonly encoded in a special plain-text format. The specifications for the latest version of this format (4.0) is defined in RFC 6350. An older version (3.0) is defined in RFC 2426. An even older version (2.1) is defined here. All three versions have similar, but not idential, syntax. And they support a similar, but not identical, set of properties. See the Property List for a listing of all the vCard properties, along with what vCard versions support them.

Most vCard applications support versions 2.1 and 3.0. Widespread adoption of version 4.0 has yet to take place. All three versions are supported by ez-vcard.

1 Reading plain-text vCard data

The VCardReader class handles the parsing of plain-text vCard data. The data is read in a streaming fashion, meaning it parses the data as it is read off the wire. This results in a smaller memory footprint than other approaches.

VCardReader automatically detects the version of the vCard data that's being read, and adjusts its parsing algorithm accordingly.

1.1 Important methods

readNext()
Parses and returns the next VCard object in the data stream. The method returns null when the end of stream has been reached.

getWarnings()
VCardReader does its best to skip over invalid or unparseable data and log it as a warning (as opposed to throwing an exception and aborting the entire parsing process). The getWarnings() method returns any problems the parser encountered while parsing the ICalendar object that was last returned by readNext(). Examples of things that could cause warnings are: invalid syntax or unparseable property values (such as malformed date values).

close()
As with all I/O operations, it's important to call the close() method when you are done with the VCardReader object in order to properly close the input stream.

Please see the Javadocs for a complete listing of all the methods.

1.2 Example

The example below outputs the names and birthdays of each vCard in the data stream.

File file = new File("vcards.vcf");
VCardReader reader = new VCardReader(file);
try {
  VCard vcard;
  DateFormat df = new SimpleDateFormat("MM/dd/yyyy");
  while ((vcard = reader.readNext()) != null) {
    FormattedName fn = vcard.getFormattedName();
    String name = (fn == null) ? null : fn.getValue();

    Birthday bday = vcard.getBirthday();
    Date date = (bday == null) ? null : bday.getDate();
    String birthday = (date == null) ? null : df.format(date);

    System.out.println(name + " " + birthday);
  }
} finally {
  reader.close();
}

1.3 A note about unparseable property values

If a property's value cannot be parsed (for example, due to a malformed date value), the property is treated as an extended property and a warning is logged. The code below demonstrates this:

String str =
"BEGIN:VCARD\r\n" +
"VERSION:2.1\r\n" +
"BDAY:Jan 5, 1980\r\n" +
"END:VCARD\r\n";

VCardReader reader = new VCardReader(str);
VCard vcard = reader.readNext();
reader.close();

List<String> warnings = reader.getWarnings();
System.out.println("Warnings: " + warnings);

System.out.println("BDAY property: " + vcard.getBirthday());

RawProperty prop = vcard.getExtendedProperty("BDAY");
System.out.println("Extended property: " + prop.getValue());

The above code produces the following output:

Warnings: [Line 3 (BDAY property): Property value could not be parsed.  It will be saved as an extended property instead.
  Reason: Could not parse date string.
  Value: Jan 5, 1980]
BDAY property: null
Extended property: Jan 5, 1980

2 Writing plain-text vCard data

The VCardWriter class handles the serialization of plain-text vCard data. Its constructor takes a VCardVersion object, which specifies the vCard version that the data will be written in.

2.1 Important methods

write()
Writes the contents of a VCard object to the data stream.

close()
As with all I/O operations, it's important to call the close() method when you are done with the VCardWriter object in order to properly close the output stream.

Please see the Javadocs for a complete listing of all the methods.

2.2 Example

The example below writes a list of VCard objects to a file using the latest vCard version.

List<VCard> vcards = ...
File file = new File("vcards.vcf");
VCardWriter writer = new VCardWriter(file, VCardVersion.V4_0);
try {
  for (VCard vcard : vcards) {
    writer.write(vcard);
  }
} finally {
  writer.close();
}