net.fortuna.ical4j.model.component

Class VFreeBusy


public class VFreeBusy
extends CalendarComponent

$Id: VFreeBusy.java,v 1.35 2009/01/07 10:02:30 fortuna Exp $ [Apr 5, 2004] Defines an iCalendar VFREEBUSY component.
  4.6.4 Free/Busy Component

     Component Name: VFREEBUSY

     Purpose: Provide a grouping of component properties that describe
     either a request for free/busy time, describe a response to a request
     for free/busy time or describe a published set of busy time.

     Formal Definition: A "VFREEBUSY" calendar component is defined by the
     following notation:

       freebusyc  = "BEGIN" ":" "VFREEBUSY" CRLF
                    fbprop
                    "END" ":" "VFREEBUSY" CRLF

       fbprop     = *(

                  ; the following are optional,
                  ; but MUST NOT occur more than once

                  contact / dtstart / dtend / duration / dtstamp /
                  organizer / uid / url /

                  ; the following are optional,
                  ; and MAY occur more than once

                  attendee / comment / freebusy / rstatus / x-prop

                  )

     Description: A "VFREEBUSY" calendar component is a grouping of
     component properties that represents either a request for, a reply to
     a request for free or busy time information or a published set of
     busy time information.

     When used to request free/busy time information, the "ATTENDEE"
     property specifies the calendar users whose free/busy time is being
     requested; the "ORGANIZER" property specifies the calendar user who
     is requesting the free/busy time; the "DTSTART" and "DTEND"
     properties specify the window of time for which the free/busy time is
     being requested; the "UID" and "DTSTAMP" properties are specified to
     assist in proper sequencing of multiple free/busy time requests.

     When used to reply to a request for free/busy time, the "ATTENDEE"
     property specifies the calendar user responding to the free/busy time
     request; the "ORGANIZER" property specifies the calendar user that
     originally requested the free/busy time; the "FREEBUSY" property
     specifies the free/busy time information (if it exists); and the
     "UID" and "DTSTAMP" properties are specified to assist in proper
     sequencing of multiple free/busy time replies.

     When used to publish busy time, the "ORGANIZER" property specifies
     the calendar user associated with the published busy time; the
     "DTSTART" and "DTEND" properties specify an inclusive time window
     that surrounds the busy time information; the "FREEBUSY" property
     specifies the published busy time information; and the "DTSTAMP"
     property specifies the date/time that iCalendar object was created.

     The "VFREEBUSY" calendar component cannot be nested within another
     calendar component. Multiple "VFREEBUSY" calendar components can be
     specified within an iCalendar object. This permits the grouping of
     Free/Busy information into logical collections, such as monthly
     groups of busy time information.

     The "VFREEBUSY" calendar component is intended for use in iCalendar
     object methods involving requests for free time, requests for busy
     time, requests for both free and busy, and the associated replies.

     Free/Busy information is represented with the "FREEBUSY" property.
     This property provides a terse representation of time periods. One or
     more "FREEBUSY" properties can be specified in the "VFREEBUSY"
     calendar component.

     When present in a "VFREEBUSY" calendar component, the "DTSTART" and
     "DTEND" properties SHOULD be specified prior to any "FREEBUSY"
     properties. In a free time request, these properties can be used in
     combination with the "DURATION" property to represent a request for a
     duration of free time within a specified window of time.

     The recurrence properties ("RRULE", "EXRULE", "RDATE", "EXDATE") are
     not permitted within a "VFREEBUSY" calendar component. Any recurring
     events are resolved into their individual busy time periods using the
     "FREEBUSY" property.

     Example: The following is an example of a "VFREEBUSY" calendar
     component used to request free or busy time information:

       BEGIN:VFREEBUSY
       ORGANIZER:MAILTO:jane_doe@host1.com
       ATTENDEE:MAILTO:john_public@host2.com
       DTSTART:19971015T050000Z
       DTEND:19971016T050000Z
       DTSTAMP:19970901T083000Z
       END:VFREEBUSY

     The following is an example of a "VFREEBUSY" calendar component used
     to reply to the request with busy time information:

       BEGIN:VFREEBUSY
       ORGANIZER:MAILTO:jane_doe@host1.com
       ATTENDEE:MAILTO:john_public@host2.com
       DTSTAMP:19970901T100000Z
       FREEBUSY;VALUE=PERIOD:19971015T050000Z/PT8H30M,
        19971015T160000Z/PT5H30M,19971015T223000Z/PT6H30M
       URL:http://host2.com/pub/busy/jpublic-01.ifb
       COMMENT:This iCalendar file contains busy time information for
         the next three months.
       END:VFREEBUSY

     The following is an example of a "VFREEBUSY" calendar component used
     to publish busy time information.

       BEGIN:VFREEBUSY
       ORGANIZER:jsmith@host.com
       DTSTART:19980313T141711Z
       DTEND:19980410T141711Z
       FREEBUSY:19980314T233000Z/19980315T003000Z
       FREEBUSY:19980316T153000Z/19980316T163000Z
       FREEBUSY:19980318T030000Z/19980318T040000Z
       URL:http://www.host.com/calendar/busytime/jsmith.ifb
       END:VFREEBUSY
 
