XUtils

iCal4j

Parse and build iCalendar [RFC 5545](https://tools.ietf.org/html/rfc5545) data models.

Java
https://github.com/ical4j/ical4j

Setup

System requirements

  • Version 4.x - Java 11 or later
  • Version 3.x - Java 8 or later
  • Version 2.x - Java 7 or later

Release Downloads

  • [mavenrepo]

Install with Maven

Install with Gradle

iCal4j 4.x (new Java Date/Time API)

The following table provides a comparison between the old and the new date/time API for creating dates and date-based properties:

Description New API Old API
DTSTART with date value new DtStart<>(LocalDate.now()) new DtStart(new org.mnode.ical4j.model.Date())
DTSTART with date-time value new DtStart<>(ZoneDateTime.now()) new DtStart(new org.mnode.ical4j.model.DateTime())
DTSTART with specific timezone new DtStart<>(ZonedDateTime.now(tzReg.getTimeZone("Australia/Melbourne").toZoneId())); dtStart = new DtStart(new org.mnode.ical4j.model.DateTime()); dtStart.setTimeZone(tzReg.getTimeZone("Australia/Melbourne"));
Parse a DATE-TIME string TemporalAdapter.parse("20130101T120000Z") new org.mnode.ical4j.model.DateTime("20130101T120000Z")
Parse a DATE string TemporalAdapter.parse("20200229") new org.mnode.ical4j.model.Date("20200229")

You may also find the [Java Legacy Date-Time Code] web page useful.

iCal4j 3.x (old Java Date API)

Examples

Configuration

net.fortuna.ical4j.parser=net.fortuna.ical4j.data.HCalendarParserFactory

net.fortuna.ical4j.timezone.registry=net.fortuna.ical4j.model.DefaultTimeZoneRegistryFactory

net.fortuna.ical4j.timezone.update.enabled={true|false}

net.fortuna.ical4j.factory.decoder=net.fortuna.ical4j.util.DefaultDecoderFactory

net.fortuna.ical4j.factory.encoder=net.fortuna.ical4j.util.DefaultEncoderFactory

net.fortuna.ical4j.recur.maxincrementcount=1000

net.fortuna.ical4j.timezone.cache.impl=net.fortuna.ical4j.util.MapTimeZoneCache

Compatibility Hints

Relaxed Parsing

ical4j.parsing.relaxed={true|false}

iCal4j now has the capability to “relax” its parsing rules to enable parsing of *.ics files that don’t properly conform to the iCalendar specification (RFC2445)

This property is intended as a general relaxation of parsing rules to allow for parsing otherwise invalid calendar files. Initially enabling this property will allow for the creation of properties and components with illegal names (e.g. Mozilla Calendar’s “X” property). Note that although this will allow for parsing calendars with illegal names, validation will still identify such names as an error in the calendar model.

  • You can relax iCal4j’s unfolding rules by specifying the following system property:

    ical4j.unfolding.relaxed={true|false}

Note that I believe this problem is not restricted to Mozilla calendaring products, but rather may be caused by UNIX/Linux-based applications relying on the default newline character (LF) to fold long lines (KOrganizer also seems to have this problem). This is, however, still incorrect as by definition long lines are folded using a (CRLF) combination.

I’ve obtained a couple of samples of non-standard iCalendar files that I’ve included in the latest release (0.9.11). There is a Sunbird, phpicalendar, and a KOrganizer sample there (open them in Notepad on Windows to see what I mean).

It seems that phpicalendar and KOrganizer always use LF instead of CRLF, and in addition KOrganizer seems to fold all property parameters and values (similar to Mozilla Calendar/Sunbird).

Mozilla Calendar/Sunbird uses CRLF to fold all property parameter/values, however it uses just LF to fold long lines (i.e. longer than 75 characters).

The latest release of iCal4j includes changes to UnfoldingReader that should work correctly with Mozilla Calendar/Sunbird, as long as the ical4j.unfolding.relaxed system property is set to true.

KOrganizer/phpicalendar files should also work with the relaxed property, although because ALL lines are separated with just LF it also relies on the StreamTokenizer to correctly identify LF as a newline on Windows, and CRLF as a newline on UNIX/Linux. The API documentation for Java 1.5 says that it does do this, so if you still see problems with parsing it could be a bug in the Java implementation.

The full set of system properties may be found in net.fortuna.ical4j.util.CompatibilityHints.

iCal4j and Timezones

Validation

ical4j.validation.relaxed={true|false}

Micosoft Outlook compatibility

ical4j.compatibility.outlook={true|false}

Behaviour:

  • Enforces a folding length of 75 characters (by default ical4j will fold at 73 characters)
  • Allows for spaces when parsing a WEEKDAY list

Microsoft Outlook also appears to provide quoted TZID parameter values, as follows:

DTSTART;TZID="Pacific Time (US & Canada),Tijuana":20041011T223000

Lotus Notes compatibility

ical4j.compatibility.notes={true|false}

Development

Building with Gradle

iCal4j includes the Gradle wrapper for a simpler and more consistent build.

Run unit tests

./gradlew clean test

Build a new release

./gradlew clean test release -Prelease.forceVersion=2.0.0

Upload release binaries and packages

RELEASE_VERSION=2.0.0 ./gradlew uploadArchives uploadDist

Articles

  • coming soon...