public interface CalendarHierarchySession extends OsidSession
This session defines methods for traversing a hierarchy of
Calendar
objects. Each node in the hierarchy is a unique
Calendar.
The hierarchy may be traversed recursively to establish
the tree structure through getParentCalendars()
and
getChildCalendars().
To relate these Ids
to another
OSID, getCalendarNodes()
can be used for retrievals that
can be used for bulk lookups in other OSIDs. Any Calendar
available in the Calendaring OSID is known to this hierarchy but does not
appear in the hierarchy traversal until added as a root node or a child of
another node.
A user may not be authorized to traverse the entire hierarchy. Parts
of the hierarchy may be made invisible through omission from the returns
of getParentCalendars()
or getChildCalendars()
in lieu of a PERMISSION_DENIED
error that may
disrupt the traversal through authorized pathways.
This session defines views that offer differing behaviors when retrieving multiple objects.
Modifier and Type | Method and Description |
---|---|
boolean |
canAccessCalendarHierarchy()
Tests if this user can perform hierarchy queries.
|
Hierarchy |
getCalendarHierarchy()
Gets the hierarchy associated with this session.
|
Id |
getCalendarHierarchyId()
Gets the hierarchy
Id associated with this session. |
Node |
getCalendarNodeIds(Id calendarId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given calendar.
|
CalendarNode |
getCalendarNodes(Id calendarId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given calendar.
|
IdList |
getChildCalendarIds(Id calendarId)
Gets the child
Ids of the given calendar. |
CalendarList |
getChildCalendars(Id calendarId)
Gets the children of the given calendar.
|
IdList |
getParentCalendarIds(Id calendarId)
Gets the parent
Ids of the given calendar. |
CalendarList |
getParentCalendars(Id calendarId)
Gets the parents of the given calendar.
|
IdList |
getRootCalendarIds()
Gets the root calendar
Ids in this hierarchy. |
CalendarList |
getRootCalendars()
Gets the root calendars in this calendar hierarchy.
|
boolean |
hasChildCalendars(Id calendarId)
Tests if a calendar has any children.
|
boolean |
hasParentCalendars(Id calendarId)
Tests if the
Calendar has any parents. |
boolean |
isAncestorOfCalendar(Id id,
Id calendarId)
Tests if an
Id is an ancestor of a calendar. |
boolean |
isChildOfCalendar(Id id,
Id calendarId)
Tests if a calendar is a direct child of another.
|
boolean |
isDescendantOfCalendar(Id id,
Id calendarId)
Tests if an
Id is a descendant of a calendar. |
boolean |
isParentOfCalendar(Id id,
Id calendarId)
Tests if an
Id is a direct parent of a calendar. |
void |
useComparativeCalendarView()
The returns from the calendar methods may omit or translate elements
based on this session, such as authorization, and not result in an
error.
|
void |
usePlenaryCalendarView()
A complete view of the
Hierarchy returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getCalendarHierarchyId()
Id
associated with this session. Id
associated with this sessionmandatory
- This method must be implemented. Hierarchy getCalendarHierarchy() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canAccessCalendarHierarchy()
PERMISSION_DENIED.
This is intended as a hint to an
an application that may not offer traversal functions to unauthorized
users. false
if hierarchy traversal methods are not
authorized, true
otherwisemandatory
- This method must be implemented. void useComparativeCalendarView()
mandatory
- This method is must be implemented. void usePlenaryCalendarView()
Hierarchy
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.mandatory
- This method is must be implemented. IdList getRootCalendarIds() throws OperationFailedException, PermissionDeniedException
Ids
in this hierarchy. Ids
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. CalendarList getRootCalendars() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method is must be implemented. boolean hasParentCalendars(Id calendarId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Calendar
has any parents.calendarId
- the Id
of a calendar true
if the calendar has parents, false
otherwiseNotFoundException
- calendarId
is not
foundNullArgumentException
- calendarId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isParentOfCalendar(Id id, Id calendarId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a direct parent of a calendar.id
- an Id
calendarId
- the Id
of a calendar true
if this id
is a parent of
calendarId,
false
otherwiseNotFoundException
- calendarId
is not
foundNullArgumentException
- id
or
calendarId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getParentCalendarIds(Id calendarId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given calendar.calendarId
- the Id
of a calendar Ids
of the calendarNotFoundException
- calendarId
is not
foundNullArgumentException
- calendarId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. CalendarList getParentCalendars(Id calendarId) throws NotFoundException, OperationFailedException, PermissionDeniedException
calendarId
- the Id
of a calendarNotFoundException
- calendarId
is not
foundNullArgumentException
- calendarId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isAncestorOfCalendar(Id id, Id calendarId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is an ancestor of a calendar.id
- an Id
calendarId
- the Id
of a calendar true
if this id
is an ancestor
of calendarId,
false
otherwiseNotFoundException
- calendarId
is not
foundNullArgumentException
- id
or
calendarId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
boolean hasChildCalendars(Id calendarId) throws NotFoundException, OperationFailedException, PermissionDeniedException
calendarId
- the Id
of a calendar true
if the calendarId
has
children, false
otherwiseNotFoundException
- calendarId
is not
foundNullArgumentException
- calendarId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isChildOfCalendar(Id id, Id calendarId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id
- an Id
calendarId
- the Id
of a calendar true
if the id
is a child of
calendarId,
false
otherwiseNotFoundException
- calendarId
is not
foundNullArgumentException
- id
or
calendarId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getChildCalendarIds(Id calendarId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given calendar.calendarId
- the Id
to queryNotFoundException
- calendarId
is not
foundNullArgumentException
- calendarId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. CalendarList getChildCalendars(Id calendarId) throws NotFoundException, OperationFailedException, PermissionDeniedException
calendarId
- the Id
to queryNotFoundException
- calendarId
is not
foundNullArgumentException
- calendarId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isDescendantOfCalendar(Id id, Id calendarId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a descendant of a calendar.id
- an Id
calendarId
- the Id
of a calendar true
if the id
is a descendant
of the calendarId,
false
otherwiseNotFoundException
- calendarId
is not
foundNullArgumentException
- id
or
calendarId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
is not found return false.
Node getCalendarNodeIds(Id calendarId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
calendarId
- the Id
to queryancestorLevels
- the maximum number of ancestor levels to
include. A value of 0 returns no parents in the node.descendantLevels
- the maximum number of descendant levels to
include. A value of 0 returns no children in the node.includeSiblings
- true
to include the siblings of
the given node, false
to omit the siblingsNotFoundException
- calendarId
not foundNullArgumentException
- calendarId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. CalendarNode getCalendarNodes(Id calendarId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
calendarId
- the Id
to queryancestorLevels
- the maximum number of ancestor levels to
include. A value of 0 returns no parents in the node.descendantLevels
- the maximum number of descendant levels to
include. A value of 0 returns no children in the node.includeSiblings
- true
to include the siblings of
the given node, false
to omit the siblingsNotFoundException
- calendarId
not foundNullArgumentException
- calendarId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.