public interface EngineHierarchySession extends OsidSession
This session defines methods for traversing a hierarchy of
Engine
objects. Each node in the hierarchy is a unique
Engine.
The hierarchy may be traversed recursively to establish
the tree structure through getParentEngines()
and
getChildEngines().
To relate these Ids
to another
OSID, getEngienNodes()
can be used for retrievals that can
be used for bulk lookups in other OSIDs. Any Engine
available in the Rule 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 getParentEngines()
or getChildEngines()
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 |
canAccessEngineHierarchy()
Tests if this user can perform hierarchy queries.
|
IdList |
getChildEngineIds(Id engineId)
Gets the child
Ids of the given engine. |
EngineList |
getChildEngines(Id engineId)
Gets the child engines of the given
id. |
Hierarchy |
getEngineHierarchy()
Gets the hierarchy associated with this session.
|
Id |
getEngineHierarchyId()
Gets the hierarchy
Id associated with this session. |
Node |
getEngineNodeIds(Id engineId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given engine.
|
EngineNode |
getEngineNodes(Id engineId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given engine.
|
IdList |
getParentEngineIds(Id engineId)
Gets the parent
Ids of the given engine |
EngineList |
getParentEngines(Id engineId)
Gets the parent engines of the given
id. |
IdList |
getRootEngineIds()
Gets the root engine
Ids in this hierarchy. |
EngineList |
getRootEngines()
Gets the root engines in this engine hierarchy.
|
boolean |
hasChildEngines(Id engineId)
Tests if an engine has any children.
|
boolean |
hasParentEngines(Id engineId)
Tests if the
Engine has any parents. |
boolean |
isAncestorOfEngine(Id id,
Id engineId)
Tests if an
Id is an ancestor of an engine. |
boolean |
isChildOfEngine(Id id,
Id engineId)
Tests if an engine is a direct child of another.
|
boolean |
isDescendantOfEngine(Id id,
Id engineId)
Tests if an
Id is a descendant of an egine. |
boolean |
isParentOfEngine(Id id,
Id engineId)
Tests if an
Id is a direct parent of an engine. |
void |
useComparativeEngineView()
The returns from the engine methods may omit or translate elements
based on this session, such as authorization, and not result in an
error.
|
void |
usePlenaryEngineView()
A complete view of the
Engine returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getEngineHierarchyId()
Id
associated with this session. Id
associated with this sessionmandatory
- This method must be implemented. Hierarchy getEngineHierarchy() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canAccessEngineHierarchy()
PERMISSION_DENIED.
This is intended as a hint to an
an application that may wish not to offer traversal operations to
unauthorized users. false
if hierarchy traversal methods are not
authorized, true
otherwisemandatory
- This method must be implemented. void useComparativeEngineView()
mandatory
- This method is must be implemented. void usePlenaryEngineView()
Engine
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 getRootEngineIds() throws OperationFailedException, PermissionDeniedException
Ids
in this hierarchy. Ids
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. EngineList getRootEngines() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method is must be implemented. boolean hasParentEngines(Id engineId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Engine
has any parents.engineId
- the Id
of a engine true
if the engine has parents, false
otherwiseNotFoundException
- engineId
is not
foundNullArgumentException
- engineId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isParentOfEngine(Id id, Id engineId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a direct parent of an engine.id
- an Id
engineId
- the Id
of an egine true
if this id
is a parent of
engineId,
false
otherwiseNotFoundException
- engineId
is not
foundNullArgumentException
- id
or
engineId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getParentEngineIds(Id engineId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given engineengineId
- the Id
of an egine Ids
of the engineNotFoundException
- engineId
is not
foundNullArgumentException
- engineId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. EngineList getParentEngines(Id engineId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id.
engineId
- the Id
of the Engine
to
query id
NotFoundException
- an Engine
identified
by Id is
not foundNullArgumentException
- engineId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isAncestorOfEngine(Id id, Id engineId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is an ancestor of an engine.id
- an Id
engineId
- the Id
of an engine true
if this id
is an ancestor
of engineId,
false
otherwiseNotFoundException
- engineId
is not
foundNullArgumentException
- id
or
engineId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
boolean hasChildEngines(Id engineId) throws NotFoundException, OperationFailedException, PermissionDeniedException
engineId
- the Id
of an engine true
if the engineId
has
children, false
otherwiseNotFoundException
- engineId
is not
foundNullArgumentException
- engineId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isChildOfEngine(Id id, Id engineId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id
- an Id
engineId
- the Id
of an engine true
if the id
is a child of
engineId,
false
otherwiseNotFoundException
- engineId
is not
foundNullArgumentException
- id
or
engineId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getChildEngineIds(Id engineId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given engine.engineId
- the Id
to queryNotFoundException
- engineId
is not
foundNullArgumentException
- engineId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. EngineList getChildEngines(Id engineId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id.
engineId
- the Id
of the Engine
to
query id
NotFoundException
- an Engine
identified
by Id is
not foundNullArgumentException
- engineId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isDescendantOfEngine(Id id, Id engineId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a descendant of an egine.id
- an Id
engineId
- the Id
of an engine true
if the id
is a descendant
of the engineId,
false
otherwiseNotFoundException
- engineId
is not
foundNullArgumentException
- id
or
engineId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
is not found return false.
Node getEngineNodeIds(Id engineId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
engineId
- 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
- engineId
is not
foundNullArgumentException
- engineId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. EngineNode getEngineNodes(Id engineId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
engineId
- 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
- engineId
is not
foundNullArgumentException
- engineId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.