com.nitido.nimx.nuggets.wcap
Class WcapNugget

java.lang.Object
  com.nitido.nim.Nugget
      com.nitido.nim.CachableNugget
          com.nitido.nimx.nuggets.wcap.WcapNugget

All Implemented Interfaces:

CredentialConstants, java.io.Serializable

public class WcapNugget
extends CachableNugget
implements CredentialConstants

WcapNugget - A Nugget that wraps iPlanet Calendar Server Web Calendar Access Protocol (WCAP) commands. The design is based on WCAP version 2.0 running on iCS v5.1 or later.

It requires the following settings:

1. host (KEY_HOST)
   - the host name of the calendar server.
2. port (KEY_PORT)
   - the port number of the calendar server.
3. autologin (KEY_AUTOLOGIN)
   - if true, the nugget will login automatically when it is instantiated. It will also force all of the member methods to relogin automatically if the session has expired. If this parameter is not set or false, the caller will need to explicitly use the login() and sessionIsAlive() methods.
4. relogin.delay (KEY_RELOGIN_DELAY)
   - the time for the nugget to sleep before attempting relogin.
5. relogin.limit (KEY_RELOGIN_LIMIT)
   - the number of attempt relogin before the nugget throws an exception for the login problem
6. cred.loginid (KEY_CRED_USERID)
   - specifies the key of the credential token to be used as the login user ID for the calendar. (The credential comes from the Entity that instantiates this nugget.) - This configuration is optional. If no value has been defined or it is an empty string, the nugget will use the credential's entity ID as the login user ID for this nugget.
7. cred.password (KEY_CRED_PASSWORD)
   - specifies the key of the credential token to be used as the login password for the calendar. (The credential comes from the Entity that instantiates this nugget.) - This configuration is optional. If no value has been defined or it is an empty string, the nugget will use the credential token "password" as the login password for the calendar. (The constant for the token key "password" is defined in com.nitido.nim.CredentialConstants.KEY_PASSWORD)
8. url.charset (KEY_URL_CHARSET)
   - specifies the character set to be used for URL encoding. According to W3C recommendation, it is recommended to use "UTF-8" for the encoding. - This configuration is optional. If no value has been defined or it is an empty string, the nugget will use the "UTF-8" as the character set for URL encoding.
9. busyonly (KEY_BUSY_ONLY)
   - a string of "true" or "false" that indicates whether to return only the busy slots when getFreeBusy() is invoked. - This option is effective only if the backend calendar server is running WCAP 3.0 (SunONE Calendar Server 6).
   - This configuration is optional. If no value has been defined or it is an empty string, the nugget will treat it as "false". (i.e. getFreeBusy will return both free and busy slots.)
   
10. relativealarm (KEY_RELATIVE_ALARM)
    - WCAP allow users to store an alarm time in the absolute time or as a time duration. This option value is a string of "true" or "false" that indicates whether to return the alarm time as it was stored at the beginning.
    - This option is effective only if the backend calendar server is running WCAP 3.0 (SunONE Calendar Server 6).
    - This configuration is optional. If no value has been defined or it is an empty string, the nugget will treat it as "false". (i.e. getFreeBusy will return both free and busy slots.)
    

See Also:

Serialized Form

Field Summary

static java.lang.String	DEFAULT_TIMEZONE_ID
static java.lang.String	KEY_AUTOLOGIN
static java.lang.String	KEY_BUSY_ONLY
static java.lang.String	KEY_CRED_PASSWORD
static java.lang.String	KEY_CRED_USERID
static java.lang.String	KEY_HOST
static java.lang.String	KEY_PORT
static java.lang.String	KEY_RELATIVE_ALARM
static java.lang.String	KEY_RELOGIN_DELAY
static java.lang.String	KEY_RELOGIN_LIMIT
static java.lang.String	KEY_URL_CHARSET

Fields inherited from class com.nitido.nim.Nugget

_entity, _nim, _nuggetName, _settings

Fields inherited from interface com.nitido.nim.CredentialConstants

CRED_ADMIN, CRED_CONTAINER, CRED_HELPDESK, CRED_SYSTEM, CRED_USER, KEY_PASSWORD

Constructor Summary

