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.
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 ClassesModifier and TypeClassDescriptionstatic class
The iCalendar alarm component class.static enum
Enumeration describing the types of actions associated with alarms as described in Section 3.8.6.1 of RFC 5545.static class
Base class for iCalendar components.static class
Superclass for those ICalendar components have a unique ID.static class
Superclass for those ICalendar components that can contain alarms.static class
Arbitrary top-level iCalendar component.static class
The iCalendar event component class.static class
The iCalendar free/busy component class.static enum
Methods defined by iTIP (iCalendar Transport-Independent Interoperability Protocol).static class
The iCalendar journal component class.static enum
Status values.static class
The iCalendar timezone component class.static class
The iCalendar to-do component class.static enum
Duration units. -
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
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
Apply the RFC 5545 encoding rules to a string.static String
Apply RFC 5545 line-folding rules to a line of textstatic String
Create an unfolded iCalendar property line when there are no parameters.static String
Create an unfolded iCalendar property line when there are no parameters.static String
Create an unfolded iCalendar property line when there is one parameter.void
Set the method for an iCalendar object.void
setMethod
(ICalBuilder.ITIPMethod method) Set the method for an iCalendar object using RFC 5456 methods.byte[]
Return an iCalendar object.void
Write an iCalendar object to a file.void
write
(OutputStream os, boolean close) Write an iCalendar object to an output stream().
-
Field Details
-
MEDIA_TYPE
The media type for an iCalendar object- See Also:
-
-
Constructor Details
-
ICalBuilder
public ICalBuilder()Constructor.
-
-
Method Details
-
setMethod
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
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 enumerationICalBuilder.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
Add an iCalendar component to this iCalendar builder.- Parameters:
component
- the component to add.
-
add
Add a user-specified iCalendar component to this iCalendar builder.- Parameters:
component
- the component to add.
-
escape
Apply the RFC 5545 encoding rules to a string.- Parameters:
text
- the string to encode- Returns:
- the encoded string
-
icalProp
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 propertyescapeValues
- add escape sequences for reserved charactersvalues
- the values for the property- Returns:
- an unfolded line representing an iCalendar property, and without a terminating EOL sequence
-
icalProp
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 propertyparm
- a parameterescapeValues
- add escape sequences for reserved charactersvalues
- 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 propertyparms
- a array of parametersescapeValues
- add escape sequences for reserved charactersvalues
- the values for the property- Returns:
- an unfolded line representing an iCalendar property, and without a terminating EOL sequence
-
fold
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
Write an iCalendar object to a file.- Parameters:
file
- file the file- Throws:
IOException
- an error occurred while opening or writing the file
-
write
Write an iCalendar object to an output stream().- Parameters:
os
- the output streamclose
- 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
-