net.fortuna.ical4j.model.component

## Class VEvent

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

All Implemented Interfaces:
  Serializable

    public class VEvent
    extends CalendarComponent

$Id$ [Apr 5, 2004] Defines an iCalendar VEVENT component.

           4.6.1 Event Component

              Component Name: "VEVENT"

              Purpose: Provide a grouping of component properties that describe an
              event.

              Format Definition: A "VEVENT" calendar component is defined by the
              following notation:

                eventc     = "BEGIN" ":" "VEVENT" CRLF
                             eventprop *alarmc
                             "END" ":" "VEVENT" CRLF

                eventprop  = *(

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

                           class / created / description / dtstart / geo /
                           last-mod / location / organizer / priority /
                           dtstamp / seq / status / summary / transp /
                           uid / url / recurid /

                           ; either 'dtend' or 'duration' may appear in
                           ; a 'eventprop', but 'dtend' and 'duration'
                           ; MUST NOT occur in the same 'eventprop'

                           dtend / duration /

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

                           attach / attendee / categories / comment /
                           contact / exdate / exrule / rstatus / related /
                           resources / rdate / rrule / x-prop

                           )

Example 1 - Creating a new all-day event:

     java.util.Calendar cal = java.util.Calendar.getInstance();
     cal.set(java.util.Calendar.MONTH, java.util.Calendar.DECEMBER);
     cal.set(java.util.Calendar.DAY_OF_MONTH, 25);

     VEvent christmas = new VEvent(cal.getTime(), "Christmas Day");

     // initialise as an all-day event..
     christmas.getProperties().getProperty(Property.DTSTART).getParameters().add(
             Value.DATE);

     // add timezone information..
     VTimeZone tz = VTimeZone.getDefault();
     TzId tzParam = new TzId(tz.getProperties().getProperty(Property.TZID)
             .getValue());
     christmas.getProperties().getProperty(Property.DTSTART).getParameters().add(
             tzParam);

Example 2 - Creating an event of one (1) hour duration:

     java.util.Calendar cal = java.util.Calendar.getInstance();
     // tomorrow..
     cal.add(java.util.Calendar.DAY_OF_MONTH, 1);
     cal.set(java.util.Calendar.HOUR_OF_DAY, 9);
     cal.set(java.util.Calendar.MINUTE, 30);

     VEvent meeting = new VEvent(cal.getTime(), 1000 * 60 * 60, "Progress Meeting");

     // add timezone information..
     VTimeZone tz = VTimeZone.getDefault();
     TzId tzParam = new TzId(tz.getProperties().getProperty(Property.TZID)
             .getValue());
     meeting.getProperties().getProperty(Property.DTSTART).getParameters().add(
             tzParam);

Example 3 - Retrieve a list of periods representing a recurring event in a specified range:

     Calendar weekday9AM = Calendar.getInstance();
     weekday9AM.set(2005, Calendar.MARCH, 7, 9, 0, 0);
     weekday9AM.set(Calendar.MILLISECOND, 0);

     Calendar weekday5PM = Calendar.getInstance();
     weekday5PM.set(2005, Calendar.MARCH, 7, 17, 0, 0);
     weekday5PM.set(Calendar.MILLISECOND, 0);

     // Do the recurrence until December 31st.
     Calendar untilCal = Calendar.getInstance();
     untilCal.set(2005, Calendar.DECEMBER, 31);
     untilCal.set(Calendar.MILLISECOND, 0);

     // 9:00AM to 5:00PM Rule
     Recur recur = new Recur(Recur.WEEKLY, untilCal.getTime());
     recur.getDayList().add(WeekDay.MO);
     recur.getDayList().add(WeekDay.TU);
     recur.getDayList().add(WeekDay.WE);
     recur.getDayList().add(WeekDay.TH);
     recur.getDayList().add(WeekDay.FR);
     recur.setInterval(3);
     recur.setWeekStartDay(WeekDay.MO.getDay());
     RRule rrule = new RRule(recur);

     Summary summary = new Summary("TEST EVENTS THAT HAPPEN 9-5 MON-FRI");

     weekdayNineToFiveEvents = new VEvent();
     weekdayNineToFiveEvents.getProperties().add(rrule);
     weekdayNineToFiveEvents.getProperties().add(summary);
     weekdayNineToFiveEvents.getProperties().add(new DtStart(weekday9AM.getTime()));
     weekdayNineToFiveEvents.getProperties().add(new DtEnd(weekday5PM.getTime()));

     // Test Start 04/01/2005, End One month later.
     // Query Calendar Start and End Dates.
     Calendar queryStartDate = Calendar.getInstance();
     queryStartDate.set(2005, Calendar.APRIL, 1, 14, 47, 0);
     queryStartDate.set(Calendar.MILLISECOND, 0);
     Calendar queryEndDate = Calendar.getInstance();
     queryEndDate.set(2005, Calendar.MAY, 1, 11, 15, 0);
     queryEndDate.set(Calendar.MILLISECOND, 0);

     // This range is monday to friday every three weeks, starting from
     // March 7th 2005, which means for our query dates we need
     // April 18th through to the 22nd.
     PeriodList periods = weekdayNineToFiveEvents.getPeriods(queryStartDate
             .getTime(), queryEndDate.getTime());

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
`VEvent()` Default constructor.
`VEvent(Date start, Date end, String summary)` Constructs a new VEVENT instance starting and ending at the specified times with the specified summary.
`VEvent(Date start, Dur duration, String summary)` Constructs a new VEVENT instance starting at the specified times, for the specified duration, with the specified summary.
`VEvent(Date start, String summary)` Constructs a new VEVENT instance starting at the specified time with the specified summary.
`VEvent(PropertyList properties)` Constructor.
`VEvent(PropertyList properties, ComponentList alarms)` Constructor.

