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"));
calendar.getProperties().add(Version.VERSION_2_0);
calendar.getProperties().add(CalScale.GREGORIAN);

// Add events, etc..
	            

BEGIN:VCALENDAR
PRODID:-//Ben Fortuna//iCal4j 1.0//EN
VERSION:2.0
CALSCALE:GREGORIAN
END:VCALENDAR
            

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..
christmas.getProperties().getProperty(Property.DTSTART).getParameters().add(Value.DATE);
            

BEGIN:VEVENT
DTSTAMP:20050222T044240Z
DTSTART;VALUE=DATE:20051225
SUMMARY:Christmas Day
END:VEVENT
            

Working with TimeZones

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

• iCal4j includes its own set of timezone definitions, which are based on the defacto standard Olson timezone database. Whilst iCal4j's timezone identifiers may be identical to those provided by the Java API, there is no guarantee that the rules defining a timezone will match those used by a Java timezone.
• The default timezone for iCal4j is the same as the default Java timezone. This timezone is used where no iCal4j timezone is specified (i.e. floating time), and the relevant iCal4j object is not set as being in UTC time. Note that it is not recommended to use floating time values in externalisable calendars (i.e. calendars you want to import into another program), as it may lead to inconsistent handling of timezone information.
• iCal4j timezones are accessible via the applicable TimeZoneRegistry implementation. When parsing existing iCalendar data you should obtain the appropriate TimeZoneRegistry via the CalendarBuilder.getRegistry() method after calling CalendarBuilder.build(). In addition to the default iCal4j timezone definitions this registry instance will also provide you access to any timezones defined in the parsed iCalendar data stream. If you are creating a new calendar object you should call TimeZoneRegistryFactory.getInstance().createRegistry() to construct a default registry instance.
• You can provide your own TimeZoneRegistry implementation by sub-classing the TimeZoneRegistyFactory class and specifying the following system property:

  net.fortuna.ical4j.timezone.registry=<factory_class_name>

  This may be useful if you want to read and/or store your timezone definitions in a database.

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);
cal.clear(java.util.Calendar.MINUTE);
cal.clear(java.util.Calendar.SECOND);

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

BEGIN:VEVENT
DTSTAMP:20051105T094739Z
DTSTART;TZID=Australia/Melbourne:20051101T150000
SUMMARY:Melbourne Cup
END:VEVENT
                    

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.