public interface HierarchyTraversalSession extends OsidSession
This session defines methods for traversing a hierarchy. Each node in
the hierarchy is a unique OSID Id.
The hierarchy may be
traversed recursively to establish the tree structure through
getParents()
and getChildren().
To relate these
Ids
to another OSID, getNodes()
can be used
for retrievals that can be used for bulk lookups in other OSIDs.
Any Id available in an associated OSID is known to this hierarchy. A
lookup up a particular Id
in this hierarchy for the
purposes of establishing a starting point for traversal or determining
relationships should use the Id
returned from the
corresponding OSID object, not an Id that has been stored, to avoid
problems with Id
translation or aliasing.
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 getParents()
or getChildren()
in lieu of
a PERMISSION_DENIED
error that may disrupt the traversal
through authorized pathways.
Modifier and Type | Method and Description |
---|---|
boolean |
canAccessHierarchy()
Tests if this user can perform hierarchy queries.
|
IdList |
getChildren(Id id)
Gets the children of the given
Id. |
Hierarchy |
getHierarchy()
Gets the hierarchy associated with this session.
|
Id |
getHierarchyId()
Gets the hierarchy
Id associated with this session. |
Node |
getNodes(Id id,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given
Id. |
IdList |
getParents(Id id)
Gets the parents of the given
id. |
IdList |
getRoots()
Gets the root nodes of this hierarchy.
|
boolean |
hasChildren(Id id)
Tests if this
Id has any children. |
boolean |
hasParents(Id id)
Tests if this
Id contains any parents. |
boolean |
isAncestor(Id id,
Id ancestorId)
Tests if an
Id is an ancestor of another. |
boolean |
isChild(Id id,
Id childId)
Tests if a node is a direct child of another.
|
boolean |
isDescendant(Id id,
Id descendantId)
Tests if a node is a descendant of another.
|
boolean |
isParent(Id id,
Id parentId)
Tests if an
Id is a direct parent of another. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getHierarchyId()
Id
associated with this session. Id
associated with this sessionmandatory
- This method must be implemented. Hierarchy getHierarchy() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canAccessHierarchy()
PERMISSION_DENIED.
This is intended as a hint to an
application that may opt not to offer lookup operations. false
if lookup methods are not authorized,
true
otherwisemandatory
- This method must be implemented. IdList getRoots() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean hasParents(Id id) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
contains any parents.id
- the Id
to query true
if this Id
contains
parents, false
otherwiseNotFoundException
- id
is not foundNullArgumentException
- id
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isParent(Id id, Id parentId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a direct parent of another.id
- the Id
to queryparentId
- the Id
of a parent true
if this parentId
is a
parent of id,
false
otherwiseNotFoundException
- id
is not foundNullArgumentException
- id
or
parentId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- parentId
not found return false.
IdList getParents(Id id) throws NotFoundException, OperationFailedException, PermissionDeniedException
id.
id
- the Id
to query id
NotFoundException
- id
is not foundNullArgumentException
- id
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isAncestor(Id id, Id ancestorId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is an ancestor of another.id
- the Id
to queryancestorId
- the Id
of an ancestor true
if this ancestorId
is a
parent of id,
false
otherwiseNotFoundException
- id
is not foundNullArgumentException
- id
or
ancestorId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- ancestorId
not found return false.
boolean hasChildren(Id id) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
has any children.id
- the Id
to query true
if this Id
has children,
false
otherwiseNotFoundException
- id
is not foundNullArgumentException
- id
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isChild(Id id, Id childId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id
- the Id
to querychildId
- the Id
of a child true
if this childId
is a child
of the Id,
false
otherwiseNotFoundException
- id
is not foundNullArgumentException
- id
or
childId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- childId
not found return false.
IdList getChildren(Id id) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id.
id
- the Id
to query id
NotFoundException
- id
is not foundNullArgumentException
- id
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isDescendant(Id id, Id descendantId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id
- the Id
to querydescendantId
- the Id
of a descendant true
if this descendantId
is a
child of the Id,
false
otherwiseNotFoundException
- id
is not foundNullArgumentException
- id
or
descendant
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- not found return false.
Node getNodes(Id id, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id.
id
- 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
- id
is not foundNullArgumentException
- id
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.