jCard

vCard data can be encoded in JSON. This format is called jCard. The jCard specification is defined in RFC 7095. jCards only adhere to version 4.0 of the vCard specification. They do not support versions 2.1 or 3.0.

Note that, unlike the rest of ez-vcard which requires a 1.5 JVM, you must have a 1.6 JVM or later in order to work with jCards.

Below is an example of a jCard.

["vcard",
  [
    ["version", {}, "text", "4.0"],
    ["n", {}, "text", ["Doe", "John", "", "Mr", ""]],
    ["fn", {}, "text", "Mr. John Doe"],
    ["email", {"group":"group1", "type":"home"}, "text", "[email protected]"],
    ["note", {}, "text", "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec at lacus justo. Phasellus quis nisl eget augue gravida tempor in at ante. Suspendisse suscipit eleifend molestie."]
  ]
]

If your application does not require jCard functionality, you can exclude the "jackson-core" dependency from your build.

<dependency>
  <groupId>com.googlecode.ez-vcard</groupId>
  <artifactId>ez-vcard</artifactId>
  <version>...</version>
  <exclusions>
    <!-- jCard parsing not needed -->
    <exclusion>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-core</artifactId>
    </exclusion>
  </exclusions>
</dependency>

1 Reading JSON-encoded vCard data

The JCardReader class handles the parsing of JSON-encoded 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.

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()
Returns any problems the parser encountered while parsing the VCard object that was last returned by readNext(). Examples of things that could cause warnings are: malformed date values or unparseable property values.

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

1.2 Example

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

File file = new File("vcards.json");
JCardReader reader = new JCardReader(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

Properties whose values cannot be parsed are treated as extended properties (properties that are not defined in the specifications). For example, if the date in a REV property value is malformed, the property will instead be unmarshalled as a RawProperty. A warning will also be logged.

String json =
"[\"vcard\"," +
  "[" +
    "[\"version\", {}, \"text\", \"4.0\"]," +
    "[\"rev\", {}, \"timestamp\", \"I don't know, like, 2 days ago?\"]" +
  "]" +
"]";

JCardReader reader = new JCardReader(json);
VCard vcard = reader.readNext();
reader.close();

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

System.out.println("REV property: " + vcard.getRevision());

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

The above code outputs the following. The comma characters are escaped to simulate how the value would appear in a plain-text vCard.

Warnings: [Line 1 (rev property): Property value could not be parsed.  It will be saved as an extended property instead.
  Reason: Could not parse date string.
  Value: I don't know\, like\, 2 days ago?]
REV property: null
Extended property: I don't know\, like\, 2 days ago?

2 Writing JSON-encoded vCard data

The JCardWriter class handles the serialization of JSON-encoded vCard data.

2.1 Important methods

write()
Writes the contents of an 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 JCardWriter object in order to properly close the output stream. It's especially important for JCardWriter because it must write the proper closing characters to complete the JSON syntax.

2.2 Example

The example below writes a list of VCard objects to a JSON file.

List<VCard> vcards = ...
File file = new File("vcards.json");
JCardWriter writer = new JCardWriter(file);
try {
  for (VCard vcard : vcards) {
    writer.write(vcard);
  }
} finally {
  writer.close();
}