WcapNugget(NuggetVisa visa)
Default Nugget constructor.

Method Summary

void	activate() Used by NiM Nugget mechanism.
CalendarProperty	createCalendar(java.lang.String calId) Create a calendar (with default properties).
CalendarProperty	createCalendarWithProperty(CalendarProperty calProp) Create a calendar with the specified properties.
void	deactivate() Used by NiM Nugget mechanism.
void	deleteCalendar(java.lang.String calId) Delete the specific calendar.
void	deleteEventsById(java.lang.String calId, java.lang.String uid, java.lang.String rid, WcapModifier mod, boolean notify) Remove the specified event and its recurrence as specified.
void	deleteEventsByRange(java.lang.String calId, java.util.Date dtstart, java.util.Date dtend) Delete all events within the specified time range.
void	deleteToDosById(java.lang.String calId, java.lang.String uid, java.lang.String rid, WcapModifier mod, boolean notify) Remove the specified todo and its recurrence as specified.
void	deleteToDosByRange(java.lang.String calId, java.util.Date dtstart, java.util.Date dtend) Delete ToDos within the range.
java.util.Vector	fetchEventsByAlarmRange(java.lang.String calId, java.util.Date dtstart, java.util.Date dtend, int maxResults) Retrieve events from the specified calendar that have alarm (reminder) within the time range.
java.util.Vector	fetchEventsByAttendeeError(java.lang.String calId, java.lang.String attendee, int maxResults) Retrieves all events from the specified calId that has errors associated to the attendee.
java.util.Vector	fetchEventsById(java.lang.String calId, java.lang.String uid, java.lang.String rid, WcapModifier modifier) Fetch the event and all its recurrences from the specified calendar.
java.util.Vector	fetchEventsByLastMod(java.lang.String calId, java.util.Date dtstart, java.util.Date dtend, int maxResults) Retrieves all events from the specified calendar that has been modified within the time range.
java.util.Vector	fetchEventsByRange(java.lang.String calId, java.util.Date dtstart, java.util.Date dtend, int maxResults) Retrieve all events from the specified calendar with activity within the time range.
java.util.Vector	fetchToDosByAlarmRange(java.lang.String calId, java.util.Date dtstart, java.util.Date dtend, int maxResults) Retrieve ToDos from the specified calendar that have alarm (reminder) within the time range.
java.util.Vector	fetchToDosByAttendeeError(java.lang.String calId, java.lang.String attendee, int maxResults) Retrieves all todos from the specified calId that has errors associated to the attendee.
java.util.Vector	fetchToDosById(java.lang.String calId, java.lang.String uid, java.lang.String rid, WcapModifier modifier) Fetch the todo and all its recurrences from the specified calendar.
java.util.Vector	fetchToDosByLastMod(java.lang.String calId, java.util.Date dtstart, java.util.Date dtend, int maxResults) Retrieves all todos from the specified calendar that has been modified within the time range.
java.util.Vector	fetchToDosByRange(java.lang.String calId, java.util.Date dtstart, java.util.Date dtend, int maxResults) Retrieve all todos from the specified calendar with activity within the time range.
java.util.Vector	getAllTimeZoneIds() Get a list of all TimeZone ids that are supported by the iPlanet Calendar Server.
CalendarProperty	getCalendarProperty(java.lang.String calId) Retrieves the property of the specified calendar.
java.lang.String	getDefaultCalendarId() Get the default calendar id associated to the user.
java.lang.String	getDescriptor() Used by NiM Nugget mechanism.
java.util.Vector	getFreeBusy(java.lang.String calId, java.util.Date dtstart, java.util.Date dtend) Get the free/busy slots within the specified time range.
java.util.Vector	getFreeBusyByEmail(java.lang.String email, java.util.Date dtstart, java.util.Date dtend) Get the free/busy slots within the specified time range by the user's email address.
UserPref	getUserPreference() Get the user's preference.
protected void	initImpl() This method is called by the init() method after the member variables _nuggetName, _entity and _settings are assigned.
boolean	login(boolean isRelogin, boolean needDelay) Login to calendar server.
void	logout() Logout from the calendar server.
java.util.Vector	searchForCalendars(java.lang.String searchString, boolean searchCalId, boolean searchName, boolean searchPrimaryOwner, SearchOption searchOption, int maxResults) Search for calendars that matches the criteria.
boolean	sessionIsAlive() Check whether the current session is still accepted by the Calendar Server.
void	setCalendarProperty(CalendarProperty calProp) Set the specified calendar property.
void	setUserPreference(UserPref userPref) Set the user's preference.
java.lang.String	storeEvent(java.lang.String calId, WcapModifier modifier, Event event) Add or modify an event.
java.lang.String	storeToDo(java.lang.String calId, WcapModifier modifier, ToDo todo) Add or modify an todo.
protected java.lang.String	urlEncode(java.lang.String inStr)

