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

See Also:

RFC 6321

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	XCalDocument.XCalDocumentStreamWriter

Constructor Summary

Constructors

Constructor and Description
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

Methods

Modifier and Type	Method and Description
void	add(ICalendar ical) Adds an iCalendar object to this XML document.
Document	getDocument() Gets the raw XML DOM object.
List<ICalendar>	getICalendars() Parses all iCalendar objects from this XML document.
StreamReader	reader() Creates a StreamReader object that parses iCalendar objects from this XML document.
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.
XCalDocument.XCalDocumentStreamWriter	writer() Creates a StreamWriter object that adds iCalendar objects to this XML document.

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

getDocument

public Document getDocument()

Gets the raw XML DOM object.

Returns:

the XML DOM

getICalendars

public List<ICalendar> getICalendars()

Parses all iCalendar objects from this XML document.

Returns:

the parsed iCalendar objects

add

public void add(ICalendar ical)

Adds an iCalendar object to this XML document.

Parameters:

ical - the iCalendar object to add

reader

public StreamReader reader()

Creates a StreamReader object that parses iCalendar objects from this XML document.

Returns:

the reader

writer

public XCalDocument.XCalDocumentStreamWriter writer()

Creates a StreamWriter object that adds iCalendar objects to this XML document.

Returns:

the writer

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