org.osid.calendaring

Interface RecurringEventAdminSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

All Known Subinterfaces:

RecurringEventBatchAdminSession

public interface RecurringEventAdminSession
extends OsidSession

This session creates, updates, and deletes RecurringEvents. The data for create and update is provided by the consumer via the form object. OsidForms are requested for each create or update and may not be reused.

Create and update operations differ in their usage. To create a RecurringEvent, a RecurringEventForm is requested using getRecurringEventFormForCreate() specifying the desired relationship peers and record Types or none if no record Types are needed. The returned RecurringEventForm will indicate that it is to be used with a create operation and can be used to examine metdata or validate data prior to creation. Once the RecurringEventForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each RecurringEventForm corresponds to an attempted transaction.

For updates, RecurringEventForms are requested to the RecurringEvent Id that is to be updated using getRecurringEventFormForUpdate(). Similarly, the RecurringEventForm has metadata about the data that can be updated and it can perform validation before submitting the update. The RecurringEventForm can only be used once for a successful update and cannot be reused.

The delete operations delete Recurring Events. To unmap a RecurringEvent from the current Calendar, the RecurringEventCalendarAssignmentSession should be used. These delete operations attempt to remove the Event itself thus removing it from all known Calendar catalogs.

This session includes an Id aliasing mechanism to assign an external Id to an internally assigned Id.

Method Summary

Methods

Modifier and Type	Method and Description
void	addBlackout(Id recurringEventId, DateTime from, DateTime to) Adds a blackout to the given recurring event that blocks events in the series.
void	addEvent(Id recurringEventId, Id eventId) Adds another event as part of this recurring event.
Id	addSchedule(Id recurringEventId, Id scheduleId) Adds a schedule to the given recurring event.
void	addSpecificDate(Id recurringEventId, DateTime date, DisplayText locationDescription) Adds a specific date to the given recurring event.
void	addSpecificDateWithLocation(Id recurringEventId, DateTime date, Id locationId) Adds a specific date to the given recurring event.
void	aliasRecurringEvent(Id recurringEventId, Id aliasId) Adds an Id to a RecurringEvent for the purpose of creating compatibility.
boolean	canCreateRecurringEvents() Tests if this user can create RecurringEvents.
boolean	canCreateRecurringEventWithRecordTypes(Type[] recurringEventRecordTypes) Tests if this user can create a single RecurringEvent using the desired record types.
boolean	canDeleteRecurringEvents() Tests if this user can delete RecurringEvents.
boolean	canManageRecurringEventAliases() Tests if this user can manage Id aliases for RecurringEvents.
boolean	canScheduleRecurringEvents() Tests if this user can schedule recurring events.
boolean	canUpdateRecurringEvents() Tests if this user can update RecurringEvents.
void	clearBlackout(Id recurringEventId, DateTime from, DateTime to) Clears any blackouts between the given dates inclusive.
void	clearSpecificDates(Id recurringEventId, DateTime from, DateTime to) Clears any specific dates between the given dates inclusive.
RecurringEvent	createRecurringEvent(RecurringEventForm recurringEventForm) Creates a new RecurringEvent.
void	deleteRecurringEvent(Id recurringEventId) Deletes the RecurringEvent identified by the given Id.
Calendar	getCalendar() Gets the Calendar associated with this session.
Id	getCalendarId() Gets the Calendar Id associated with this session.
RecurringEventForm	getRecurringEventFormForCreate(Type[] recurringEventRecordTypes) Gets the recurring event form for creating new recurring events.
RecurringEventForm	getRecurringEventFormForUpdate(Id recurringEventId) Gets the recurring event form for updating an existing recurring event.
void	removeEvent(Id recurringEventId, Id eventId) Removes an event as part of this recurring event.
void	removeSchedule(Id recurringEventId, Id scheduleId) Removes a schedule from a given recurring event.
void	updateRecurringEvent(RecurringEventForm recurringEventForm) Updates an existing recurring event.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

getCalendarId

Id getCalendarId()

Gets the Calendar Id associated with this session.

Returns:

the Calendar Id associated with this session

Compliance:

