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

   4.6.6 Alarm Component

      Component Name: VALARM

      Purpose: Provide a grouping of component properties that define an
      alarm.

      Formal Definition: A "VALARM" calendar component is defined by the
      following notation:

             alarmc     = "BEGIN" ":" "VALARM" CRLF
                          (audioprop / dispprop / emailprop / procprop)
                          "END" ":" "VALARM" CRLF

        audioprop  = 2*(

                   ; 'action' and 'trigger' are both REQUIRED,
                   ; but MUST NOT occur more than once

                   action / trigger /

                   ; 'duration' and 'repeat' are both optional,
                   ; and MUST NOT occur more than once each,
                   ; but if one occurs, so MUST the other

                   duration / repeat /

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

                   attach /

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

                   x-prop

                   )



        dispprop   = 3*(

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

                   action / description / trigger /

                   ; 'duration' and 'repeat' are both optional,
                   ; and MUST NOT occur more than once each,
                   ; but if one occurs, so MUST the other

                   duration / repeat /

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

                   *x-prop

                   )



        emailprop  = 5*(

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

                   action / description / trigger / summary

                   ; the following is REQUIRED,
                   ; and MAY occur more than once

                   attendee /

                   ; 'duration' and 'repeat' are both optional,
                   ; and MUST NOT occur more than once each,
                   ; but if one occurs, so MUST the other

                   duration / repeat /

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

                   attach / x-prop

                   )



        procprop   = 3*(

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

                   action / attach / trigger /

                   ; 'duration' and 'repeat' are both optional,
                   ; and MUST NOT occur more than once each,
                   ; but if one occurs, so MUST the other

                   duration / repeat /

                   ; 'description' is optional,
                   ; and MUST NOT occur more than once

                   description /

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

                   x-prop

                   )

Example 1 - Creating an alarm to trigger at a specific time:

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);

VAlarm christmas = new VAlarm(cal.getTime());

Example 2 - Creating an alarm to trigger one (1) hour before the scheduled start of the parent event/the parent todo is due:

VAlarm reminder = new VAlarm(new Dur(0, -1, 0, 0));

// repeat reminder four (4) more times every fifteen (15) minutes..
reminder.add(new Repeat(4));
reminder.add(new Duration(new Dur(0, 0, 15, 0)));

// display a message..
reminder.add(Action.DISPLAY);
reminder.add(new Description("Progress Meeting at 9:30am"));