ezvcard.io.text

Class VCardWriter

java.lang.Object

ezvcard.io.StreamWriter

ezvcard.io.text.VCardWriter

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

public class VCardWriter
extends StreamWriter
implements Flushable

Writes VCard objects to a plain-text vCard data stream.

Example:

 VCard vcard1 = ...
 VCard vcard2 = ...
 Path file = Paths.get("vcard.vcf");
 try (VCardWriter writer = new VCardWriter(file, VCardVersion.V3_0)) {
   writer.write(vcard1);
   writer.write(vcard2);
 }
 

Changing the line folding settings:

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

Author:

Michael Angstadt

See Also:

vCard 2.1, RFC 2426 (3.0), RFC 6350 (4.0)

Field Summary

Fields inherited from class ezvcard.io.StreamWriter

addProdId, index, versionStrict

Constructor Summary

Constructors

Constructor and Description
VCardWriter(OutputStream out, VCardVersion targetVersion)
VCardWriter(Path file, boolean append, VCardVersion targetVersion)
VCardWriter(Path file, VCardVersion targetVersion)
VCardWriter(Writer writer, VCardVersion targetVersion)

Method Summary

Modifier and Type	Method and Description
protected void	_write(VCard vcard, List<VCardProperty> propertiesToAdd) Writes a vCard to the stream.
void	close() Closes the output stream.
void	flush() Flushes the output stream.
TargetApplication	getTargetApplication() Gets the application that the vCards will be targeted for.
VCardVersion	getTargetVersion() Gets the version that the vCards should adhere to.
VObjectWriter	getVObjectWriter() Gets the writer that this object uses to write data to the output stream.
boolean	isCaretEncodingEnabled() Gets whether the writer will apply circumflex accent encoding on parameter values (disabled by default).
Boolean	isIncludeTrailingSemicolons() Gets whether this writer will include trailing semicolon delimiters for structured property values whose list of values end with null or empty values.
void	setCaretEncodingEnabled(boolean enable) Sets whether the writer will apply circumflex accent encoding on parameter values (disabled by default).
void	setIncludeTrailingSemicolons(Boolean include) Sets whether to include trailing semicolon delimiters for structured property values whose list of values end with null or empty values.
void	setTargetApplication(TargetApplication targetApplication) Sets the application that the vCards will be targeted for.
void	setTargetVersion(VCardVersion targetVersion) Sets the version that the vCards should adhere to.

Methods inherited from class ezvcard.io.StreamWriter

getScribeIndex, isAddProdId, isVersionStrict, registerScribe, setAddProdId, setScribeIndex, setVersionStrict, write

Methods inherited from class java.lang.Object

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

Constructor Detail

VCardWriter

public VCardWriter(OutputStream out,
                   VCardVersion targetVersion)

Parameters:

out - the output stream to write to

targetVersion - the version that the vCards should conform to (if set to "4.0", vCards will be written in UTF-8 encoding)

VCardWriter

public VCardWriter(Path file,
                   VCardVersion targetVersion)
            throws IOException

Parameters:

file - the file to write to

targetVersion - the version that the vCards should conform to (if set to "4.0", vCards will be written in UTF-8 encoding)

Throws:

IOException - if there's a problem opening the file

VCardWriter

public VCardWriter(Path file,
                   boolean append,
                   VCardVersion targetVersion)
            throws IOException

Parameters:

file - the file to write to

append - true to append to the end of the file, false to overwrite it

targetVersion - the version that the vCards should conform to (if set to "4.0", vCards will be written in UTF-8 encoding)

Throws:

IOException - if there's a problem opening the file

VCardWriter

public VCardWriter(Writer writer,
                   VCardVersion targetVersion)

Parameters:

writer - the writer to write to

targetVersion - the version that the vCards should conform to

Method Detail

getVObjectWriter

public VObjectWriter getVObjectWriter()

Gets the writer that this object uses to write data to the output stream.

Returns:

the writer

getTargetVersion

public VCardVersion getTargetVersion()

Gets the version that the vCards should adhere to.

Specified by:

getTargetVersion in class StreamWriter

Returns:

the vCard version

setTargetVersion

public void setTargetVersion(VCardVersion targetVersion)

Sets the version that the vCards should adhere to.

Parameters:

targetVersion - the vCard version

getTargetApplication

public TargetApplication getTargetApplication()

Gets the application that the vCards will be targeted for.

Some vCard consumers do not completely adhere to the vCard specifications and require their vCards to be formatted in a specific way. See the TargetApplication class for a list of these applications.

Returns:

the target application or null if the vCards do not be given any special processing (defaults to null)

setTargetApplication

public void setTargetApplication(TargetApplication targetApplication)

Sets the application that the vCards will be targeted for.

Some vCard consumers do not completely adhere to the vCard specifications and require their vCards to be formatted in a specific way. See the TargetApplication class for a list of these applications.

Parameters:

targetApplication - the target application or null if the vCards do not require any special processing (defaults to null)

isIncludeTrailingSemicolons

public Boolean isIncludeTrailingSemicolons()

Gets whether this writer will include trailing semicolon delimiters for structured property values whose list of values end with null or empty values. Examples of properties that use structured values are StructuredName and Address.

This setting exists for compatibility reasons and should not make a difference to consumers that correctly implement the vCard grammar.

Returns:

true to include the trailing semicolons, false not to, null to use the default behavior (defaults to false for vCard versions 2.1 and 3.0 and true for vCard version 4.0)

See Also:

Issue 57

setIncludeTrailingSemicolons

public void setIncludeTrailingSemicolons(Boolean include)

Sets whether to include trailing semicolon delimiters for structured property values whose list of values end with null or empty values. Examples of properties that use structured values are StructuredName and Address.

This setting exists for compatibility reasons and should not make a difference to consumers that correctly implement the vCard grammar.

Parameters:

include - true to include the trailing semicolons, false not to, null to use the default behavior (defaults to false for vCard versions 2.1 and 3.0 and true for vCard version 4.0)

See Also:

Issue 57

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 vCard versions 3.0 and 4.0.

Note that this encoding mechanism is defined separately from the vCard specification and may not be supported by the consumer of the vCard.

Returns:

true if circumflex accent encoding is enabled, false if not

See Also:

VObjectWriter.isCaretEncodingEnabled()

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 vCard versions 3.0 and 4.0.

Note that this encoding mechanism is defined separately from the vCard specification and may not be supported by the consumer of the vCard.

Parameters:

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

See Also:

VObjectWriter.setCaretEncodingEnabled(boolean)

_write

protected void _write(VCard vcard,
                      List<VCardProperty> propertiesToAdd)
               throws IOException

Description copied from class: StreamWriter

Writes a vCard to the stream.

Specified by:

_write in class StreamWriter

Parameters:

vcard - the vCard that is being written

propertiesToAdd - the properties to write

Throws:

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

flush

public void flush()
           throws IOException

Flushes the 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 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