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);
Modifier and Type | Class and Description |
---|---|
class |
XCardDocument.XCardDocumentStreamWriter |
Constructor and Description |
---|
XCardDocument()
Creates an empty xCard document.
|
XCardDocument(Document document)
Wraps an existing XML DOM object.
|
XCardDocument(InputStream in)
Parses an xCard document from an input stream.
|
XCardDocument(Path file)
Parses an xCard document from a file.
|
XCardDocument(Reader reader)
Parses an xCard document from a reader.
|
XCardDocument(String xml)
Parses an xCard document from a string.
|
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.
|
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(Path file)
Writes the XML document to a file.
|
void |
write(Path file,
Integer indent)
Writes the XML document to a file.
|
void |
write(Path file,
Integer indent,
String xmlVersion)
Writes the XML document to a file.
|
void |
write(Path file,
Map<String,String> outputProperties)
Writes the XML document to a file.
|
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. |
public XCardDocument()
public XCardDocument(String xml) throws SAXException
xml
- the XML string to read the vCards fromSAXException
- if there's a problem parsing the XMLpublic XCardDocument(InputStream in) throws SAXException, IOException
in
- the input stream to read the vCards fromIOException
- if there's a problem reading from the input streamSAXException
- if there's a problem parsing the XMLpublic XCardDocument(Path file) throws SAXException, IOException
file
- the file to read the vCards fromIOException
- if there's a problem reading from the fileSAXException
- if there's a problem parsing the XMLpublic 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.
reader
- the reader to read the vCards fromIOException
- if there's a problem reading from the readerSAXException
- if there's a problem parsing the XMLpublic XCardDocument(Document document)
document
- the XML DOM that contains the xCard documentpublic StreamReader reader()
StreamReader
object that reads vCards from this XML
document.public XCardDocument.XCardDocumentStreamWriter writer()
StreamWriter
object that adds vCards to this XML
document.public Document getDocument()
public List<VCard> getVCards()
VCard
objects will NOT be applied to the XML document.public void addVCard(VCard vcard)
vcard
- the vCard to addIllegalArgumentException
- if no scribe has been registered for the
property (only applies to custom property classes)public String write(Integer indent)
indent
- the number of indent spaces to use for pretty-printing or
null to disable pretty-printing (disabled by default)public String write(Integer indent, String xmlVersion)
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)public String write(Map<String,String> outputProperties)
outputProperties
- properties to assign to the JAXP transformer (see
Transformer.setOutputProperty(java.lang.String, java.lang.String)
)public void write(OutputStream out) throws TransformerException
out
- the output stream (UTF-8 encoding will be used)TransformerException
- if there's a problem writing to the output
streampublic void write(OutputStream out, Integer indent) throws TransformerException
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)TransformerException
- if there's a problem writing to the output
streampublic void write(OutputStream out, Integer indent, String xmlVersion) throws TransformerException
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)TransformerException
- if there's a problem writing to the output
streampublic void write(OutputStream out, Map<String,String> outputProperties) throws TransformerException
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)
)TransformerException
- if there's a problem writing to the output
streampublic void write(Path file) throws TransformerException, IOException
file
- the file to write to (UTF-8 encoding will be used)TransformerException
- if there's a problem writing to the fileIOException
- if there's a problem writing to the filepublic void write(Path file, Integer indent) throws TransformerException, IOException
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)TransformerException
- if there's a problem writing to the fileIOException
- if there's a problem writing to the filepublic void write(Path file, Integer indent, String xmlVersion) throws TransformerException, IOException
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)TransformerException
- if there's a problem writing to the fileIOException
- if there's a problem writing to the filepublic void write(Path file, Map<String,String> outputProperties) throws TransformerException, IOException
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)
)TransformerException
- if there's a problem writing to the fileIOException
- if there's a problem writing to the filepublic void write(Writer writer) throws TransformerException
writer
- the writerTransformerException
- if there's a problem writing to the writerpublic void write(Writer writer, Integer indent) throws TransformerException
writer
- the writerindent
- the number of indent spaces to use for pretty-printing or
null to disable pretty-printing (disabled by default)TransformerException
- if there's a problem writing to the writerpublic void write(Writer writer, Integer indent, String xmlVersion) throws TransformerException
writer
- the writerindent
- 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)TransformerException
- if there's a problem writing to the writerpublic void write(Writer writer, Map<String,String> outputProperties) throws TransformerException
writer
- the writeroutputProperties
- properties to assign to the JAXP transformer (see
Transformer.setOutputProperty(java.lang.String, java.lang.String)
)TransformerException
- if there's a problem writing to the writerCopyright © 2012–2023 Michael Angstadt. All rights reserved.