com.github.mangstadt.vinnie.io

Class VObjectReader

java.lang.Object

com.github.mangstadt.vinnie.io.VObjectReader

All Implemented Interfaces:

Closeable, AutoCloseable

public class VObjectReader
extends Object
implements Closeable

Parses a vobject data stream.

Example:

 Reader reader = ...
 SyntaxRules rules = SyntaxRules.vcard();
 VObjectReader vobjectReader = new VObjectReader(reader, rules);
 vobjectReader.parse(new VObjectDataListener(){ ... });
 vobjectReader.close();
 

Quoted-printable Encoding

Property values encoded in quoted-printable encoding are automatically decoded. A property value is considered to be encoded in quoted-printable encoding if it has a "ENCODING=QUOTED-PRINTABLE" parameter. Even though the property value is automatically decoded, the ENCODING and CHARSET parameters are not removed from the parsed property object so that the caller can determine its original encoding.

 Reader reader = new StringReader("NOTE;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:=C2=A1Hola, mundo!");
 VObjectReader vobjectReader = new VObjectReader(reader, ...);
 vobjectReader.parse(new VObjectDataAdapter() {
   public void onProperty(VObjectProperty property, Context context) {
     assertEquals("¡Hola, mundo!", property.getValue());
     assertEquals("QUOTED-PRINTABLE", property.getParameters().first("ENCODING"));
     assertEquals("UTF-8", property.getParameters().first("CHARSET"));
   }
 });
 vobjectReader.close();
 

If a CHARSET parameter is not present in the quoted-printable property, then the character set of the input stream will be used to decode the value. If this cannot be determined, then the local JVM's default character set will be used. However, this behavior can be overridden by supplying your own character set to use in the event that a CHARSET parameter is not present.

 Reader reader = new StringReader("NOTE;ENCODING=QUOTED-PRINTABLE:=A1Hola, mundo!");
 VObjectReader vobjectReader = new VObjectReader(reader, ...);
 vobjectReader.setDefaultQuotedPrintableCharset(Charset.forName("Windows-1252"));
 vobjectReader.parse(new VObjectDataAdapter() {
   public void onProperty(VObjectProperty property, Context context) {
     assertEquals("¡Hola, mundo!", property.getValue());
     assertEquals("QUOTED-PRINTABLE", property.getParameters().first("ENCODING"));
     assertNull(property.getParameters().first("CHARSET"));
   }
 });
 vobjectReader.close();
 

Nameless ENCODING parameters are also recognized for backwards compatibility with old-style syntax.

 NOTE;QUOTED-PRINTABLE;CHARSET=UTF-8:=C2=A1Hola, mundo!
 

If there is an error decoding a quoted-printable value, then a warning will be emitted and the value will be treated as plain-text.

 Reader reader = new StringReader("NOTE;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:=ZZ invalid");
 VObjectReader vobjectReader = new VObjectReader(reader, ...);
 vobjectReader.parse(new VObjectDataAdapter() {
   public void onProperty(VObjectProperty property, Context context) {
     assertEquals("=ZZ invalid", property.getValue());
   }
   public void onWarning(Warning warning, VObjectProperty property, Exception thrown, Context context) {
     assertEquals(Warning.QUOTED_PRINTABLE_ERROR, warning);
   }
 });
 vobjectReader.close();
 

Circumflex Accent Encoding

Circumflex accent encoding allows newlines and double quote characters to be included inside of parameter values. Parameter values that are encoded using this encoding scheme are automatically decoded. Note that this encoding mechanism is only supported by new-style syntax.

 Reader reader = new StringReader("NOTE;X-AUTHOR=Fox ^'Spooky^' Mulder:The truth is out there.");
 VObjectReader vobjectReader = new VObjectReader(reader, new SyntaxRules(SyntaxStyle.NEW));
 vobjectReader.parse(new VObjectDataAdapter() {
   public void onProperty(VObjectProperty property, Context context) {
     assertEquals("Fox \"Spooky\" Mulder", property.getParameters().first("X-AUTHOR"));
   }
 });
 vobjectReader.close();
 

In the rare event that your vobject data has raw "^" characters in its parameter values, and it does not use this encoding scheme, circumflex accent decoding can be turned off.

 Reader reader = new StringReader("NOTE;X-EMOTE=^_^:Good morning!");
 VObjectReader vobjectReader = new VObjectReader(reader, new SyntaxRules(SyntaxStyle.NEW));
 vobjectReader.setCaretDecodingEnabled(false);
 vobjectReader.parse(new VObjectDataAdapter() {
   public void onProperty(VObjectProperty property, Context context) {
     assertEquals("^_^", property.getParameters().first("X-EMOTE"));
   }
 });
 vobjectReader.close();
 

