iCal4j
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 `List`s, `Iterator`s, 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..

Output:

    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);

Output:

    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");

Output:

    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.