ezvcard.io.text
Class VCardWriter

java.lang.Object
  ezvcard.io.text.VCardWriter

All Implemented Interfaces:

Closeable, Flushable

public class VCardWriter
extends Object
implements Closeable, Flushable

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

Example:

 VCard vcard1 = ...
 VCard vcard2 = ...
 
 File file = new File("vcard.vcf");
 VCardWriter vcardWriter = new VCardWriter(file);
 vcardWriter.write(vcard1);
 vcardWriter.write(vcard2);
 vcardWriter.close();
 

Author:

Michael Angstadt

Constructor Summary

VCardWriter(File file)
Creates a writer that writes vCards to a file (writes v3.0 vCards and uses the standard folding scheme and newline sequence).

VCardWriter(File file, boolean append)
Creates a writer that writes vCards to a file (writes v3.0 vCards and uses the standard folding scheme and newline sequence).

VCardWriter(File file, boolean append, VCardVersion targetVersion)
Creates a writer that writes vCards to a file (uses the standard folding scheme and newline sequence).

VCardWriter(File file, boolean append, VCardVersion targetVersion, FoldingScheme foldingScheme, String newline)
Creates a writer that writes vCards to a file.

VCardWriter(OutputStream out)
Creates a writer that writes vCards to an output stream (writes v3.0 vCards and uses the standard folding scheme and newline sequence).

VCardWriter(OutputStream out, VCardVersion targetVersion)
Creates a writer that writes vCards to an output stream (uses the standard folding scheme and newline sequence).

VCardWriter(OutputStream out, VCardVersion targetVersion, FoldingScheme foldingScheme, String newline)
Creates a writer that writes vCards to an output stream.

VCardWriter(Writer writer)
Creates a writer that writes vCards to a writer (writes v3.0 vCards and uses the standard folding scheme and newline sequence).

VCardWriter(Writer writer, VCardVersion targetVersion)
Creates a writer that writes vCards to a writer (uses the standard folding scheme and newline sequence).

VCardWriter(Writer writer, VCardVersion targetVersion, FoldingScheme foldingScheme, String newline)
Creates a writer that writes vCards to a writer.

Method Summary

void	close() Closes the underlying Writer object.
void	flush() Flushes the underlying Writer object.
FoldingScheme	getFoldingScheme() Gets the rules for how each line is folded.
String	getNewline() Gets the newline sequence that is used to separate lines.
ScribeIndex	getScribeIndex() Gets the scribe index.
VCardVersion	getTargetVersion() Gets the version that the vCards should adhere to.
boolean	isAddProdId() Gets whether or not a "PRODID" property will be added to each vCard, saying that the vCard was generated by this library.
boolean	isCaretEncodingEnabled() Gets whether the writer will apply circumflex accent encoding on parameter values (disabled by default, only applies to 3.0 and 4.0 vCards).
boolean	isVersionStrict() Gets whether properties that do not support the target version will be excluded from the written vCard.
void	registerScribe(VCardPropertyScribe<? extends VCardProperty> scribe) Registers a property scribe.
void	setAddProdId(boolean addProdId) Sets whether or not to add a "PRODID" property to each vCard, saying that the vCard was generated by this library.
void	setCaretEncodingEnabled(boolean enable) Sets whether the writer will apply circumflex accent encoding on parameter values (disabled by default, only applies to 3.0 and 4.0 vCards).
void	setScribeIndex(ScribeIndex index) Sets the scribe index.
void	setTargetVersion(VCardVersion targetVersion) Sets the version that the vCards should adhere to.
void	setVersionStrict(boolean versionStrict) Sets whether properties that do not support the target version will be excluded from the written vCard.
void	write(VCard vcard) Writes a vCard to the stream.

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)

Creates a writer that writes vCards to an output stream (writes v3.0 vCards and uses the standard folding scheme and newline sequence).

Parameters:

out - the output stream to write the vCard to

VCardWriter

public VCardWriter(OutputStream out,
                   VCardVersion targetVersion)

Creates a writer that writes vCards to an output stream (uses the standard folding scheme and newline sequence).

Parameters:

out - the output stream to write the vCard 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(OutputStream out,
                   VCardVersion targetVersion,
                   FoldingScheme foldingScheme,
                   String newline)

Creates a writer that writes vCards to an output stream.

Parameters:

out - the output stream to write the vCard to

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

foldingScheme - the folding scheme to use or null not to fold at all

newline - the newline sequence to use

VCardWriter

public VCardWriter(File file)
            throws IOException

Creates a writer that writes vCards to a file (writes v3.0 vCards and uses the standard folding scheme and newline sequence).

Parameters:

file - the file to write the vCard to

Throws:

IOException - if there's a problem opening the file

VCardWriter

public VCardWriter(File file,
                   boolean append)
            throws IOException

Creates a writer that writes vCards to a file (writes v3.0 vCards and uses the standard folding scheme and newline sequence).

Parameters:

file - the file to write the vCard to

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

Throws:

IOException - if there's a problem opening the file

VCardWriter

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

Creates a writer that writes vCards to a file (uses the standard folding scheme and newline sequence).

