Getting started

This quick start guide will show you the basics of how to read and write iCalendar objects using biweekly. If you are familiar with Java programming and a programming idiom called method chaining, it should be fairly intuitive once you see some examples. The Javadocs are also a good source of information.

In this guide, we will be using the Biweekly class. This class contains a collection of static factory methods that use method chaining to simplify the reading/writing process. For more control over the reading/writing process, you can use the ICalReader and ICalWriter classes.

Reading iCalendar data

To parse an iCalendar object, start by calling the Biweekly.parse() method. This method is overloaded to take a String, File, InputStream, or Reader as an argument.

Then, you can optionally call additional methods which allow you to customize the parsing process. For example, caretDecoding(false) can be called to disable a certain kind of encoding scheme that only some iCalendar producers support.

Finally, call the first() or all() methods to execute the parsing operation.

The parsed data of each iCalendar is returned in an ICalendar object. This object is essentially a DTO, containing mostly getter/setter methods.

String str =
"BEGIN:VCALENDAR\r\n" +
  "VERSION:2.0\r\n" +
  "PRODID:-//Microsoft Corporation//Outlook 14.0 MIMEDIR//EN\r\n" +
  "BEGIN:VEVENT\r\n" +
    "UID:0123\r\n" +
    "DTSTAMP:20130601T080000Z\r\n" +
    "SUMMARY;LANGUAGE=en-us:Team Meeting\r\n" +
    "DTSTART:20130610T120000Z\r\n" +
    "DURATION:PT1H\r\n" +
    "RRULE:FREQ=WEEKLY;INTERVAL=2\r\n" +
  "END:VEVENT\r\n" +
"END:VCALENDAR\r\n";

//parse the first iCalendar object from the data stream
ICalendar ical = Biweekly.parse(str).first();

//or parse all objects from the data stream 
//List<ICalendar> icals = Biweekly.parse(str).all();

VEvent event = ical.getEvents().get(0);
String summary = event.getSummary().getValue();

Writing iCalendar data

To write an iCalendar object, simply create a new instance of the ICalendar class, and populate it with data. Then, pass it into the Biweekly.write() method.

Then, you can optionally call additional methods which allow you to customize the writing process. For example, version() can be called to specify what version of the iCalendar standard the written data should adhere to (it defaults to the latest verison).

Finally, call the go() method to execute the write operation. This method is overloaded to take a File, OutputStream, or Writer as an argument. The no-argument version will return the iCalendar as a String.

ICalendar ical = new ICalendar();
VEvent event = new VEvent();
  Summary summary = event.setSummary("Team Meeting");
  summary.setLanguage("en-us");

  Date start = ...
  event.setDateStart(start);

  Duration duration = new Duration.Builder().hours(1).build();
  event.setDuration(duration);

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

File file = new File("meeting.ics");
Biweekly.write(ical).go(file);

Validating an ICalendar object

To help ensure that data within an ICalendar Java object properly adheres to the iCalendar specifications, the validate() method can be called. This method returns a list of warnings, alerting the developer to such things as required fields being missing (such as the ACTION property in a VALARM component) or other data inconsistencies (such as the date in a DTSTART property coming after the date in a DTEND property).

Note that the presence of validation warnings will not prevent the ICalendar object from being properly written to a data stream. Syntactically-correct iCalendar data will still be produced. However, the consuming application may have trouble interpreting some of the data, due to the presence of these warnings.

DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm");
ICalendar ical = new ICalendar();
VEvent event = new VEvent();
  event.setDateStart(df.parse("2013-07-15 13:00"));
  event.setDateEnd(df.parse("2013-07-15 11:00"));
ical.addEvent(event);

ValidationWarnings warnings = ical.validate(ICalVersion.V2_0);
System.out.println(warnings.toString());

//produces this warning:
//[ICalendar > VEvent]: DateStart must come before DateEnd.