org.osid.calendaring

Interface RecurringEventUnravellingSession

All Superinterfaces:

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

public interface RecurringEventUnravellingSession
extends OsidSession

This session provides methods for retrieving and expanding RecurringEvent s.

This session defines views that offer differing behaviors when retrieving multiple objects.

• comparative view: elements may be silently omitted or re-ordered
• plenary view: provides a complete set or is an error condition
• isolated calendar view: All recurring event methods in this session operate, retrieve and pertain to recurring events defined explicitly in the current calendar. Using an isolated view is useful for managing recurring events with the RecurringEventAdminSession.
• federated calendar view: All recurring event methods in this session operate, retrieve and pertain to all recurring events defined in this calendar and any other calendars implicitly available in this calendar through calendar inheritence.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canUnravelRecurringEvents() Tests if this user can perform RecurringEvent lookups.
EventList	expandRecurringEvent(Id recurringEventId) Expands the given recurring event into a series of non-recurring events.
EventList	expandRecurringEventInDateRange(Id recurringEventId, DateTime from, DateTime to) Expands the given recurring event into a series of non-recurring events that fall within the given date range inclusive.
EventList	expandRecurringEvents(IdList recurringEventIds) Expands the given recurring events into a series of non-recurring events.
EventList	expandRecurringEventsInDateRange(Id recurringEventIds, DateTime from, DateTime to) Expands the given recurring events into a series of non-recurring events that fall within the given date range inclusive.
Calendar	getCalendar() Gets the Calendar associated with this session.
Id	getCalendarId() Gets the Calendar Id associated with this session.
long	getNumberOfEvents(Id recurringEventId) Gets the number of events in the recurring series.
long	getNumberOfEventsInDateRange(Id recurringEventId, DateTime from, DateTime to) Gets the number of events in the recurring series between the given dates inclusive.
RecurringEvent	getRecurringEventByEvent(Id eventId) Gets the recurring event where the given event Id was issued as part of the recurring series.
RecurringEventList	getRecurringEventsByDate(DateTime datetime) Gets a list of recurring events where the given date falls within the span of a recurring event.
RecurringEventList	getRecurringEventsByEvents(IdList eventIds) Gets a RecurringEventList corresponding to the given event IdList where the events were implcitly created from the recurring series.
RecurringEventList	getRecurringEventsInDateRange(DateTime from, DateTime to) Gets a RecurringEventList whose series falls entirely within the given range inclusive .
void	useComparativeRecurringEventView() The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	useFederatedCalendarView() Federates the view for methods in this session.
void	useIsolatedCalendarView() Isolates the view for methods in this session.
void	usePlenaryRecurringEventView() A complete view of the Event returns is desired.

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.

canUnravelRecurringEvents

boolean canUnravelRecurringEvents()

Tests if this user can perform RecurringEvent lookups. A return of true does not guarantee successful authorization. A return of false indicates that it is known all 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 lookup operations to unauthorized users.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeRecurringEventView

void useComparativeRecurringEventView()

The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.

Compliance:

mandatory - This method is must be implemented.

usePlenaryRecurringEventView

void usePlenaryRecurringEventView()

A complete view of the Event returns is desired. Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.

Compliance:

mandatory - This method is must be implemented.

useFederatedCalendarView

void useFederatedCalendarView()

Federates the view for methods in this session. A federated view will include events in calendars which are children of this calendar in the calendar hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedCalendarView

void useIsolatedCalendarView()

Isolates the view for methods in this session. An isolated view restricts lookups to this calendar only.

Compliance:

mandatory - This method is must be implemented.

getRecurringEventByEvent

RecurringEvent getRecurringEventByEvent(Id eventId)
                                        throws NotFoundException,
                                               OperationFailedException,
                                               PermissionDeniedException

Gets the recurring event where the given event Id was issued as part of the recurring series.

Parameters:

eventId - an event Id

Returns:

the returned RecurringEvent

Throws:

NotFoundException - eventId is not found

NullArgumentException - eventId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRecurringEventsByEvents

RecurringEventList getRecurringEventsByEvents(IdList eventIds)
                                              throws NotFoundException,
                                                     OperationFailedException,
                                                     PermissionDeniedException

Gets a RecurringEventList corresponding to the given event IdList where the events were implcitly created from the recurring series. In plenary mode, the returned list contains all of the recurring events corresponding to the events in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible Events may be omitted from the list and may present the elements in any order including returning a unique set.

Parameters:

eventIds - the list of Ids to retrieve

Returns:

the returned RecurringEvent list

Throws:

NotFoundException - an Id was not found

