Introduction to iCal4j
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.
Parsing an iCalendar fileSupport for parsing and building an iCalendar object model is provided by the
ContentHandlerinterfaces. You can provide your own implementations of either of these, or just use the default implementations as provided by the
CalendarBuilderclass. Note that
CalendarBuilderis 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).
Iterating over a CalendarThe 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
Creating a new calendarCreating a new calendar is quite straight-forward, in that all you need to remember is that a
Calendarcontains a list of
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.
Creating an eventOne 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.
Working with TimeZonesComplete 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
TimeZoneRegistryimplementation. When parsing existing iCalendar data you should obtain the appropriate
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
TimeZoneRegistryimplementation by sub-classing the
TimeZoneRegistyFactoryclass 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.
Saving an iCalendar fileWhen 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