com.github.mangstadt.vinnie.io

Class VObjectWriter

java.lang.Object

com.github.mangstadt.vinnie.io.VObjectWriter

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

public class VObjectWriter
extends Object
implements Closeable, Flushable

Writes data to a vobject data stream.

Example:

 Writer writer = ...
 VObjectWriter vobjectWriter = new VObjectWriter(writer, SyntaxStyle.NEW);
 vobjectWriter.writeBeginComponent("VCARD");
 vobjectWriter.writeVersion("4.0");
 vobjectWriter.writeProperty("FN", "John Doe");
 vobjectWriter.writeEndComponent("VCARD");
 vobjectWriter.close();
 

Invalid characters

If property data contains any invalid characters, the writeProperty method throws an IllegalArgumentException and the property is not written. A character is considered to be invalid if it cannot be encoded or escaped, and would break the vobject syntax if written.

The rules regarding which characters are considered invalid is fairly complex. Here are some general guidelines:

• Try to limit group names, property names, and parameter names to alphanumerics and hyphens.
• Avoid the use of newlines, double quotes, and colons inside of parameter values. They can be used in some contexts, but not others.

Newlines in property values

All newline characters ("\r" or "\n") within property values are automatically escaped.

In old-style syntax, the property value will be encoded in quoted-printable encoding.

 StringWriter sw = new StringWriter();
 VObjectWriter vobjectWriter = new VObjectWriter(sw, SyntaxStyle.OLD);
 vobjectWriter.writeProperty("NOTE", "one\r\ntwo");
 vobjectWriter.close();
 
 assertEquals("NOTE;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:one=0D=0Atwo\r\n", sw.toString());
 

In new-style syntax, the newline characters will be replaced with the "\n" escape sequence (Windows newline sequences are replaced with a single "\n" even though they consist of two characters).

 StringWriter sw = new StringWriter();
 VObjectWriter vobjectWriter = new VObjectWriter(sw, SyntaxStyle.NEW);
 vobjectWriter.writeProperty("NOTE", "one\r\ntwo");
 vobjectWriter.close();
 
 assertEquals("NOTE:one\\ntwo\r\n", sw.toString());
 

Quoted-printable Encoding

If a property has a parameter named ENCODING that has a value of QUOTED-PRINTABLE (case-insensitive), then the property's value will automatically be written in quoted-printable encoding.

 StringWriter sw = new StringWriter();
 VObjectWriter vobjectWriter = new VObjectWriter(sw, ...);
 
 VObjectProperty note = new VObjectProperty("NOTE", "¡Hola, mundo!");
 note.getParameters().put("ENCODING", "QUOTED-PRINTABLE");
 vobjectWriter.writeProperty(note);
 vobjectWriter.close();
 
 assertEquals("NOTE;ENCODING=QUOTED-PRINTABLE;CHARSET=UTF-8:=C2=A1Hola, mundo!\r\n", sw.toString());
 

A nameless parameter may also be used for backwards compatibility with old-style syntax.

 VObjectProperty note = new VObjectProperty("NOTE", "¡Hola, mundo!");
 note.getParameters().put(null, "QUOTED-PRINTABLE");
 vobjectWriter.writeProperty(note);
 

By default, the property value is encoded under the UTF-8 character set when encoded in quoted-printable encoding. This can be changed by specifying a CHARSET parameter. If the character set is not recognized by the local JVM, then UTF-8 will be used.

 StringWriter sw = new StringWriter();
 VObjectWriter vobjectWriter = new VObjectWriter(sw, ...);
 
 VObjectProperty note = new VObjectProperty("NOTE", "¡Hola, mundo!");
 note.getParameters().put("ENCODING", "QUOTED-PRINTABLE");
 note.getParameters().put("CHARSET", "Windows-1252");
 vobjectWriter.writeProperty(note);
 vobjectWriter.close();
 
 assertEquals("NOTE;ENCODING=QUOTED-PRINTABLE;CHARSET=Windows-1252:=A1Hola, mundo!\r\n", sw.toString());
 

