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.getVCards();
 
 //creating an empty xCard document
 XCardDocument xcard = new XCardDocument();
 
 //VCard objects can be added at any time
 VCard vcard = ...
 xcard.addVCard(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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	XCardDocument.XCardDocumentStreamWriter

Constructor Summary

Constructors

Constructor and Description
XCardDocument() Creates an empty 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

Modifier and Type	Method and Description
void	addVCard(VCard vcard) Adds a vCard to the XML document.
Document	getDocument() Gets the wrapped XML document.
List<VCard>	getVCards() Parses all of the vCards from this XML document.
StreamReader	reader() Creates a StreamReader object that reads vCards from this XML document.
String	write() Writes the XML document to a string.
void	write(File file) Writes the XML document to a file.
void	write(File file, Integer indent) Writes the XML document to a file.
void	write(File file, Integer indent, String xmlVersion) Writes the XML document to a file.
void	write(File file, Map<String,String> outputProperties) Writes the XML document to a file.
String	write(Integer indent) Writes the XML document to a string.
String	write(Integer indent, String xmlVersion) Writes the XML document to a string.
String	write(Map<String,String> outputProperties) Writes the XML document to a string.
void	write(OutputStream out) Writes the XML document to an output stream.
void	write(OutputStream out, Integer indent) Writes the XML document to an output stream.
void	write(OutputStream out, Integer indent, String xmlVersion) Writes the XML document to an output stream.
void	write(OutputStream out, Map<String,String> outputProperties) Writes the XML document to an output stream.
void	write(Writer writer) Writes the XML document to a writer.
void	write(Writer writer, Integer indent) Writes the XML document to a writer.
void	write(Writer writer, Integer indent, String xmlVersion) Writes the XML document to a writer.
void	write(Writer writer, Map<String,String> outputProperties) Writes the XML document to a writer.
XCardDocument.XCardDocumentStreamWriter	writer() Creates a StreamWriter object that adds vCards to this XML document.

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 empty 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 is preferred, 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

reader

public StreamReader reader()

Creates a StreamReader object that reads vCards from this XML document.

Returns:

the reader

writer

public XCardDocument.XCardDocumentStreamWriter writer()

Creates a StreamWriter object that adds vCards to this XML document.

Returns:

the writer

getDocument

public Document getDocument()

Gets the wrapped XML document.

Returns:

the XML document

getVCards

public List<VCard> getVCards()

Parses all of the vCards from this XML document. Modifications made to these VCard objects will NOT be applied to the XML document.

Returns:

the parsed vCards

addVCard

public void addVCard(VCard vcard)

Adds a vCard to the XML document.

Parameters:

vcard - the vCard to add

Throws:

IllegalArgumentException - if no scribe has been registered for the property (only applies to custom property classes)

write

public String write()

Writes the XML document to a string.

Returns:

the XML string

write

public String write(Integer indent)

Writes the XML document to a string.

Parameters:

indent - the number of indent spaces to use for pretty-printing or null to disable pretty-printing (disabled by default)

Returns:

the XML string

write

public String write(Integer indent,
                    String xmlVersion)

Writes the XML document to a string.

Parameters:

indent - the number of indent spaces to use for pretty-printing or null to disable pretty-printing (disabled by default)

xmlVersion - the XML version to use (defaults to "1.0") (Note: Many JDKs only support 1.0 natively. For XML 1.1 support, add a JAXP library like xalan to your project)

Returns:

the XML string

write

public String write(Map<String,String> outputProperties)

Writes the XML document to a string.

Parameters:

outputProperties - properties to assign to the JAXP transformer (see Transformer.setOutputProperty(java.lang.String, java.lang.String))

Returns:

the XML string

write

public void write(OutputStream out)
           throws TransformerException

Writes the XML document to an output stream.

Parameters:

out - the output stream (UTF-8 encoding will be used)

Throws:

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

write

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

Writes the XML document to an output stream.

Parameters:

out - the output stream (UTF-8 encoding will be used)

indent - the number of indent spaces to use for pretty-printing or null to disable pretty-printing (disabled by default)

Throws:

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

write

public void write(OutputStream out,
                  Integer indent,
                  String xmlVersion)
           throws TransformerException

Writes the XML document to an output stream.

Parameters:

out - the output stream (UTF-8 encoding will be used)

indent - the number of indent spaces to use for pretty-printing or null to disable pretty-printing (disabled by default)

xmlVersion - the XML version to use (defaults to "1.0") (Note: Many JDKs only support 1.0 natively. For XML 1.1 support, add a JAXP library like xalan to your project)

Throws:

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

write

public void write(OutputStream out,
                  Map<String,String> outputProperties)
           throws TransformerException

Writes the XML document to an output stream.

Parameters:

out - the output stream (UTF-8 encoding will be used)

outputProperties - properties to assign to the JAXP transformer (see Transformer.setOutputProperty(java.lang.String, java.lang.String))

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.

Parameters:

file - the file to write to (UTF-8 encoding will be used)

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,
                  Integer indent)
           throws TransformerException,
                  IOException

Writes the XML document to a file.

Parameters:

file - the file to write to (UTF-8 encoding will be used)

indent - the number of indent spaces to use for pretty-printing or null to disable pretty-printing (disabled by default)

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,
                  Integer indent,
                  String xmlVersion)
           throws TransformerException,
                  IOException

Writes the XML document to a file.

Parameters:

file - the file to write to (UTF-8 encoding will be used)

indent - the number of indent spaces to use for pretty-printing or null to disable pretty-printing (disabled by default)

xmlVersion - the XML version to use (defaults to "1.0") (Note: Many JDKs only support 1.0 natively. For XML 1.1 support, add a JAXP library like xalan to your project)

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,
                  Map<String,String> outputProperties)
           throws TransformerException,
                  IOException

Writes the XML document to a file.

Parameters:

file - the file to write to (UTF-8 encoding will be used)

outputProperties - properties to assign to the JAXP transformer (see Transformer.setOutputProperty(java.lang.String, java.lang.String))

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.

Parameters:

writer - the writer

Throws:

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

write

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

Writes the XML document to a writer.

Parameters:

writer - the writer

indent - the number of indent spaces to use for pretty-printing or null to disable pretty-printing (disabled by default)

Throws:

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

write

public void write(Writer writer,
                  Integer indent,
                  String xmlVersion)
           throws TransformerException

Writes the XML document to a writer.

Parameters:

writer - the writer

indent - the number of indent spaces to use for pretty-printing or null to disable pretty-printing (disabled by default)

xmlVersion - the XML version to use (defaults to "1.0") (Note: Many JDKs only support 1.0 natively. For XML 1.1 support, add a JAXP library like xalan to your project)

Throws:

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

write

public void write(Writer writer,
                  Map<String,String> outputProperties)
           throws TransformerException

Writes the XML document to a writer.

Parameters:

writer - the writer

outputProperties - properties to assign to the JAXP transformer (see Transformer.setOutputProperty(java.lang.String, java.lang.String))

Throws:

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