xCal

iCalendar data can be encoded in XML. This format is called xCal. The xCal specification is defined in RFC 6321.

Reading XML-encoded iCalendar data

XCalReader

The XCalReader class handles the parsing of XML-encoded iCalendar data. The data is read in a streaming fashion, meaning it parses the data as it is read off the wire. This results in a smaller memory footprint than other approaches.

XCalReader automatically takes timezone data into account by parsing date/time values according to their assigned VTIMEZONE definition. See the Timezones page for more information on working with timezones.

Important methods

readNext()
Parses and returns the next ICalendar object in the data stream. The method returns null when the end of stream has been reached.

getWarnings()
Returns any problems the parser encountered while parsing the ICalendar object that was last returned by readNext(). Examples of things that could cause warnings are: malformed date values or unparseable property values.

close()
As with all I/O operations, it's important to call the close() method when you are done with the XCalReader object in order to properly close the input stream.

The example below outputs the start times and summaries of each event in an XML-encoded iCalendar data stream.

Note that, when outputting the start dates, the DateFormat object is not configured with a timezone. Therefore, the dates will be displayed in the user's local timezone. For example, if a date/time value has a time of 13:00 UTC, and the user's local timezone is 5 hours behind UTC, the time will be displayed as "08:00".

File file = new File("events.xml");
XCalReader reader = new XCalReader(file);
try {
	ICalendar ical;
	DateFormat df = new SimpleDateFormat("MM/dd/yyyy HH:mm");
	while ((ical = reader.readNext()) != null) {
		for (VEvent event : ical.getEvents()) {
			DateStart dateStart = event.getDateStart();
			String dateStartStr = (dateStart == null) ? null : df.format(dateStart.getValue());

			Summary summary = event.getSummary();
			String summaryStr = (summary == null) ? null : summary.getValue();

			if (summaryStr != null && dateStartStr != null) {
				System.out.println(dateStartStr + ": " + summaryStr);
				continue;
			}

			if (summaryStr != null){
				System.out.println(summaryStr);
				continue;
			}

			if (dateStartStr != null){
				System.out.println(dateStartStr);
				continue;
			}
		}
	}
} finally {
	reader.close();
}

XCalDocument

Alternatively, the XCalDocument class can be used to read XML-encoded iCalendar data. This class is essentially a wrapper for a org.w3c.dom.Document object, providing methods that read and write ICalendar objects from/to the DOM tree.

Important methods

getICalendars()
Parses all ICalendar objects that exist inside of the DOM tree.

getDocument()
Returns the wrapped Document object, giving you full control over the XML data.

The example below reads XML-encoded iCalendar data from the Internet and outputs the start times and summaries of each event.

InputStream in = new URL("http://example.com/events.xml").openStream();
XCalDocument document;
try {
	document = new XCalDocument(in);
} finally {
	in.close();
}

List<ICalendar> icals = document.getICalendars();
DateFormat df = new SimpleDateFormat("MM/dd/yyyy HH:mm");
for (ICalendar ical : icals){
	for (VEvent event : ical.getEvents()) {
		DateStart dateStart = event.getDateStart();
		String dateStartStr = (dateStart == null) ? null : df.format(dateStart.getValue());

		Summary summary = event.getSummary();
		String summaryStr = (summary == null) ? null : summary.getValue();

		if (summaryStr != null && dateStartStr != null) {
			System.out.println(dateStartStr + ": " + summaryStr);
			continue;
		}

		if (summaryStr != null){
			System.out.println(summaryStr);
			continue;
		}

		if (dateStartStr != null){
			System.out.println(dateStartStr);
			continue;
		}
	}
}

Writing XML-encoded iCalendar data

XCalWriter

The XCalWriter class handles the creation of XML-encoded iCalendar data.

By default, ICalWriter automatically formats all date/time values in UTC time, but this can be changed. See the Timezones page for more information on working with timezones.

Important methods

write()
Writes the contents of an ICalendar object to the data stream.

close()
As with all I/O operations, it's important to call the close() method when you are done with the XCalWriter object in order to properly close the output stream. It's especially important for XCalWriter because it must write the proper XML closing tags to properly close the XML document.

The example below writes a list of ICalendar objects to an XML file. The output will be pretty-printed, using an indentation string of 2 spaces.

List<ICalendar> icals = ...
File file = new File("events.xml");
XCalWriter writer = new XCalWriter(file, 2);
try {
	for (ICalendar ical : icals) {
		writer.write(ical);
	}
} finally {
	writer.close();
}

XCalDocument

Alternatively, the XCalDocument class can be used to write XML-encoded iCalendar data. This class is essentially a wrapper for a org.w3c.dom.Document object, providing methods that read and write ICalendar objects from/to the DOM tree.

Important methods

add()
Adds the contents of an ICalendar object to the XML DOM tree.

getDocument()
Returns the wrapped Document object, giving you full control over the XML data.

write()
Outputs the XML DOM tree to a string or output stream. This method is overloaded to allow you to customize the write process (for example, by specifying the number of indentation spaces to use to pretty-print the XML).

The example below writes a list of ICalendar objects to an XML file. The output will be pretty-printed, using an indentation string of 2 spaces.

List<ICalendar> icals = ...
XCalDocument document = new XCalDocument();
for (ICalendar ical : icals) {
	document.add(ical);
}

File file = new File("events.xml");
document.write(file, 2);