Skip to content

Extensions

iCal4j Extensions is a Java library that provides support for widely used non-standard iCalendar objects (i.e. properties and parameters). These model extensions are implemented via the [object registry]]([ModelExtensions|custom) support in iCal4j.

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

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.

Comments