Methods inherited from class com.nitido.nim.CachableNugget

isCachable

Methods inherited from class com.nitido.nim.Nugget

destroy, destroyImpl, getEntity, getNuggetName, getSetting, getSettings, init, requestBegin, requestEnd

Methods inherited from class java.lang.Object

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

Field Detail

KEY_HOST

public static final java.lang.String KEY_HOST

See Also:

Constant Field Values

KEY_PORT

public static final java.lang.String KEY_PORT

See Also:

Constant Field Values

KEY_AUTOLOGIN

public static final java.lang.String KEY_AUTOLOGIN

See Also:

Constant Field Values

KEY_RELOGIN_DELAY

public static final java.lang.String KEY_RELOGIN_DELAY

See Also:

Constant Field Values

KEY_RELOGIN_LIMIT

public static final java.lang.String KEY_RELOGIN_LIMIT

See Also:

Constant Field Values

KEY_CRED_USERID

public static final java.lang.String KEY_CRED_USERID

See Also:

Constant Field Values

KEY_CRED_PASSWORD

public static final java.lang.String KEY_CRED_PASSWORD

See Also:

Constant Field Values

KEY_URL_CHARSET

public static final java.lang.String KEY_URL_CHARSET

See Also:

Constant Field Values

KEY_BUSY_ONLY

public static final java.lang.String KEY_BUSY_ONLY

See Also:

Constant Field Values

KEY_RELATIVE_ALARM

public static final java.lang.String KEY_RELATIVE_ALARM

See Also:

Constant Field Values

DEFAULT_TIMEZONE_ID

public static final java.lang.String DEFAULT_TIMEZONE_ID

See Also:

Constant Field Values

Constructor Detail

WcapNugget

public WcapNugget(NuggetVisa visa)

Default Nugget constructor.

Method Detail

activate

public void activate()
              throws ActivationException

Used by NiM Nugget mechanism. An application developer should never invoke this.

Overrides:

activate in class Nugget

Throws:

ActivationException - If unable to activate the Nugget

deactivate

public void deactivate()
                throws ActivationException

Used by NiM Nugget mechanism. An application developer should never invoke this.

Overrides:

deactivate in class Nugget

Throws:

ActivationException - If unable to deactivate the Nugget

getDescriptor

public java.lang.String getDescriptor()

Used by NiM Nugget mechanism. An application developer should never invoke this.

Specified by:

getDescriptor in class Nugget

Returns:

The string with the description of the Nugget.

initImpl

protected void initImpl()
                 throws InitializationFailedException,
                        InvalidSettingException

Description copied from class: Nugget

This method is called by the init() method after the member variables _nuggetName, _entity and _settings are assigned. This method allows nugget implementations to put in code for initializing itself.

Specified by:

initImpl in class Nugget

Throws:

InitializationFailedException - If unable to initialize the nugget with the given parameters.

InvalidSettingException - If any of the expected initialization settings are null.

sessionIsAlive

public boolean sessionIsAlive()
                       throws WcapServerException,
                              WcapException

Check whether the current session is still accepted by the Calendar Server. This session time out is determined by the Calendar Server and has nothing to do with the Nugget. Please read the iPlanet Calendar Server Administration Guide for details.

If you have enabled the auto-relogin option when instantiating this nugget, the nugget will automatically re-authenticate you.

Returns:

true if the current session is alive. false otherwise (i.e. require invoking login() again)

Throws:

WcapServerException

WcapException

getAllTimeZoneIds

public java.util.Vector getAllTimeZoneIds()
                                   throws WcapServerException,
                                          WcapException

