public interface VaultHierarchySession extends OsidSession
This session defines methods for traversing a hierarchy of Vault
objects. Each node in the hierarchy is a unique Vault.
The hierarchy may be traversed recursively to establish the tree
structure through getParentVaults()
and
getChildVaults().
To relate these Ids
to another
OSID, getVaultNodes()
can be used for retrievals that can
be used for bulk lookups in other OSIDs. Any Vault
available in the Authorization 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 getParentVaults()
or getChildVaults()
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 |
canAccessVaultHierarchy()
Tests if this user can perform hierarchy queries.
|
IdList |
getChildVaultIds(Id vaultId)
Gets the child
Ids of the given vault. |
VaultList |
getChildVaults(Id vaultId)
Gets the children of the given vault.
|
IdList |
getParentVaultIds(Id vaultId)
Gets the parent
Ids of the given vault. |
VaultList |
getParentVaults(Id vaultId)
Gets the parents of the given vault.
|
IdList |
getRootVaultIds()
Gets the root vault
Ids in this hierarchy. |
VaultList |
getRootVaults()
Gets the root vaults in this vault hierarchy.
|
Hierarchy |
getVaultHierarchy()
Gets the hierarchy associated with this session.
|
Id |
getVaultHierarchyId()
Gets the hierarchy
Id associated with this session. |
Node |
getVaultNodeIds(Id vaultId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given vault.
|
VaultNode |
getVaultNodes(Id vaultId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given vault.
|
boolean |
hasChildVaults(Id vaultId)
Tests if a vault has any children.
|
boolean |
hasParentVaults(Id vaultId)
Tests if the
Vault has any parents. |
boolean |
isAncestorOfVault(Id id,
Id vaultId)
Tests if an
Id is an ancestor of a vault. |
boolean |
isChildOfVault(Id id,
Id vaultId)
Tests if a vault is a direct child of another.
|
boolean |
isDescendantOfVault(Id id,
Id vaultId)
Tests if an
Id is a descendant of a vault. |
boolean |
isParentOfVault(Id id,
Id vaultId)
Tests if an
Id is a direct parent of a vault. |
void |
useComparativeVaultView()
The returns from the vault methods may omit or translate elements
based on this session, such as authorization, and not result in an
error.
|
void |
usePlenaryVaultView()
A complete view of the
Hierarchy returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getVaultHierarchyId()
Id
associated with this session. Id
associated with this sessionmandatory
- This method must be implemented. Hierarchy getVaultHierarchy() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canAccessVaultHierarchy()
PERMISSION_DENIED.
This is intended as a hint to an
application that may opt not to offer lookup operations. false
if hierarchy traversal methods are not
authorized, true
otherwisemandatory
- This method must be implemented. void useComparativeVaultView()
mandatory
- This method is must be implemented. void usePlenaryVaultView()
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 getRootVaultIds() throws OperationFailedException, PermissionDeniedException
Ids
in this hierarchy. Ids
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. VaultList getRootVaults() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method is must be implemented. boolean hasParentVaults(Id vaultId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Vault
has any parents.vaultId
- a vault Id
true
if the vault has parents, false
otherwiseNotFoundException
- vaultId
is not foundNullArgumentException
- vaultId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isParentOfVault(Id id, Id vaultId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a direct parent of a vault.id
- an Id
vaultId
- the Id
of a vault true
if this id
is a parent of
vaultId,
false
otherwiseNotFoundException
- vaultId
is not foundNullArgumentException
- id
or
vaultId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getParentVaultIds(Id vaultId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given vault.vaultId
- a vault Id
Ids
of the vaultNotFoundException
- vaultId
is not foundNullArgumentException
- vaultId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. VaultList getParentVaults(Id vaultId) throws NotFoundException, OperationFailedException, PermissionDeniedException
vaultId
- a vault Id
NotFoundException
- vaultId
is not foundNullArgumentException
- vaultId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isAncestorOfVault(Id id, Id vaultId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is an ancestor of a vault.id
- an Id
vaultId
- the Id
of a vault true
if this id
is an ancestor
of vaultId,
false
otherwiseNotFoundException
- vaultId
is not foundNullArgumentException
- vaultId
or
id
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
boolean hasChildVaults(Id vaultId) throws NotFoundException, OperationFailedException, PermissionDeniedException
vaultId
- a vaultId
true
if the vaultId
has
children, false
otherwiseNotFoundException
- vaultId
is not foundNullArgumentException
- vaultId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isChildOfVault(Id id, Id vaultId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id
- an Id
vaultId
- the Id
of a vault true
if the id
is a child of
vaultId,
false
otherwiseNotFoundException
- vaultId
not foundNullArgumentException
- vaultId
or
id
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getChildVaultIds(Id vaultId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given vault.vaultId
- the Id
to queryNotFoundException
- vaultId
is not foundNullArgumentException
- vaultId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. VaultList getChildVaults(Id vaultId) throws NotFoundException, OperationFailedException, PermissionDeniedException
vaultId
- the Id
to queryNotFoundException
- vaultId
is not foundNullArgumentException
- vaultId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isDescendantOfVault(Id id, Id vaultId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a descendant of a vault.id
- an Id
vaultId
- the Id
of a vault true
if the id
is a descendant
of the vaultId,
false
otherwiseNotFoundException
- vaultId
not foundNullArgumentException
- vaultId
or
id
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
is not found return false.
Node getVaultNodeIds(Id vaultId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
vaultId
- 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
- vaultId
is not foundNullArgumentException
- vaultId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. VaultNode getVaultNodes(Id vaultId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
vaultId
- 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
- vaultId
is not foundNullArgumentException
- vaultId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.