com.nitido.nimx.nuggets.wcap
Class Alarm

java.lang.Object
  com.nitido.nimx.nuggets.wcap.Alarm

public class Alarm
extends java.lang.Object

The Alarm object encapsulate the information for a reminder alarm. The current implementation supports the reminder notification through email only. As a result, the Alarm object contains only two fields: time and email.

The iPlanet Calendar's implementation of Alarm component (i.e. reminder) follows the framework of RFC 2445. The section 4.6.6 and 4.8.6 of RFC 2445 contains more information on the Alarm component.

This object is used by Event or ToDo ojbects for indicating the reminder information.

The JavaDoc description of the default constructor contains more information of the fields.

Field Summary

static Alarm

NO_ALARM This object is used for removing the alarm notificaiton from an existing event/todo.

Constructor Summary

Alarm(java.util.Date time, Duration duration, java.util.Vector emails)
Duration based constructor.

Alarm(java.util.Date time, java.util.Vector emails)
Time based constructor.

Alarm(Duration duration, java.util.Vector emails)
Duration based constructor.

Method Summary

boolean	equals(java.lang.Object inObj) Override the default java.lang.Object's equal command.
Duration	getDuration() Get the duration field.
java.util.Vector	getEmails() Get the emails field.
java.util.Date	getTime() Get the time field.
void	setDuration(Duration duration) Set the duration field.
void	setEmails(java.util.Vector emails) Set the emails field.
void	setTime(java.util.Date time) Set the time field.
java.lang.String	toString() Returns a meaningful message with respect to the content of the object.
java.lang.String	toWcapQuery(WcapNugget nugget, java.text.DateFormat dfFull) Convert the component into a string that is used for constructing a WCAP query.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

NO_ALARM

public static final Alarm NO_ALARM

This object is used for removing the alarm notificaiton from an existing event/todo.

In WCAP, if we don't specify a value, the server will regard it as no change. Therefore, there is no way to remove an alarm.

Therefore, we have a special instance of NO_ALARM, that can be used to turn off the alarm signals. This special instance of Alarm will tell the server to do an "alarm pop up" in 1970. (i.e. set it to an alarm that will never happens).

Constructor Detail

Alarm

public Alarm(java.util.Date time,
             java.util.Vector emails)
      throws InvalidParameterException

Time based constructor.

If you don't have any values for emails field, you should not create an Alarm object at all. You just don't have any valid reminder alarm. You may simply set the alarm field of your Event or ToDo to be null object to indicate there is no alarm setting.

If you don't have any valid value for the time field, but you have the duration value, you should use the duration based constructor instead of this constructor.

Parameters:

time - The GMT date-time for the reminder alarm to be triggered. Note: although it is supposed to be earlier than the actual occurrence of the event/todo, the server never check that. The application should check for this error itself.

emails - A Vector of String that contains the Strings of the email addresses to be notified when the reminder triggers. This Vector must contains at least one email. (Note: if you don't have any email address, you shouldn't create an Alarm object at all. You may just pass "null" to the corresponding field of Event and ToDo)

Throws:

InvalidParameterException

Alarm

public Alarm(Duration duration,
             java.util.Vector emails)
      throws InvalidParameterException

Duration based constructor.

If you don't have any values for emails field, you should not create an Alarm object at all. You just don't have any valid reminder alarm. You may simply set the alarm field of your Event or ToDo to be null object to indicate there is no alarm setting.

If you don't have any valid value for the duration field, but you have the time value, you should use the time based constructor instead of this constructor.

Parameters:

duration - The Duration object that specify when to send the alarm in the format of the time before the event/todo happens.

Please note that this duration is referencing the start time of the corresponding event or todo. If you want to trigger the alarm before the event or todo happens, this Duration object's isPositive boolean flag MUST be set to "false". Otherwise, your alarm triger will happen after the event or todo has happened.

emails - A Vector of String that contains the Strings of the email addresses to be notified when the reminder triggers. This Vector must contains at least one email. (Note: if you don't have any email address, you shouldn't create an Alarm object at all. You may just pass "null" to the corresponding field of Event and ToDo)

Throws:

InvalidParameterException

Alarm

public Alarm(java.util.Date time,
             Duration duration,
             java.util.Vector emails)
      throws InvalidParameterException

Duration based constructor.

If you don't have any values for emails field, you should not create an Alarm object at all. You just don't have any valid reminder alarm. You may simply set the alarm field of your Event or ToDo to be null object to indicate there is no alarm setting.

The time and duration parameters cannot be null at the same time. One of them must be valid. If both parameters are not null objects, the time parameter will be used while the duration parameter will be ignored.

Parameters:

time - The GMT date-time for the reminder alarm to be triggered. Note: although it is supposed to be earlier than the actual occurrence of the event/todo, the server never check that. The application should check for this error itself.

duration - The Duration object that specify when to send the alarm in the format of the time before the event/todo happens.

Please note that this duration is referencing the start time of the corresponding event or todo. If you want to trigger the alarm before the event or todo happens, this Duration object's isPositive boolean flag MUST be set to "false". Otherwise, your alarm triger will happen after the event or todo has happened.

emails - A Vector of String that contains the Strings of the email addresses to be notified when the reminder triggers. This Vector must contains at least one email. (Note: if you don't have any email address, you shouldn't create an Alarm object at all. You may just pass "null" to the corresponding field of Event and ToDo)

Throws:

InvalidParameterException

Method Detail

setTime

public void setTime(java.util.Date time)
             throws InvalidParameterException

Set the time field. The parameter must be a valid Date object.

Parameters:

time - The GMT date-time for the reminder alarm to be triggered. Note: although it is supposed to be earlier than the actual occurrence of the event/todo, the server never check that. The application should check for this error itself.

Throws:

InvalidParameterException

getTime

public java.util.Date getTime()

Get the time field.

setDuration

public void setDuration(Duration duration)
                 throws InvalidParameterException

Set the duration field. The parameter must be a valid Duration object.

Parameters:

duration - The Duration object that specify when to send the alarm in the format of the time before the event/todo happens.

Please note that this duration is referencing the start time of the corresponding event or todo. If you want to trigger the alarm before the event or todo happens, this Duration object's isPositive boolean flag MUST be set to "false". Otherwise, your alarm triger will happen after the event or todo has happened.

Throws:

InvalidParameterException

getDuration

public Duration getDuration()

Get the duration field.

setEmails

public void setEmails(java.util.Vector emails)
               throws InvalidParameterException

Set the emails field.

Parameters:

emails - A Vector of String that contains the Strings of the email addresses to be notified when the reminder triggers. This Vector must contains at least one email. (Note: if you don't have any email address, you shouldn't create an Alarm object at all. You may just pass "null" to the corresponding field of Event and ToDo)

Throws:

InvalidParameterException

getEmails

public java.util.Vector getEmails()

Get the emails field.

toWcapQuery

public java.lang.String toWcapQuery(WcapNugget nugget,
                                    java.text.DateFormat dfFull)
                             throws WcapException

Convert the component into a string that is used for constructing a WCAP query. This method is designed for internal use by the WcapNugget only.

Throws:

WcapException

equals

public boolean equals(java.lang.Object inObj)

Override the default java.lang.Object's equal command. This will compares the content of the fields. In case of a vector or array field, it will compare the content of the field.

Overrides:

equals in class java.lang.Object

toString

public java.lang.String toString()

Returns a meaningful message with respect to the content of the object. This is mainly used for debugging purpose.

Overrides:

toString in class java.lang.Object