org.osid.resource

Interface GroupHierarchySession

All Superinterfaces:

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

public interface GroupHierarchySession
extends OsidSession

This session provides a hierarchical view of resource groups. Each node in the hierarchy is a unique Resource. The hierarchy may be traversed recursively to establish the tree structure through getParentResources() and getChildResources(). To relate these Ids to another OSID, getResourceNodes() can be used for retrievals that can be used for bulk lookups in other OSIDs.

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 getParentResources() or getChildResources() 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: resource 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	canAccessGroupHierarchy() Tests if this user can perform hierarchy queries.
Bin	getBin() Gets the Bin associated with this session.
Id	getBinId() Gets the Bin Id associated with this session.
Node	getResourceNodeIds(Id resourceId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given resource group.
BillingNode	getResourceNodes(Id resourceId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given resource group.
boolean	isMemberOfGroup(Id groupId, Id resourceId) Tests if a resource Id is a member of a group either directly or indirectly through nested groups.
void	useComparativeResourceView() The returns from the group methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	useFederatedBinView() Federates the view for methods in this session.
void	useIsolatedBinView() Isolates the view for methods in this session.
void	usePlenaryResourceView() A complete view of the Resource 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

getBinId

Id getBinId()

Gets the Bin Id associated with this session.

Returns:

the Bin Id associated with this session

Compliance:

mandatory - This method must be implemented.

getBin

Bin getBin()
           throws OperationFailedException,
                  PermissionDeniedException

Gets the Bin associated with this session.

Returns:

the Bin associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canAccessGroupHierarchy

boolean canAccessGroupHierarchy()

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.

useComparativeResourceView

void useComparativeResourceView()

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

usePlenaryResourceView

void usePlenaryResourceView()

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

useFederatedBinView

void useFederatedBinView()

Federates the view for methods in this session. A federated view will include resources in bins which are children of this bin in the bin hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedBinView

void useIsolatedBinView()

Isolates the view for methods in this session. An isolated view restricts lookups to this bin only.

Compliance:

mandatory - This method is must be implemented.

isMemberOfGroup

boolean isMemberOfGroup(Id groupId,
                      Id resourceId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Tests if a resource Id is a member of a group either directly or indirectly through nested groups.

Parameters:

groupId - a resource group Id

resourceId - the Id of a resource

Returns:

true if this resourceId is a member of groupId, f alse otherwise

Throws:

NotFoundException - groupId is not found

NullArgumentException - groupId or resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - resourceId not found return false.

getResourceNodeIds

Node getResourceNodeIds(Id resourceId,
                      long ancestorLevels,
                      long descendantLevels,
                      boolean includeSiblings)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Gets a portion of the hierarchy for the given resource group.

Parameters:

resourceId - 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:

a resource node

Throws:

NotFoundException - resourceId is not found

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getResourceNodes

BillingNode getResourceNodes(Id resourceId,
                           long ancestorLevels,
                           long descendantLevels,
                           boolean includeSiblings)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Gets a portion of the hierarchy for the given resource group.

Parameters:

resourceId - 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:

a resource node

Throws:

NotFoundException - resourceId is not found

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.