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:

Class 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.

  • Field Details

  • 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