vCalendar

In addition to supporting the latest version of the iCalendar specification, biweekly also supports an older version of the iCalendar format called vCalendar. vCalendar is defined in a specification found on this page. vCalendar files use the .vcs file extension.

Reading and Writing vCalendar data with biweekly

When parsing vCalendar data, ICalReader automatically detects when it has encountered vCalendar data and converts it to the newer iCalendar data model on the fly.

In order to write vCalendar data with biweekly, simply populate your ICalendar object according to the iCalendar data model. Then, pass the appropriate ICalVersion object to the ICalWriter constructor and write the ICalendar object. biweekly automatically converts everything to use the vCalendar data model when writing an ICalendar object to a vCalendar data stream.

ICalendar ical = new ICalendar();
VEvent event = new VEvent();
  Date start = new SimpleDateFormat("MM/dd/yyyy HH:mm").parse("7/1/2015 8:00");
  event.setDateStart(start);

  Recurrence recur = new Recurrence.Builder(Frequency.WEEKLY).interval(2).build();
  event.setRecurrenceRule(recur);
ical.addEvent(event);

ICalWriter writer = new ICalWriter(System.out, ICalVersion.V1_0);
writer.getTimezoneInfo().setDefaultTimeZone(TimeZone.getTimeZone("America/New_York"));
writer.write(ical);

The above code sample produces the following output:

BEGIN:VCALENDAR
VERSION:1.0
PRODID:-//Michael Angstadt//biweekly 0.4.4//EN
BEGIN:VEVENT
UID:0def9b9a-23cf-4a4c-a043-15c6fa19b443
DTSTART:20150701T080000
RRULE:W2 #0
END:VEVENT
TZ:-0500
DAYLIGHT:TRUE;-0400;20150308T020000;20151101T020000;EST;EDT
END:VCALENDAR

Differences between vCalendar and iCalendar

vCalendar is very similar to iCalendar in syntax, but differs in regards to how it represents certain data. These differences are summarized below in no particular order.

1. Properties with URI values
vCalendar: Assigns a TYPE=URL parameter to the property.
iCalendar: Assigns a TYPE=URI parameter to the property.

2. ATTACH properties with Content IDs
vCalendar: Sets the property value to the content ID and gives the property a TYPE=CONTENT-ID parameter.
iCalendar: Sets the property value to the content ID in URI format (cid:ID) and gives the property a TYPE=URI parameter.

3. RSVP parameter ofATTENDEE properties
vCalendar: Valid values are YES and NO.
iCalendar: Valid values are TRUE and FALSE.

4. ATTENDEE properties with a role of "chair" and a participation level of "optional"
vCalendar: Gives the property EXPECT=REQUEST and ROLE=CHAIR parameters.
iCalendar: Just gives the property a ROLE=CHAIR parameter.

5. Participation parameter mappings in ATTENDEE properties

vCalendar	iCalendar
STATUS=ACCEPTED	PARTSTAT=ACCEPTED
STATUS=NEEDS ACTION	PARTSTAT=NEEDS-ACTION
EXPECT=REQUIRE	ROLE=REQ-PARTICIPANT
EXPECT=REQUEST	ROLE=OPT-PARTICIPANT
EXPECT=FYI	ROLE=NON-PARTICIPANT

6. ATTENDEE property value
vCalendar: Includes both the name and email address in the format: NAME <EMAIL>.
iCalendar: Sets a CN parameter to the attendee's name. Sets the property value to the attendee's email address in URI format: mailto:EMAIL. Also sets a TYPE=CAL-ADDRESS parameter.

7. Alarms
vCalendar: Represented with the AALARM, DALARM, MALARM, and PALARM properties.
iCalendar: Represented with the VALARM component.

8. Timezones
vCalendar: Represented with the DAYLIGHT and TZ properties.
iCalendar: Represented with the VTIMEZONE component.

9. RRULE property value
Uses completely different syntax.

10. TRANSP property value
vCalendar: Valid values are 0 and 1.
iCalendar: Valid values are OPAQUE and TRANSPARENT.

11. STATUS property values

Value	vCalendar	iCalendar
ACCEPTED
CANCELLED
COMPLETED
CONFIRMED
DECLINED
DELEGATED
DRAFT
FINAL
IN-PROGRESS
NEEDS ACTION
NEEDS-ACTION
SENT
TENTATIVE

12. CREATED vs DCREATED property name
The property that defines the time that the calendar information was created is named differently.
vCalendar: The property is named DCREATED.
iCalendar: The property is named CREATED.