public interface AgencyHierarchySession extends OsidSession
This session defines methods for traversing a hierarchy of
Agency
objects. Each node in the hierarchy is a unique
Agency.
The hierarchy may be traversed recursively to establish
the tree structure through getParentAgencies()
and
getChildAgencies().
To relate these Ids
to another
OSID, getAgencyNodes()
can be used for retrievals that can
be used for bulk lookups in other OSIDs. Any Agency
available in the Authentication 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 getParentAgencies()
or getChildAgencies()
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 |
canAccessAgencyHierarchy()
Tests if this user can perform hierarchy queries.
|
Hierarchy |
getAgencyHierarchy()
Gets the hierarchy associated with this session.
|
Id |
getAgencyHierarchyId()
Gets the hierarchy
Id associated with this session. |
Node |
getAgencyNodeIds(Id agencyId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given agency.
|
AgencyNode |
getAgencyNodes(Id agencyId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given agency.
|
AgencyList |
getChildAgencies(Id agencyId)
Gets the children of the given agency.
|
IdList |
getChildAgencyIds(Id agencyId)
Gets the child
Ids of the given agency. |
AgencyList |
getParentAgencies(Id agencyId)
Gets the parents of the given agency.
|
IdList |
getParentAgencyIds(Id agencyId)
Gets the parent
Ids of the given agency. |
AgencyList |
getRootAgencies()
Gets the root agencies in this agency hierarchy.
|
IdList |
getRootAgencyIds()
Gets the root agency
Ids in this hierarchy. |
boolean |
hasChildAgencies(Id agencyId)
Tests if an agency has any children.
|
boolean |
hasParentAgencies(Id agencyId)
Tests if the
Agency has any parents. |
boolean |
isAncestorOfAgency(Id id,
Id agencyId)
Tests if an
Id is an ancestor of an agency. |
boolean |
isChildOfAgency(Id id,
Id agencyId)
Tests if a node is a direct child of another.
|
boolean |
isDescendantOfAgency(Id id,
Id agencyId)
Tests if an
Id is a descendant of an agency. |
boolean |
isParentOfAgency(Id id,
Id agencyId)
Tests if an
Id is a direct parent of an agency. |
void |
useComparativeAgencyView()
The returns from the agency methods may omit or translate elements
based on this session, such as authorization, and not result in an
error.
|
void |
usePlenaryAgencyView()
A complete view of the hierarchy returns is desired.
|
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getAgencyHierarchyId()
Id
associated with this session. Id
associated with this sessionmandatory
- This method must be implemented. Hierarchy getAgencyHierarchy() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canAccessAgencyHierarchy()
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 useComparativeAgencyView()
mandatory
- This method is must be implemented. void usePlenaryAgencyView()
mandatory
- This method is must be implemented. IdList getRootAgencyIds() throws OperationFailedException, PermissionDeniedException
Ids
in this hierarchy. Ids
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. AgencyList getRootAgencies() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method is must be implemented. boolean hasParentAgencies(Id agencyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Agency
has any parents.agencyId
- an agency Id
true
if the agency has parents, false
otherwiseNotFoundException
- agencyId
is not
foundNullArgumentException
- agencyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isParentOfAgency(Id id, Id agencyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a direct parent of an agency.id
- an Id
agencyId
- the Id
of an agency true
if this id
is a parent of
agencyId,
false
otherwiseNotFoundException
- agencyId
is not
foundNullArgumentException
- id
or
agencyId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getParentAgencyIds(Id agencyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given agency.agencyId
- an agency Id
Ids
of the agencyNotFoundException
- agencyId
is not
foundNullArgumentException
- agencyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. AgencyList getParentAgencies(Id agencyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
agencyId
- an agency Id
NotFoundException
- agencyId
is not
foundNullArgumentException
- agencyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isAncestorOfAgency(Id id, Id agencyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is an ancestor of an agency.id
- an Id
agencyId
- the Id
of an agency true
if this id
is an ancestor
of agencyId,
false
otherwiseNotFoundException
- agencyId
is not
foundNullArgumentException
- agencyId
or
id
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
boolean hasChildAgencies(Id agencyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
agencyId
- an agencyId
true
if the agencyId
has
children, false
otherwiseNotFoundException
- agencyId
is not
foundNullArgumentException
- agencyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isChildOfAgency(Id id, Id agencyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id
- an Id
agencyId
- the Id
of an agency true
if the id
is a child of
agencyId,
false
otherwiseNotFoundException
- agencyId
is not
foundNullArgumentException
- agencyId
or
id
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getChildAgencyIds(Id agencyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given agency.agencyId
- the Id
to queryNotFoundException
- agencyId
is not
foundNullArgumentException
- agencyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. AgencyList getChildAgencies(Id agencyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
agencyId
- the Id
to queryNotFoundException
- agencyId
is not
foundNullArgumentException
- agencyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isDescendantOfAgency(Id id, Id agencyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a descendant of an agency.id
- an Id
agencyId
- the Id
of an agency true
if the id
is a descendant
of the agencyId,
false
otherwiseNotFoundException
- agencyId
is not
foundNullArgumentException
- agencyId
or
id
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
is not found return false.
Node getAgencyNodeIds(Id agencyId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
agencyId
- 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
- agencyId
is not
foundNullArgumentException
- agencyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. AgencyNode getAgencyNodes(Id agencyId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
agencyId
- 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
- agencyId
is not
foundNullArgumentException
- agencyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.