public interface LogHierarchySession extends OsidSession
This session defines methods for traversing a hierarchy of Log
objects. Each node in the hierarchy is a unique Log.
The hierarchy may be traversed recursively to establish the tree
structure through getParentLogs()
and
getChildLogs().
To relate these Ids
to another
OSID, getLogNodes()
can be used for retrievals that can be
used for bulk lookups in other OSIDs. Any Log
available in
the Log 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 getParentLogs()
or getChildLogs()
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 |
canAccessLogHierarchy()
Tests if this user can perform hierarchy queries.
|
IdList |
getChildLogIds(Id logId)
Gets the child
Ids of the given log. |
LogList |
getChildLogs(Id logId)
Gets the child logs of the given
id. |
Hierarchy |
getLogHierarchy()
Gets the hierarchy associated with this session.
|
Id |
getLogHierarchyId()
Gets the hierarchy
Id associated with this session. |
Node |
getLogNodeIds(Id logId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given log.
|
LogNode |
getLogNodes(Id logId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given log.
|
IdList |
getParentLogIds(Id logId)
Gets the parent
Ids of the given log. |
LogList |
getParentLogs(Id logId)
Gets the parent logs of the given
id. |
IdList |
getRootLogIds()
Gets the root log
Ids in this hierarchy. |
LogList |
getRootLogs()
Gets the root logs in the log hierarchy.
|
boolean |
hasChildLogs(Id logId)
Tests if a log has any children.
|
boolean |
hasParentLogs(Id logId)
Tests if the
Log has any parents. |
boolean |
isAncestorOfLog(Id id,
Id logId)
Tests if an
Id is an ancestor of a log. |
boolean |
isChildOfLog(Id id,
Id logId)
Tests if an
Id is a direct child of a log. |
boolean |
isDescendantOfLog(Id id,
Id logId)
Tests if an
Id is a descendant of a log. |
boolean |
isParentOfLog(Id id,
Id logId)
Tests if an
Id is a direct parent of a log. |
void |
useComparativeLogView()
The returns from the log methods may omit or translate elements based
on this session, such as authorization, and not result in an error.
|
void |
usePlenaryLogView()
A complete view of the
Log returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getLogHierarchyId()
Id
associated with this session. Id
associated with this sessionmandatory
- This method must be implemented. Hierarchy getLogHierarchy() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canAccessLogHierarchy()
PERMISSION_DENIED.
This is intended as a hint to an
an application that may not offer hierrachy traversal operations to
unauthorized users. false
if hierarchy traversal methods are not
authorized, true
otherwisemandatory
- This method must be implemented. void useComparativeLogView()
mandatory
- This method is must be implemented. void usePlenaryLogView()
Log
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 getRootLogIds() throws OperationFailedException, PermissionDeniedException
Ids
in this hierarchy. Ids
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. LogList getRootLogs() throws OperationFailedException, PermissionDeniedException
Ids
are known to the hierarchy,
an orphan does not appear in the hierarchy unless explicitly added as
a root node or child of another node.OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method is must be implemented. boolean hasParentLogs(Id logId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Log
has any parents.logId
- the Id
of a log true
if the log has parents, false
otherwiseNotFoundException
- logId
is not foundNullArgumentException
- logId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isParentOfLog(Id id, Id logId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a direct parent of a log.id
- an Id
logId
- the Id
of a log true
if this id
is a parent of
logId,
false
otherwiseNotFoundException
- logId
is not foundNullArgumentException
- id
or
logId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getParentLogIds(Id logId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given log.logId
- the Id
of a log Ids
of the logNotFoundException
- logId
is not foundNullArgumentException
- logId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. LogList getParentLogs(Id logId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id.
logId
- the Id
of the Log
to query id
NotFoundException
- a Log
identified by
Id is
not foundNullArgumentException
- logId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isAncestorOfLog(Id id, Id logId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is an ancestor of a log.id
- an Id
logId
- the Id
of a log true
if the id
is an ancestor of
the logId,
false
otherwiseNotFoundException
- logId
is not foundNullArgumentException
- id
or
logId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
is not found return false.
boolean hasChildLogs(Id logId) throws NotFoundException, OperationFailedException, PermissionDeniedException
logId
- the Id
of a log true
if the logId
has children,
false
otherwiseNotFoundException
- logId
is not foundNullArgumentException
- logId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isChildOfLog(Id id, Id logId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a direct child of a log.id
- an Id
logId
- the Id
of a log true
if this id
is a child of
logId,
false
otherwiseNotFoundException
- logId
is not foundNullArgumentException
- id
or
logId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getChildLogIds(Id logId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given log.logId
- the Id
to queryNotFoundException
- logId
is not foundNullArgumentException
- logId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. LogList getChildLogs(Id logId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id.
logId
- the Id
of the Log
to query id
NotFoundException
- a Log
identified by
Id is
not foundNullArgumentException
- logId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isDescendantOfLog(Id id, Id logId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a descendant of a log.id
- an Id
logId
- the Id
of a log true
if the id
is a descendant
of the logId,
false
otherwiseNotFoundException
- logId
is not foundNullArgumentException
- id
or
logId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
is not found return false.
Node getLogNodeIds(Id logId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
logId
- 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
- logId
is not foundNullArgumentException
- logId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. LogNode getLogNodes(Id logId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
logId
- 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
- logId
is not foundNullArgumentException
- logId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.