org.osid.resourcing

Interface FoundryHierarchySession

All Superinterfaces:

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

public interface FoundryHierarchySession
extends OsidSession

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

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

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

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

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canAccessFoundryHierarchy() Tests if this user can perform hierarchy queries.
FoundryList	getChildFoundries(Id foundryId) Gets the children of the given foundry.
IdList	getChildFoundryIds(Id foundryId) Gets the child Ids of the given foundry.
Hierarchy	getFoundryHierarchy() Gets the hierarchy associated with this session.
Id	getFoundryHierarchyId() Gets the hierarchy Id associated with this session.
Node	getFoundryNodeIds(Id foundryId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given foundry.
FoundryNode	getFoundryNodes(Id foundryId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given foundry.
FoundryList	getParentFoundries(Id foundryId) Gets the parents of the given foundry.
IdList	getParentFoundryIds(Id foundryId) Gets the parent Ids of the given foundry.
FoundryList	getRootFoundries() Gets the root foundry in the foundry hierarchy.
IdList	getRootFoundryIds() Gets the root foundry Ids in this hierarchy.
boolean	hasChildFoundries(Id foundryId) Tests if a foundry has any children.
boolean	hasParentFoundries(Id foundryId) Tests if the Foundry has any parents.
boolean	isAncestorOfFoundry(Id id, Id foundryId) Tests if an Id is an ancestor of a foundry.
boolean	isChildOfFoundry(Id id, Id foundryId) Tests if a foundry is a direct child of another.
boolean	isDescendantOfFoundry(Id id, Id foundryId) Tests if an Id is a descendant of a foundry.
boolean	isParentOfFoundry(Id id, Id foundryId) Tests if an Id is a direct parent of foundry.
void	useComparativeFoundryView() The returns from the foundry methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	usePlenaryFoundryView() A complete view of the Foundries 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

getFoundryHierarchyId

Id getFoundryHierarchyId()

Gets the hierarchy Id associated with this session.

Returns:

the hierarchy Id associated with this session

Compliance:

mandatory - This method must be implemented.

getFoundryHierarchy

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

canAccessFoundryHierarchy

boolean canAccessFoundryHierarchy()

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.

useComparativeFoundryView

void useComparativeFoundryView()

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

usePlenaryFoundryView

void usePlenaryFoundryView()

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

getRootFoundryIds

IdList getRootFoundryIds()
                         throws OperationFailedException,
                                PermissionDeniedException

Gets the root foundry Ids in this hierarchy.

Returns:

the root foundry Ids

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRootFoundries

FoundryList getRootFoundries()
                             throws OperationFailedException,
                                    PermissionDeniedException

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

Returns:

the root foundries

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

hasParentFoundries

boolean hasParentFoundries(Id foundryId)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Tests if the Foundry has any parents.

Parameters:

foundryId - a foundry Id

Returns:

true if the foundry has parents, f alse otherwise

Throws:

NotFoundException - foundryId is not found

NullArgumentException - foundryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isParentOfFoundry

boolean isParentOfFoundry(Id id,
                        Id foundryId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Tests if an Id is a direct parent of foundry.

Parameters:

id - an Id

foundryId - the Id of a foundry

Returns:

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

Throws:

NotFoundException - foundryId is not found

NullArgumentException - id or foundryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getParentFoundryIds

IdList getParentFoundryIds(Id foundryId)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Gets the parent Ids of the given foundry.

Parameters:

foundryId - a foundry Id

Returns:

the parent Ids of the foundry

Throws:

NotFoundException - foundryId is not found

NullArgumentException - foundryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getParentFoundries

FoundryList getParentFoundries(Id foundryId)
                               throws NotFoundException,
                                      OperationFailedException,
                                      PermissionDeniedException

Gets the parents of the given foundry.

Parameters:

foundryId - the Id to query

Returns:

the parents of the foundry

Throws:

NotFoundException - foundryId not found

NullArgumentException - foundryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isAncestorOfFoundry

boolean isAncestorOfFoundry(Id id,
                          Id foundryId)
                            throws NotFoundException,
                                   OperationFailedException,
                                   PermissionDeniedException

Tests if an Id is an ancestor of a foundry.

Parameters:

id - an Id

foundryId - the Id of a foundry

Returns:

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

Throws:

NotFoundException - foundryId not found

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

hasChildFoundries

boolean hasChildFoundries(Id foundryId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Tests if a foundry has any children.

Parameters:

foundryId - a foundry Id

Returns:

true if the foundryId has children, false otherwise

Throws:

NotFoundException - foundryId not found

NullArgumentException - foundryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isChildOfFoundry

boolean isChildOfFoundry(Id id,
                       Id foundryId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Tests if a foundry is a direct child of another.

Parameters:

id - an Id

foundryId - the Id of a foundry

Returns:

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

Throws:

NotFoundException - foundryId not found

NullArgumentException - id or foundryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getChildFoundryIds

IdList getChildFoundryIds(Id foundryId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Gets the child Ids of the given foundry.

Parameters:

foundryId - the Id to query

Returns:

the children of the foundry

Throws:

NotFoundException - foundryId not found

NullArgumentException - foundryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getChildFoundries

FoundryList getChildFoundries(Id foundryId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Gets the children of the given foundry.

Parameters:

foundryId - the Id to query

Returns:

the children of the foundry

Throws:

NotFoundException - foundryId not found

NullArgumentException - foundryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isDescendantOfFoundry

boolean isDescendantOfFoundry(Id id,
                            Id foundryId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Tests if an Id is a descendant of a foundry.

Parameters:

id - an Id

foundryId - the Id of a foundry

Returns:

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

Throws:

NotFoundException - foundryId not found

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

getFoundryNodeIds

Node getFoundryNodeIds(Id foundryId,
                     long ancestorLevels,
                     long descendantLevels,
                     boolean includeSiblings)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Gets a portion of the hierarchy for the given foundry.

Parameters:

foundryId - 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 hier.archy

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

Returns:

a foundry node

Throws:

NotFoundException - foundryId not found

NullArgumentException - foundryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getFoundryNodes

FoundryNode getFoundryNodes(Id foundryId,
                          long ancestorLevels,
                          long descendantLevels,
                          boolean includeSiblings)
                            throws NotFoundException,
                                   OperationFailedException,
                                   PermissionDeniedException

Gets a portion of the hierarchy for the given foundry.

Parameters:

foundryId - 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 foundry, false to omit the siblings

Returns:

a foundry node

Throws:

NotFoundException - foundryId not found

NullArgumentException - foundryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.