org.osid.authentication

Interface AgencyHierarchySession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

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.

• comparative view: agency elements may be silently omitted or re-ordered
• plenary view: provides a complete set or is an error condition

Method Summary

Methods

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.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

getAgencyHierarchyId

Id getAgencyHierarchyId()

Gets the hierarchy Id associated with this session.

Returns:

the hierarchy Id associated with this session

Compliance:

mandatory - This method must be implemented.

getAgencyHierarchy

Hierarchy getAgencyHierarchy()
                             throws OperationFailedException,
                                    PermissionDeniedException

Gets the hierarchy associated with this session.

Returns:

the hierarchy associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canAccessAgencyHierarchy

boolean canAccessAgencyHierarchy()

Tests if this user can perform hierarchy queries. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer lookup operations.

Returns:

false if hierarchy traversal methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeAgencyView

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. This view is used when greater interoperability is desired at the expense of precision.

Compliance:

mandatory - This method is must be implemented.

usePlenaryAgencyView

void usePlenaryAgencyView()

A complete view of the 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.

Compliance:

mandatory - This method is must be implemented.

getRootAgencyIds

IdList getRootAgencyIds()
                        throws OperationFailedException,
                               PermissionDeniedException

Gets the root agency Ids in this hierarchy.

Returns:

the root agency Ids

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRootAgencies

AgencyList getRootAgencies()
                           throws OperationFailedException,
                                  PermissionDeniedException

Gets the root agencies in this agency hierarchy.

Returns:

the root agencies

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

hasParentAgencies

boolean hasParentAgencies(Id agencyId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Tests if the Agency has any parents.

Parameters:

agencyId - an agency Id

Returns:

true if the agency has parents, false otherwise

Throws:

NotFoundException - agencyId is not found

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isParentOfAgency

boolean isParentOfAgency(Id id,
                       Id agencyId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Tests if an Id is a direct parent of an agency.

Parameters:

id - an Id

agencyId - the Id of an agency

Returns:

true if this id is a parent of agencyId, false otherwise

Throws:

NotFoundException - agencyId is not found

NullArgumentException - id or agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getParentAgencyIds

IdList getParentAgencyIds(Id agencyId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Gets the parent Ids of the given agency.

Parameters:

agencyId - an agency Id

Returns:

the parent Ids of the agency

Throws:

NotFoundException - agencyId is not found

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getParentAgencies

AgencyList getParentAgencies(Id agencyId)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Gets the parents of the given agency.

Parameters:

agencyId - an agency Id

Returns:

the parents of the agency

Throws:

NotFoundException - agencyId is not found

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isAncestorOfAgency

boolean isAncestorOfAgency(Id id,
                         Id agencyId)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Tests if an Id is an ancestor of an agency.

Parameters:

id - an Id

agencyId - the Id of an agency

Returns:

true if this id is an ancestor of agencyId, false otherwise

Throws:

NotFoundException - agencyId is not found

NullArgumentException - agencyId or id is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

hasChildAgencies

boolean hasChildAgencies(Id agencyId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Tests if an agency has any children.

Parameters:

agencyId - an agencyId

Returns:

true if the agencyId has children, false otherwise

Throws:

NotFoundException - agencyId is not found

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isChildOfAgency

boolean isChildOfAgency(Id id,
                      Id agencyId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Tests if a node is a direct child of another.

Parameters:

id - an Id

agencyId - the Id of an agency

Returns:

true if the id is a child of agencyId, false otherwise

Throws:

NotFoundException - agencyId is not found

NullArgumentException - agencyId or id is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getChildAgencyIds

IdList getChildAgencyIds(Id agencyId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Gets the child Ids of the given agency.

Parameters:

agencyId - the Id to query

Returns:

the children of the agency

Throws:

NotFoundException - agencyId is not found

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getChildAgencies

AgencyList getChildAgencies(Id agencyId)
                            throws NotFoundException,
                                   OperationFailedException,
                                   PermissionDeniedException

Gets the children of the given agency.

Parameters:

agencyId - the Id to query

Returns:

the children of the agency

Throws:

NotFoundException - agencyId is not found

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isDescendantOfAgency

boolean isDescendantOfAgency(Id id,
                           Id agencyId)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Tests if an Id is a descendant of an agency.

Parameters:

id - an Id

agencyId - the Id of an agency

Returns:

true if the id is a descendant of the agencyId, false otherwise

Throws:

NotFoundException - agencyId is not found

NullArgumentException - agencyId or id is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id is not found return false.

getAgencyNodeIds

Node getAgencyNodeIds(Id agencyId,
                    long ancestorLevels,
                    long descendantLevels,
                    boolean includeSiblings)
                      throws NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

Gets a portion of the hierarchy for the given agency.

Parameters:

agencyId - the Id to query

ancestorLevels - 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 siblings

Returns:

an agency node

Throws:

NotFoundException - agencyId is not found

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getAgencyNodes

AgencyNode getAgencyNodes(Id agencyId,
                        long ancestorLevels,
                        long descendantLevels,
                        boolean includeSiblings)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Gets a portion of the hierarchy for the given agency.

Parameters:

agencyId - the Id to query

ancestorLevels - 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 siblings

Returns:

an agency node

Throws:

NotFoundException - agencyId is not found

NullArgumentException - agencyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.