NullArgumentException - eventIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

expandRecurringEvent

EventList expandRecurringEvent(Id recurringEventId)
                               throws NotFoundException,
                                      OperationFailedException,
                                      PermissionDeniedException

Expands the given recurring event into a series of non-recurring events. In plenary mode, the returned list contains all of the events in the series, including duplicates, or an error results. In comparative mode, events may be omitted from the list and may present the elements in any order, including providing a unique set.

Parameters:

recurringEventId - Id of the recurring Event

Returns:

the returned Event list

Throws:

NotFoundException - recurringEventId was not found

NullArgumentException - recurringEventId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

expandRecurringEventInDateRange

EventList expandRecurringEventInDateRange(Id recurringEventId,
                                        DateTime from,
                                        DateTime to)
                                          throws NotFoundException,
                                                 OperationFailedException,
                                                 PermissionDeniedException

Expands the given recurring event into a series of non-recurring events that fall within the given date range inclusive. In plenary mode, the returned list contains all of the events in the series, including duplicates, or an error results. In comparative mode, events may be omitted from the list and may present the elements in any order, including providing a unique set.

Parameters:

recurringEventId - Id of the recurring Event

from - start date

to - end date

Returns:

the returned Event list

Throws:

InvalidArgumentException - to is less than from

NotFoundException - recurringEventId was not found

NullArgumentException - recurringEventId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

expandRecurringEvents

EventList expandRecurringEvents(IdList recurringEventIds)
                                throws NotFoundException,
                                       OperationFailedException,
                                       PermissionDeniedException

Expands the given recurring events into a series of non-recurring events. In plenary mode, the returned list contains all of the events in the series, including duplicates, or an error results. In comparative mode, events may be omitted from the list and may present the elements in any order, including providing a unique set.

Parameters:

recurringEventIds - the list of Ids to expand

Returns:

the returned Event list

Throws:

NotFoundException - an Id was not found

NullArgumentException - recurringEventIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

expandRecurringEventsInDateRange

EventList expandRecurringEventsInDateRange(Id recurringEventIds,
                                         DateTime from,
                                         DateTime to)
                                           throws NotFoundException,
                                                  OperationFailedException,
                                                  PermissionDeniedException

Expands the given recurring events into a series of non-recurring events that fall within the given date range inclusive. In plenary mode, the returned list contains all of the events in the series, including duplicates, or an error results. In comparative mode, events may be omitted from the list and may present the elements in any order, including providing a unique set.

Parameters:

recurringEventIds - the list of Ids to expand

from - start date

to - end date

Returns:

the returned Event list

Throws:

InvalidArgumentException - to is less than from

NotFoundException - an Id was not found

NullArgumentException - recurringEventIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

getRecurringEventsByDate

RecurringEventList getRecurringEventsByDate(DateTime datetime)
                                            throws OperationFailedException,
                                                   PermissionDeniedException

Gets a list of recurring events where the given date falls within the span of a recurring event. In plenary mode, the returned list contains all known events or an error results. Otherwise, the returned list may contain only those events that are accessible through this session. In both cases, the order of the set is not specified.

Parameters:

datetime - a date

Returns:

the returned RecurringEvent list

Throws:

NullArgumentException - datetime is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRecurringEventsInDateRange

RecurringEventList getRecurringEventsInDateRange(DateTime from,
                                               DateTime to)
                                                 throws OperationFailedException,
                                                        PermissionDeniedException

Gets a RecurringEventList whose series falls entirely within the given range inclusive . In plenary mode, the returned list contains all known recurring events or an error results. Otherwise, the returned list may contain only those recurring events that are accessible through this session. In both cases, the order of the set is not specified.

Parameters:

from - start date

to - end date

Returns:

the returned RecurringEvent list

Throws:

InvalidArgumentException - to is less than from

NullArgumentException - from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getNumberOfEvents

long getNumberOfEvents(Id recurringEventId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Gets the number of events in the recurring series.

Parameters:

recurringEventId - Id of the recurring Event

Returns:

the number of meeting times

Throws:

NotFoundException - recurringEventId was not found

NullArgumentException - recurringEventId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

getNumberOfEventsInDateRange

long getNumberOfEventsInDateRange(Id recurringEventId,
                                DateTime from,
                                DateTime to)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

Gets the number of events in the recurring series between the given dates inclusive.

Parameters:

recurringEventId - Id of the recurring Event

from - start date

to - end date

Returns:

the number of meeting times

Throws:

InvalidArgumentException - to is less than from

NotFoundException - recurringEventId was not found

NullArgumentException - recurringEventId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.