FAQ

Parts of my ADR property value are getting lost. What's wrong?

Comma characters have special meaning inside of a vCard. If they are not escaped properly, then ez-vcard splits the value by comma and ignores everything but the first value.

In the example below, ez-vcard thinks the street address is "123 Main St" because the comma character is not escaped with a backslash.

ADR:;;123 Main St, Apt 22;Springfield;MA;01109;USA

In ez-vcard versions 0.9.9 and above, calling the Address.getStreetAddressFull() method will return the entire street address field, treating the comma as a normal character. Or, you can call the Address.getStreetAddresses() method to get the entire list of split values.

In versions 0.9.8 and below, you'll need to register a custom ADR scribe in order to treat comma characters as normal characters (shown below).

VCardReader reader = new VCardReader(...);
reader.getScribeIndex().register(new AddressScribe() {
  @Override
  protected Address _parseText(String value, VCardDataType dataType, VCardVersion version, VCardParameters parameters, List<String> warnings) {
    String components[] = value.split(";");
    int i = 0;

    Address property = new Address();
    property.setPoBox(next(components, i++));
    property.setExtendedAddress(next(components, i++));
    property.setStreetAddress(next(components, i++));
    property.setLocality(next(components, i++));
    property.setRegion(next(components, i++));
    property.setPostalCode(next(components, i++));
    property.setCountry(next(components, i++));
    return property;
  }

  private String next(String components[], int index) {
    if (index >= components.length) return null;
    String next = components[index];
    return (next.length() > 0) ? next : null;
  }
});

I want to create an hCard (HTML-encoded vCard), but want to customize the HTML that is generated. Why can't I specify my own HTML template with the HCardPage class?

hCards are very tightly intertwined with the HTML code of a webpage. Due to this fact, it's difficult to develop a general purpose hCard "writer" that can be "plugged into" any given webpage. The HCardPage class serves more as an example of what a vCard looks like when embedded in HTML than anything else. But feel free to use ez-vcard's hCard template file as a starting point for learning how to embed a vCard in an HTML document.

At any rate, the HCardPage class is not much more than a wrapper around some Freemarker templating code. You're not missing much.

How do I get the names and values of all the properties in a vCard? There's no getName() or getValue() method!

ez-vcard considers property names to be part of the "serialization" part of the framework. Therefore, they are not stored in the property class, but in the property's scribe class.

Similarly, the way a property's value looks varies depending on the format a vCard is serialized to. Many property classes lack a getValue() method because the unmarshalled value of property is not always a simple String. For example, the ADR property value is composed of multiple components. So, ez-vcard's Address class separates each component out into individual String fields.

The example below outputs the property names of all the properties in a vCard, along with their value serialized in version 3.0 of the plain-text format.

VCard vcard = ...
ScribeIndex index = new ScribeIndex();
for (VCardProperty property : vcard){
  VCardPropertyScribe scribe = index.getPropertyScribe(property);
  String name = scribe.getPropertyName();
  String value = scribe.writeText(property, VCardVersion.V3_0);
  System.out.println(name + " = " + value);
}

P.S. Maybe you would be better off just calling vcard.write(System.out)...?

Some of the characters in my vCard are not being read correctly by my email client.

Some email clients have trouble processing non-ASCII characters. One possible work-around is to encode the property's value in "quoted-printable" encoding, as demonstrated below:

VCard vcard = new VCard();
FormattedName fn = vcard.setFormattedName("André Müller");
fn.getParameters().setEncoding(Encoding.QUOTED_PRINTABLE);
fn.getParameters().setCharset("ISO-8859-1");
vcard.write(System.out);

Outputs:

BEGIN:VCARD
VERSION:3.0
FN;ENCODING=quoted-printable;CHARSET=ISO-8859-1:Andr=E9 M=FCller
PRODID:ez-vcard 0.9.8
END:VCARD

How do you change the line folding settings?

VCardWriter writer = new VCardWriter(...);
 
//disable line folding
writer.getRawWriter().getFoldedLineWriter().setLineLength(null);
 
//change line length
writer.getRawWriter().getFoldedLineWriter().setLineLength(50);
 
//change folded line indent string
writer.getRawWriter().getFoldedLineWriter().setIndent("\t");
 
//change newline character
writer.getRawWriter().getFoldedLineWriter().setNewline("*");