-
Notifications
You must be signed in to change notification settings - Fork 92
jCard
vCard data can be encoded in JSON using the jCard format. 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.
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", "jdoe@example.com"],
["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."]
]
]
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.
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.
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();
}
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 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 produces the following output. 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?
The JCardWriter
class handles the serialization of JSON-encoded vCard data.
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.
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();
}
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>
ez-vcard is maintained by Michael Angstadt
Table of Contents
Getting started
Examples
FAQ
Javadocs
Downloads
1 An Overview of the vCard data format
2 Reading and Writing vCard data with ez-vcard
2.1 Plain-text (traditional)
2.2 XML-encoded (xCard)
2.3 JSON-encoded (jCard)
2.4 HTML-encoded (hCard)
3 Differences between the vCard versions
4 Dealing with Non-standard Data
4.1 Working with non-standard properties and parameters
4.2 Property scribe
5 Project Information
5.1 News
5.2 Dependencies
5.3 Supported Specifications
5.4 Changelog
6 Reference
6.1 vCard Property Reference
6.2 Javadocs