Circumflex Accent Encoding

Newlines and double quote characters are not permitted inside of parameter values unless circumflex accent encoding is enabled. It is turned off by default.

Note that this encoding mechanism is defined in a separate specification and may not be supported by the consumer of the vobject data. Also note that it can only be used with new-style syntax.

 StringWriter sw = new StringWriter();
 VObjectWriter vobjectWriter = new VObjectWriter(sw, SyntaxStyle.NEW);
 vobjectWriter.setCaretEncodingEnabled(true);
 
 VObjectProperty note = new VObjectProperty("NOTE", "The truth is out there.");
 note.getParameters().put("X-AUTHOR", "Fox \"Spooky\" Mulder");
 vobjectWriter.writeProperty(note);
 vobjectWriter.close();
 
 assertEquals("NOTE;X-AUTHOR=Fox ^'Spooky^' Mulder:The truth is out there.\r\n", sw.toString());
 

Line Folding

Lines longer than 75 characters are automatically folded, as per the vCard/iCalendar recommendation.

 StringWriter sw = new StringWriter();
 VObjectWriter vobjectWriter = new VObjectWriter(sw, ...);
 
 vobjectWriter.writeProperty("NOTE", "Lorem ipsum dolor sit amet\, consectetur adipiscing elit. Vestibulum ultricies tempor orci ac dignissim.");
 vobjectWriter.close();
 
 assertEquals(
 "NOTE:Lorem ipsum dolor sit amet\\, consectetur adipiscing elit. Vestibulum u\r\n" +
 " ltricies tempor orci ac dignissim.\r\n"
 , sw.toString());
 

The line folding length can be adjusted to a length of your choosing. In addition, passing in a "null" line length will disable line folding.

 StringWriter sw = new StringWriter();
 VObjectWriter vobjectWriter = new VObjectWriter(sw, ...);
 vobjectWriter.getFoldedLineWriter().setLineLength(null);
 
 vobjectWriter.writeProperty("NOTE", "Lorem ipsum dolor sit amet\, consectetur adipiscing elit. Vestibulum ultricies tempor orci ac dignissim.");
 vobjectWriter.close();
 
 assertEquals("NOTE:Lorem ipsum dolor sit amet\\, consectetur adipiscing elit. Vestibulum ultricies tempor orci ac dignissim.\r\n", sw.toString());
 

You may also specify what kind of folding whitespace to use. The default is a single space character, but this can be changed to any combination of tabs and spaces. Note that new-style syntax requires the folding whitespace to be EXACTLY ONE character long.

 StringWriter sw = new StringWriter();
 VObjectWriter vobjectWriter = new VObjectWriter(sw, ...);
 vobjectWriter.getFoldedLineWriter().setIndent("\t");
 
 vobjectWriter.writeProperty("NOTE", "Lorem ipsum dolor sit amet\, consectetur adipiscing elit. Vestibulum ultricies tempor orci ac dignissim.");
 vobjectWriter.close();
 
 assertEquals(
 "NOTE:Lorem ipsum dolor sit amet\\, consectetur adipiscing elit. Vestibulum u\r\n" +
 "\tltricies tempor orci ac dignissim.\r\n"
 , sw.toString());
 

Author:

Michael Angstadt

Constructor Summary

Constructors

Constructor and Description
VObjectWriter(Writer writer, SyntaxStyle syntaxStyle) Creates a new vobject writer.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the underlying output stream.
void	flush() Flushes the underlying output stream.
FoldedLineWriter	getFoldedLineWriter() Gets the writer that is used to write data to the output stream.
SyntaxStyle	getSyntaxStyle() Gets the syntax style the writer is using.
boolean	isCaretEncodingEnabled() Gets whether the writer will apply circumflex accent encoding on parameter values (disabled by default).
void	setCaretEncodingEnabled(boolean enable) Sets whether the writer will apply circumflex accent encoding on parameter values (disabled by default).
void	setSyntaxStyle(SyntaxStyle syntaxStyle) Sets the syntax style that the writer should use.
void	writeBeginComponent(String componentName) Writes a property marking the beginning of a component.
void	writeEndComponent(String componentName) Writes a property marking the end of a component.
void	writeProperty(String name, String value) Writes a property to the data stream.
void	writeProperty(String group, String name, VObjectParameters parameters, String value) Writes a property to the data stream.
void	writeProperty(VObjectProperty property) Writes a property to the data stream.
void	writeVersion(String version) Writes a "VERSION" property.