### Method Summary

Methods
`Component` `copy()` Overrides default copy method to add support for copying alarm sub-components.
`boolean` `equals(Object arg0)`
`ComponentList` `getAlarms()` Returns the list of alarms for this event.
`Clazz` `getClassification()`
`PeriodList` `getConsumedTime(Date rangeStart, Date rangeEnd)` Returns a normalised list of periods representing the consumed time for this event.
`PeriodList` `getConsumedTime(Date rangeStart, Date rangeEnd, boolean normalise)` Returns a list of periods representing the consumed time for this event in the specified range.
`Created` `getCreated()`
`DtStamp` `getDateStamp()`
`Description` `getDescription()`
`Duration` `getDuration()`
`DtEnd` `getEndDate()` Returns the end date of this event.
`DtEnd` `getEndDate(boolean deriveFromDuration)` Convenience method to pull the DTEND out of the property list.
`Geo` `getGeographicPos()`
`LastModified` `getLastModified()`
`Location` `getLocation()`
`VEvent` `getOccurrence(Date date)` Returns a single occurrence of a recurring event.
`Organizer` `getOrganizer()`
`Priority` `getPriority()`
`RecurrenceId` `getRecurrenceId()`
`Sequence` `getSequence()`
`DtStart` `getStartDate()` Convenience method to pull the DTSTART out of the property list.
`Status` `getStatus()`
`Summary` `getSummary()`
`Transp` `getTransparency()`
`Uid` `getUid()` Returns the UID property of this component if available.
`Url` `getUrl()`
`protected Validator` `getValidator(Method method)`
`int` `hashCode()`
`String` `toString()`
`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, getName, getProperties, getProperties, getProperty, validate, validateProperties`

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

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

### Constructor Detail

#### VEvent

    public VEvent()

Default constructor.

#### VEvent

    public VEvent(PropertyList properties)

Constructor.

Parameters:
  `properties` - a list of properties

#### VEvent

    public VEvent(PropertyList properties,
          ComponentList alarms)

Constructor.

Parameters:
  `properties` - a list of properties
  `alarms` - a list of alarms

#### VEvent

    public VEvent(Date start,
          String summary)

Constructs a new VEVENT instance starting at the specified time with the specified summary.

Parameters:
  `start` - the start date of the new event
  `summary` - the event summary

#### VEvent

    public VEvent(Date start,
          Date end,
          String summary)

Constructs a new VEVENT instance starting and ending at the specified times with the specified summary.

Parameters:
  `start` - the start date of the new event
  `end` - the end date of the new event
  `summary` - the event summary

#### VEvent

    public VEvent(Date start,
          Dur duration,
          String summary)

Constructs a new VEVENT instance starting at the specified times, for the specified duration, with the specified summary.

Parameters:
  `start` - the start date of the new event
  `duration` - the duration of the new event
  `summary` - the event summary

### Method Detail

#### getAlarms

    public final ComponentList getAlarms()

Returns the list of alarms for this event.

Returns:
  a component list

#### toString

    public final String toString()

