Interface DistributorHierarchySession

All Superinterfaces:

AutoCloseable, Closeable, OsidSession, 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

Modifier and Type	Method	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 Closeable

close

Methods inherited from interface OsidSession

close

Modifier and Type	Method	Description
void	close()	Close this session.

Methods inherited from interface OsidSession

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

Modifier and Type	Method	Description
Agent	getAuthenticatedAgent()	Gets the agent authenticated to this session.
Id	getAuthenticatedAgentId()	Gets the Id of the agent authenticated to this session.
BigDecimal	getClockRate()	Gets the rate of the service clock.
Date	getDate()	Gets the service date which may be the current date or the effective date in which this session exists.
Agent	getEffectiveAgent()	Gets the effective agent in use by this session.
Id	getEffectiveAgentId()	Gets the Id of the effective agent in use by this session.
Type	getFormatType()	Gets the DisplayText format Type preference in effect for this session.
Locale	getLocale()	Gets the locale indicating the localization preferences in effect for this session.
boolean	isAuthenticated()	Tests if an agent is authenticated to this session.
Transaction	startTransaction()	Starts a new transaction for this sesson.
boolean	supportsTransactions()	Tests for the availability of transactions.

Method Details

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 - {@code id} not found return {@code 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:

true 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 - {@code id} not found return {@code 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 - {@code id} not found return {@code 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 - {@code id} is not found return {@code 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.