- All Implemented Interfaces:
VAttendee<VAlarm>
,VComponent
,VDescribable<VAlarm>
,VDescribable2<VAlarm>
,VDuration<VAlarm>
,VChild
,VElement
,VParent
VALARM
Alarm ComponentRFC 5545 iCalendar 3.6.6. page 71
The body of the iCalendar object is defined by the following notation:
- alarmc
- "BEGIN" ":" "VALARM" CRLF
- (audioprop / dispprop / emailprop)
- "END" ":" "VALARM" CRLF
- audioprop
- The following are REQUIRED, but MUST NOT occur more than once.
- The following are OPTIONAL, but MUST NOT occur more than once; but if one occurs, so MUST the other.
- The following are OPTIONAL, but MUST NOT occur more than once.
- The following are OPTIONAL, and MAY occur more than once.
IANA-PROP
X-PROP
- dispprop
- emailprop
- The following are REQUIRED, but MUST NOT occur more than once.
- The following are REQUIRED, but MAY occur more than once.
- The following are OPTIONAL, but MUST NOT occur more than once; but if one occurs, so MUST the other.
- The following are OPTIONAL, and MAY occur more than once.
Provide a grouping of component properties that define an alarm.
Description: A VALARM
calendar component is a grouping of
component properties that is a reminder or alarm for an event or a
to-do. For example, it may be used to define a reminder for a
pending event or an overdue to-do.
The VALARM
calendar component MUST include the ACTION
and
TRIGGER
properties. The ACTION
property further constrains
the VALARM
calendar component in the following ways:
When the action is "AUDIO", the alarm can also include one and
only one ATTACH
property, which MUST point to a sound resource,
which is rendered when the alarm is triggered.
When the action is "DISPLAY", the alarm MUST also include a
DESCRIPTION
property, which contains the text to be displayed
when the alarm is triggered.
When the action is "EMAIL", the alarm MUST include a DESCRIPTION
property, which contains the text to be used as the message body,
a SUMMARY
property, which contains the text to be used as the
message subject, and one or more ATTENDEE
properties, which
contain the email address of attendees to receive the message. It
can also include one or more ATTACH
properties, which are
intended to be sent as message attachments. When the alarm is
triggered, the email message is sent.
The VALARM
calendar component MUST only appear within either a
VEVENT
or VTODO
calendar component. VALARM
calendar
components cannot be nested. Multiple mutually independent
VALARM
calendar components can be specified for a single
VEVENT
or VTODO
calendar component.
The TRIGGER
property specifies when the alarm will be triggered.
The TRIGGER
property specifies a duration prior to the start of
an event or a to-do. The TRIGGER
edge may be explicitly set to
be relative to the "START" or "END" of the event or to-do with the
"RELATED" parameter of the TRIGGER
property. The TRIGGER
property value type can alternatively be set to an absolute
calendar date with UTC time.
In an alarm set to trigger on the "START" of an event or to-do,
the DTSTART
property MUST be present in the associated event or
to-do. In an alarm in a VEVENT
calendar component set to
trigger on the "END" of the event, either the DTEND
property
MUST be present, or the DTSTART
and DURATION
properties MUST
both be present. In an alarm in a VTODO
calendar component set
to trigger on the "END" of the to-do, either the "DUE" property
MUST be present, or the DTSTART
and DURATION
properties MUST
both be present.
The alarm can be defined such that it triggers repeatedly. A
definition of an alarm with a repeating trigger MUST include both
the DURATION
and REPEAT
properties. The DURATION
property
specifies the delay period, after which the alarm will repeat.
The REPEAT
property specifies the number of additional
repetitions that the alarm will be triggered. This repetition
count is in addition to the initial triggering of the alarm. Both
of these properties MUST be present in order to specify a
repeating alarm. If one of these two properties is absent, then
the alarm will not repeat beyond the initial trigger.
The ACTION
property is used within the VALARM
calendar
component to specify the type of action invoked when the alarm is
triggered. The VALARM
properties provide enough information for
a specific action to be invoked. It is typically the
responsibility of a "Calendar User Agent" (CUA) to deliver the
alarm in the specified fashion. An ACTION
property value of
AUDIO specifies an alarm that causes a sound to be played to alert
the user; DISPLAY specifies an alarm that causes a text message to
be displayed to the user; and EMAIL specifies an alarm that causes
an electronic email message to be delivered to one or more email
addresses.
In an AUDIO alarm, if the optional ATTACH
property is included,
it MUST specify an audio sound resource. The intention is that
the sound will be played as the alarm effect. If an ATTACH
property is specified that does not refer to a sound resource, or
if the specified sound resource cannot be rendered (because its
format is unsupported, or because it cannot be retrieved), then
the CUA or other entity responsible for playing the sound may
choose a fallback action, such as playing a built-in default
sound, or playing no sound at all.
In a DISPLAY alarm, the intended alarm effect is for the text
value of the DESCRIPTION
property to be displayed to the user.
In an EMAIL alarm, the intended alarm effect is for an email
message to be composed and delivered to all the addresses
specified by the ATTENDEE
properties in the VALARM
calendar
component. The DESCRIPTION
property of the VALARM
calendar
component MUST be used as the body text of the message, and the
SUMMARY
property MUST be used as the subject text. Any ATTACH
properties in the VALARM
calendar component SHOULD be sent as
attachments to the message.
Note: Implementations should carefully consider whether they accept alarm components from untrusted sources, e.g., when importing calendar objects from external sources. One reasonable policy is to always ignore alarm components that the calendar user has not set herself, or at least ask for confirmation in such a case.
-
Nested Class Summary
Nested classes/interfaces inherited from class jfxtras.icalendarfx.VElementBase
VElementBase.Message, VElementBase.MessageEffect
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Action
Defines the action to be invoked when an alarm is triggered.
RFC 5545 iCalendar 3.8.6.1 page 132private Description
private DurationProp
private RepeatCount
This property defines the number of times the alarm should be repeated, after the initial trigger.
RFC 5545 iCalendar 3.8.6.2 page 133,private Trigger<?>
This property specifies when an alarm will trigger.
RFC 5545 iCalendar 3.8.6.3 page 133Fields inherited from class jfxtras.icalendarfx.components.VComponentBase
parent
Fields inherited from class jfxtras.icalendarfx.VParentBase
contentLineGenerator, orderer
Fields inherited from class jfxtras.icalendarfx.VElementBase
BEGIN, END
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionList<? extends VComponent>
errors()
Produces a list of error messages indicating problems with calendar elementVElement.errors()
is invoked recursively to return errors of child elements in addition to errors in parentThis property defines an "Attendee" within a calendar component.
RFC 5545 iCalendar 3.8.4.1 page 107This property provides a more complete description of the calendar component than that provided by theSummary
property.
RFC 5545 iCalendar 3.8.1.5.Gets the value of theDurationProp
Trigger<?>
static VAlarm
Creates a new VAlarm calendar component by parsing a String of iCalendar content linesvoid
void
void
setAction
(Action.ActionType action) void
setAttendees
(List<Attendee> attendees) void
setDescription
(Description description) void
setDuration
(DurationProp duration) Sets the value of theDurationProp
void
setRepeatCount
(int repeatCount) void
setRepeatCount
(String repeatCount) void
setRepeatCount
(RepeatCount repeatCount) void
setTrigger
(String trigger) void
setTrigger
(Duration trigger) void
setTrigger
(ZonedDateTime trigger) void
setTrigger
(Trigger<?> trigger) withAction
(String action) Sets the value of the#actionProperty()
by parsing iCalendar content textwithAction
(Action action) Sets the value of the#actionProperty()
withAction
(Action.ActionType actionType) Sets the value of the#actionProperty()
by creating a newAction
from theAction.ActionType
parameterwithRepeatCount
(int repeatCount) Sets the value of the#repeatCountProperty()
by creating newRepeatCount
from int parameterwithRepeatCount
(String repeatCount) Sets the value of the#repeatCountProperty()
by parsing iCalendar content textwithRepeatCount
(RepeatCount repeatCount) Sets the value of the#repeatCountProperty()
withTrigger
(String trigger) Sets the value of the#triggerProperty()
by parsing iCalendar content textwithTrigger
(Duration trigger) Sets the value of the#triggerProperty()
by creating newTrigger
from Duration parameterwithTrigger
(ZonedDateTime trigger) Sets the value of the#triggerProperty()
by creating newTrigger
from ZonedDateTime parameterwithTrigger
(Trigger<?> trigger) Sets the value of the#triggerProperty()
Methods inherited from class jfxtras.icalendarfx.components.VDescribableBase
getAttachments, getSummary, setAttachments, setSummary
Methods inherited from class jfxtras.icalendarfx.components.VCommon
getNonStandard, setNonStandard, withNonStandard, withNonStandard, withNonStandard
Methods inherited from class jfxtras.icalendarfx.components.VComponentBase
addSubcomponent, getParent, isContentValid, name, setParent
Methods inherited from class jfxtras.icalendarfx.VParentBase
addChild, addChild, addChild, addChildInternal, checkChild, childrenUnmodifiable, collectGetterMap, collectSetterMap, copyChildrenInto, equals, getGetter, getGetters, getSetter, getSetters, hashCode, orderChild, orderChild, orderChild, parseContent, parseContent, processInLineChild, removeChild, removeChild, replaceChild, replaceChild, toString, withChild
Methods inherited from class jfxtras.icalendarfx.VElementBase
elementName, newEmptyVElement, parse, throwMessageExceptions
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface jfxtras.icalendarfx.components.VAttendee
withAttendees, withAttendees, withAttendees
Methods inherited from interface jfxtras.icalendarfx.components.VComponent
toString
Methods inherited from interface jfxtras.icalendarfx.components.VDescribable
getAttachments, getSummary, setAttachments, setSummary, setSummary, withAttachments, withAttachments, withAttachments, withSummary, withSummary
Methods inherited from interface jfxtras.icalendarfx.components.VDescribable2
setDescription, withDescription, withDescription
Methods inherited from interface jfxtras.icalendarfx.components.VDuration
setDuration, setDuration, withDuration, withDuration, withDuration
Methods inherited from interface jfxtras.icalendarfx.VParent
addChild, addChild, addChild, childrenUnmodifiable, orderChild, orderChild, orderChild, removeChild, removeChild, replaceChild, replaceChild
-
Field Details
-
action
Defines the action to be invoked when an alarm is triggered.
RFC 5545 iCalendar 3.8.6.1 page 132actionvalue = "AUDIO" / "DISPLAY" / "EMAIL" / iana-token / x-name
Example:
- ACTION:DISPLAY
-
attendees
-
description
-
duration
-
repeatCount
This property defines the number of times the alarm should be repeated, after the initial trigger.
RFC 5545 iCalendar 3.8.6.2 page 133,If the alarm triggers more than once, then this property MUST be specified along with the
DURATION
property.Example: The following is an example of this property for an alarm that repeats 4 additional times with a 5-minute delay after the initial triggering of the alarm:
REPEAT:4
DURATION:PT5M -
trigger
This property specifies when an alarm will trigger.
RFC 5545 iCalendar 3.8.6.3 page 133Examples:
-
A trigger set 15 minutes prior to the start of the event or to-do.
- TRIGGER:-PT15M
A trigger set five minutes after the end of an event or the due date of a to-do. - TRIGGER;RELATED=END:PT5M
A trigger set to an absolute DATE-TIME. - TRIGGER;VALUE=DATE-TIME:19980101T050000Z
- TRIGGER:-PT15M
-
-
Constructor Details
-
VAlarm
public VAlarm()Creates a default VAlarm calendar component with no properties -
VAlarm
Creates a deep copy of a VAlarm calendar component
-
-
Method Details
-
getAction
-
setAction
-
setAction
-
setAction
-
withAction
Sets the value of the#actionProperty()
- Returns:
- this class for chaining
-
withAction
Sets the value of the#actionProperty()
by creating a newAction
from theAction.ActionType
parameter- Returns:
- this class for chaining
-
withAction
Sets the value of the#actionProperty()
by parsing iCalendar content text- Returns:
- this class for chaining
-
getAttendees
Description copied from interface:VAttendee
This property defines an "Attendee" within a calendar component.
RFC 5545 iCalendar 3.8.4.1 page 107Examples:
- ATTENDEE;MEMBER="mailto:DEV-GROUP@example.com":
mailto:joecool@example.com - ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED;CN=Jane Doe
:mailto:jdoe@example.com
- Specified by:
getAttendees
in interfaceVAttendee<VAlarm>
- ATTENDEE;MEMBER="mailto:DEV-GROUP@example.com":
-
setAttendees
- Specified by:
setAttendees
in interfaceVAttendee<VAlarm>
-
getDescription
Description copied from interface:VDescribable2
This property provides a more complete description of the calendar component than that provided by the
Summary
property.
RFC 5545 iCalendar 3.8.1.5. page 84Example:
- DESCRIPTION:Meeting to provide technical review for "Phoenix"
design.\nHappy Face Conference Room. Phoenix design team
MUST attend this meeting.\nRSVP to team leader.
Note: Only
VJournal
allows multiple instances of DESCRIPTION- Specified by:
getDescription
in interfaceVDescribable2<VAlarm>
- DESCRIPTION:Meeting to provide technical review for "Phoenix"
-
setDescription
- Specified by:
setDescription
in interfaceVDescribable2<VAlarm>
-
getDuration
Description copied from interface:VDuration
Gets the value of theDurationProp
- Specified by:
getDuration
in interfaceVDuration<VAlarm>
-
setDuration
Description copied from interface:VDuration
Sets the value of theDurationProp
- Specified by:
setDuration
in interfaceVDuration<VAlarm>
-
getRepeatCount
-
setRepeatCount
-
setRepeatCount
public void setRepeatCount(int repeatCount) -
setRepeatCount
-
withRepeatCount
Sets the value of the#repeatCountProperty()
- Returns:
- this class for chaining
-
withRepeatCount
Sets the value of the#repeatCountProperty()
by creating newRepeatCount
from int parameter- Returns:
- this class for chaining
-
withRepeatCount
Sets the value of the#repeatCountProperty()
by parsing iCalendar content text- Returns:
- this class for chaining
-
getTrigger
-
setTrigger
-
setTrigger
-
setTrigger
-
setTrigger
-
withTrigger
Sets the value of the#triggerProperty()
- Returns:
- this class for chaining
-
withTrigger
Sets the value of the#triggerProperty()
by creating newTrigger
from Duration parameter- Returns:
- this class for chaining
-
withTrigger
Sets the value of the#triggerProperty()
by creating newTrigger
from ZonedDateTime parameter- Returns:
- this class for chaining
-
withTrigger
Sets the value of the#triggerProperty()
by parsing iCalendar content text- Returns:
- this class for chaining
-
errors
Description copied from interface:VElement
Produces a list of error messages indicating problems with calendar elementVElement.errors()
is invoked recursively to return errors of child elements in addition to errors in parent- Specified by:
errors
in interfaceVElement
- Overrides:
errors
in classVParentBase<VAlarm>
- Returns:
- - list of error messages
-
calendarList
- Specified by:
calendarList
in interfaceVComponent
-
parse
Creates a new VAlarm calendar component by parsing a String of iCalendar content lines- Parameters:
content
- the text to parse, not null- Returns:
- the parsed VAlarm
-