[opensourcedex]

ical4j is a free, open source scheduling & event management project written in Java and released under BSD-3-Clause. It has 837 GitHub stars, 218 forks and 162 open issues, and was last pushed 29 days ago. On this registry it ranks #18 of 23 tracked projects in Scheduling & Event Management, with 5 head-to-head comparisons available.

What is ical4j?

iCal4j is a BSD-3-Clause licensed Java library that reads and writes iCalendar data streams and exposes them as an object model, built for Java developers who need to handle calendar data such as events, appointments and to-do lists inside their own applications.

What it is

iCal4j is an open-source Java library that parses and builds iCalendar data models. The README describes it as a Java library used to read and write iCalendar data streams as defined in RFC2445, the standard that provides a common data format for calendar-specific information including events, appointments and to-do lists. The project lives in the Java ecosystem: it is distributed for Maven and Gradle builds, built with Gradle, and published under group and artifact coordinates org.mnode.ical4j:ical4j. Its topic list covers icalendar, java, library and scheduling.

The concrete problem is format handling. The iCalendar standard is supported by widely used calendaring tools such as Lotus Notes, Outlook and Apple's iCal, so an application that wants to exchange calendar data has to speak that format correctly. iCal4j replaces the work of writing and maintaining a bespoke iCalendar parser and serializer, providing a ready object model plus validators instead. It deliberately keeps the number of dependent libraries to a minimum for portability and compatibility with as many environments as possible, and it documents configuration options and compatibility hints rather than leaving deployment behaviour implicit.

Key capabilities

  • Reads and writes iCalendar data streams conforming to RFC2445, exposed through a documented Java object model and API documentation.
  • Covers a broad set of calendar specifications, with references in the README to RFC2445, RFC2446, RFC2447, RFC5545, RFC5546, RFC6047, RFC6868, RFC7808, RFC7953, RFC7986, RFC7529, RFC9073, RFC9074 and RFC9253.
  • Ships for Maven and Gradle under the coordinates org.mnode.ical4j:ical4j.
  • Validates calendar data through net.fortuna.ical4j.validate.Validator implementations, which use commons-collections4 to reduce duplication in validity checks.
  • Integrates with a logging stack through slf4j-api, a logging meta-library with integration to different logging framework implementations, used in all classes that require logging.
  • Supports multiple concurrent runtime baselines: version 4.x requires Java 11 or later, version 3.x requires Java 8 or later, and version 2.x requires Java 7 or later.
  • Provides custom equality support through commons-lang3, including custom equals() and hashcode() implementations.

Who uses it and how

  • Java teams adding calendar exchange to applications that already interoperate with tools such as Lotus Notes, Outlook and Apple's iCal through the shared iCalendar format.
  • Projects pinned to an older runtime, which the README accommodates directly: 3.x for Java 8 and 2.x for Java 7, rather than forcing an upgrade to the 4.x line.
  • Build pipelines that pull the artifact through Maven or Gradle, with the README covering both installation paths.
  • Developers who want worked scenarios before writing code, served by the examples on the official website and the API documentation hosted under ical4j.github.io.
  • Maintainers tracking behaviour changes between releases, using the release notes published as the CHANGELOG.

Getting started

Declare a dependency on org.mnode.ical4j:ical4j from Maven Central using either Maven or Gradle, on Java 11 or later for the 4.x line. Building from source is done with Gradle, and redistribution details are covered in the README.

How it compares

No comparable parsing library is named in the facts provided for this registry, so iCal4j stands alone here. The calendaring products the README does name, such as Lotus Notes, Outlook and Apple's iCal, are client applications that support the same iCalendar standard rather than substitutes for a Java parsing library — they are the software an integrating application exchanges data with.

When to use it — and when not to

A self-hoster operates a Java 11 or later runtime plus a logging implementation behind slf4j-api, along with commons-lang3 and commons-collections4, and optionally javax.cache.cache-api. Teams outside the Java ecosystem, or those wanting a hosted scheduling service rather than a library to embed, should not pick this project, and the 162 open issues suggest a project where unanswered reports accumulate. The README is also thin on the details that matter most to day-to-day users: it points to the open issues for goals and directions, keeps limitations, configuration options and compatibility hints in separate sections rather than the introduction, and references Java legacy date-time code, so anyone integrating it should read those sections before committing.

project readme (upstream, from github) — read inline

iCal4j - iCalendar parser and object model

Table of Contents
  1. Introduction - What is iCal4j?
  2. Setup - Download and installation of iCal4j
  3. Usage - The iCal4j object model and how to use it
  4. References
  5. Configuration options
  6. Development - Guide for contributing to the iCalj project

Introduction

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

  • For a concise description of the goals and directions of iCal4j please take a look at the open issues.

  • You will find examples of how to use iCal4j in the official website and throughout the API documentation.

  • Detailed descriptions of changes included in each release may be found in the CHANGELOG.

  • iCal4j was created with the help of Open Source software.

Setup

System requirements

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

Dependencies

In the interests of portability and compatibility with as many environments as possible, the number of dependent libraries for iCal4j is kept to a minimum. The following describes the required (and optional) dependencies and the functionality 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 custom equals() and hashcode() 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 in net.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 set a value for the net.fortuna.ical4j.timezone.cache.impl configuration

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

  • groovy-all [optional] - The runtime for the Groovy language. Required for library enhancements such as iCalendar object construction using the net.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, and is used only to generate version information in the javadoc API documentation.

Release Downloads

Install with Maven

Install with Gradle

Usage

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

References

  • RFC5545 - Internet Calendaring and Scheduling Core Object Specification (iCalendar)
  • RFC5546 - iCalendar Transport-Independent Interoperability Protocol (iTIP)
  • RFC6047 - iCalendar Message-Based Interoperability Protocol (iMIP)
  • RFC6868 - Parameter Value Encoding in iCalendar and vCard
  • RFC7953 - Calendar Availability
  • RFC7808 - Time Zone Data Distribution Service
  • RFC7986 - New Properties for iCalendar
  • RFC7529 - Non-Gregorian Recurrence Rules in iCalendar
  • RFC9073 - Event Publishing Extensions to iCalendar
  • RFC9074 - "VALARM" Extensions for iCalendar
  • RFC9253 - Support for iCalendar Relationships

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 C

readme truncated — read the full docs on github

Frequently asked questions

Is ical4j free to use?

ical4j is open source under the BSD-3-Clause licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does ical4j do?

A Java library for parsing and building iCalendar data models

What is ical4j written in?

ical4j is primarily written in Java. Its source is publicly available at https://github.com/ical4j/ical4j, and it has 837 GitHub stars.