Module org.bzdev.base

Package org.bzdev.net.calendar

Class ICalBuilder

java.lang.Object

org.bzdev.net.calendar.ICalBuilder

public class ICalBuilder
extends Object

Builder for an iCalendar file. The iCalendar format is described in RFC 5545. Users of this class should be familiar with this RFC. This class uses several additional classes as shown in the following diagram:

Users of this class will first create an instance of it and also instances of inner classes representing iCalendar components. Then these components will be added to the iCalendar instance by calling add(ICalBuilder.Component) or add(ICalBuilder.Common).

The most general way of creating components is to create an instance of ICalBuilder.Component by providing the name of the component in the constructor. The methods ICalBuilder.Base.addProperty(String,String,boolean, String...) and/or ICalBuilder.Base.addProperty(String,String[],boolean, String...) can be used to add explicitly properties to the component. A more convenient alternative is to use several inner classes:

• ICalBuilder.Event. This class represents an iCalendar event component.
• ICalBuilder.ToDo. This class represents an iCalendar to-do component.
• ICalBuilder.Journal. This class represents an iCalendar journal component.
• ICalBuilder.FreeBusy. This class represents an iCalendar free-busy component.
• ICalBuilder.TimeZone. This class represents a time-zone component.
• ICalBuilder.Alarm. This class represents an iCalendar alarm component. Alarms are allowed within iCalendar event and to-do components, and an alarm's constructor determines the component containing that alarm.

Each of these inner classes contains methods that will set their properties, covering the most common cases. Additional properties can be added using ICalBuilder.Base.addProperty(String,String,boolean, String...) and/or ICalBuilder.Base.addProperty(String,String[],boolean, String...) in which case the user must ensure that a property is allowed by RFC 5545. These methods can also be used for cases where the methods of an inner class do not provide parameters (e.g., parameters not explicitly defined in RFC 5545).

The classes ICalBuilder.FreeBusy and ICalBuilder.TimeZone can also be used, but these are trivial implementations of the ICalBuilder.Component class, providing little more than the component name used in the "BEGIN" and "END" lines.

Note: while RFC 5545 allows a mix of component types in an iCalendar object, RFC 6047, which defines the iMIP (iCalendar Message-Based Interoperability Protocol) requires that all component in the same object have the same component type. Since different transport protocols can differ in what constraints are used, the user of this class must ensure that an object created is appropriate for a given transport protocol.

This class and most of its inner classes have methods for which one or more arguemnts are declared with the type TemporalAccessor. The argument must be one of the following classes (which implement TemporalAccessor): LocalDate, LocalDateTime, ZonedDateTime, Instant, The classesLocalDate and LocalDateTime will be treated as a "floating time" (see RFC 5545) and both ZonedDateTime and Instant will have their times represented using UTC.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ICalBuilder.Alarm	The iCalendar alarm component class.
static enum	ICalBuilder.AlarmType	Enumeration describing the types of actions associated with alarms as described in Section 3.8.6.1 of RFC 5545.
static class	ICalBuilder.Base	Base class for iCalendar components.
static class	ICalBuilder.Common	Superclass for those ICalendar components have a unique ID.
static class	ICalBuilder.CommonWithAlarm	Superclass for those ICalendar components that can contain alarms.
static class	ICalBuilder.Component	Arbitrary top-level iCalendar component.
static class	ICalBuilder.Event	The iCalendar event component class.
static class	ICalBuilder.FreeBusy	The iCalendar free/busy component class.
static enum	ICalBuilder.ITIPMethod	Methods defined by iTIP (iCalendar Transport-Independent Interoperability Protocol).
static class	ICalBuilder.Journal	The iCalendar journal component class.
static enum	ICalBuilder.Status	Status values.
static class	ICalBuilder.TimeZone	The iCalendar timezone component class.
static class	ICalBuilder.ToDo	The iCalendar to-do component class.
static enum	ICalBuilder.Units	Duration units.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	MEDIA_TYPE	The media type for an iCalendar object

Constructor Summary

Constructors

Constructor	Description
ICalBuilder()	Constructor.

Method Summary

Modifier and Type	Method	Description
void	add(ICalBuilder.Common component)	Add an iCalendar component to this iCalendar builder.
void	add(ICalBuilder.Component component)	Add a user-specified iCalendar component to this iCalendar builder.
static String	escape(String text)	Apply the RFC 5545 encoding rules to a string.
static String	fold(String text)	Apply RFC 5545 line-folding rules to a line of text
static String	icalProp(String property, boolean escapeValues, String... values)	Create an unfolded iCalendar property line when there are no parameters.
static String	icalProp(String property, String[] parms, boolean escapeValues, String... values)	Create an unfolded iCalendar property line when there are no parameters.
static String	icalProp(String property, String parm, boolean escapeValues, String... values)	Create an unfolded iCalendar property line when there is one parameter.
void	setMethod(String method)	Set the method for an iCalendar object.
void	setMethod(ICalBuilder.ITIPMethod method)	Set the method for an iCalendar object using RFC 5456 methods.
byte[]	toByteArray()	Return an iCalendar object.
void	write(File file)	Write an iCalendar object to a file.
void	write(OutputStream os, boolean close)	Write an iCalendar object to an output stream().

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

