Home | Introduction | Wiki | Documentation | News | Support | Download | License

Introduction »

iCal4j may be used for modifying existing iCalendar data or creating new iCalendar data from scratch. Here you will find a few examples indicating the recommended usage of this library.

Usage »

Simply add the iCal4j jar file, the Commons Logging jar file, and the Commons Language jar file to your classpath.

Examples »

Parsing an iCalendar file

Support for parsing and building an iCalendar object model is provided by the CalendarParser and ContentHandler interfaces. You can provide your own implementations of either of these, or just use the default implementations as provided by the CalendarBuilder class. Note that CalendarBuilder is not thread-safe, and as such it is good practice to construct a new instance for each data stream you wish to parse (see Working with TimeZones for further reasons).

FileInputStream fin = new FileInputStream("mycalendar.ics");

CalendarBuilder builder = new CalendarBuilder();

Calendar calendar = builder.build(fin);

Iterating over a Calendar

The iCal4j API is designed to conform with the standard Java collections API as much as possible. As such, you will find that for searching and manipulating a calendar object model you can make use of familiar concepts such as Lists, Iterators, etc.

for (Iterator i = calendar.getComponents().iterator(); i.hasNext();) {
    Component component = (Component) i.next();
    System.out.println("Component [" + component.getName() + "]");

    for (Iterator j = component.getProperties().iterator(); j.hasNext();) {
        Property property = (Property) j.next();
        System.out.println("Property [" + property.getName() + ", " + property.getValue() + "]");

Creating a new calendar

Creating a new calendar is quite straight-forward, in that all you need to remember is that a Calendar contains a list of Properties and Components. A calendar must contain certain standard properties and at least one component to be valid. You can verify that a calendar is valid via the method Calendar.validate(). All iCal4j objects also override Object.toString(), so you can verify the resulting calendar data via this mechanism.

Calendar calendar = new Calendar();
calendar.getProperties().add(new ProdId("-//Ben Fortuna//iCal4j 1.0//EN"));

// Add events, etc..

PRODID:-//Ben Fortuna//iCal4j 1.0//EN

Creating an event

One of the more commonly used components is a VEvent. To create a VEvent you can either set the date value and properties manually or you can make use of the convenience constructors to initialise standard values.

java.util.Calendar cal = java.util.Calendar.getInstance();
cal.set(java.util.Calendar.MONTH, java.util.Calendar.DECEMBER);
cal.set(java.util.Calendar.DAY_OF_MONTH, 25);

VEvent christmas = new VEvent(new Date(cal.getTime()), "Christmas Day");
// initialise as an all-day event..

SUMMARY:Christmas Day

Working with TimeZones

Complete timezone support is now provided by iCal4j, which follows these basic principles:

TimeZoneRegistry registry = TimeZoneRegistryFactory.getInstance().createRegistry();
TimeZone timezone = registry.getTimeZone("Australia/Melbourne");

java.util.Calendar cal = java.util.Calendar.getInstance(timezone);
cal.set(java.util.Calendar.YEAR, 2005);
cal.set(java.util.Calendar.MONTH, java.util.Calendar.NOVEMBER);
cal.set(java.util.Calendar.DAY_OF_MONTH, 1);
cal.set(java.util.Calendar.HOUR_OF_DAY, 15);

DateTime dt = new DateTime(cal.getTime());
VEvent melbourneCup = new VEvent(dt, "Melbourne Cup");

SUMMARY:Melbourne Cup

Saving an iCalendar file

When saving an iCalendar file iCal4j will automatically validate your calendar object model to ensure it complies with the RFC2445 specification. If you would prefer not to validate your calendar data you can disable the validation by calling CalendarOutputter.setValidating(false).

FileOutputStream fout = new FileOutputStream("mycalendar.ics");

CalendarOutputter outputter = new CalendarOutputter();
outputter.output(calendar, fout);

More examples may be found in the API Documentation.