com.tibco.n2.service.adapter.binding

Interface WorkCalService

All Known Implementing Classes:

WorkCalService

public interface WorkCalService

Interface to provide the CalendarService methods.

This service provides interfaces to allow a calendar to be configured with respect to working time.

An example of the sequence of events would be:

• Call listCalendars, to get a list of available calendars.
• Call getCalendar, to retrieve the details for a named Calendar.
• Call getCalendarEntries, to retrieve the details of calendar entries for a named Calendar.
• Call saveCalendar, to save (or create) the main details of a Calendar.
• Call saveCalendarEntry, to add a new, or update an existing, calendar entry.
• Call deleteCalendarEntry, to remove an existing calendar entry.

COPYRIGHT: (C) 2007-2012 Cloud Software Group, Inc. All Rights Reserved.

Method Summary

Methods

Modifier and Type	Method and Description
com.tibco.n2.dac.api.basic.XmlUpdatedCalendar	copyCalendar(java.lang.String aNamespace, java.lang.String aName, java.lang.String aDestNamespace, java.lang.String aDestName, boolean aIncludeEntries) This service copies an identified Calendar to create a new Calendar of the same type.
void	deleteCalendar(int aVersion, java.lang.String aNamespace, java.lang.String aName) Deletes the named Calendar, and all the Working Day and Calendar Entries associated with it.
void	deleteCalendarEntries(int aVersion, java.lang.String aNamespace, java.lang.String aName, java.lang.String[] aEntryGuids) Deletes the Calendar Entries identified by their GUID (e.g.
com.tibco.n2.dac.api.workcal.XmlCalendarResponse	getCalendar(java.lang.String aNamespace, java.lang.String aName) Returns the details of a named Calendar.
com.tibco.n2.dac.api.workcal.XmlCalendarEntries	getCalEntries(java.lang.String aNamespace, java.lang.String aName, java.util.Calendar aStart, java.util.Calendar aEnd) Returns the collection of CalendarEntries, from the named Calendar, that fall within the given date range.
com.tibco.n2.dac.api.basic.XmlCalendarSummary[]	listCalendars(java.lang.String aNamespace) Returns the list of known WorkCalendar instances (that is; Base and Overlay Calendars).
java.lang.String[]	listTimeZones(int empty) Returns the list of time-zone identifiers recognised by the Calendar Component.
com.tibco.n2.dac.api.workcal.XmlTimeZone[]	listTimeZones(com.tibco.n2.dac.api.basic.XmlLocale aLocale, int aDetail) Returns the list of time-zone identifiers recognised by the Calendar Component.
void	purgeCalendarEntries(int aVersion, java.lang.String aNamespace, java.lang.String aName, java.util.Calendar aToDate) Deletes the Calendar Entries, of the named Calendar, whose end date is earlier than the given date.
void	renameCalendar(int aVersion, java.lang.String aOldNamespace, java.lang.String aOldName, java.lang.String aNewNamespace, java.lang.String aNewName) Changes the name, and/or namespace, of a Calendar.
com.tibco.n2.dac.api.basic.XmlCalendarReference[]	resolveReferences(java.lang.String[] aReferences) Resolves a given collection of Calendar References, by returning the identifier of the Calendar instance to which each are associated.
com.tibco.n2.dac.api.workcal.XmlCalendarResponse	saveCalendar(com.tibco.n2.dac.api.basic.XmlBaseCalendar aBaseCalendar) Updates, or creates, a named Base Calendar.
com.tibco.n2.dac.api.workcal.XmlCalendarResponse	saveCalendar(com.tibco.n2.dac.api.basic.XmlOverlayCalendar aOverlayCalendar) Updates, or creates, a named Overlay Calendar.
com.tibco.n2.dac.api.workcal.XmlCalendarEntries	saveCalendarEntry(int aVersion, java.lang.String aNamespace, java.lang.String aName, java.util.Calendar aStart, java.util.Calendar aEnd, com.tibco.n2.dac.api.basic.XmlNewWorkingDayExclusion[] aNewWorkingDayExclusion, com.tibco.n2.dac.api.basic.XmlExistingWorkingDayExclusion[] aExistingWorkindDayExclusion, com.tibco.n2.dac.api.basic.XmlNewRecurringExclusion[] aNewRecurringExclusion, com.tibco.n2.dac.api.basic.XmlExistingRecurringExclusion[] aExistingRecurringExclusion) Creates or updates a list of Recurring or Non-Recurring Working Day Exclusions.
com.tibco.n2.dac.api.workcal.SaveCalendarReferencesResponseDocument.SaveCalendarReferencesResponse	saveCalendarReferences(int aVersion, java.lang.String aNamespace, java.lang.String aName, java.lang.String[] aAddReferences) Associates a Calendar with a client component's reference identifier.
com.tibco.n2.dac.api.workcal.SaveCalendarReferencesResponseDocument.SaveCalendarReferencesResponse	saveCalendarReferences(int aVersion, java.lang.String aNamespace, java.lang.String aName, java.lang.String[] aAddReferences, java.lang.String[] aRemoveReferences) Associates a Calendar with a client component's reference identifier.

Method Detail

listTimeZones

java.lang.String[] listTimeZones(int empty)
                                 throws com.tibco.n2.dac.services.CalendarFault,
                                        com.tibco.n2.dac.services.SecurityFault

Returns the list of time-zone identifiers recognised by the Calendar Component. The entries in the returned list are possible values for the time-zone property of a Base Calendar.

Returns:

a list of the known time-zone identifiers.

Throws:

com.tibco.n2.dac.services.CalendarFault - if an error occurs whilst accessing the Time-Zones.

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

listTimeZones

com.tibco.n2.dac.api.workcal.XmlTimeZone[] listTimeZones(com.tibco.n2.dac.api.basic.XmlLocale aLocale,
                                                       int aDetail)
                                                         throws com.tibco.n2.dac.services.CalendarFault,
                                                                com.tibco.n2.dac.services.SecurityFault

Returns the list of time-zone identifiers recognised by the Calendar Component. The entries in the returned list are possible values for the time-zone property of a Base Calendar.

Specifies the level of detail required about each time-zone in the result. To maintain backward compatibility, the default is to return the same, original response. The levels currently suppoted are 0 and 1. The following lists when each:

• time-zone id - (0 and 1) - a unique identifier of this time-zone.
• display-name - (1) - the name of this time-zone suitable for presentation to the user in the server's default locale.
• use-daylight-time - (1) - true if this time-zone uses daylight savings time.
• raw-offset - (1) - the amount of time in milliseconds to add to UTC to get standard time in this time-zone.

The locale identifies a specific geographical, political, or cultural region for which the time-zone descriptions are to be listed (i.e. the language). If available, the description for each time-zone in the result will be given in the language appropriate to the locale identified by this element. If not available (or no locale is specified), the server's default locale will be used.

Parameters:

aLocale - identifies the language in which the display-names are to be listed. If null, the default locale will be used.

aDetail - the level of detail to be returned.

Returns:

a list of the known time-zone identifiers.

Throws:

com.tibco.n2.dac.services.CalendarFault - if an error occurs whilst accessing the Time-Zones.

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

listCalendars

com.tibco.n2.dac.api.basic.XmlCalendarSummary[] listCalendars(java.lang.String aNamespace)
                                                              throws com.tibco.n2.dac.services.CalendarFault,
                                                                     com.tibco.n2.dac.services.SecurityFault

Returns the list of known WorkCalendar instances (that is; Base and Overlay Calendars). If there are no WorkCalendar instances, the result will be an empty list.

An optional namespace value can be specified to return only those calendars with the given namespace. The namespace comparison will be case-sensitive. If the given namespace ends in an asterisk, then all calendars whose namespace starts with the given value will be returned. If no namespace is specified, all calendars will be listed.

Parameters:

aNamespace - the optional namespace from which to list calendars.

Returns:

the summary list of all calendars.

Throws:

com.tibco.n2.dac.services.CalendarFault

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

getCalendar

com.tibco.n2.dac.api.workcal.XmlCalendarResponse getCalendar(java.lang.String aNamespace,
                                                           java.lang.String aName)
                                                             throws com.tibco.n2.dac.services.CalendarFault,
                                                                    com.tibco.n2.dac.services.SecurityFault

Returns the details of a named Calendar. For a Base Calendar, the time-zone and Working Day entries will be included. Also includes the Calendar Entries (e.g. Working Day Exclusions and Recurring Exclusions) for a date range given in the request. If no date range is given, no Calendar Entries are returned. If an open-ended date-range is given, the response will include all Calendar Entries for the given start date/time onwards. The given date range will be given as time-zone neutral values.

The date and time values of the Calendar Entries are specified as time-zone neutral, and should be displayed as is, without time-zone adjustment. However, for Base Calendars, the time-zone identifier will be included in the response, and this should be displayed for the user to edit.

Recurring Exclusions will be listed only once, and will include the Recurrence Rule expression used to calculate the repeating occurrences.

Parameters:

aNamespace - the namespace of the calendar to be retrieved.

aName - the name of the calendar to be retrieved.

aStartDateTime - optional start filter on the calendar entries to be included.

aEndDateTime - optional end filter on the calendar entries to be included.

Returns:

the details for the named Calendar.

Throws:

com.tibco.n2.dac.services.CalendarFault - if the named Calendar does not exist, or an error occurred whilst reading the Calendar.

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

saveCalendar

com.tibco.n2.dac.api.workcal.XmlCalendarResponse saveCalendar(com.tibco.n2.dac.api.basic.XmlBaseCalendar aBaseCalendar)
                                                              throws com.tibco.n2.dac.services.CalendarFault,
                                                                     com.tibco.n2.dac.services.SecurityFault

Updates, or creates, a named Base Calendar. Calendar Entries will not be included in the request. The time-zone and Working Day entries should be included. Calendar Entries will be saved using the Save Calendar Entry. Date and time values in the request are expected to be time-zone neutral.

The request must include a version number that will be compared against the value held by the identified Calendar entry. If the values don't match, the request will fail with a "concurrency exception".

Parameters:

aBaseCalendar - the calendar details to be saved.

Throws:

com.tibco.n2.dac.services.CalendarFault - if the Calendar could not be saved.

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

saveCalendar

com.tibco.n2.dac.api.workcal.XmlCalendarResponse saveCalendar(com.tibco.n2.dac.api.basic.XmlOverlayCalendar aOverlayCalendar)
                                                              throws com.tibco.n2.dac.services.CalendarFault,
                                                                     com.tibco.n2.dac.services.SecurityFault

Updates, or creates, a named Overlay Calendar. Calendar Entries will not be included in the request. Calendar Entries will be saved using the Save Calendar Entry. Date and time values in the request are expected to be time-zone neutral.

The request must include a version number that will be compared against the value held by the identified Calendar entry. If the values don't match, the request will fail with a "concurrency exception".

Parameters:

aOverlayCalendar - the calendar details to be saved.

Throws:

com.tibco.n2.dac.services.CalendarFault - if the Calendar could not be saved.

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

copyCalendar

com.tibco.n2.dac.api.basic.XmlUpdatedCalendar copyCalendar(java.lang.String aNamespace,
                                                         java.lang.String aName,
                                                         java.lang.String aDestNamespace,
                                                         java.lang.String aDestName,
                                                         boolean aIncludeEntries)
                                                           throws com.tibco.n2.dac.services.CalendarFault,
                                                                  com.tibco.n2.dac.services.SecurityFault

This service copies an identified Calendar to create a new Calendar of the same type. For Base Calendars, the properties to be copied from the original Calendar will include the time-zone and working hours. For Base and Overlay Calendars, all future Calendar Entries can also be copied, if requested.

Parameters:

aNamespace - the namespace of the Calendar to be copied.

aName - the name of the Calendar to be copied.

aDestNamespace - the namespace of the Calendar to be created.

aDestName - the name of the Calendar to be created.

aIncludeEntries - true if future Calendar Entries are also to be included.

Returns:

the confirmation of the newly created Calendar (includes version).

Throws:

com.tibco.n2.dac.services.CalendarFault - if the Calendar could not be copied.

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

renameCalendar

void renameCalendar(int aVersion,
                  java.lang.String aOldNamespace,
                  java.lang.String aOldName,
                  java.lang.String aNewNamespace,
                  java.lang.String aNewName)
                    throws com.tibco.n2.dac.services.CalendarFault,
                           com.tibco.n2.dac.services.SecurityFault

Changes the name, and/or namespace, of a Calendar. The change will not succeed if no Calendar already exists with the new name and namespace combination.

The request must include a version number that will be compared against the value held by the identified Calendar entry. If the values don't match, the request will fail with a "concurrency exception".

Parameters:

aVersion - the version of the referenced Calendar. This is used to detect concurrent updates.

aOldNamespace - the namespace identifying the calendar to be renamed.

aOldName - the name identifying the calendar to be renamed.

aNewNamespace - the new namespace value.

aNewName - the new name value.

Throws:

com.tibco.n2.dac.services.CalendarFault - if the Calendar could not be renamed.

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

deleteCalendar

void deleteCalendar(int aVersion,
                  java.lang.String aNamespace,
                  java.lang.String aName)
                    throws com.tibco.n2.dac.services.CalendarFault,
                           com.tibco.n2.dac.services.SecurityFault

Deletes the named Calendar, and all the Working Day and Calendar Entries associated with it. The deleted Calendar cannot be recovered.

The request must include a version number that will be compared against the value held by the identified Calendar entry. If the values don't match, the request will fail with a "concurrency exception".

Parameters:

aVersion - the version of the referenced Calendar. This is used to detect concurrent updates.

aNamespace - the namespace of the calendar to be deleted.

aName - the name of the calendar to be deleted.

Throws:

com.tibco.n2.dac.services.CalendarFault - if the Calendar could not be deleted.

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

getCalEntries

com.tibco.n2.dac.api.workcal.XmlCalendarEntries getCalEntries(java.lang.String aNamespace,
                                                            java.lang.String aName,
                                                            java.util.Calendar aStart,
                                                            java.util.Calendar aEnd)
                                                              throws com.tibco.n2.dac.services.CalendarFault,
                                                                     com.tibco.n2.dac.services.SecurityFault

Returns the collection of CalendarEntries, from the named Calendar, that fall within the given date range. For recurring entries, the entry will include those occurrences that fall within the given date range.

Parameters:

aNamespace - the namespace of the Calendar to which the Entry belongs.

aName - the name of the Calendar to which the Entry belongs.

aStart - the start date of the period for which entries are to be returned.

aEnd - the end date of the period for which entries are to be returned.

Returns:

the collection of Calendar Entries - also include the Calendar's version number.

Throws:

com.tibco.n2.dac.services.CalendarFault

com.tibco.n2.dac.services.SecurityFault

saveCalendarEntry

com.tibco.n2.dac.api.workcal.XmlCalendarEntries saveCalendarEntry(int aVersion,
                                                                java.lang.String aNamespace,
                                                                java.lang.String aName,
                                                                java.util.Calendar aStart,
                                                                java.util.Calendar aEnd,
                                                                com.tibco.n2.dac.api.basic.XmlNewWorkingDayExclusion[] aNewWorkingDayExclusion,
                                                                com.tibco.n2.dac.api.basic.XmlExistingWorkingDayExclusion[] aExistingWorkindDayExclusion,
                                                                com.tibco.n2.dac.api.basic.XmlNewRecurringExclusion[] aNewRecurringExclusion,
                                                                com.tibco.n2.dac.api.basic.XmlExistingRecurringExclusion[] aExistingRecurringExclusion)
                                                                  throws com.tibco.n2.dac.services.CalendarFault,
                                                                         com.tibco.n2.dac.services.SecurityFault

Creates or updates a list of Recurring or Non-Recurring Working Day Exclusions. Date and time values in the request are expected to be time-zone neutral. Updates are identified by GUID.

A Recurring Exclusion is passed using the Recurrence Rule expression, and not as individual dates and times.

The request must include a version number that will be compared against the value held by the identified Calendar entry. If the values don't match, the request will fail with a "concurrency exception".

Parameters:

aVersion - the version of the referenced Calendar. This is used to detect concurrent updates.

aNamespace - the namespace of the Calendar to which the Entry belongs.

aName - the name of the Calendar to which the Entry belongs.

aStart - the start date of the period for which entries are to be returned.

aEnd - the end date of the period for which entries are to be returned.

aNewWorkingDayExclusion - the Working Day Exclusion(s) to be created.

aExistingWorkindDayExclusion - the Working Day Exclusion to be updated.

aNewRecurringExclusion - the Recurring Exclusion(s) to be created.

aExistingRecurringExclusion - the Recurring Exclusion(s) to be updated.

Returns:

the newly created or updated Working Day Exclusion. Includes the generated GUID for new entris and the updated versions of the Calendar.

Throws:

com.tibco.n2.dac.services.CalendarFault - if the Calendar could not be deleted.

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

deleteCalendarEntries

void deleteCalendarEntries(int aVersion,
                         java.lang.String aNamespace,
                         java.lang.String aName,
                         java.lang.String[] aEntryGuids)
                           throws com.tibco.n2.dac.services.CalendarFault,
                                  com.tibco.n2.dac.services.SecurityFault

Deletes the Calendar Entries identified by their GUID (e.g. Working Day Exclusions and Recurring Exclusions). The deleted entries cannot be recovered.

If any of the entries fails to be deleted, non of the listed entries will be deleted.

The request must include a version number that will be compared against the value held by the identified Calendar entry. If the values don't match, the request will fail with a "concurrency exception".

Parameters:

aVersion - the version of the referenced Calendar. This is used to detect concurrent updates.

aNamespace - the namespace of the Calendar from which the entries are to be deleted.

aName - the name of the Calendar from which the entries are to be deleted.

aEntryGuids - an array of GUIDs identifying the Calendar Entries to be deleted.

Throws:

com.tibco.n2.dac.services.CalendarFault - if any of the Calendar Entries could not be deleted.

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

purgeCalendarEntries

void purgeCalendarEntries(int aVersion,
                        java.lang.String aNamespace,
                        java.lang.String aName,
                        java.util.Calendar aToDate)
                          throws com.tibco.n2.dac.services.CalendarFault,
                                 com.tibco.n2.dac.services.SecurityFault

Deletes the Calendar Entries, of the named Calendar, whose end date is earlier than the given date. The deleted entries cannot be recovered.

If any of the entries fails to be deleted, no entries will be deleted.

The request must include a version number that will be compared against the value held by the identified Calendar entry. If the values don't match, the request will fail with a "concurrency exception".

Parameters:

aVersion - the version of the referenced Calendar. This is used to detect concurrent updates.

aNamespace - the namespace of the Calendar from which the entries are to be deleted.

aName - the name of the Calendar from which the entries are to be deleted.

aToDate - the date up-to which the Calendar Entries are to be deleted.

Throws:

com.tibco.n2.dac.services.CalendarFault - if any of the Calendar Entries could not be deleted.

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

saveCalendarReferences

com.tibco.n2.dac.api.workcal.SaveCalendarReferencesResponseDocument.SaveCalendarReferencesResponse saveCalendarReferences(int aVersion,
                                                                                                                        java.lang.String aNamespace,
                                                                                                                        java.lang.String aName,
                                                                                                                        java.lang.String[] aAddReferences)
                                                                                                                          throws com.tibco.n2.dac.services.CalendarFault,
                                                                                                                                 com.tibco.n2.dac.services.SecurityFault

Associates a Calendar with a client component's reference identifier. A reference can refer to only one Calendar, but a Calendar can be referenced by any number of client references.

The request must include a version number that will be compared against the value held by the identified Calendar entry. If the values don't match, the request will fail with a "concurrency exception".

Parameters:

aVersion - the version of the referenced Calendar. This is used to detect concurrent updates.

aNamespace - the namespace of the Calendar whose references are to be saved.

aName - the name of the Calendar whose references are to be saved.

aReferences - the collection of reference identifiers to be associated with the Calendar.

Throws:

com.tibco.n2.dac.services.CalendarFault - if any of the Calendar references could not be listed.

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

saveCalendarReferences

com.tibco.n2.dac.api.workcal.SaveCalendarReferencesResponseDocument.SaveCalendarReferencesResponse saveCalendarReferences(int aVersion,
                                                                                                                        java.lang.String aNamespace,
                                                                                                                        java.lang.String aName,
                                                                                                                        java.lang.String[] aAddReferences,
                                                                                                                        java.lang.String[] aRemoveReferences)
                                                                                                                          throws com.tibco.n2.dac.services.CalendarFault,
                                                                                                                                 com.tibco.n2.dac.services.SecurityFault

Associates a Calendar with a client component's reference identifier. A reference can refer to only one Calendar, but a Calendar can be referenced by any number of client references.

The request must include a version number that will be compared against the value held by the identified Calendar. If the values don't match, the request will fail with a "concurrency exception".

Parameters:

aVersion - the version of the Calendar to be updated.

aNamespace - the namespace in which the Calendar resides.

aName - the name of the Calendar to be updated.

aAddReferences - the references to be added to the identified Calendar.

aRemoveReferences - the references to be removed from the identified Calendar.

Returns:

the updated version number of the Calendar identified in the request.

Throws:

com.tibco.n2.dac.services.CalendarFault

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.

resolveReferences

com.tibco.n2.dac.api.basic.XmlCalendarReference[] resolveReferences(java.lang.String[] aReferences)
                                                                    throws com.tibco.n2.dac.services.CalendarFault,
                                                                           com.tibco.n2.dac.services.SecurityFault

Resolves a given collection of Calendar References, by returning the identifier of the Calendar instance to which each are associated.

A Calendar Reference is an external reference to a Calendar instance held within the Calendar Component. References simply consist of a unique identifier (a GUID), that can be associated with any one of the Calendars held within the Calendar Component. The same Calendar instance can be associated with any number of Calendar References.

The response will consist of the same Calendar References as the request, but with the identifier of the Calendar instance they are associated with.

If a given Reference is not associated with a Calendar instance, it will still be included but no Calendar will be identified for that reference.

Parameters:

aReferences - an array of the Calendar Reference GUIDs to be resolved.

Returns:

the array of resolved, and un-resolved, Calendar References.

Throws:

com.tibco.n2.dac.services.CalendarFault - if an error occurred whilst accessing the Calendars.

com.tibco.n2.dac.services.SecurityFault - if the caller is not authorised to perform this action.