Methods inherited from class java.lang.Object

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

Constructor Detail

VObjectWriter

public VObjectWriter(Writer writer,
                     SyntaxStyle syntaxStyle)

Creates a new vobject writer.

Parameters:

writer - the output stream

syntaxStyle - the syntax style to use

Method Detail

getFoldedLineWriter

public FoldedLineWriter getFoldedLineWriter()

Gets the writer that is used to write data to the output stream.

Returns:

the folded line writer

isCaretEncodingEnabled

public boolean isCaretEncodingEnabled()

Gets whether the writer will apply circumflex accent encoding on parameter values (disabled by default). This escaping mechanism allows for 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 encoding is enabled, false if not

See Also:

RFC 6868

setCaretEncodingEnabled

public void setCaretEncodingEnabled(boolean enable)

Sets whether the writer will apply circumflex accent encoding on parameter values (disabled by default). This escaping mechanism allows for 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
 

Parameters:

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

See Also:

RFC 6868

getSyntaxStyle

public SyntaxStyle getSyntaxStyle()

Gets the syntax style the writer is using.

Returns:

the syntax style

setSyntaxStyle

public void setSyntaxStyle(SyntaxStyle syntaxStyle)

Sets the syntax style that the writer should use.

Parameters:

syntaxStyle - the syntax style

writeBeginComponent

public void writeBeginComponent(String componentName)
                         throws IOException

Writes a property marking the beginning of a component.

Parameters:

componentName - the component name (e.g. "VCARD")

Throws:

IllegalArgumentException - if the component name is null or empty

IOException - if there's a problem writing to the data stream

writeEndComponent

public void writeEndComponent(String componentName)
                       throws IOException

Writes a property marking the end of a component.

Parameters:

componentName - the component name (e.g. "VCARD")

Throws:

IllegalArgumentException - if the component name is null or empty

IOException - if there's a problem writing to the data stream

writeVersion

public void writeVersion(String version)
                  throws IOException

Writes a "VERSION" property.

Parameters:

version - the version string (e.g. "2.1")

Throws:

IllegalArgumentException - if the version string is null or empty

IOException - if there's a problem writing to the data stream

writeProperty

public void writeProperty(String name,
                          String value)
                   throws IOException

Writes a property to the data stream.

Parameters:

name - the property name (e.g. "FN")

value - the property value

Throws:

IllegalArgumentException - if the given data contains one or more characters which would break the syntax and cannot be written

IOException - if there's a problem writing to the data stream

writeProperty

public void writeProperty(VObjectProperty property)
                   throws IOException

Writes a property to the data stream.

Parameters:

property - the property to write

Throws:

IllegalArgumentException - if the given data contains one or more characters which would break the syntax and cannot be written

IOException - if there's a problem writing to the data stream

writeProperty

public void writeProperty(String group,
                          String name,
                          VObjectParameters parameters,
                          String value)
                   throws IOException

Writes a property to the data stream.

Parameters:

group - the group or null if there is no group

name - the property name (e.g. "FN")

parameters - the property parameters

value - the property value (will be converted to "quoted-printable" encoding if the ENCODING parameter is set to "QUOTED-PRINTABLE")

Throws:

IllegalArgumentException - if the given data contains one or more characters which would break the syntax and cannot be written

IOException - if there's a problem writing to the data stream

flush

public void flush()
           throws IOException

Flushes the underlying output stream.

Specified by:

flush in interface Flushable

Throws:

IOException - if there's a problem flushing the output stream

close

public void close()
           throws IOException

Closes the underlying output stream.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - if there's a problem closing the output stream