Repository files navigation

1. Introduction - What is iCal4j?
2. Setup - Download and installation of iCal4j
   • System requirements - What is required to use iCal4j
   • Release downloads - Where to get iCal4j
   • Install with Maven
   • Install with Gradle
3. Usage - The iCal4j object model and how to use it
   • Examples - common usage scenarios
4. Reference - Specification
   • Specifications
5. Configuration options
   • Compatibility Hints
6. Limitations - CUA compatibility, etc.
7. Development - Guide for contributing to the iCalj project
   • Building with Gradle
   • Redistribution
   • Contributing to iCal4j

iCal4j is a Java library used to read and write iCalendar data streams as defined inRFC2445. The iCalendar standardprovides a common data format used to store information about calendar-specific data such as events, appointments, to-dolists, etc. All of the popular calendaring tools, such as Lotus Notes, Outlook and Apple's iCal also support the iCalendarstandard.

• For a concise description of the goals and directions of iCal4j pleasetake a look at theopen issues.

• You will find examples of how to use iCal4j inthe wikiand throughout theAPI documentation.

• Detailed descriptions of changes included in each release may be foundin theCHANGELOG.

• iCal4j was created with the help ofOpen Source software.

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

In the interests of portability and compatibility with as many environments as possible, the number of dependentlibraries for iCal4j is kept to a minimum. The following describes the required (and optional) dependencies and thefunctionality they provide.

• slf4j-api [required] - A logging meta-library with integration to different logging framework implementations. Used in all classes that require logging.

• commons-lang3 [required] - Provides enhancements to the standard Java library, including support for customequals() andhashcode()implementations. Used in all classes requiring custom equality implementations.

• commons-collections4 [required] - Provides enhancements to the standard Java collections API, including support for closures. Used innet.fortuna.ical4j.validate.Validator implementations to reduce the duplication of code in validity checks.

• javax.cache.cache-api [optional*] - Supports caching timzeone definitions. * NOTE: when not included you must seta value for thenet.fortuna.ical4j.timezone.cache.impl configuration

• commons-codec [optional] - Provides support for encoding and decoding binary data in text form. Used innet.fortuna.ical4j.model.property.Attach

• groovy-all [optional] - The runtime for the Groovy language. Required for library enhancements such as iCalendar object construction usingthenet.fortuna.ical4j.model.ContentBuilder DSL. This library is optional for all non-Groovy features of iCal4j.

• bndlib [optional] - A tool for generating OSGi library metadata and packaging OSGi bundles. This library is not a runtime requirement, andis used only to generate version information in the javadoc API documentation.

• Bintray Releases

• RFC5545 (SupersedesRFC2445)
• RFC5546 (SupersedesRFC2446)
• RFC5547 (SupersedesRFC2447)

net.fortuna.ical4j.parser=net.fortuna.ical4j.data.HCalendarParserFactorynet.fortuna.ical4j.timezone.registry=net.fortuna.ical4j.model.DefaultTimeZoneRegistryFactorynet.fortuna.ical4j.timezone.update.enabled={true|false}net.fortuna.ical4j.factory.decoder=net.fortuna.ical4j.util.DefaultDecoderFactorynet.fortuna.ical4j.factory.encoder=net.fortuna.ical4j.util.DefaultEncoderFactorynet.fortuna.ical4j.recur.maxincrementcount=1000net.fortuna.ical4j.timezone.cache.impl=net.fortuna.ical4j.util.MapTimeZoneCache

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 parsingotherwise invalid calendar files. Initially enabling this property will allow for thecreation 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 calendaringproducts, but rather may be caused by UNIX/Linux-based applications relying on thedefault newline character (LF) to fold long lines (KOrganizer also seems to have thisproblem). This is, however, still incorrect as by definition long lines are foldedusing a (CRLF) combination.

I've obtained a couple of samples of non-standard iCalendar files that I've includedin the latest release (0.9.11). There is a Sunbird, phpicalendar, and a KOrganizersample 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 inaddition KOrganizer seems to fold all property parameters and values (similar toMozilla Calendar/Sunbird).

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

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

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

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

net.fortuna.ical4j.timezone.date.floating={true|false}

Supporting timezones in an iCalendar implementation can be a complicated process,mostly due to the fact that there is not a definitive list of timezone definitionsused by all iCalendar implementations. This means that an iCalendar file may beproduced by one implementation and, if the file does not include all definitionsfor timezones relevant to the calendar properties, an alternate implementationmay not know how to interpret the timezone identified in the calendar (or worse,it may interpret the timezone differently to the original implementation). Allof these possibilities mean unpredictable behaviour which, to put it nicely, isnot desireable.

iCal4j approaches the problem of timezones in two ways: The first and by far thepreferred approach is for iCalendar files to include definitions for all timezonesreferenced in the calendar object. To support this, when an existing calendar isparsed a list of VTimeZone definitions contained in the calendar is constructed.This list may then be queried whenever a VTimeZone definition is required.

The second approach is to rely on a registry of VTimeZone definitions. iCal4jincludes a default registry of timezone definitions (derived from the Olson timezonedatabase - a defacto standard for timezone definitions), or you may also provide yourown registry implementation from which to retreieve timezones. This approach isrequired when constructing new iCalendar files.

Note that the intention of the iCal4j model is not to provide continuous validationfeedback for every change in the model. For this reason you are free to changetimezones on Time objects, remove or add TzId parameters, remove or add VTimeZonedefinitions, etc. without restriction. However when validation is run (automaticallyon output of the calendar) you will be notified if the changes are invalid.

ical4j.validation.relaxed={true|false}

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

ical4j.compatibility.notes={true|false}

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

If you intend to use and distribute iCal4j in your own project pleasefollow these very simple guidelines:

• Make a copy of the LICENSE, rename it to LICENSE.ical4j, and saveit to the directory where you are re-distributing the iCal4j JAR.

• I don't recommend extracting the iCal4j classes from its JAR and packagein another JAR along with other classes. It may lead to version incompatibilitesin the future. Rather I would suggest to include the ical4j.jar in your classpathas required.

Open source software is made stronger by the community that supports it. Through participation you not only contribute to the quality of the software, but also gain a deeper insight into the inner workings.

Contributions may be in the form of feature enhancements, bug fixes, test cases, documentation and forum participation. If you have a question, just ask. If you have an answer, write it down.

And if you are somehow constrained from participation, through corporate policy or otherwise, consider financial support. After all, if you are profiting from open source it's only fair to give something back to the community that make it all possible.