-
Overview »
-
- 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.
-
-
- Providing both a parser and an object model, iCal4j allows
- you to either modify existing iCalendar data or create new
- data models. Validation is also provided to ensure the
- data maintains a state consistent with the specification.
-
-
-
Dependencies »
-
- Please see the
-
Project Documentation
- for a list of dependencies.
-
-
Introduction »
-
- iCal4j may be used for modifying existing iCalendar data or creating new iCalendar
- data from scratch. Here you will find a few examples indicating the recommended usage
- of this library.
-
-
-
Usage »
-
- Simply add the iCal4j jar file,
- the Commons Logging jar file, and the Commons Language jar file to your classpath.
-
-
-
Examples »
-
-
Parsing an iCalendar file
-
- Support for parsing and building an iCalendar object model is provided
- by the CalendarParser and ContentHandler
- interfaces. You can provide your own implementations of either
- of these, or just use the default implementations as provided by
- the CalendarBuilder class. Note that CalendarBuilder
- is not thread-safe, and as such it is good practice to construct a new
- instance for each data stream you wish to parse (see Working with TimeZones
- for further reasons).
-
-
-
-
-FileInputStream fin = new FileInputStream("mycalendar.ics");
-
-CalendarBuilder builder = new CalendarBuilder();
-
-Calendar calendar = builder.build(fin);
-
|
-
-
-
-
Iterating over a Calendar
-
- The iCal4j API is designed to conform with the standard Java collections
- API as much as possible. As such, you will find that for searching and
- manipulating a calendar object model you can make use of familiar concepts
- such as Lists, Iterators, etc.
-
-
-
-
-for (Iterator i = calendar.getComponents().iterator(); i.hasNext();) {
- Component component = (Component) i.next();
- System.out.println("Component [" + component.getName() + "]");
-
- for (Iterator j = component.getProperties().iterator(); j.hasNext();) {
- Property property = (Property) j.next();
- System.out.println("Property [" + property.getName() + ", " + property.getValue() + "]");
- }
-}
-
|
-
-
-
-
Creating a new calendar
-
- Creating a new calendar is quite straight-forward, in that all you need
- to remember is that a Calendar contains a list of
- Properties and Components. A calendar must
- contain certain standard properties and at least one component to be
- valid. You can verify that a calendar is valid via the method
- Calendar.validate(). All iCal4j objects also override
- Object.toString(), so you can verify the resulting calendar
- data via this mechanism.
-
-
-
-
-Calendar calendar = new Calendar();
-calendar.getProperties().add(new ProdId("-//Ben Fortuna//iCal4j 1.0//EN"));
-calendar.getProperties().add(Version.VERSION_2_0);
-calendar.getProperties().add(CalScale.GREGORIAN);
-
-// Add events, etc..
-
|
-
- |
- Output:
- |
-
-
-BEGIN:VCALENDAR
-PRODID:-//Ben Fortuna//iCal4j 1.0//EN
-VERSION:2.0
-CALSCALE:GREGORIAN
-END:VCALENDAR
-
|
-
-
-
-
Creating an event
-
- One of the more commonly used components is a VEvent. To create
- a VEvent you can either set the date value and properties manually or you can
- make use of the convenience constructors to initialise standard values.
-
-
-
-
-java.util.Calendar cal = java.util.Calendar.getInstance();
-cal.set(java.util.Calendar.MONTH, java.util.Calendar.DECEMBER);
-cal.set(java.util.Calendar.DAY_OF_MONTH, 25);
-
-VEvent christmas = new VEvent(new Date(cal.getTime()), "Christmas Day");
-// initialise as an all-day event..
-christmas.getProperties().getProperty(Property.DTSTART).getParameters().add(Value.DATE);
-
|
-
- |
- Output:
- |
-
-
-BEGIN:VEVENT
-DTSTAMP:20050222T044240Z
-DTSTART;VALUE=DATE:20051225
-SUMMARY:Christmas Day
-END:VEVENT
-
|
-
-
-
-
Working with TimeZones
-
- Complete timezone support is now provided by iCal4j, which follows these
- basic principles:
-
-
-
-
-
-
-
-
-
-TimeZoneRegistry registry = TimeZoneRegistryFactory.getInstance().createRegistry();
-TimeZone timezone = registry.getTimeZone("Australia/Melbourne");
-
-java.util.Calendar cal = java.util.Calendar.getInstance(timezone);
-cal.set(java.util.Calendar.YEAR, 2005);
-cal.set(java.util.Calendar.MONTH, java.util.Calendar.NOVEMBER);
-cal.set(java.util.Calendar.DAY_OF_MONTH, 1);
-cal.set(java.util.Calendar.HOUR_OF_DAY, 15);
-cal.clear(java.util.Calendar.MINUTE);
-cal.clear(java.util.Calendar.SECOND);
-
-DateTime dt = new DateTime(cal.getTime());
-dt.setTimeZone(timezone);
-VEvent melbourneCup = new VEvent(dt, "Melbourne Cup");
-
|
-
- |
- Output:
- |
-
-
-BEGIN:VEVENT
-DTSTAMP:20051105T094739Z
-DTSTART;TZID=Australia/Melbourne:20051101T150000
-SUMMARY:Melbourne Cup
-END:VEVENT
-
- |
-
-
-
-
-
Saving an iCalendar file
-
- When saving an iCalendar file iCal4j will automatically validate your
- calendar object model to ensure it complies with the
- RFC2445 specification.
- If you would prefer not to validate your calendar data you can disable the
- validation by calling CalendarOutputter.setValidating(false).
-
-
-
-
-FileOutputStream fout = new FileOutputStream("mycalendar.ics");
-
-CalendarOutputter outputter = new CalendarOutputter();
-outputter.output(calendar, fout);
-
|
-
-
-
- More examples may be found in the API Documentation.
-
-