Timezones 0.4.6

Note: This page refers to versions 0.4.6 and earlier. See the Timezones if you are using a later version.

Writing iCalendar objects with timezones

By default, biweekly will output all date-time property values in UTC time. For example, let's say that the default timezone of the local computer's JVM is set to "America/New_York", which, at this moment in time, is 4 hours behind UTC. When written to an iCal file, if the java.util.Date object is constructed using the default timezone, its hour component will be 4 hours ahead of whatever hour value it was assigned in the Java code because it was converted to UTC.

//JVM's timezone is "America/New_York" (4 hours behind UTC)
Calendar c = Calendar.getInstance();
c.clear();
c.set(Calendar.YEAR, 2013);
c.set(Calendar.MONTH, Calendar.JUNE);
c.set(Calendar.DATE, 27);
c.set(Calendar.HOUR_OF_DAY, 13); //this is "17" in UTC time
Date start = c.getTime();

DateStart dateStart = new DateStart(start);
//outputs as: "DTSTART:20130627T170000Z"

If you want to output date/time property values in a timezone other than UTC, you may pass a java.util.TimeZone object into ICalWriter before invoking the write() method. An appropriate VTIMEZONE component will automatically be downloaded from tzurl.org and included in the written iCalendar object.

//JVM's default timezone is "America/New_York"
Calendar c = Calendar.getInstance();
c.clear();
c.set(Calendar.YEAR, 2013);
c.set(Calendar.MONTH, Calendar.JUNE);
c.set(Calendar.DATE, 27);
c.set(Calendar.HOUR_OF_DAY, 13); //this is "10" in LA time
Date start = c.getTime();

VEvent event = new VEvent();
event.setDateStart(start);

ICalendar ical = new ICalendar();
ical.addEvent(event);

Writer writer = ...
ICalWriter icalWriter = new ICalWriter(writer, ICalVersion.V2_0);

//optional: Use Outlook-friendly VTIMEZONE components:
icalWriter.getTimezoneInfo().setGenerator(new TzUrlDotOrgGenerator(true));

//output date/time values in LA time
TimeZone tz = TimeZone.getTimeZone("America/Los_Angeles");
icalWriter.getTimezoneInfo().setDefaultTimeZone(tz);

icalWriter.write(ical);

(Note that both of the dates from the above examples are the same. They both represent the same moment in time, they are just displayed in different timezones!)

You may construct your own VTIMEZONE component if you like. First, call assign() to assign your VTIMEZONE component to a Java TimeZone object. Then, pass the TimeZone object into the setDefaultTimeZone() method as shown in the previous example.

ICalendar ical = ...
ICalWriter icalWriter = ...

//output date/time values in LA time
TimeZone tz = TimeZone.getTimeZone("America/Los_Angeles");
VTimezone component = ...
icalWriter.getTimezoneInfo().assign(component, tz);
icalWriter.getTimezoneInfo().setDefaultTimeZone(tz);

icalWriter.write(ical);

Parsing iCalendar objects with timezones

As of version 0.4.0, biweekly automatically parses all date/time values according to the VTIMEZONE components that are present in the iCalendar object.

Because biweekly considers VTIMEZONE components to only be necessary for parsing an iCalendar object, it does not include these components in the ICalendar data model. However, the VTIMEZONE components of the parsed iCalendar object can be retrieved from the ICalReader object if you really need them.

Reader reader = ...
ICalReader icalReader = new ICalReader(reader);
ICalendar ical = icalReader.readNext();
Collection<VTimezone> components = icalReader.getTimezoneInfo().getComponents();