ezvcard.io.xml
Class XCardDocument

java.lang.Object
  ezvcard.io.xml.XCardDocument

public class XCardDocument
extends Object

Represents an XML document that contains vCard objects ("xCard" standard). This class can be used to read and write xCard documents.

Examples:

 String xml =
 "<vcards xmlns=\"urn:ietf:params:xml:ns:vcard-4.0\">" +
   "<vcard>" +
     "<fn>" +
       "<text>John Doe</text>" +
     "</fn>" +
     "<n>" +
       "<surname>Doe</surname>" +
        "<given>Johnathan</given>" +
        "<additional>Jonny</additional>" +
        "<additional>John</additional>" +
        "<prefix>Mr.</prefix>" +
        "<suffix />" +
      "</n>" +
    "</vcard>" +
 "</vcards>";
     
 //parsing an existing xCard document
 XCardDocument xcard = new XCardDocument(xml);
 List<VCard> vcards = xcard.parseAll();
 
 //creating an empty xCard document
 XCardDocument xcard = new XCardDocument();
 
 //VCard objects can be added at any time
 VCard vcard = ...
 xcard.add(vcard);
 
 //retrieving the raw XML DOM
 Document document = xcard.getDocument();
 
 //call one of the "write()" methods to output the xCard document
 File file = new File("johndoe.xml");
 xcard.write(file);
 

Author:

Michael Angstadt

See Also:

RFC 6351

Constructor Summary

XCardDocument()
Creates an xCard document.

XCardDocument(Document document)
Wraps an existing XML DOM object.

XCardDocument(File file)
Parses an xCard document from a file.

XCardDocument(InputStream in)
Parses an xCard document from an input stream.

XCardDocument(Reader reader)
Parses an xCard document from a reader.

XCardDocument(String xml)
Parses an xCard document from a string.

Method Summary

void	add(VCard vcard) Adds a vCard to the XML document.
Document	getDocument() Gets the XML document that was generated.
List<List<String>>	getParseWarnings() Gets the warnings from the last parse operation.
ScribeIndex	getScribeIndex() Gets the scribe index.
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	isVersionStrict() Gets whether properties that do not support xCard (vCard version 4.0) will be excluded from the written vCard.
List<VCard>	parseAll() Parses all the VCard objects from the xCard document.
VCard	parseFirst() Parses the first the VCard object from the xCard document.
void	registerParameterDataType(String parameterName, VCardDataType dataType) Registers the data type of an experimental parameter.
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	setScribeIndex(ScribeIndex index) Sets the scribe index.
void	setVersionStrict(boolean versionStrict) Sets whether properties that do not support xCard (vCard version 4.0) will be excluded from the written vCard.
String	write() Writes the XML document to a string without pretty-printing it.
void	write(File file) Writes the XML document to a file without pretty-printing it.
void	write(File file, int indent) Writes the XML document to a file and pretty-prints it.
String	write(int indent) Writes the XML document to a string and pretty-prints it.
void	write(OutputStream out) Writes the XML document to an output stream without pretty-printing it.
void	write(OutputStream out, int indent) Writes the XML document to an output stream and pretty-prints it.
void	write(Writer writer) Writes the XML document to a writer without pretty-printing it.
void	write(Writer writer, int indent) Writes the XML document to a writer and pretty-prints it.

Methods inherited from class java.lang.Object

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

Constructor Detail

XCardDocument

public XCardDocument()

Creates an xCard document.

XCardDocument

public XCardDocument(String xml)
              throws SAXException

Parses an xCard document from a string.

Parameters:

xml - the XML string to read the vCards from

Throws:

SAXException - if there's a problem parsing the XML

XCardDocument

public XCardDocument(InputStream in)
              throws SAXException,
                     IOException

Parses an xCard document from an input stream.

Parameters:

in - the input stream to read the vCards from

Throws:

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

SAXException - if there's a problem parsing the XML

XCardDocument

public XCardDocument(File file)
              throws SAXException,
                     IOException