Overrides:
  `toString` in class `Component`

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

#### getConsumedTime

    public final PeriodList getConsumedTime(Date rangeStart,
                             Date rangeEnd)

Returns a normalised list of periods representing the consumed time for this event.

Parameters:
  `rangeStart` - the start of a range
  `rangeEnd` - the end of a range
Returns:
  a normalised list of periods representing consumed time for this event
See Also:
  `getConsumedTime(Date, Date, boolean)`

#### getConsumedTime

    public final PeriodList getConsumedTime(Date rangeStart,
                             Date rangeEnd,
                             boolean normalise)

Returns a list of periods representing the consumed time for this event in the specified range. Note that the returned list may contain a single period for non-recurring components or multiple periods for recurring components. If no time is consumed by this event an empty list is returned.

Parameters:
  `rangeStart` - the start of the range to check for consumed time
  `rangeEnd` - the end of the range to check for consumed time
  `normalise` - indicate whether the returned list of periods should be normalised
Returns:
  a list of periods representing consumed time for this event

#### getOccurrence

    public final VEvent getOccurrence(Date date)
                               throws IOException,
                                      URISyntaxException,
                                      ParseException

Returns a single occurrence of a recurring event.

Parameters:
  `date` - a date on which the occurence should occur
Returns:
  a single non-recurring event instance for the specified date, or null if the event doesn't occur on the specified date
Throws:
  `IOException` - where an error occurs reading data
  `URISyntaxException` - where an invalid URI is encountered
  `ParseException` - where an error occurs parsing data

#### getClassification

    public final Clazz getClassification()

Returns:
  the optional access classification property for an event

#### getCreated

    public final Created getCreated()

Returns:
  the optional creation-time property for an event

#### getDescription

    public final Description getDescription()

Returns:
  the optional description property for an event

#### getStartDate

    public final DtStart getStartDate()

Convenience method to pull the DTSTART out of the property list.

Returns:
  The DtStart object representation of the start Date

#### getGeographicPos

    public final Geo getGeographicPos()

Returns:
  the optional geographic position property for an event

#### getLastModified

    public final LastModified getLastModified()

Returns:
  the optional last-modified property for an event

#### getLocation

    public final Location getLocation()

Returns:
  the optional location property for an event

#### getOrganizer

    public final Organizer getOrganizer()

Returns:
  the optional organizer property for an event

#### getPriority

    public final Priority getPriority()

Returns:
  the optional priority property for an event

#### getDateStamp

    public final DtStamp getDateStamp()

Returns:
  the optional date-stamp property

#### getSequence

    public final Sequence getSequence()

Returns:
  the optional sequence number property for an event

#### getStatus

    public final Status getStatus()

Returns:
  the optional status property for an event

#### getSummary

    public final Summary getSummary()

Returns:
  the optional summary property for an event

#### getTransparency

    public final Transp getTransparency()

Returns:
  the optional time transparency property for an event

#### getUrl

    public final Url getUrl()

Returns:
  the optional URL property for an event

#### getRecurrenceId

    public final RecurrenceId getRecurrenceId()

Returns:
  the optional recurrence identifier property for an event

#### getEndDate

    public final DtEnd getEndDate()

Returns the end date of this event. Where an end date is not available it will be derived from the event duration.

Returns:
  a DtEnd instance, or null if one cannot be derived

#### getEndDate

    public final DtEnd getEndDate(boolean deriveFromDuration)

Convenience method to pull the DTEND out of the property list. If DTEND was not specified, use the DTSTART + DURATION to calculate it.

Parameters:
  `deriveFromDuration` - specifies whether to derive an end date from the event duration where an end date is not found
Returns:
  The end for this VEVENT.

#### getDuration

    public final Duration getDuration()

Returns:
  the optional Duration property

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

#### equals

    public boolean equals(Object arg0)

Overrides:
  `equals` in class `Component`

#### hashCode

    public int hashCode()

Overrides:
  `hashCode` in class `Component`

#### copy

    public Component copy()
                   throws ParseException,
                          IOException,
                          URISyntaxException

Overrides default copy method to add support for copying alarm sub-components.

Overrides:
  `copy` in class `Component`
Returns:
  a copy of the instance
Throws:
  `ParseException` - where values in the instance cannot be parsed
  `IOException` - where values in the instance cannot be read
  `URISyntaxException` - where an invalid URI value is encountered in the instance
See Also:
  `Component.copy()`