Line Folding

Folded lines are automatically unfolded when read.

 String string = 
 "NOTE:Lorem ipsum dolor sit amet\\, consectetur adipiscing elit. Vestibulum u\r\n" +
 " ltricies tempor orci ac dignissim.";
 Reader reader = new StringReader(string);
 VObjectReader vobjectReader = new VObjectReader(reader, ...);
 vobjectReader.parse(new VObjectDataAdapter() {
   public void onProperty(VObjectProperty property, Context context) {
     assertEquals("Lorem ipsum dolor sit amet\\, consectetur adipiscing elit. Vestibulum ultricies tempor orci ac dignissim.", property.getValue());
   }
 });
 vobjectReader.close();
 

Author:

Michael Angstadt

Constructor Summary

Constructors

Constructor and Description
VObjectReader(Reader reader, SyntaxRules syntaxRules) Creates a new vobject reader.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the underlying input stream.
Charset	getDefaultQuotedPrintableCharset() Gets the default character set to use when decoding quoted-printable values of properties that lack CHARSET parameters, or of properties whose CHARSET parameters are not recognized by the local JVM.
boolean	isCaretDecodingEnabled() Gets whether the reader will decode parameter values that use circumflex accent encoding (enabled by default).
void	parse(VObjectDataListener listener) Starts or continues to parse the data off the input stream.
void	setCaretDecodingEnabled(boolean enable) Sets whether the reader will decode parameter values that use circumflex accent encoding (enabled by default).
void	setDefaultQuotedPrintableCharset(Charset charset) Sets the character set to use when decoding quoted-printable values of properties that lack CHARSET parameters, or of properties whose CHARSET parameters are not recognized by the local JVM.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

VObjectReader

public VObjectReader(Reader reader,
                     SyntaxRules syntaxRules)

Creates a new vobject reader.

Parameters:

reader - the input stream

syntaxRules - defines the rules that are used to determine what kind of syntax the data is in

Method Detail

getDefaultQuotedPrintableCharset

public Charset getDefaultQuotedPrintableCharset()

Gets the default character set to use when decoding quoted-printable values of properties that lack CHARSET parameters, or of properties whose CHARSET parameters are not recognized by the local JVM.

By default, this is set to the character set of the Reader object that this class was constructed with. If the character set of the Reader object could not be determined, then it will be set to the local JVM's default character set.

Returns:

the default quoted-printable character set

setDefaultQuotedPrintableCharset

public void setDefaultQuotedPrintableCharset(Charset charset)

Sets the character set to use when decoding quoted-printable values of properties that lack CHARSET parameters, or of properties whose CHARSET parameters are not recognized by the local JVM.

By default, this is set to the character set of the Reader object that this class was constructed with. If the character set of the Reader object could not be determined, then it will be set to the local JVM's default character set.

Parameters:

charset - the default quoted-printable character set (cannot be null)

isCaretDecodingEnabled

public boolean isCaretDecodingEnabled()

Gets whether the reader will decode parameter values that use circumflex accent encoding (enabled by default). This escaping mechanism allows newlines and double quotes to be included in parameter values. It is only supported by new style syntax.

Characters encoded by circumflex accent encoding

Raw Character	Encoded Character
"	^'
newline	^n
^	^^

Example:

 GEO;X-ADDRESS="Pittsburgh Pirates^n115 Federal St^nPittsburgh, PA 15212":40.446816;80.00566
 

Returns:

true if circumflex accent decoding is enabled, false if not

See Also:

RFC 6868

setCaretDecodingEnabled

public void setCaretDecodingEnabled(boolean enable)

Sets whether the reader will decode parameter values that use circumflex accent encoding (enabled by default). This escaping mechanism allows newlines and double quotes to be included in parameter values. It is only supported by new style syntax.

Characters encoded by circumflex accent encoding

Raw Character	Encoded Character
"	^'
newline	^n
^	^^

Example:

 GEO;X-ADDRESS="Pittsburgh Pirates^n115 Federal St^nPittsburgh, PA 15212":geo:40.446816,-80.00566
 

Parameters:

enable - true to use circumflex accent decoding, false not to

See Also:

RFC 6868

parse

public void parse(VObjectDataListener listener)
           throws IOException

Starts or continues to parse the data off the input stream.

This method blocks until one of the following events happen:

1. The end of the input stream has been reached or
2. One of the methods in the given VObjectDataListener implementation has invoked Context.stop().

Parameters:

listener - callback interface for handling data as it is read off the input stream

Throws:

IOException - if there's a problem reading from the input stream

close

public void close()
           throws IOException

Closes the underlying input stream.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException