Skip to content

iCal4j Extensions

javadoc

Overview

iCal4j Extensions is a Java library that provides support for extension (and some non-standard) iCalendar properties and components. This includes support for CalDAV properties, common Calendar User Agents (CUAs) such as Microsoft Outlook, and convenience implementations of components and properties not explicitly defined in the core specifications.

This library also defines a collection of strategies, which are opinionated approaches to constructing iCalendar and vCard objects for common use-cases.

Usage

To add support for extensions you may register the required factories with your CalendarBuilder instance:

CalendarParser parser = CalendarParserFactory.getInstance().createParser();

PropertyFactoryRegistry propertyFactoryRegistry = new PropertyFactoryRegistry();
propertyFactoryRegistry.register(WrTimezone.PROPERTY_NAME, WrTimezone.FACTORY);
propertyFactoryRegistry.register(WrCalName.PROPERTY_NAME, WrCalName.FACTORY);

ParameterFactoryRegistry parameterFactoryRegistry = new ParameterFactoryRegistry();

TimeZoneRegistry tzRegistry = TimeZoneRegistryFactory.getInstance().createRegistry();

builder = new CalendarBuilder(parser, propertyFactoryRegistry, parameterFactoryRegistry, tzRegistry);

Minimum requirements

iCal4j Extensions requires a minimum of Java 5 due to the use of features introduced in this version. If you need to run on an earlier version of Java, consider using Retroweaver.

Project Information

Download

Traditionally any components, properties and parameters not defined by RFC2445 are classified as non-standard or extension objects. These objects must include the "X-" name prefix to be compliant with the specification.

In the iCal4j object model, these objects are represented by the XComponent, XProperty and XParameter classes respectively. Names that do not conform to the "X-" name prefix requirement may be supported by enabling the following Compatibility Hint:

ical4j.parsing.relaxed=true

Extension Factory Registration

There are a number of deficiences with above approach, most notably that only String values are supported by X{Component|Property|Parameter}, and there is no option for supporting some well-known non-standard objects.

PropertyFactoryRegistry

You can now add support for extension properties by registering custom PropertyFactory implementations:

PropertyFactory somePropertyFactory = ...

PropertyFactoryRegistry propertyFactoryRegistry = new PropertyFactoryRegistry();
propertyFactoryRegistry.register(somePropertyFactory);

CalendarBuilder builder = new CalendarBuilder(CalendarParserFactory.getInstance().createParser(),
    ComponentFactory.getInstance(),
    propertyFactoryRegistry,
    new ParameterFactoryRegistry(),
    TimeZoneRegistryFactory.getInstance().createRegistry());

Calendar calendar = builder.build(..);

ParameterFactoryRegistry

Extension parameters are also supported:

ParameterFactory someParameterFactory = ...

ParameterFactoryRegistry parameterFactoryRegistry = new ParameterFactoryRegistry();
parameterFactoryRegistry.register(someParameterFactory);

CalendarBuilder builder = new CalendarBuilder(CalendarParserFactory.getInstance().createParser(),
    ComponentFactory.getInstance(),
    new PropertyFactoryRegistry(),
    parameterFactoryRegistry,
    TimeZoneRegistryFactory.getInstance().createRegistry());

Calendar calendar = builder.build(..);

Common Extensions

A collection of commonly used iCalendar extension objects are available in the [[Extensions|ical4j-extensions]] sub-project.