MEDIA_TYPE

public static final String MEDIA_TYPE

The media type for an iCalendar object

See Also:

• Constant Field Values

Constructor Details

ICalBuilder

public ICalBuilder()

Constructor.

Method Details

setMethod

public void setMethod(String method)

Set the method for an iCalendar object. The method field is defined in Section 3.7.2 of RFC 5545.

This Java method is provided for cases where the desired method is not one defined by RFC 5546. Otherwise one should use setMethod(ITIPMethod), which is type safe—a mistyped method name will result in a compile-time error.

Parameters:

method - the method to use; null if no method is to be provided

setMethod

public void setMethod(ICalBuilder.ITIPMethod method)

Set the method for an iCalendar object using RFC 5456 methods. The method field is defined in Section 3.7.2 of RFC 5545. The enumeration ICalBuilder.ITIPMethod provides the methods defined in Section 1.4 of RFC 5546.

Parameters:

method - the method; null if no method is to be provided

add

public void add(ICalBuilder.Common component)

Add an iCalendar component to this iCalendar builder.

Parameters:

component - the component to add.

add

public void add(ICalBuilder.Component component)

Add a user-specified iCalendar component to this iCalendar builder.

Parameters:

component - the component to add.

escape

public static String escape(String text)

Apply the RFC 5545 encoding rules to a string.

Parameters:

text - the string to encode

Returns:

the encoded string

icalProp

public static String icalProp(String property,
 boolean escapeValues,
 String... values)

Create an unfolded iCalendar property line when there are no parameters.

When there are multiple values, these will be comma-separated. If a comma appears in a value, the escapeValues argument should be set to true. The syntax for iCalendar properties is such that the escapeValues argument will be 'true' only when the values are text.

Note: this method is used internally, but is public in case it is useful for other purposes.

Parameters:

property - the name of the property

escapeValues - add escape sequences for reserved characters

values - the values for the property

Returns:

an unfolded line representing an iCalendar property, and without a terminating EOL sequence

icalProp

public static String icalProp(String property,
 String parm,
 boolean escapeValues,
 String... values)

Create an unfolded iCalendar property line when there is one parameter.

When there are multiple values, these will be comma-separated. If a comma appears in a value, the escapeValues argument should be set to true. The syntax for iCalendar properties is such that the escapeValues argument will be 'true' only when the values are text.

The parameter consists of a keyword or a keyword followed by the character '=" followed by a parameter value. If the parameter contains reserved characters, that value will be quoted (unless that value is already quoted).

Note: this method is used internally, but is public in case it is useful for other purposes.

Parameters:

property - the name of the property

parm - a parameter

escapeValues - add escape sequences for reserved characters

values - the values for the property

Returns:

an unfolded line representing an iCalendar property, and without a terminating EOL sequence

icalProp

public static String icalProp(String property,
 String[] parms,
 boolean escapeValues,
 String... values)

Create an unfolded iCalendar property line when there are no parameters.

When there are multiple values, these will be comma-separated. If a comma appears in a value, the escapeValues argument should be set to true. The syntax for iCalendar properties is such that the escapeValues argument will be 'true' only when the values are text.

Each parameter consists of a keyword or a keyword followed by the character '=" followed by a parameter value. If a parameter contains reserved characters, its value will be quoted (unless its value is already quoted).

Note: this method is used internally, but is public in case it is useful for other purposes.

Parameters:

property - the name of the property

parms - a array of parameters

escapeValues - add escape sequences for reserved characters

values - the values for the property

Returns:

an unfolded line representing an iCalendar property, and without a terminating EOL sequence

fold

public static String fold(String text)

Apply RFC 5545 line-folding rules to a line of text

Parameters:

text - a line of text

Returns:

the line-folded text

toByteArray

public byte[] toByteArray()

Return an iCalendar object.

Returns:

a byte array containing an iCalendar object as UTF-8 encoded text with CRLF end-of-lines

write

public void write(File file)
           throws IOException

Write an iCalendar object to a file.

Parameters:

file - file the file

Throws:

IOException - an error occurred while opening or writing the file

write

public void write(OutputStream os,
 boolean close)
           throws IOException

Write an iCalendar object to an output stream().

Parameters:

os - the output stream

close - true if the writer constructed from the output stream should be closed when the iCalendar object is complete; false otherwise

Throws:

IOException - an error occurred while writing to the output stream