$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());
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.
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.
duration
- the length of the period being requested
VFreeBusy
public VFreeBusy(PropertyList properties)
Constructor.
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.
request
- a VFREEBUSY requestcomponents
- a component list used to initialise busy time
getContact
public final Contact getContact()
getDateStamp
public final DtStamp getDateStamp()
getDuration
public final Duration getDuration()
getEndDate
public final DtEnd getEndDate()
getOrganizer
public final Organizer getOrganizer()
getStartDate
public final DtStart getStartDate()
getUid
public final Uid getUid()
Returns the UID property of this component if available.
- a Uid instance, or null if no UID property exists
getUrl
public final Url getUrl()
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