Example 1 - Requesting all busy time slots for a given period:

 // request all busy times between today and 1 week from now..
 DateTime start = new DateTime();
 DateTime end = new DateTime(start.getTime() + 1000 * 60 * 60 * 24 * 7);

 VFreeBusy request = new VFreeBusy(start, end);

 VFreeBusy reply = new VFreeBusy(request, calendar.getComponents());
 
Example 2 - Requesting all free time slots for a given period of at least the specified duration:

 // request all free time between today and 1 week from now of
 // duration 2 hours or more..
 DateTime start = new DateTime();
 DateTime end = new DateTime(start.getTime() + 1000 * 60 * 60 * 24 * 7);

 VFreeBusy request = new VFreeBusy(start, end, new Dur(0, 2, 0, 0));

 VFreeBusy response = new VFreeBusy(request, myCalendar.getComponents());
 

Constructor Summary

VFreeBusy()
Default constructor.
VFreeBusy(DateTime start, DateTime end)
Constructs a new VFreeBusy instance with the specified start and end boundaries.
VFreeBusy(DateTime start, DateTime end, Dur duration)
Constructs a new VFreeBusy instance with the specified start and end boundaries.
VFreeBusy(PropertyList properties)
Constructor.
VFreeBusy(VFreeBusy request, ComponentList components)
Constructs a new VFreeBusy instance representing a reply to the specified VFREEBUSY request according to the specified list of components.

Method Summary

Contact
getContact()
DtStamp
getDateStamp()
Duration
getDuration()
DtEnd
getEndDate()
Organizer
getOrganizer()
DtStart
getStartDate()
Uid
getUid()
Returns the UID property of this component if available.
Url
getUrl()
void
validate(boolean recurse)
void
validateAdd()
void
validateCancel()
void
validateCounter()
void
validateDeclineCounter()
void
validatePublish()
 Component/Property  Presence
 ------------------- ----------------------------------------------
 METHOD              1       MUST be "PUBLISH"
 
 VFREEBUSY           1+
     DTSTAMP         1
     DTSTART         1       DateTime values must be in UTC
     DTEND           1       DateTime values must be in UTC
     FREEBUSY        1+      MUST be BUSYTIME.
