org.osid.ordering

Interface StoreHierarchySession

All Superinterfaces:

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

public interface StoreHierarchySession
extends OsidSession

This session defines methods for traversing a hierarchy of Store objects. Each node in the hierarchy is a unique Store. The hierarchy may be traversed recursively to establish the tree structure through getParentStores() and getChildStores(). To relate these Ids to another OSID, getStoreNodes() can be used for retrievals that can be used for bulk lookups in other OSIDs. Any Store available in the Order 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 getParentStores() or getChildStores() 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: store 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	canAccessStoreHierarchy() Tests if this user can perform hierarchy queries.
IdList	getChildStoreIds(Id storeId) Gets the child Ids of the given store.
StoreList	getChildStores(Id storeId) Gets the child stores of the given id.
IdList	getParentStoreIds(Id storeId) Gets the parent Ids of the given store.
StoreList	getParentStores(Id storeId) Gets the parent stores of the given id.
IdList	getRootStoreIds() Gets the root store Ids in this hierarchy.
StoreList	getRootStores() Gets the root stores in the store hierarchy.
Hierarchy	getStoreHierarchy() Gets the hierarchy associated with this session.
Id	getStoreHierarchyId() Gets the hierarchy Id associated with this session.
Node	getStoreNodeIds(Id storeId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given store.
StoreNode	getStoreNodes(Id storeId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given store.
boolean	hasChildStores(Id storeId) Tests if a store has any children.
boolean	hasParentStores(Id storeId) Tests if the Store has any parents.
boolean	isAncestorOfStore(Id id, Id storeId) Tests if an Id is an ancestor of a store.
boolean	isChildOfStore(Id id, Id storeId) Tests if a store is a direct child of another.
boolean	isDescendantOfStore(Id id, Id storeId) Tests if an Id is a descendant of a store.
boolean	isParentOfStore(Id id, Id storeId) Tests if an Id is a direct parent of store.
void	useComparativeStoreView() The returns from the store methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	usePlenaryStoreView() A complete view of the Store 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

getStoreHierarchyId

Id getStoreHierarchyId()

Gets the hierarchy Id associated with this session.

Returns:

the hierarchy Id associated with this session

Compliance:

mandatory - This method must be implemented.

getStoreHierarchy

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

canAccessStoreHierarchy

boolean canAccessStoreHierarchy()

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.

useComparativeStoreView

void useComparativeStoreView()

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

usePlenaryStoreView

void usePlenaryStoreView()

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

getRootStoreIds

IdList getRootStoreIds()
                       throws OperationFailedException,
                              PermissionDeniedException

Gets the root store Ids in this hierarchy.

Returns:

the root store Ids

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRootStores

StoreList getRootStores()
                        throws OperationFailedException,
                               PermissionDeniedException

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

Returns:

the root stores

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

hasParentStores

boolean hasParentStores(Id storeId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Tests if the Store has any parents.

Parameters:

storeId - a store Id

Returns:

true if the store has parents, f alse otherwise

Throws:

NotFoundException - storeId is not found

NullArgumentException - storeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isParentOfStore

boolean isParentOfStore(Id id,
                      Id storeId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Tests if an Id is a direct parent of store.

Parameters:

id - an Id

storeId - the Id of a store

Returns:

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

Throws:

NotFoundException - storeId is not found

NullArgumentException - id or storeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getParentStoreIds

IdList getParentStoreIds(Id storeId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Gets the parent Ids of the given store.

Parameters:

storeId - a store Id

Returns:

the parent Ids of the store

Throws:

NotFoundException - storeId is not found

NullArgumentException - storeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getParentStores

StoreList getParentStores(Id storeId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Gets the parent stores of the given id.

Parameters:

storeId - the Id of the Store to query

Returns:

the parent stores of the id

Throws:

NotFoundException - a Store identified by Id is not found

NullArgumentException - storeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isAncestorOfStore

boolean isAncestorOfStore(Id id,
                        Id storeId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Tests if an Id is an ancestor of a store.

Parameters:

id - an Id

storeId - the Id of a store

Returns:

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

Throws:

NotFoundException - storeId is not found

NullArgumentException - id or storeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

hasChildStores

boolean hasChildStores(Id storeId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Tests if a store has any children.

Parameters:

storeId - a store Id

Returns:

true if the storeId has children, false otherwise

Throws:

NotFoundException - storeId is not found

NullArgumentException - storeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isChildOfStore

boolean isChildOfStore(Id id,
                     Id storeId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Tests if a store is a direct child of another.

Parameters:

id - an Id

storeId - the Id of a store

Returns:

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

Throws:

NotFoundException - storeId is not found

NullArgumentException - id or storeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getChildStoreIds

IdList getChildStoreIds(Id storeId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Gets the child Ids of the given store.

Parameters:

storeId - the Id to query

Returns:

the children of the store

Throws:

NotFoundException - storeId is not found

NullArgumentException - storeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getChildStores

StoreList getChildStores(Id storeId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Gets the child stores of the given id.

Parameters:

storeId - the Id of the Store to query

Returns:

the child stores of the id

Throws:

NotFoundException - a Store identified by Id is not found

NullArgumentException - storeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isDescendantOfStore

boolean isDescendantOfStore(Id id,
                          Id storeId)
                            throws NotFoundException,
                                   OperationFailedException,
                                   PermissionDeniedException

Tests if an Id is a descendant of a store.

Parameters:

id - an Id

storeId - the Id of a store

Returns:

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

Throws:

NotFoundException - storeId is not found

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

getStoreNodeIds

Node getStoreNodeIds(Id storeId,
                   long ancestorLevels,
                   long descendantLevels,
                   boolean includeSiblings)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Gets a portion of the hierarchy for the given store.

Parameters:

storeId - 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 store node

Throws:

NotFoundException - storeId is not found

NullArgumentException - storeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getStoreNodes

StoreNode getStoreNodes(Id storeId,
                      long ancestorLevels,
                      long descendantLevels,
                      boolean includeSiblings)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Gets a portion of the hierarchy for the given store.

Parameters:

storeId - 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 store node

Throws:

NotFoundException - storeId is not found

NullArgumentException - storeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.