Parses an xCard document from a file.

Parameters:

file - the file to read the vCards from

Throws:

IOException - if there's a problem reading from the file

SAXException - if there's a problem parsing the XML

XCardDocument

public XCardDocument(Reader reader)
              throws SAXException,
                     IOException

Parses an xCard document from a reader.

Note that use of this constructor is discouraged. It ignores the character encoding that is defined within the XML document itself, and should only be used if the encoding is undefined or if the encoding needs to be ignored for whatever reason. The XCardDocument(InputStream) constructor should be used instead, since it takes the XML document's character encoding into account when parsing.

Parameters:

reader - the reader to read the vCards from

Throws:

IOException - if there's a problem reading from the reader

SAXException - if there's a problem parsing the XML

XCardDocument

public XCardDocument(Document document)

Wraps an existing XML DOM object.

Parameters:

document - the XML DOM that contains the xCard document

Method Detail

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.

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.

Parameters:

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

isVersionStrict

public boolean isVersionStrict()

Gets whether properties that do not support xCard (vCard version 4.0) will be excluded from the written vCard.

Returns:

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

setVersionStrict

public void setVersionStrict(boolean versionStrict)

Sets whether properties that do not support xCard (vCard version 4.0) will be excluded from the written vCard.

Parameters:

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

getParseWarnings

public List<List<String>> getParseWarnings()

Gets the warnings from the last parse operation.

Returns:

the warnings (it is a "list of lists"--each parsed VCard object has its own warnings list)

See Also:

parseAll(), parseFirst()

registerParameterDataType

public void registerParameterDataType(String parameterName,
                                      VCardDataType dataType)

Registers the data type of an experimental parameter. Experimental parameters use the "unknown" data type by default.

Parameters:

parameterName - the parameter name (e.g. "x-foo")

dataType - the data type or null to remove

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

getDocument

public Document getDocument()

Gets the XML document that was generated.

Returns:

the XML document

parseAll

public List<VCard> parseAll()

Parses all the VCard objects from the xCard document.

Returns:

the vCard objects

parseFirst

public VCard parseFirst()

Parses the first the VCard object from the xCard document.

Returns:

the vCard object

write

public String write()

Writes the XML document to a string without pretty-printing it.

Returns:

the XML string

write

public String write(int indent)

Writes the XML document to a string and pretty-prints it.

Parameters:

indent - the number of indent spaces to use for pretty-printing

Returns:

the XML string

write

public void write(OutputStream out)
           throws TransformerException

Writes the XML document to an output stream without pretty-printing it.

Parameters:

out - the output stream

Throws:

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

write

public void write(OutputStream out,
                  int indent)
           throws TransformerException

Writes the XML document to an output stream and pretty-prints it.

Parameters:

out - the output stream

indent - the number of indent spaces to use for pretty-printing

Throws:

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

write

public void write(File file)
           throws TransformerException,
                  IOException

Writes the XML document to a file without pretty-printing it.

Parameters:

file - the file

Throws:

TransformerException - if there's a problem writing to the file

IOException - if there's a problem writing to the file

write

public void write(File file,
                  int indent)
           throws TransformerException,
                  IOException

Writes the XML document to a file and pretty-prints it.

Parameters:

file - the file stream

indent - the number of indent spaces to use for pretty-printing

Throws:

TransformerException - if there's a problem writing to the file

IOException - if there's a problem writing to the file

write

public void write(Writer writer)
           throws TransformerException

Writes the XML document to a writer without pretty-printing it.

Parameters:

writer - the writer

Throws:

TransformerException - if there's a problem writing to the writer

write

public void write(Writer writer,
                  int indent)
           throws TransformerException

Writes the XML document to a writer and pretty-prints it.

Parameters:

writer - the writer

indent - the number of indent spaces to use for pretty-printing

Throws:

TransformerException - if there's a problem writing to the writer

add

public void add(VCard vcard)

Adds a vCard to the XML document.

Parameters:

vcard - the vCard to add

Throws:

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