net.fortuna.ical4j.model.component

## Class VFreeBusy

- java.lang.Object
- - net.fortuna.ical4j.model.Component
  - - net.fortuna.ical4j.model.component.CalendarComponent
    - - net.fortuna.ical4j.model.component.VFreeBusy

All Implemented Interfaces:
  Serializable

    public class VFreeBusy
    extends CalendarComponent

$Id$ [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());

Author:
  Ben Fortuna
See Also:
  Serialized Form

### Field Summary

### Fields inherited from class net.fortuna.ical4j.model.component.CalendarComponent

`EMPTY_VALIDATOR`

### Fields inherited from class net.fortuna.ical4j.model.Component

`AVAILABLE, BEGIN, END, EXPERIMENTAL_PREFIX, VALARM, VAVAILABILITY, VEVENT, VFREEBUSY, VJOURNAL, VTIMEZONE, VTODO, VVENUE`

### Constructor Summary

Constructors
Constructor and Description
`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

Methods
`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()`
`protected Validator` `getValidator(Method method)`
`void` `validate(boolean recurse)` Perform validation on a component.

### Methods inherited from class net.fortuna.ical4j.model.component.CalendarComponent

`validate, validateAdd, validateCancel, validateCounter, validateDeclineCounter, validatePublish, validateRefresh, validateReply, validateRequest`

### Methods inherited from class net.fortuna.ical4j.model.Component

`calculateRecurrenceSet, copy, equals, getName, getProperties, getProperties, getProperty, hashCode, toString, validate, validateProperties`

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

### Constructor Detail

#### VFreeBusy

    public VFreeBusy()

Default constructor.

#### VFreeBusy

    public VFreeBusy(PropertyList properties)

Constructor.

Parameters:
  `properties` - a list of properties

#### 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 busy time for a specified period.

Parameters:
  `start` - the starting boundary for the VFreeBusy
  `end` - the ending boundary for the VFreeBusy

#### 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 time for a specified duration in given period defined by the start date and end date.

Parameters:
  `start` - the starting boundary for the VFreeBusy
  `end` - the ending boundary for the VFreeBusy
  `duration` - the length of the period being requested

#### 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
Throws:
  `ValidationException`

### Method Detail

#### validate

    public final void validate(boolean recurse)
                        throws ValidationException

Perform validation on a component.

Specified by:
  `validate` in class `Component`
Parameters:
  `recurse` - indicates whether to validate the component's properties
Throws:
  `ValidationException` - where the component is not in a valid state

#### getValidator

    protected Validator getValidator(Method method)

Specified by:
  `getValidator` in class `CalendarComponent`
Parameters:
  `method` - a method to validate on
Returns:
  a validator for the specified method or null if the method is not supported

#### getContact

    public final Contact getContact()

Returns:
  the CONTACT property or null if not specified

#### getStartDate

    public final DtStart getStartDate()

Returns:
  the DTSTART propery or null if not specified

#### getEndDate

    public final DtEnd getEndDate()

Returns:
  the DTEND property or null if not specified

#### getDuration

    public final Duration getDuration()

Returns:
  the DURATION property or null if not specified

#### getDateStamp

    public final DtStamp getDateStamp()

Returns:
  the DTSTAMP property or null if not specified

#### getOrganizer

    public final Organizer getOrganizer()

Returns:
  the ORGANIZER property or null if not specified

#### getUrl

    public final Url getUrl()

Returns:
  the URL property or null if not specified

#### 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