Parameters:

file - the file to write the vCard 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(File file,
                   boolean append,
                   VCardVersion targetVersion,
                   FoldingScheme foldingScheme,
                   String newline)
            throws IOException

Creates a writer that writes vCards to a file.

Parameters:

file - the file to write the vCard 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)

foldingScheme - the folding scheme to use or null not to fold at all

newline - the newline sequence to use

Throws:

IOException - if there's a problem opening the file

VCardWriter

public VCardWriter(Writer writer)

Creates a writer that writes vCards to a writer (writes v3.0 vCards and uses the standard folding scheme and newline sequence).

Parameters:

writer - the writer to write the vCard to

VCardWriter

public VCardWriter(Writer writer,
                   VCardVersion targetVersion)

Creates a writer that writes vCards to a writer (uses the standard folding scheme and newline sequence).

Parameters:

writer - the writer to write the vCard to

targetVersion - the version that the vCards should conform to

VCardWriter

public VCardWriter(Writer writer,
                   VCardVersion targetVersion,
                   FoldingScheme foldingScheme,
                   String newline)

Creates a writer that writes vCards to a writer.

Parameters:

writer - the writer to write the vCard to

targetVersion - the version that the vCards should conform to

foldingScheme - the folding scheme to use or null not to fold at all

newline - the newline sequence to use

Method Detail

getTargetVersion

public VCardVersion getTargetVersion()

Gets the version that the vCards should adhere to.

Returns:

the vCard version

setTargetVersion

public void setTargetVersion(VCardVersion targetVersion)

Sets the version that the vCards should adhere to.

Parameters:

targetVersion - the vCard version

isAddProdId

public boolean isAddProdId()

Gets whether or not a "PRODID" property will be added to each vCard, saying that the vCard was generated by this library. For 2.1 vCards, the extended property "X-PRODID" will be added, since "PRODID" is not supported by that version.

Returns:

true if the property will be added, false if not (defaults to true)

setAddProdId

public void setAddProdId(boolean addProdId)

Sets whether or not to add a "PRODID" property to each vCard, saying that the vCard was generated by this library. For 2.1 vCards, the extended property "X-PRODID" will be added, since "PRODID" is not supported by that version.

Parameters:

addProdId - true to add this property, false not to (defaults to true)

isVersionStrict

public boolean isVersionStrict()

Gets whether properties that do not support the target version will be excluded from the written vCard.

Returns:

true to exclude properties that do not support the target version, false to include them anyway (defaults to true)

setVersionStrict

public void setVersionStrict(boolean versionStrict)

Sets whether properties that do not support the target version will be excluded from the written vCard.

Parameters:

versionStrict - true to exclude properties that do not support the target version, false to include them anyway (defaults to true)

isCaretEncodingEnabled

public boolean isCaretEncodingEnabled()

Gets whether the writer will apply circumflex accent encoding on parameter values (disabled by default, only applies to 3.0 and 4.0 vCards). This escaping mechanism allows for newlines and double quotes to be included in parameter values.

When disabled, the writer will replace newlines with spaces and double quotes with single quotes.

Returns:

true if circumflex accent encoding is enabled, false if not

See Also:

VCardRawWriter.isCaretEncodingEnabled()

setCaretEncodingEnabled

public void setCaretEncodingEnabled(boolean enable)

Sets whether the writer will apply circumflex accent encoding on parameter values (disabled by default, only applies to 3.0 and 4.0 vCards). This escaping mechanism allows for newlines and double quotes to be included in parameter values.

When disabled, the writer will replace newlines with spaces and double quotes with single quotes.

Parameters:

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

See Also:

VCardRawWriter.setCaretEncodingEnabled(boolean)

getNewline

public String getNewline()

Gets the newline sequence that is used to separate lines.

Returns:

the newline sequence

getFoldingScheme

public FoldingScheme getFoldingScheme()

Gets the rules for how each line is folded.

Returns:

the folding scheme or null if the lines are not folded

registerScribe

public void registerScribe(VCardPropertyScribe<? extends VCardProperty> scribe)

Registers a property scribe. This is the same as calling:

getScribeIndex().register(scribe)

Parameters:

scribe - the scribe to register

getScribeIndex

public ScribeIndex getScribeIndex()

Gets the scribe index.

Returns:

the scribe index

setScribeIndex

public void setScribeIndex(ScribeIndex index)

Sets the scribe index.

Parameters:

index - the scribe index

write

public void write(VCard vcard)
           throws IOException

Writes a vCard to the stream.

Parameters:

vcard - the vCard to write

Throws:

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

IllegalArgumentException - if a scribe hasn't been registered for a custom property class (see: registerScribe(ezvcard.io.scribe.VCardPropertyScribe))

flush

public void flush()
           throws IOException

Flushes the underlying Writer object.

Specified by:

flush in interface Flushable

Throws:

IOException - if there's a problem flushing the writer

close

public void close()
           throws IOException

Closes the underlying Writer object.

Specified by:

close in interface Closeable

Throws:

IOException - if there's a problem closing the writer