public interface OrganizationHierarchySession extends OsidSession
This session defines methods for traversing a hierarchy of
Organization
objects. Each node in the hierarchy is a unique
Organization.
The hierarchy may be traversed recursively to
establish the tree structure through getOrganizationNodes().
To relate these Ids
to another OSID,
getAncestorOrganizations()
and getDescendantOrganizations()
can be used for retrievals that can be used for bulk lookups in
other OSIDs. Any Organization
available in the Personnel
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 getParentOrganizations()
or
getChildOrganizations()
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 |
canAccessOrganizationHierarchy()
Tests if this user can perform hierarchy queries.
|
IdList |
getChildOrganizationIds(Id organizationId)
Gets the child
Ids of the given organization. |
OrganizationList |
getChildOrganizations(Id organizationId)
Gets the children of the given organization.
|
Hierarchy |
getOrganizationHierarchy()
Gets the hierarchy associated with this session.
|
Id |
getOrganizationHierarchyId()
Gets the hierarchy
Id associated with this session. |
Node |
getOrganizationNodeIds(Id organizationId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given organization.
|
OrganizationNode |
getOrganizationNodes(Id organizationId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given organization.
|
IdList |
getParentOrganizationIds(Id organizationId)
Gets the parent Ids of the given organization.
|
OrganizationList |
getParentOrganizations(Id organizationId)
Gets the parents of the given organization.
|
IdList |
getRootOrganizationIds()
Gets the root organization
Ids in this hierarchy. |
OrganizationList |
getRootOrganizations()
Gets the root organizations in this organization hierarchy.
|
boolean |
hasChildOrganizations(Id organizationId)
Tests if an organization has any children.
|
boolean |
hasParentOrganizations(Id organizationId)
Tests if the
Organization has any parents. |
boolean |
isAncestorOfOrganization(Id id,
Id organizationId)
Tests if an
Id is an ancestor of an organization. |
boolean |
isChildOfOrganization(Id id,
Id organizationId)
Tests if an organization is a direct child of another.
|
boolean |
isDescendantOfOrganization(Id id,
Id organizationId)
Tests if an
Id is a descendant of an organization. |
boolean |
isParentOfOrganization(Id id,
Id organizationId)
Tests if an
Id is a direct parent of an organization. |
void |
useComparativeOrganizationView()
The returns from the organization methods may omit or translate
elements based on this session, such as authorization, and not result
in an error.
|
void |
usePlenaryOrganizationView()
A complete view of the
Hierarchy returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getOrganizationHierarchyId()
Id
associated with this session. Id
associated with this sessionmandatory
- This method must be implemented. Hierarchy getOrganizationHierarchy() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canAccessOrganizationHierarchy()
PERMISSION_DENIED.
This is intended as a hint to an
application that may opt not to offer traversal operations. false
if hierarchy traversal methods are not
authorized, true
otherwisemandatory
- This method must be implemented. void useComparativeOrganizationView()
mandatory
- This method is must be implemented. void usePlenaryOrganizationView()
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 getRootOrganizationIds() throws OperationFailedException, PermissionDeniedException
Ids
in this hierarchy. Ids
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. OrganizationList getRootOrganizations() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method is must be implemented. boolean hasParentOrganizations(Id organizationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Organization
has any parents.organizationId
- the Id
of an organization true
if the organization has parents,
false
otherwiseNotFoundException
- organizationId
is
not foundNullArgumentException
- organizationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isParentOfOrganization(Id id, Id organizationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a direct parent of an organization.id
- an Id
organizationId
- the Id
of an organization true
if this id
is a parent of
organizationId,
false
otherwiseNotFoundException
- organizationId
is
not foundNullArgumentException
- id
or
organizationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getParentOrganizationIds(Id organizationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
organizationId
- the Id
of an organization Ids
of the organizationNotFoundException
- organizationId
is
not foundNullArgumentException
- organizationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. OrganizationList getParentOrganizations(Id organizationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
organizationId
- the Id
of an organizationNotFoundException
- organizationId
is
not foundNullArgumentException
- organizationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isAncestorOfOrganization(Id id, Id organizationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is an ancestor of an organization.id
- an Id
organizationId
- the Id
of an organization true
if this id
is an ancestor
of organizationId,
false
otherwiseNotFoundException
- organizationId
is
not foundNullArgumentException
- id
or
organizationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
boolean hasChildOrganizations(Id organizationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
organizationId
- the Id
of an organization true
if the organizationId
has
children, false
otherwiseNotFoundException
- organizationId
is
not foundNullArgumentException
- organizationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isChildOfOrganization(Id id, Id organizationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id
- an Id
organizationId
- the Id
of an organization true
if the id
is a child of
organizationId,
false
otherwiseNotFoundException
- organizationId
is
not foundNullArgumentException
- id
or
organizationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getChildOrganizationIds(Id organizationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given organization.organizationId
- the Id
to queryNotFoundException
- organizationId
is
not foundNullArgumentException
- organizationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. OrganizationList getChildOrganizations(Id organizationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
organizationId
- the Id
to queryNotFoundException
- organizationId
is
not foundNullArgumentException
- organizationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isDescendantOfOrganization(Id id, Id organizationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a descendant of an organization.id
- an Id
organizationId
- the Id
of an organization true
if the id
is a descendant
of the organizationId,
false
otherwiseNotFoundException
- organizationId
is
not foundNullArgumentException
- id
or
organizationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
is not found return false.
Node getOrganizationNodeIds(Id organizationId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
organizationId
- 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
- organizationId
is
not foundNullArgumentException
- organizationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. OrganizationNode getOrganizationNodes(Id organizationId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
organizationId
- 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
- organizationId
is
not foundNullArgumentException
- organizationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.