Get a list of all TimeZone ids that are supported by the iPlanet Calendar Server. This method is usually invoked by the presentation layer for providing a list of ICS supported TimeZone id for the user to chose from.

Returns:

a Vector contains the string of the TimeZone ids.

Throws:

WcapServerException

WcapException

createCalendar

public CalendarProperty createCalendar(java.lang.String calId)
                                throws WcapServerException,
                                       WcapException

Create a calendar (with default properties).

Note: If you have created a calendar, the iPlanet Calendar Server will assign "userid:calid" as the actual id of the new calendar. You should never regard calId as the new id! To ensure you should get the correct calendar id from the CalendarProperty returned.

Parameters:

calId - the new calendar's id.

Throws:

WcapServerException

WcapException

createCalendarWithProperty

public CalendarProperty createCalendarWithProperty(CalendarProperty calProp)
                                            throws WcapServerException,
                                                   WcapException

Create a calendar with the specified properties.

Note: If you have created a calendar, the iPlanet Calendar Server will assign "userid:calid" as the actual id of the new calendar. You should never regard calId as the new id! To ensure you should get the correct calendar id from the CalendarProperty returned.

For example, assume your user id is "tester" and you have:

 CalendarProperty prop = new CalendarProperty( "my_cal", ... );
 myWcapNugget.createCalendarWithProperty( prop );
 

Then, the iPlanet Calendar Server will create a calendar with id "tester:my_cal". This correct calendar id will appear in the CalendarProperty object returned by this method.

Parameters:

calProp - a CalendarProperty object that has the property settings.

Returns:

a CalendarProperty object of the created calendar.

Throws:

WcapServerException

WcapException

deleteCalendar

public void deleteCalendar(java.lang.String calId)
                    throws WcapServerException,
                           WcapException

Delete the specific calendar.

Parameters:

calId - The full id of the calendar to be deleted. This parameter must be valid and non-null.

Throws:

WcapServerException

WcapException

getCalendarProperty

public CalendarProperty getCalendarProperty(java.lang.String calId)
                                     throws WcapServerException,
                                            WcapException

Retrieves the property of the specified calendar.

Parameters:

calId - the id of the calendar that you are interested. If it is null, it assume it's the default calendar.

Returns:

the CalendarProperty object that contains the property value of the calendar.

Throws:

WcapServerException

WcapException

searchForCalendars

public java.util.Vector searchForCalendars(java.lang.String searchString,
                                           boolean searchCalId,
                                           boolean searchName,
                                           boolean searchPrimaryOwner,
                                           SearchOption searchOption,
                                           int maxResults)
                                    throws InvalidParameterException,
                                           WcapServerException,
                                           WcapException

Search for calendars that matches the criteria. It allows the developer to specify a search string and perform the search on fields of calendar id, name, and primary owner. The result will be an enumeration of matched calendar's properties. However, the iPlanet Calendar Server doesn't check for access control at this stage. The result may contain calendars that you don't have access privilege to it at all.

Parameters:

searchString - the string to search for.

searchCalId - if true, will search on the calendar id against the searchString.

searchName - if true, will search on the calendar name against the searchString.

searchPrimaryOwner - if true, will search on the calendar's primary owner id against the searchString.

searchOption - the search option to be performed.

maxResults - the maximum number of result to be returned. If 0, no limit.

Returns:

an Vector of CalendarProperty objects for each calendar that matches the criteria.

Throws:

InvalidParameterException

WcapServerException

WcapException

setCalendarProperty

public void setCalendarProperty(CalendarProperty calProp)
                         throws WcapServerException,
                                WcapException

Set the specified calendar property.

Parameters:

calProp - The CalendarProperty that is going to be modified.

Throws:

WcapServerException

WcapException

login

public boolean login(boolean isRelogin,
                     boolean needDelay)
              throws WcapServerException,
                     WcapException

Login to calendar server. If you have turned off the auto-login option, you will need to invoke this method to login.

Throws:

WcapServerException

WcapException

logout

public void logout()
            throws WcapException

Logout from the calendar server. If you have turned off the auto-login option, you will need to invoke this method to logout.

Throws:

WcapException

getDefaultCalendarId

public java.lang.String getDefaultCalendarId()