void
validateRefresh()
void
validateReply()
 Component/Property  Presence
 ------------------- ----------------------------------------------
 METHOD              1      MUST be "REPLY"
 
 VFREEBUSY           1
     ATTENDEE        1      (address of recipient replying)
     DTSTAMP         1
     DTEND           1      DateTime values must be in UTC
     DTSTART         1      DateTime values must be in UTC
     FREEBUSY        1+      (values MUST all be of the same data
                             type.
void
validateRequest()
 Component/Property  Presence
 ------------------- ----------------------------------------------
 METHOD              1      MUST be "REQUEST"
 
 VFREEBUSY           1
     ATTENDEE        1+     contain the address of the calendar store
     DTEND           1      DateTime values must be in UTC
     DTSTAMP         1
     DTSTART         1      DateTime values must be in UTC
     ORGANIZER       1      MUST be the request originator's address
     UID             1
     COMMENT         0 or 1
     CONTACT         0+
     X-PROPERTY      0+
 
     FREEBUSY        0
     DURATION        0
     REQUEST-STATUS  0
     URL             0
 
 X-COMPONENT         0+
 VALARM              0
 VEVENT              0
 VTODO               0
 VJOURNAL            0
 VTIMEZONE           0
 

Constructor Details

VFreeBusy

public VFreeBusy()
Default constructor.

VFreeBusy

public VFreeBusy(DateTime start,
                 DateTime end)
Constructs a new VFreeBusy instance with the specified start and end boundaries. This constructor should be used for requesting Free/Busy time for a specified period.
Parameters:

VFreeBusy

public VFreeBusy(DateTime start,
                 DateTime end,
                 Dur duration)
Constructs a new VFreeBusy instance with the specified start and end boundaries. This constructor should be used for requesting Free/Busy time for a specified duration in given period defined by the start date and end date.
Parameters:
duration - the length of the period being requested

VFreeBusy

public VFreeBusy(PropertyList properties)
Constructor.
Parameters:
properties - a list of properties

VFreeBusy

public VFreeBusy(VFreeBusy request,
                 ComponentList components)
Constructs a new VFreeBusy instance representing a reply to the specified VFREEBUSY request according to the specified list of components. If the request argument has its duration set, then the result represents a list of free times (that is, parameter FBTYPE is set to FbType.FREE). If the request argument does not have its duration set, then the result represents a list of busy times.
Parameters:
request - a VFREEBUSY request
components - a component list used to initialise busy time

Method Details

getContact

public final Contact getContact()
Returns:

getDateStamp

public final DtStamp getDateStamp()
Returns:

getDuration

public final Duration getDuration()
Returns:

getEndDate

public final DtEnd getEndDate()
Returns:

getOrganizer

public final Organizer getOrganizer()
Returns:

getStartDate

public final DtStart getStartDate()
Returns:

getUid

public final Uid getUid()
Returns the UID property of this component if available.
Returns:
a Uid instance, or null if no UID property exists

getUrl

public final Url getUrl()
Returns:

validate

public final void validate(boolean recurse)
            throws ValidationException

validateAdd

public void validateAdd()
            throws ValidationException

validateCancel

public void validateCancel()
            throws ValidationException

validateCounter

public void validateCounter()
            throws ValidationException

validateDeclineCounter

public void validateDeclineCounter()
            throws ValidationException

validatePublish

public void validatePublish()
            throws ValidationException
 Component/Property  Presence
 ------------------- ----------------------------------------------
 METHOD              1       MUST be "PUBLISH"
 
 VFREEBUSY           1+
     DTSTAMP         1
     DTSTART         1       DateTime values must be in UTC
     DTEND           1       DateTime values must be in UTC
     FREEBUSY        1+      MUST be BUSYTIME. Multiple instances are
                             allowed. Multiple instances must be sorted
                             in ascending order
     ORGANIZER       1       MUST contain the address of originator of
                             busy time data.
 
     COMMENT         0 or 1
     CONTACT         0+
     X-PROPERTY      0+
     URL             0 or 1  Specifies busy time URL
 
     ATTENDEE        0
     DURATION        0
     REQUEST-STATUS  0
     UID             0
 
 X-COMPONENT         0+
 
 VEVENT              0
 VTODO               0
 VJOURNAL            0
 VTIMEZONE           0
 VALARM              0
 

validateRefresh

public void validateRefresh()
            throws ValidationException

validateReply

public void validateReply()
            throws ValidationException
 Component/Property  Presence
 ------------------- ----------------------------------------------
 METHOD              1      MUST be "REPLY"
 
 VFREEBUSY           1
     ATTENDEE        1      (address of recipient replying)
     DTSTAMP         1
     DTEND           1      DateTime values must be in UTC
     DTSTART         1      DateTime values must be in UTC
     FREEBUSY        1+      (values MUST all be of the same data
                             type. Multiple instances are allowed.
                             Multiple instances MUST be sorted in
                             ascending order. Values MAY NOT overlap)
     ORGANIZER       1       MUST be the request originator's address
     UID             1
 
     COMMENT         0 or 1
     CONTACT         0+
     REQUEST-STATUS  0+
     URL             0 or 1  (specifies busy time URL)
     X-PROPERTY      0+
     DURATION        0
     SEQUENCE        0
 
 X-COMPONENT         0+
 VALARM              0
 VEVENT              0
 VTODO               0
 VJOURNAL            0
 VTIMEZONE           0
 

validateRequest

public void validateRequest()
            throws ValidationException
 Component/Property  Presence
 ------------------- ----------------------------------------------
 METHOD              1      MUST be "REQUEST"
 
 VFREEBUSY           1
     ATTENDEE        1+     contain the address of the calendar store
     DTEND           1      DateTime values must be in UTC
     DTSTAMP         1
     DTSTART         1      DateTime values must be in UTC
     ORGANIZER       1      MUST be the request originator's address
     UID             1
     COMMENT         0 or 1
     CONTACT         0+
     X-PROPERTY      0+
 
     FREEBUSY        0
     DURATION        0
     REQUEST-STATUS  0
     URL             0
 
 X-COMPONENT         0+
 VALARM              0
 VEVENT              0
 VTODO               0
 VJOURNAL            0
 VTIMEZONE           0