org.osid.provisioning

Interface DistributorHierarchySession

All Superinterfaces:

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

public interface DistributorHierarchySession
extends OsidSession

This session defines methods for traversing a hierarchy of Distributor objects. Each node in the hierarchy is a unique Distributor. The hierarchy may be traversed recursively to establish the tree structure through getParentDistributors() and getChildDistributors(). To relate these Ids to another OSID, getDistributorNodes() can be used for retrievals that can be used for bulk lookups in other OSIDs. Any Distributor available in the Provisioning OSID is known to this hierarchy but does not appear in the hierarchy traversal until added as a root distributor or a child of another distributor.

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 getParentDistributors() or getChildDistributors() in lieu of a PERMISSION_DENIED error that may disrupt the traversal through authorized provisionways.

This session defines views that offer differing behaviors when retrieving multiple objects.

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

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canAccessDistributorHierarchy() Tests if this user can perform hierarchy queries.
IdList	getChildDistributorIds(Id distributorId) Gets the child Ids of the given distributor.
DistributorList	getChildDistributors(Id distributorId) Gets the children of the given distributor.
Hierarchy	getDistributorHierarchy() Gets the hierarchy associated with this session.
Id	getDistributorHierarchyId() Gets the hierarchy Id associated with this session.
Node	getDistributorNodeIds(Id distributorId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given distributor.
DistributorNode	getDistributorNodes(Id distributorId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given distributor.
IdList	getParentDistributorIds(Id distributorId) Gets the parent Ids of the given distributor.
DistributorList	getParentDistributors(Id distributorId) Gets the parents of the given distributor.
IdList	getRootDistributorIds() Gets the root distributor Ids in this hierarchy.
DistributorList	getRootDistributors() Gets the root distributor in the distributor hierarchy.
boolean	hasChildDistributors(Id distributorId) Tests if a distributor has any children.
boolean	hasParentDistributors(Id distributorId) Tests if the Distributor has any parents.
boolean	isAncestorOfDistributor(Id id, Id distributorId) Tests if an Id is an ancestor of a distributor.
boolean	isChildOfDistributor(Id id, Id distributorId) Tests if a distributor is a direct child of another.
boolean	isDescendantOfDistributor(Id id, Id distributorId) Tests if an Id is a descendant of a distributor.
boolean	isParentOfDistributor(Id id, Id distributorId) Tests if an Id is a direct parent of distributor.
void	useComparativeDistributorView() The returns from the distributor methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	usePlenaryDistributorView() A complete view of the Distributors 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

getDistributorHierarchyId

Id getDistributorHierarchyId()

Gets the hierarchy Id associated with this session.

Returns:

the hierarchy Id associated with this session

Compliance:

mandatory - This method must be implemented.

getDistributorHierarchy

Hierarchy getDistributorHierarchy()
                                  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.

canAccessDistributorHierarchy

boolean canAccessDistributorHierarchy()

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.

useComparativeDistributorView

void useComparativeDistributorView()

The returns from the distributor 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.

usePlenaryDistributorView

void usePlenaryDistributorView()

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

getRootDistributorIds

IdList getRootDistributorIds()
                             throws OperationFailedException,
                                    PermissionDeniedException

Gets the root distributor Ids in this hierarchy.

Returns:

the root distributor Ids

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRootDistributors

DistributorList getRootDistributors()
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets the root distributor in the distributor hierarchy. A distributor with no parents is an orphan. While all distributor Ids are known to the hierarchy, an orphan does not appear in the hierarchy unless explicitly added as a root distributor or child of another distributor.

Returns:

the root distributors

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

hasParentDistributors

boolean hasParentDistributors(Id distributorId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Tests if the Distributor has any parents.

Parameters:

distributorId - a distributor Id

Returns:

true if the distributor has parents, f alse otherwise

Throws:

NotFoundException - distributorId is not found

NullArgumentException - distributorId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isParentOfDistributor

boolean isParentOfDistributor(Id id,
                            Id distributorId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Tests if an Id is a direct parent of distributor.

Parameters:

id - an Id

distributorId - the Id of a distributor

Returns:

true if this id is a parent of distributorId, f alse otherwise

Throws:

NotFoundException - distributorId is not found

NullArgumentException - id or distributorId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getParentDistributorIds

IdList getParentDistributorIds(Id distributorId)
                               throws NotFoundException,
                                      OperationFailedException,
                                      PermissionDeniedException

Gets the parent Ids of the given distributor.

Parameters:

distributorId - a distributor Id

Returns:

the parent Ids of the distributor

Throws:

NotFoundException - distributorId is not found

NullArgumentException - distributorId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getParentDistributors

DistributorList getParentDistributors(Id distributorId)
                                      throws NotFoundException,
                                             OperationFailedException,
                                             PermissionDeniedException

Gets the parents of the given distributor.

Parameters:

distributorId - the Id to query

Returns:

the parents of the distributor

Throws:

NotFoundException - distributorId not found

NullArgumentException - distributorId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isAncestorOfDistributor

boolean isAncestorOfDistributor(Id id,
                              Id distributorId)
                                throws NotFoundException,
                                       OperationFailedException,
                                       PermissionDeniedException

Tests if an Id is an ancestor of a distributor.

Parameters:

id - an Id

distributorId - the Id of a distributor

Returns:

tru e if this id is an ancestor of distributorId, false otherwise

Throws:

NotFoundException - distributorId not found

NullArgumentException - distributorId 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.

hasChildDistributors

boolean hasChildDistributors(Id distributorId)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Tests if a distributor has any children.

Parameters:

distributorId - a distributor Id

Returns:

true if the distributorId has children, false otherwise

Throws:

NotFoundException - distributorId not found

NullArgumentException - distributorId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isChildOfDistributor

boolean isChildOfDistributor(Id id,
                           Id distributorId)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Tests if a distributor is a direct child of another.

Parameters:

id - an Id

distributorId - the Id of a distributor

Returns:

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

Throws:

NotFoundException - distributorId not found

NullArgumentException - id or distributorId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getChildDistributorIds

IdList getChildDistributorIds(Id distributorId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Gets the child Ids of the given distributor.

Parameters:

distributorId - the Id to query

Returns:

the children of the distributor

Throws:

NotFoundException - distributorId not found

NullArgumentException - distributorId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getChildDistributors

DistributorList getChildDistributors(Id distributorId)
                                     throws NotFoundException,
                                            OperationFailedException,
                                            PermissionDeniedException

Gets the children of the given distributor.

Parameters:

distributorId - the Id to query

Returns:

the children of the distributor

Throws:

NotFoundException - distributorId not found

NullArgumentException - distributorId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isDescendantOfDistributor

boolean isDescendantOfDistributor(Id id,
                                Id distributorId)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

Tests if an Id is a descendant of a distributor.

Parameters:

id - an Id

distributorId - the Id of a distributor

Returns:

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

Throws:

NotFoundException - distributorId not found

NullArgumentException - id or distributorId 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.

getDistributorNodeIds

Node getDistributorNodeIds(Id distributorId,
                         long ancestorLevels,
                         long descendantLevels,
                         boolean includeSiblings)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Gets a portion of the hierarchy for the given distributor.

Parameters:

distributorId - the Id to query

ancestorLevels - the maximum number of ancestor levels to include. A value of 0 returns no parents in the distributor.

descendantLevels - the maximum number of descendant levels to include. A value of 0 returns no children in the distributor.

includeSiblings - true to include the siblings of the given distributor, false to omit the siblings

Returns:

a distributor node

Throws:

NotFoundException - distributorId not found

NullArgumentException - distributorId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getDistributorNodes

DistributorNode getDistributorNodes(Id distributorId,
                                  long ancestorLevels,
                                  long descendantLevels,
                                  boolean includeSiblings)
                                    throws NotFoundException,
                                           OperationFailedException,
                                           PermissionDeniedException

Gets a portion of the hierarchy for the given distributor.

Parameters:

distributorId - the Id to query

ancestorLevels - the maximum number of ancestor levels to include. A value of 0 returns no parents in the hierarchy.

descendantLevels - the maximum number of descendant levels to include. A value of 0 returns no children in the hierarchy.

includeSiblings - true to include the siblings of the given distributor, false to omit the siblings

Returns:

a distributor node

Throws:

NotFoundException - distributorId not found

NullArgumentException - distributorId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.