Get the default calendar id associated to the user.

setUserPreference

public void setUserPreference(UserPref userPref)
                       throws WcapServerException,
                              WcapException

Set the user's preference. This method will modify the corresponding user preference on the iPlanet Calendar Server.

Parameters:

userPref - The user prefs.

Throws:

WcapServerException

WcapException

getUserPreference

public UserPref getUserPreference()
                           throws WcapServerException,
                                  WcapException

Get the user's preference.

Returns:

An user preference object.

Throws:

WcapServerException

WcapException

getFreeBusy

public java.util.Vector getFreeBusy(java.lang.String calId,
                                    java.util.Date dtstart,
                                    java.util.Date dtend)
                             throws InvalidParameterException,
                                    WcapServerException,
                                    WcapException

Get the free/busy slots within the specified time range.

Parameters:

calId - the calendar Id to retrieve the free/busy time. if null, assume the user's default calendar id

dtstart - the start date/time in GMT. They must be valid dates.

dtend - the end date/time in GMT.

Returns:

a Vector of FreeBusy objects that indicates which time slots the owner is free/busy.

Throws:

InvalidParameterException

WcapServerException

WcapException

getFreeBusyByEmail

public java.util.Vector getFreeBusyByEmail(java.lang.String email,
                                           java.util.Date dtstart,
                                           java.util.Date dtend)
                                    throws InvalidParameterException,
                                           WcapServerException,
                                           WcapException

Get the free/busy slots within the specified time range by the user's email address.

Parameters:

email - the email address of the user account to retrieve the free/busy time. if null, assume the user's default calendar id

dtstart - the start date/time in GMT. They must be valid dates.

dtend - the end date/time in GMT.

Returns:

a Vector of FreeBusy objects that indicates which time slots the owner is free/busy.

Throws:

InvalidParameterException

WcapServerException

WcapException

deleteEventsById

public void deleteEventsById(java.lang.String calId,
                             java.lang.String uid,
                             java.lang.String rid,
                             WcapModifier mod,
                             boolean notify)
                      throws InvalidParameterException,
                             WcapServerException,
                             WcapException

Remove the specified event and its recurrence as specified.

Parameters:

calId - The target calendar id. If it's null, it assumes it's the user's default calendar id.

uid - The uid of the event to be deleted

rid - The recurrence identifier of the event. If the event has no recurrence, the value is 0.

It is the rid you got from an Event object fetched from server. In other words, you should delete an event that you have fetched and know the exact rid. * This rid is usually the starting time of the event, formatted in the ISO 8601 DateTime Z string.

mod - A WcapModifier object indicating which recurrence to delete. See the JavaDoc for WcapModifier class for more details.

notify - If it is set to true, ICS will notify attendees of this deletion.

Throws:

InvalidParameterException

WcapServerException

WcapException

deleteEventsByRange

public void deleteEventsByRange(java.lang.String calId,
                                java.util.Date dtstart,
                                java.util.Date dtend)
                         throws InvalidParameterException,
                                WcapServerException,
                                WcapException

Delete all events within the specified time range. The behaviour of this method resembles the iPlanet WCAP command deleteevents_by_range. If you pass null for all the parameters, this method will remove every single events on the user's default calendar! (So use it with care.)

Parameters:

calId - The id of the target calendar. If null, it is assumed to be the user's default calendar's id.

dtstart - The start date/time in GMT. If null, it is assumed to be from the start of time.

dtend - The end date/time in GMT. If null, it is assumed to be till the end of time.

Throws:

InvalidParameterException

WcapServerException

WcapException

fetchEventsByAlarmRange

public java.util.Vector fetchEventsByAlarmRange(java.lang.String calId,
                                                java.util.Date dtstart,
                                                java.util.Date dtend,
                                                int maxResults)
                                         throws InvalidParameterException,
                                                WcapServerException,
                                                WcapException

Retrieve events from the specified calendar that have alarm (reminder) within the time range.

Parameters:

calId - The id of the target calendar. If null, it is assumed to be the user's default calendar's id.

