Class VAlarm

java.lang.Object
jfxtras.icalendarfx.VElementBase
jfxtras.icalendarfx.VParentBase<VAlarm>
jfxtras.icalendarfx.components.VComponentBase<VAlarm>
jfxtras.icalendarfx.components.VCommon<VAlarm>
jfxtras.icalendarfx.components.VDescribableBase<VAlarm>
jfxtras.icalendarfx.components.VAlarm
All Implemented Interfaces:
VAttendee<VAlarm>, VComponent, VDescribable<VAlarm>, VDescribable2<VAlarm>, VDuration<VAlarm>, VChild, VElement, VParent
public class VAlarm extends VDescribableBase<VAlarm> implements VDescribable2<VAlarm>, VAttendee<VAlarm>, VDuration<VAlarm>

VALARM

Alarm Component
RFC 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.
      • invalid reference 
        IANA-PROP
      • X-PROP
  • dispprop
    • 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, and MAY occur more than once.
      • invalid reference 
        IANA-PROP
      • X-PROP
  • 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.

See Also:

  • Field Details

    • action

      private Action action

      Defines the action to be invoked when an alarm is triggered.
      RFC 5545 iCalendar 3.8.6.1 page 132

      actionvalue = "AUDIO" / "DISPLAY" / "EMAIL" / iana-token / x-name

      Example:

      • ACTION:DISPLAY

    • attendees

      private List<Attendee> attendees

    • description

      private Description description

    • duration

      private DurationProp duration

    • repeatCount

      private RepeatCount 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

      private Trigger<?> trigger

      This property specifies when an alarm will trigger.
      RFC 5545 iCalendar 3.8.6.3 page 133

      Examples:

        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

  • Constructor Details

    • VAlarm

      public VAlarm()
      Creates a default VAlarm calendar component with no properties

    • VAlarm

      public VAlarm(VAlarm source)
      Creates a deep copy of a VAlarm calendar component

  • Method Details

    • getAction

      public Action getAction()

    • setAction

      public void setAction(String action)

    • setAction

      public void setAction(Action action)

    • setAction

      public void setAction(Action.ActionType action)

    • withAction

      public VAlarm withAction(Action action)
      Sets the value of the
      invalid reference 
      #actionProperty()
      Returns:
      this class for chaining

    • withAction

      public VAlarm withAction(Action.ActionType actionType)
      Sets the value of the
      invalid reference 
      #actionProperty()
      by creating a new Action from the Action.ActionType parameter
      Returns:
      this class for chaining

    • withAction

      public VAlarm withAction(String action)
      Sets the value of the
      invalid reference 
      #actionProperty()
      by parsing iCalendar content text
      Returns:
      this class for chaining

    • getAttendees

      public List<Attendee> getAttendees()
      Description copied from interface: VAttendee

      This property defines an "Attendee" within a calendar component.
      RFC 5545 iCalendar 3.8.4.1 page 107

      Examples:

      • 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 interface VAttendee<VAlarm>

    • setAttendees

      public void setAttendees(List<Attendee> attendees)
      Specified by:
      setAttendees in interface VAttendee<VAlarm>

    • getDescription

      public Description 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 84

      Example:

      • 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 interface VDescribable2<VAlarm>

    • setDescription

      public void setDescription(Description description)
      Specified by:
      setDescription in interface VDescribable2<VAlarm>

    • getDuration

      public DurationProp getDuration()
      Description copied from interface: VDuration
      Gets the value of the DurationProp
      Specified by:
      getDuration in interface VDuration<VAlarm>

    • setDuration

      public void setDuration(DurationProp duration)
      Description copied from interface: VDuration
      Sets the value of the DurationProp
      Specified by:
      setDuration in interface VDuration<VAlarm>

    • getRepeatCount

      public RepeatCount getRepeatCount()

    • setRepeatCount

      public void setRepeatCount(RepeatCount repeatCount)

    • setRepeatCount

      public void setRepeatCount(int repeatCount)

    • setRepeatCount

      public void setRepeatCount(String repeatCount)

    • withRepeatCount

      public VAlarm withRepeatCount(RepeatCount repeatCount)
      Sets the value of the
      invalid reference 
      #repeatCountProperty()
      Returns:
      this class for chaining

    • withRepeatCount

      public VAlarm withRepeatCount(int repeatCount)
      Sets the value of the
      invalid reference 
      #repeatCountProperty()
      by creating new RepeatCount from int parameter
      Returns:
      this class for chaining

    • withRepeatCount

      public VAlarm withRepeatCount(String repeatCount)
      Sets the value of the
      invalid reference 
      #repeatCountProperty()
      by parsing iCalendar content text
      Returns:
      this class for chaining

    • getTrigger

      public Trigger<?> getTrigger()

    • setTrigger

      public void setTrigger(String trigger)

    • setTrigger

      public void setTrigger(Trigger<?> trigger)

    • setTrigger

      public void setTrigger(Duration trigger)

    • setTrigger

      public void setTrigger(ZonedDateTime trigger)

    • withTrigger

      public VAlarm withTrigger(Trigger<?> trigger)
      Sets the value of the
      invalid reference 
      #triggerProperty()
      Returns:
      this class for chaining

    • withTrigger

      public VAlarm withTrigger(Duration trigger)
      Sets the value of the
      invalid reference 
      #triggerProperty()
      by creating new Trigger from Duration parameter
      Returns:
      this class for chaining

    • withTrigger

      public VAlarm withTrigger(ZonedDateTime trigger)
      Sets the value of the
      invalid reference 
      #triggerProperty()
      by creating new Trigger from ZonedDateTime parameter
      Returns:
      this class for chaining

    • withTrigger

      public VAlarm withTrigger(String trigger)
      Sets the value of the
      invalid reference 
      #triggerProperty()
      by parsing iCalendar content text
      Returns:
      this class for chaining

    • errors

      public List<String> errors()
      Description copied from interface: VElement
      Produces a list of error messages indicating problems with calendar element VElement.errors() is invoked recursively to return errors of child elements in addition to errors in parent
      Specified by:
      errors in interface VElement
      Overrides:
      errors in class VParentBase<VAlarm>
      Returns:
      - list of error messages

    • calendarList

      public List<? extends VComponent> calendarList()
      Specified by:
      calendarList in interface VComponent

    • parse

      public static VAlarm parse(String content)
      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