mandatory - This method must be implemented.

getCalendar

Calendar getCalendar()
                     throws OperationFailedException,
                            PermissionDeniedException

Gets the Calendar associated with this session.

Returns:

the Calendar associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateRecurringEvents

boolean canCreateRecurringEvents()

Tests if this user can create RecurringEvents. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a RecurringEvent will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer create operations to an unauthorized user.

Returns:

false if RecurringEvent creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateRecurringEventWithRecordTypes

boolean canCreateRecurringEventWithRecordTypes(Type[] recurringEventRecordTypes)

Tests if this user can create a single RecurringEvent using the desired record types. While CalendaringManager.getRecurringEventRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific RecurringEvent. Providing an empty array tests if a RecurringEvent can be created with no records.

Parameters:

recurringEventRecordTypes - array of recurring event types

Returns:

true if RecurringEvent creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - recurringEventRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getRecurringEventFormForCreate

RecurringEventForm getRecurringEventFormForCreate(Type[] recurringEventRecordTypes)
                                                  throws OperationFailedException,
                                                         PermissionDeniedException

Gets the recurring event form for creating new recurring events. A new form should be requested for each create transaction.

Parameters:

recurringEventRecordTypes - array of recurring event types

Returns:

the recurring event form

Throws:

NullArgumentException - recurringEventRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createRecurringEvent

RecurringEvent createRecurringEvent(RecurringEventForm recurringEventForm)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Creates a new RecurringEvent.

Parameters:

recurringEventForm - the form for this RecurringEvent

Returns:

the new RecurringEvent

Throws:

IllegalStateException - recurringEventForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - recurringEventForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - recurringEventForm did not originate in a create transaction

Compliance:

mandatory - This method must be implemented.

canUpdateRecurringEvents

boolean canUpdateRecurringEvents()

Tests if this user can update RecurringEvents. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a RecurringEvent will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer update operations to an unauthorized user.

Returns:

false if recurring event modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getRecurringEventFormForUpdate

RecurringEventForm getRecurringEventFormForUpdate(Id recurringEventId)
                                                  throws NotFoundException,
                                                         OperationFailedException,
                                                         PermissionDeniedException

Gets the recurring event form for updating an existing recurring event. A new recurring event form should be requested for each update transaction.

Parameters:

recurringEventId - the Id of the RecurringEvent

Returns:

the recurring event form

Throws:

NotFoundException - recurringEventId is not found

NullArgumentException - recurringEventId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateRecurringEvent

void updateRecurringEvent(RecurringEventForm recurringEventForm)
                          throws OperationFailedException,
                                 PermissionDeniedException

Updates an existing recurring event.

Parameters:

recurringEventForm - the form containing the elements to be updated

Throws:

IllegalStateException - recurringEventForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - recurringEventForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - recurringEventForm did not originate in an update transaction

Compliance:

mandatory - This method must be implemented.

canDeleteRecurringEvents

boolean canDeleteRecurringEvents()

Tests if this user can delete RecurringEvents. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a RecurringEvent will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer delete operations to an unauthorized user.

Returns:

false if RecurringEvent deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteRecurringEvent

void deleteRecurringEvent(Id recurringEventId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Deletes the RecurringEvent identified by the given Id.

Parameters:

recurringEventId - the Id of the RecurringEvent to delete

Throws:

NotFoundException - a RecurringEvent was not found identified by the given Id

NullArgumentException - recurringEventId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageRecurringEventAliases

boolean canManageRecurringEventAliases()

Tests if this user can manage Id aliases for RecurringEvents. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.

Returns:

false if RecurringEvent aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasRecurringEvent

void aliasRecurringEvent(Id recurringEventId,
                       Id aliasId)
                         throws AlreadyExistsException,
                                NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Adds an Id to a RecurringEvent for the purpose of creating compatibility. The primary Id of the RecurringEvent is determined by the provider. The new Id performs as an alias to the primary Id. If the alias is a pointer to another recurring event, it is reassigned to the given recurring event Id.

Parameters:

recurringEventId - the Id of a RecurringEvent

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - recurringEventId not found

NullArgumentException - recurringEventId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canScheduleRecurringEvents

boolean canScheduleRecurringEvents()

Tests if this user can schedule recurring events. A return of true does not guarantee successful authorization. A return of false indicates that it is known recurring event methods in this session will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer create operations to an unauthorized user.

Returns:

false if recurring event scheduling is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

addSchedule

Id addSchedule(Id recurringEventId,
             Id scheduleId)
               throws AlreadyExistsException,
                      NotFoundException,
                      OperationFailedException,
                      PermissionDeniedException

Adds a schedule to the given recurring event.

Parameters:

recurringEventId - a recurring event Id

scheduleId - a schedule Id

Returns:

the Id of the schedule

Throws:

AlreadyExistsException - schedule is already part of recurring event

NotFoundException - recurringEventId or scheduleId is not found

NullArgumentException - recurringEventId or scheduleId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

removeSchedule

void removeSchedule(Id recurringEventId,
                  Id scheduleId)
                    throws NotFoundException,
                           OperationFailedException,
                           PermissionDeniedException

Removes a schedule from a given recurring event.

Parameters:

recurringEventId - a recurring event Id

scheduleId - the schedule Id

Throws:

NotFoundException - schedule not part of recurring event

NullArgumentException - recurringEventId or scheduleId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

addSpecificDate

void addSpecificDate(Id recurringEventId,
                   DateTime date,
                   DisplayText locationDescription)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Adds a specific date to the given recurring event.

Parameters:

recurringEventId - a recurring event Id

date - a date

locationDescription - location description

Throws:

NotFoundException - recurringEventId is not found

NullArgumentException - recurringEventId, date , or locationDescription is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

addSpecificDateWithLocation

void addSpecificDateWithLocation(Id recurringEventId,
                               DateTime date,
                               Id locationId)
                                 throws NotFoundException,
                                        OperationFailedException,
                                        PermissionDeniedException

Adds a specific date to the given recurring event.

Parameters:

recurringEventId - a recurring event Id

date - a date

locationId - a location

Throws:

NotFoundException - recurringEventId or locationId is not found

NullArgumentException - recurringEventId, date , or locationId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

clearSpecificDates

void clearSpecificDates(Id recurringEventId,
                      DateTime from,
                      DateTime to)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Clears any specific dates between the given dates inclusive.

Parameters:

recurringEventId - a recurring event Id

from - start date inclusive

to - end date inclusive

Throws:

InvalidArgumentException - from is greater than to

NotFoundException - recurringEventId is not found

NullArgumentException - recurringEventId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

addEvent

void addEvent(Id recurringEventId,
            Id eventId)
              throws NotFoundException,
                     OperationFailedException,
                     PermissionDeniedException

Adds another event as part of this recurring event.

Parameters:

recurringEventId - a recurring event Id

eventId - an event Id

Throws:

NotFoundException - recurringEventId or eventId is not found

NullArgumentException - recurringEventId or eventId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

removeEvent

void removeEvent(Id recurringEventId,
               Id eventId)
                 throws NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Removes an event as part of this recurring event.

Parameters:

recurringEventId - a recurring event Id

eventId - an event Id

Throws:

NotFoundException - recurringEventId or eventId is not found or eventId not part of recurringEventId

NullArgumentException - recurringEventId or eventId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

addBlackout

void addBlackout(Id recurringEventId,
               DateTime from,
               DateTime to)
                 throws NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Adds a blackout to the given recurring event that blocks events in the series.

Parameters:

recurringEventId - a recurring event Id

from - start date inclusive

to - end date inclusive

Throws:

InvalidArgumentException - from is greater than to

NotFoundException - recurringEventId is not found

NullArgumentException - recurringEventId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

clearBlackout

void clearBlackout(Id recurringEventId,
                 DateTime from,
                 DateTime to)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

Clears any blackouts between the given dates inclusive.

Parameters:

recurringEventId - a recurring event Id

from - start date inclusive

to - end date inclusive

Throws:

InvalidArgumentException - from is greater than to

NotFoundException - recurringEventId is not found

NullArgumentException - recurringEventId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.