Ben Fortuna\\’s iCal4J library is a well-established Java implementation
\nof the RFC 5545 international standard for calendar events. In this
\narticle I will show you how to use iCal4J to create a iCalendar event in
\nJava and export it to a .ics file, and how to read in a .ics file and
\nextract the useful information out of it. ICalendar files can be
\nimported into the popular calendar applications including Microsoft
\nOutlook\u2122 and Google Calendar\u2122.<\/p>\n
Put the file in your Java resources directory and call it
\nical4j.properties. Add the following key-value pairs:<\/p>\n
net.fortuna.ical4j.timezone.cache.impl=net.fortuna.ical4j.util.MapTimeZoneCache<\/code><\/pre>\nGenerating a .ics File<\/h2>\n
Note: iCal4J has several classes which have the same name as date and
\ntime classes in the Java standard library, such as Calendar, Date,
\nTimeZone, and Duration. For clarity, where I reference Java standard
\nlibrary date and time classes, in order to distinguish them from iCal4J
\nI have used fully-qualified class names, eg java.time.Duration.<\/p>\n
First we will create an empty iCalendar, and then we will start to add
\ndifferent types of events to it.<\/p>\n
\/\/Create an iCal4J Calendar\nCalendar c = new Calendar();\n\/\/"EN" is the language.\nc.getProperties().add(new ProdId("-\/\/Company Name\/\/Product name and version\/\/EN"));\nc.getProperties().add(Version.VERSION_2_0);\nc.getProperties().add(CalScale.GREGORIAN);\n\n\/\/Add an event to the calendar\nc.getComponents().add(\/* next you will create an event to add here *\/ null );\nString icsExport = c.toString();<\/code><\/pre>\nIf you take a look at the contents of the icsExport String in your
\ndebugger (or print it to the console) you will see an iCalendar file.
\nYou may find it to be more readable if you copy it into a text editor.<\/p>\n
Now we will create a simple, single event (non-recurring) which starts
\non 5th<\/sup> March 2021 at midday Australian Eastern Daylight Savings Time,
\nand lasts for one hour.<\/p>\nprivate VEvent oneHourSingleEvent() {\n \/\/Create a new calendar event that starts on 5th March 2021 at midday Australian Eastern Daylight Savings Time and goes for 1 hour.\n VEvent vEvent = new VEvent();\n PropertyList<Property> eventProps = vEvent.getProperties();\n java.time.ZonedDateTime now = java.time.ZonedDateTime.now();\n\n \/\/Create a unique ID for the event\n String uidTimestamp = java.time.format.DateTimeFormatter\n .ofPattern("uuuuMMdd'T'hhmmssXX")\n .format(now);\n \/\/In the real world this could be a number from a generated sequence:\n String uidSequence = "\/" + (int) Math.ceil(Math.random() * 1000);\n String uidDomain = "@your.domain.com";\n eventProps.add(new Uid(uidTimestamp + uidSequence + uidDomain));\n\n \/\/Add a start datetime and a duration\n TimeZoneRegistry tzReg = TimeZoneRegistryFactory.getInstance().createRegistry();\n TimeZone timezone = tzReg.getTimeZone("Australia\/Sydney");\n try {\n eventProps.add(new DtStart(new DateTime("20210305T120000", timezone)));\n } catch (ParseException e) {\n e.printStackTrace();\n }\n eventProps.add(new Duration(java.time.Duration.ofHours(1)));\n\n \/\/Add title and description\n eventProps.add(new Summary("The title of the event"));\n eventProps.add(new Description("Some longer description of the event."));\n return vEvent;\n}<\/code><\/pre>\nNext, add this event to the calendar, run it and view the result.<\/p>\n
c.getComponents().add(oneHourSingleEvent());<\/code><\/pre>\nIt should look something like the iCalendar below. Note that each line
\nterminates with a carriage return and a new line character, \\r\\n. If
\nyou copy+paste the example below for use as a test, make sure to include
\nthe correct line terminators or it may be invalid!<\/p>\n
BEGIN:VCALENDAR\nPRODID:-\/\/Your Company Name\/\/Your product name and version\/\/EN\nVERSION:2.0\nCALSCALE:GREGORIAN\nBEGIN:VEVENT\nDTSTAMP:20210305T061107Z\nUID:20210305T051107+1100\/633@your.domain.com\nDTSTART;TZID=Australia\/Sydney:20210305T120000\nDURATION:PT1H\nSUMMARY:The title of the event\nDESCRIPTION:Some longer description of the event.\nEND:VEVENT\nEND:VCALENDAR<\/code><\/pre>\nTry saving the event in a text file with a .ics extension, and importing
\nit into your favourite calendar application.<\/p>\n
Parsing a .ics file<\/h2>\n
Parsing a .ics file is very simple. The CalendarBuilder takes any object
\nwhich implements Reader, which could be a FileReader or, as in the
\nexample below, a StringReader. You can use the code that you\\’ve already
\nwritten so far in this tutorial to inject a valid serialised iCalendar
\nstring, so you don\\’t need to worry about getting the line terminators
\nright (remember \\r\\n!). The example parses the calendar, validates it,
\nand pulls out the useful attributes that we had added earlier, so that
\nyou have an idea of how it works.<\/p>\n
public Calendar importCalendar(String calendarSerialized) throws Exception {\n Calendar c = new CalendarBuilder().build(new StringReader(calendarSerialized));\n c.validate();\n VEvent event = (VEvent) c.getComponent(Component.VEVENT);\n DtStamp dtStamp = event.getDateStamp();\n Uid uid = event.getUid();\n DtStart startDate = event.getStartDate();\n String tz = startDate.getTimeZone().getVTimeZone().getTimeZoneId().getValue();\n PropertyList props = event.getProperties();\n Duration d1 = props.getProperty(Property.DURATION);\/\/Any property can be retrieved this way.\n Duration d2 = event.getDuration();\/\/d2 is the same as d1.\n Summary summary = event.getSummary();\n Description description = event.getDescription();\n return c;\n}<\/code><\/pre>\nConclusion<\/h2>\n
There you have it! These examples should be enough to get you started
\nwith the iCal4J library and give you and understanding of how it handles
\niCalendars. If you need more examples, clone the project\\’s Git
\nrepository and take a look at the test cases, which are a rich source of
\nknowledge.<\/p>\n
Further Reading<\/h2>\n