mirror of
https://github.com/etesync/android
synced 2025-06-19 14:38:52 +00:00
295 lines
11 KiB
HTML
295 lines
11 KiB
HTML
<?xml version="1.0" encoding="ISO-8859-1"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>iCal4j - Introduction</title>
|
|
<link rel="stylesheet" href="css/default.css" type="text/css" />
|
|
<link rel="alternate" href="http://sourceforge.net/export/rss2_projnews.php?group_id=107024&rss_fulltext=1" type="application/rss+xml" title="iCal4j - News"/>
|
|
<meta name="author" content="Ben Fortuna"/>
|
|
<meta name="description" content="A Java library for reading and writing iCalendar data streams"/>
|
|
<meta name="keywords" content="iCalendar, iCal, Parser, Java, Library, API"/>
|
|
</head>
|
|
<body>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<td colspan="13" class="title">iCal4<span style="background:red">j</span></td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><a href="index.html">Home</a></td>
|
|
<td>|</td>
|
|
<td><a href="introduction.html">Introduction</a></td>
|
|
<td>|</td>
|
|
<td><a href="http://wiki.modularity.net.au/ical4j">Wiki</a></td>
|
|
<td>|</td>
|
|
<td><a href="apidocs/index.html">Documentation</a></td>
|
|
<td>|</td>
|
|
<td><a href="http://sourceforge.net/news/?group_id=107024">News</a></td>
|
|
<td>|</td>
|
|
<td><a href="http://sourceforge.net/forum/?group_id=107024">Support</a></td>
|
|
<td>|</td>
|
|
<td><a href="http://sourceforge.net/project/showfiles.php?group_id=107024">Download</a></td>
|
|
<td>|</td>
|
|
<td style="width:100%"><a href="http://m2.modularity.net.au/projects/ical4j/license.html" target="_blank">License</a></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<div id="intro" class="content">
|
|
<h2>Introduction <a href="#intro">»</a></h2>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</div>
|
|
|
|
<div id="usage" class="content">
|
|
<h2>Usage <a href="#usage">»</a></h2>
|
|
<p>
|
|
Simply add the iCal4j jar file,
|
|
the Commons Logging jar file, and the Commons Language jar file to your classpath.
|
|
</p>
|
|
</div>
|
|
|
|
<div id="examples" class="content">
|
|
<h2>Examples <a href="#examples">»</a></h2>
|
|
|
|
<h3>Parsing an iCalendar file</h3>
|
|
<p>
|
|
Support for parsing and building an iCalendar object model is provided
|
|
by the <code>CalendarParser</code> and <code>ContentHandler</code>
|
|
interfaces. You can provide your own implementations of either
|
|
of these, or just use the default implementations as provided by
|
|
the <code>CalendarBuilder</code> class. Note that <code>CalendarBuilder</code>
|
|
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 <em><a href="#timezones">Working with TimeZones</a></em>
|
|
for further reasons).
|
|
</p>
|
|
<table style="border: 1px solid black; background: silver">
|
|
<tbody>
|
|
<tr><td><pre><code>
|
|
FileInputStream fin = new FileInputStream("mycalendar.ics");
|
|
|
|
CalendarBuilder builder = new CalendarBuilder();
|
|
|
|
Calendar calendar = builder.build(fin);
|
|
</code></pre></td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3>Iterating over a Calendar</h3>
|
|
<p>
|
|
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 <code>List</code>s, <code>Iterator</code>s, etc.
|
|
</p>
|
|
<table style="border: 1px solid black; background: silver">
|
|
<tbody>
|
|
<tr><td><pre><code>
|
|
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() + "]");
|
|
}
|
|
}
|
|
</code></pre></td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3>Creating a new calendar</h3>
|
|
<p>
|
|
Creating a new calendar is quite straight-forward, in that all you need
|
|
to remember is that a <code>Calendar</code> contains a list of
|
|
<code>Properties</code> and <code>Components</code>. 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
|
|
<code>Calendar.validate()</code>. All iCal4j objects also override
|
|
<code>Object.toString()</code>, so you can verify the resulting calendar
|
|
data via this mechanism.
|
|
</p>
|
|
<table style="border: 1px solid black; background: silver">
|
|
<tbody>
|
|
<tr><td><pre><code>
|
|
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..
|
|
</code></pre></td></tr>
|
|
<tr>
|
|
<th>
|
|
Output:
|
|
</th>
|
|
</tr>
|
|
<tr><td><pre><code>
|
|
BEGIN:VCALENDAR
|
|
PRODID:-//Ben Fortuna//iCal4j 1.0//EN
|
|
VERSION:2.0
|
|
CALSCALE:GREGORIAN
|
|
END:VCALENDAR
|
|
</code></pre></td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3>Creating an event</h3>
|
|
<p>
|
|
One of the more commonly used components is a <code>VEvent</code>. 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.
|
|
</p>
|
|
<table style="border: 1px solid black; background: silver">
|
|
<tbody>
|
|
<tr><td><pre><code>
|
|
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);
|
|
</code></pre></td></tr>
|
|
<tr>
|
|
<th>
|
|
Output:
|
|
</th>
|
|
</tr>
|
|
<tr><td><pre><code>
|
|
BEGIN:VEVENT
|
|
DTSTAMP:20050222T044240Z
|
|
DTSTART;VALUE=DATE:20051225
|
|
SUMMARY:Christmas Day
|
|
END:VEVENT
|
|
</code></pre></td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3 id="timezones">Working with TimeZones</h3>
|
|
<p>
|
|
Complete timezone support is now provided by iCal4j, which follows these
|
|
basic principles:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
iCal4j includes its own set of timezone definitions, which are
|
|
based on the defacto standard Olson timezone database. Whilst
|
|
iCal4j's timezone identifiers may be identical to those provided
|
|
by the Java API, there is no guarantee that the rules defining
|
|
a timezone will match those used by a Java timezone.
|
|
</li>
|
|
<li>
|
|
The default timezone for iCal4j is the same as the default Java timezone.
|
|
This timezone is used where no iCal4j timezone is specified (i.e. floating time),
|
|
and the relevant iCal4j object is not set as being in <em>UTC</em> time.
|
|
<em>
|
|
Note that it is not recommended to use floating time values in externalisable
|
|
calendars (i.e. calendars you want to import into another program), as it
|
|
may lead to inconsistent handling of timezone information.
|
|
</em>
|
|
</li>
|
|
<li>
|
|
iCal4j timezones are accessible via the applicable
|
|
<code>TimeZoneRegistry</code> implementation. When parsing existing
|
|
iCalendar data you should obtain the appropriate <code>TimeZoneRegistry</code>
|
|
via the <code>CalendarBuilder.getRegistry()</code> method after
|
|
calling <code>CalendarBuilder.build()</code>. In addition to the
|
|
default iCal4j timezone definitions this registry instance will also
|
|
provide you access to any timezones defined in the parsed iCalendar
|
|
data stream. If you are creating a new calendar object you should
|
|
call <code>TimeZoneRegistryFactory.getInstance().createRegistry()</code>
|
|
to construct a default registry instance.
|
|
</li>
|
|
<li>
|
|
You can provide your own <code>TimeZoneRegistry</code> implementation
|
|
by sub-classing the <code>TimeZoneRegistyFactory</code> class and
|
|
specifying the following system property:
|
|
<p>
|
|
<em>net.fortuna.ical4j.timezone.registry=<factory_class_name></em>
|
|
</p>
|
|
This may be useful if you want to read and/or store your timezone definitions
|
|
in a database.
|
|
</li>
|
|
</ul>
|
|
|
|
<table style="border: 1px solid black; background: silver">
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<pre><code>
|
|
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");
|
|
</code></pre></td></tr>
|
|
<tr>
|
|
<th>
|
|
Output:
|
|
</th>
|
|
</tr>
|
|
<tr><td><pre><code>
|
|
BEGIN:VEVENT
|
|
DTSTAMP:20051105T094739Z
|
|
DTSTART;TZID=Australia/Melbourne:20051101T150000
|
|
SUMMARY:Melbourne Cup
|
|
END:VEVENT
|
|
</code></pre>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3>Saving an iCalendar file</h3>
|
|
<p>
|
|
When saving an iCalendar file iCal4j will automatically validate your
|
|
calendar object model to ensure it complies with the
|
|
<a href="http://www.faqs.org/rfcs/rfc2445.html">RFC2445</a> specification.
|
|
If you would prefer not to validate your calendar data you can disable the
|
|
validation by calling <code>CalendarOutputter.setValidating(false)</code>.
|
|
</p>
|
|
<table style="border: 1px solid black; background: silver">
|
|
<tbody>
|
|
<tr><td><pre><code>
|
|
FileOutputStream fout = new FileOutputStream("mycalendar.ics");
|
|
|
|
CalendarOutputter outputter = new CalendarOutputter();
|
|
outputter.output(calendar, fout);
|
|
</code></pre></td></tr>
|
|
</tbody>
|
|
</table>
|
|
<p>
|
|
More examples may be found in the <a href="apidocs/index.html">API Documentation</a>.
|
|
</p>
|
|
</div>
|
|
|
|
<div id="footer">
|
|
<p>
|
|
Copyright 2007 ©
|
|
<a href="mailto:fortuna@users.sourceforge.net">Ben Fortun<span style="background:red">a</span></a>
|
|
</p>
|
|
<p>
|
|
<a href="http://validator.w3.org/check?uri=referer">
|
|
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" />
|
|
</a>
|
|
</p>
|
|
</div>
|
|
</body>
|
|
</html> |