biweekly.io.xml
Class XCalDocument

java.lang.Object
  biweekly.io.xml.XCalDocument

public class XCalDocument
extends Object

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

Examples:

 String xml =
 "<?xml version=\"1.0\" encoding=\"utf-8\" ?>" +
 "<icalendar xmlns=\"urn:ietf:params:xml:ns:icalendar-2.0\">" +
   "<vcalendar>" +
     "<properties>" +
       "<prodid><text>-//Example Inc.//Example Client//EN</text></prodid>" +
       "<version><text>2.0</text></version>" +
     "</properties>" +
     "<components>" +
       "<vevent>" +
         "<properties>" +
           "<dtstart><date-time>2013-06-27T13:00:00Z</date-time></dtstart>" +
           "<dtend><date-time>2013-06-27T15:00:00Z</date-time></dtend>" +
           "<summary><text>Team Meeting</text></summary>" +
         "</properties>" +
       "</vevent>" +
     "</components>" +
   "</vcalendar>" +
 "</icalendar>";
     
 //parsing an existing xCal document
 XCalDocument xcal = new XCalDocument(xml);
 List<ICalendar> icals = xcal.parseAll();
 
 //creating an empty xCal document
 XCalDocument xcal = new XCalDocument();
 
 //ICalendar objects can be added at any time
 ICalendar ical = new ICalendar();
 xcal.add(ical);
 
 //retrieving the raw XML DOM
 Document document = xcal.getDocument();
 
 //call one of the "write()" methods to output the xCal document
 File file = new File("meeting.xml");
 xcal.write(file);
 

Author:

Michael Angstadt

Specification Reference:

RFC 6321

Constructor Summary

XCalDocument()
Creates an empty xCal document.

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

XCalDocument(File file)
Parses an xCal document from a file.

XCalDocument(InputStream in)
Parses an xCal document from an input stream.

XCalDocument(Reader reader)
Parses an xCal document from a reader.

XCalDocument(String xml)
Parses an xCal document from a string.

Method Summary

void	add(ICalendar ical) Adds an iCalendar object to the xCal document.
Document	getDocument() Gets the raw XML DOM object.
List<List<String>>	getParseWarnings() Gets the warnings from the last parse operation.
ICalMarshallerRegistrar	getRegistrar() Gets the object that manages the component/property marshaller objects.
List<ICalendar>	parseAll() Parses all the ICalendar objects from the xCal document.
ICalendar	parseFirst() Parses the first ICalendar object from the xCal document.
void	registerMarshaller(ICalComponentMarshaller<? extends ICalComponent> marshaller) Registers an experimental component marshaller.
void	registerMarshaller(ICalPropertyMarshaller<? extends ICalProperty> marshaller) Registers an experimental property marshaller.
void	registerParameterDataType(String parameterName, ICalDataType dataType) Registers the data type of an experimental parameter.
void	setRegistrar(ICalMarshallerRegistrar registrar) Sets the object that manages the component/property marshaller objects.
String	toString()
String	write() Writes the xCal document to a string without pretty-printing it.
void	write(File file) Writes the xCal document to a file without pretty-printing it.
void	write(File file, int indent) Writes the xCal document to a file and pretty-prints it.
String	write(int indent) Writes the xCal document to a string and pretty-prints it.
void	write(OutputStream out) Writes the xCal document to an output stream without pretty-printing it.
void	write(OutputStream out, int indent) Writes the xCal document to an output stream and pretty-prints it.
void	write(Writer writer) Writes the xCal document to a writer without pretty-printing it.
void	write(Writer writer, int indent) Writes the xCal document to a writer and pretty-prints it.

Methods inherited from class java.lang.Object

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

Constructor Detail

XCalDocument

public XCalDocument(String xml)
             throws SAXException

Parses an xCal document from a string.

Parameters:

xml - the xCal document in the form of a string

Throws:

SAXException - if there's a problem parsing the XML

XCalDocument

public XCalDocument(InputStream in)
             throws SAXException,
                    IOException

Parses an xCal document from an input stream.

Parameters:

in - the input stream to read the the xCal document from

Throws:

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

SAXException - if there's a problem parsing the XML

XCalDocument

public XCalDocument(File file)
             throws SAXException,
                    IOException

Parses an xCal document from a file.

Parameters:

file - the file containing the xCal document

Throws:

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

SAXException - if there's a problem parsing the XML

XCalDocument

public XCalDocument(Reader reader)
             throws SAXException,
                    IOException

Parses an xCal 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 XCalDocument(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 xCal document from

Throws:

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

SAXException - if there's a problem parsing the XML

XCalDocument

public XCalDocument(Document document)

Wraps an existing XML DOM object.

Parameters:

document - the XML DOM that contains the xCal document

XCalDocument

public XCalDocument()

Creates an empty xCal document.

Method Detail

registerMarshaller

public void registerMarshaller(ICalPropertyMarshaller<? extends ICalProperty> marshaller)

Registers an experimental property marshaller. Can also be used to override the marshaller of a standard property (such as DTSTART). Calling this method is the same as calling:

getRegistrar().register(marshaller).

Parameters:

marshaller - the marshaller to register

registerMarshaller

public void registerMarshaller(ICalComponentMarshaller<? extends ICalComponent> marshaller)

Registers an experimental component marshaller. Can also be used to override the marshaller of a standard component (such as VEVENT). Calling this method is the same as calling:

getRegistrar().register(marshaller).

Parameters:

marshaller - the marshaller to register

getRegistrar

public ICalMarshallerRegistrar getRegistrar()

Gets the object that manages the component/property marshaller objects.

Returns:

the marshaller registrar

setRegistrar

public void setRegistrar(ICalMarshallerRegistrar registrar)

Sets the object that manages the component/property marshaller objects.

Parameters:

registrar - the marshaller registrar

registerParameterDataType

public void registerParameterDataType(String parameterName,
                                      ICalDataType dataType)

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

Parameters:

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

dataType - the data type or null to remove

getDocument

public Document getDocument()

Gets the raw XML DOM object.

Returns:

the XML DOM

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 ICalendar object has its own warnings list)

See Also:

parseAll(), parseFirst()

parseAll

public List<ICalendar> parseAll()

Parses all the ICalendar objects from the xCal document.

Returns:

the iCalendar objects

parseFirst

public ICalendar parseFirst()

Parses the first ICalendar object from the xCal document.

Returns:

the iCalendar object or null if there are none

add

public void add(ICalendar ical)

Adds an iCalendar object to the xCal document. This marshals the ICalendar object to the XML DOM. This means that any changes that are made to the ICalendar object after calling this method will NOT be applied to the xCal document.

Parameters:

ical - the iCalendar object to add

Throws:

IllegalArgumentException - if the marshaller class for a component or property object cannot be found (only happens when an experimental property/component marshaller is not registered with the registerMarshaller method.)

write

public String write()

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

Returns:

the XML string

write

public String write(int indent)

Writes the xCal 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 xCal 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 xCal 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 xCal document to a file without pretty-printing it.

Parameters:

file - the file

Throws:

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

TransformerException - if there's a problem writing the XML

write

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

Writes the xCal 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:

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

TransformerException - if there's a problem writing the XML

write

public void write(Writer writer)
           throws TransformerException

Writes the xCal 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 xCal 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

toString

public String toString()

Overrides:

toString in class Object