dtstart - The start date/time in GMT. Due to the restriction of iPlanet Calendar WCAP command implementation, this parameter must be valid. (The iCS 5.1 implementation of fetchcomponents_by_alarmrange.wcap does not follow the specification described by the iCS Programmer's Reference.)

dtend - The end date/time in GMT. Due to the restriction of iPlanet Calendar WCAP command implementation, this parameter must be valid. (The iCS 5.1 implementation of fetchcomponents_by_alarmrange.wcap does not follow the specification described by the iCS Programmer's Reference.)

maxResults - Maximum of result to be fetched. A value of 0 means no limit. This methods will ignore all negative values.

Returns:

A Vector of Event objects that satisfy the criteria.

Throws:

InvalidParameterException

WcapServerException

WcapException

fetchEventsByAttendeeError

public java.util.Vector fetchEventsByAttendeeError(java.lang.String calId,
                                                   java.lang.String attendee,
                                                   int maxResults)
                                            throws InvalidParameterException,
                                                   WcapServerException,
                                                   WcapException

Retrieves all events from the specified calId that has errors associated to the attendee.

Parameters:

calId - The id of the target calendar. If null, it is assumed to be the user's default calendar's id.

attendee - The attendee's calid to be searched on.

maxResults - Maximum of result to be fetched. A value of 0 means no limit. This methods will ignore all negative values.

Returns:

A Vector of Event objects that satisfy the criteria.

Throws:

InvalidParameterException

WcapServerException

WcapException

fetchEventsByLastMod

public java.util.Vector fetchEventsByLastMod(java.lang.String calId,
                                             java.util.Date dtstart,
                                             java.util.Date dtend,
                                             int maxResults)
                                      throws InvalidParameterException,
                                             WcapServerException,
                                             WcapException

Retrieves all events from the specified calendar that has been modified within the time range.

Parameters:

calId - The id of the target calendar. If null, it is assumed to be the user's default calendar's id.

dtstart - The start date/time in GMT. If null, it is assumed to be from the start of time.

dtend - The end date/time in GMT. If null, it is assumed to be till the end of time.

maxResults - Maximum of result to be fetched. A value of 0 means no limit. This methods will ignore all negative values.

Returns:

A Vector of Event objects that satisfy the criteria.

Throws:

InvalidParameterException

WcapServerException

WcapException

fetchEventsByRange

public java.util.Vector fetchEventsByRange(java.lang.String calId,
                                           java.util.Date dtstart,
                                           java.util.Date dtend,
                                           int maxResults)
                                    throws InvalidParameterException,
                                           WcapServerException,
                                           WcapException

Retrieve all events from the specified calendar with activity within the time range.

Parameters:

calId - The id of the target calendar. If null, it is assumed to be the user's default calendar's id.

dtstart - The start date/time in GMT. If null, it is assumed to be from the start of time.

dtend - The end date/time in GMT. If null, it is assumed to be till the end of time.

maxResults - Maximum of result to be fetched. A value of 0 means no limit. This methods will ignore all negative values.

Returns:

A Vector of Event objects that satisfy the criteria.

Throws:

InvalidParameterException

WcapServerException

WcapException

fetchEventsById

public java.util.Vector fetchEventsById(java.lang.String calId,
                                        java.lang.String uid,
                                        java.lang.String rid,
                                        WcapModifier modifier)
                                 throws InvalidParameterException,
                                        WcapServerException,
                                        WcapException

Fetch the event and all its recurrences from the specified calendar.

Parameters:

calId - the calId to fetch the events from.

uid - the uid of the event you want to be fetched.

rid - a string for the associated rid. If the event has no recurrence, this entry is a string "0"

modifier - modifier that indicates which recurrences to retrieve.

Returns:

A Vector of Event objects that satisfy the criteria.

Throws:

InvalidParameterException

WcapServerException

WcapException

storeEvent

public java.lang.String storeEvent(java.lang.String calId,
                                   WcapModifier modifier,
                                   Event event)
                            throws InvalidParameterException,
                                   WcapServerException,
                                   WcapException

Add or modify an event.

If modifying an existing event, the Event object must have valid uid and rid. If you got the event object from the fetchEvents* methods, these two member variables should have been set already. For all other member variables, they can be null or some valid value. When this method encounters a null value, it will leave the original value unchanged.

If creating a new event, the caller must have created an Event object with all desired parameters. The uid and rid of the object must be null, while title and dtstart must have valid non-null values. If any of the other values are missing, the iPlanet Calendar Server will assign the default values it implies. You may read the ICS's programmer's guide for more details on the default values.

Parameters:

calId - the calendar id that the change is applying to.

modifier - modifier that indicates how the recurrence instance of the events will be affected by the change.

event - the Event object to be stored. If the Event object does not contains the uid, this method assumes you are creating a new event.

Returns:

If the nugget is executing against SunONE Calendar 6, this method will return the UID of the newly created/modified Event. Otherwise, it will return null.

Throws:

InvalidParameterException

WcapServerException

WcapException

deleteToDosById

public void deleteToDosById(java.lang.String calId,
                            java.lang.String uid,
                            java.lang.String rid,
                            WcapModifier mod,
                            boolean notify)
                     throws InvalidParameterException,
                            WcapServerException,
                            WcapException

Remove the specified todo and its recurrence as specified.

Parameters:

calId - The target calendar id. If it's null, it assumes it's the user's default calendar id.

uid - The uid of the todo to be deleted

rid - The recurrence identifier of the todo. If the todo has no recurrence, the value is 0.

It is the rid you got from an ToDo object fetched from server. In other words, you should delete a todo that you have fetched and know the exact rid. * This rid is usually the starting time of the todo, formatted in the ISO 8601 DateTime Z string.

mod - A WcapModifier object indicating which recurrence to delete. See the JavaDoc for WcapModifier class for more details.

notify - If it is set to true, ICS will notify attendees of this deletion.

Throws:

InvalidParameterException

WcapServerException

WcapException

deleteToDosByRange

public void deleteToDosByRange(java.lang.String calId,
                               java.util.Date dtstart,
                               java.util.Date dtend)
                        throws InvalidParameterException,
                               WcapServerException,
                               WcapException

Delete ToDos within the range. This method invokes the deletetodos_by_range WCAP command on iPlanet Calendar Server. The server will delete all "COMPLETED" ToDos within the specified time range. If a ToDo has not been "completed", it will remain on the system.

WARNING: Due to a bug in iPlanet Calendar Server, if you specified only one of the start and end time limit, the server will delete ALL ToDos in the system. It will remove all ToDos no matter whether they are within the range or not, and no whether they are "completed" or not. As a result, you should use this method with extreme care. If you really need to remove a bunch of non-completed ToDos within a range or a number of ToDos after OR before certain time, you should fetch the uids of those ToDos and remove them with deleteToDosById method.

Parameters:

calId - the id of the target calendar.

dtstart - the start date/time.

dtend - the end date/time.

Throws:

InvalidParameterException

WcapServerException

WcapException

fetchToDosByAlarmRange

public java.util.Vector fetchToDosByAlarmRange(java.lang.String calId,
                                               java.util.Date dtstart,
                                               java.util.Date dtend,
                                               int maxResults)
                                        throws InvalidParameterException,
                                               WcapServerException,
                                               WcapException

Retrieve ToDos from the specified calendar that have alarm (reminder) within the time range.

Parameters:

calId - The id of the target calendar. If null, it is assumed to be the user's default calendar's id.

dtstart - The start date/time in GMT. Due to the restriction of iPlanet Calendar WCAP command implementation, this parameter must be valid. (The iCS 5.1 implementation of fetchcomponents_by_alarmrange.wcap does not follow the specification described by the iCS Programmer's Reference.)

dtend - The end date/time in GMT. Due to the restriction of iPlanet Calendar WCAP command implementation, this parameter must be valid. (The iCS 5.1 implementation of fetchcomponents_by_alarmrange.wcap does not follow the specification described by the iCS Programmer's Reference.)

maxResults - Maximum of result to be fetched. A value of 0 means no limit. This methods will ignore all negative values.

Returns:

A Vector of ToDo objects that satisfy the criteria.

Throws:

InvalidParameterException

WcapServerException

WcapException

fetchToDosByAttendeeError

public java.util.Vector fetchToDosByAttendeeError(java.lang.String calId,
                                                  java.lang.String attendee,
                                                  int maxResults)
                                           throws InvalidParameterException,
                                                  WcapServerException,
                                                  WcapException

Retrieves all todos from the specified calId that has errors associated to the attendee.

Parameters:

calId - The id of the target calendar. If null, it is assumed to be the user's default calendar's id.

attendee - The attendee's calid to be searched on.

maxResults - Maximum of result to be fetched. A value of 0 means no limit. This methods will ignore all negative values.

Returns:

A Vector of ToDo objects that satisfy the criteria.

Throws:

InvalidParameterException

WcapServerException

WcapException

fetchToDosByLastMod

public java.util.Vector fetchToDosByLastMod(java.lang.String calId,
                                            java.util.Date dtstart,
                                            java.util.Date dtend,
                                            int maxResults)
                                     throws InvalidParameterException,
                                            WcapServerException,
                                            WcapException

Retrieves all todos from the specified calendar that has been modified within the time range.

Parameters:

calId - The id of the target calendar. If null, it is assumed to be the user's default calendar's id.

dtstart - The start date/time in GMT. If null, it is assumed to be from the start of time.

dtend - The end date/time in GMT. If null, it is assumed to be till the end of time.

maxResults - Maximum of result to be fetched. A value of 0 means no limit. This methods will ignore all negative values.

Returns:

A Vector of ToDo objects that satisfy the criteria.

Throws:

InvalidParameterException

WcapServerException

WcapException

fetchToDosByRange

public java.util.Vector fetchToDosByRange(java.lang.String calId,
                                          java.util.Date dtstart,
                                          java.util.Date dtend,
                                          int maxResults)
                                   throws InvalidParameterException,
                                          WcapServerException,
                                          WcapException

Retrieve all todos from the specified calendar with activity within the time range.

Parameters:

calId - The id of the target calendar. If null, it is assumed to be the user's default calendar's id.

dtstart - The start date/time in GMT. If null, it is assumed to be from the start of time.

dtend - The end date/time in GMT. If null, it is assumed to be till the end of time.

maxResults - Maximum of result to be fetched. A value of 0 means no limit. This methods will ignore all negative values.

Returns:

A Vector of ToDo objects that satisfy the criteria.

Throws:

InvalidParameterException

WcapServerException

WcapException

fetchToDosById

public java.util.Vector fetchToDosById(java.lang.String calId,
                                       java.lang.String uid,
                                       java.lang.String rid,
                                       WcapModifier modifier)
                                throws InvalidParameterException,
                                       WcapServerException,
                                       WcapException

Fetch the todo and all its recurrences from the specified calendar.

Parameters:

calId - the calid to fetch the todos from.

uid - the uid of the todo you want to be fetched.

rid - a string for the associated rid. If the todo has no recurrence, this entry is a string "0"

modifier - modifier that indicates which recurrences to retrieve.

Returns:

A Vector of ToDo objects that satisfy the criteria.

Throws:

InvalidParameterException

WcapServerException

WcapException

storeToDo

public java.lang.String storeToDo(java.lang.String calId,
                                  WcapModifier modifier,
                                  ToDo todo)
                           throws InvalidParameterException,
                                  WcapServerException,
                                  WcapException

Add or modify an todo.

If modifying an existing todo, the ToDo object must have valid uid and rid. If you got the ToDo object from the fetchToDos* methods, these two member variables should have been set already. For all other member variables, they can be null or some valid value. When this method encounters a null value, it will leave the original value unchanged.

If creating a new todo, the caller must have created an ToDo object with all desired parameters. The uid and rid of the object must be null, while title and dtstart must have valid non-null values. If any of the other values are missing, the iPlanet Calendar Server will assign the default values it implies. You may read the ICS's programmer's guide for more details on the default values.

Parameters:

calId - the calendar id that the change is applying to.

modifier - modifier that indicates how the recurrence instance of the todos will be affected by the change.

todo - the ToDo object to be stored. If the ToDo object does not contains the uid, this method assumes you are creating a new todo.

Returns:

If the nugget is executing against SunONE Calendar 6, this method will return the UID of the newly created/modified Event. Otherwise, it will return null.

Throws:

InvalidParameterException

WcapServerException

WcapException

urlEncode

protected java.lang.String urlEncode(java.lang.String inStr)
                              throws WcapException

Throws:

WcapException