org.osid.personnel

Interface RealmHierarchySession

All Superinterfaces:

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

public interface RealmHierarchySession
extends OsidSession

This session defines methods for traversing a hierarchy of Realm objects. Each node in the hierarchy is a unique Realm. The hierarchy may be traversed recursively to establish the tree structure through getParentRealms() and getChildRealms(). To relate these Ids to another OSID, getRealmNodes() can be used for retrievals that can be used for bulk lookups in other OSIDs. Any Realm available in the Personnel 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 getParentRealms() or getChildRealms() 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: realm 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	canAccessRealmHierarchy() Tests if this user can perform hierarchy queries.
IdList	getChildRealmIds(Id realmId) Gets the child Ids of the given realm.
RealmList	getChildRealms(Id realmId) Gets the child realms of the given id.
IdList	getParentRealmIds(Id realmId) Gets the parent Ids of the given realm.
RealmList	getParentRealms(Id realmId) Gets the parent realms of the given id.
Hierarchy	getRealmHierarchy() Gets the hierarchy associated with this session.
Id	getRealmHierarchyId() Gets the hierarchy Id associated with this session.
Node	getRealmNodeIds(Id realmId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given realm.
RealmNode	getRealmNodes(Id realmId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given realm.
IdList	getRootRealmIds() Gets the root realm Ids in this hierarchy.
RealmList	getRootRealms() Gets the root realms in the realm hierarchy.
boolean	hasChildRealms(Id realmId) Tests if a realm has any children.
boolean	hasParentRealms(Id realmId) Tests if the Realm has any parents.
boolean	isAncestorOfRealm(Id id, Id realmId) Tests if an Id is an ancestor of a realm.
boolean	isChildOfRealm(Id id, Id realmId) Tests if a realm is a direct child of another.
boolean	isDescendantOfRealm(Id id, Id realmId) Tests if an Id is a descendant of a realm.
boolean	isParentOfRealm(Id id, Id realmId) Tests if an Id is a direct parent of realm.
void	useComparativeRealmView() The returns from the realm methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	usePlenaryRealmView() A complete view of the Realm 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

getRealmHierarchyId

Id getRealmHierarchyId()

Gets the hierarchy Id associated with this session.

Returns:

the hierarchy Id associated with this session

Compliance:

mandatory - This method must be implemented.

getRealmHierarchy

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

canAccessRealmHierarchy

boolean canAccessRealmHierarchy()

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.

useComparativeRealmView

void useComparativeRealmView()

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

usePlenaryRealmView

void usePlenaryRealmView()

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

getRootRealmIds

IdList getRootRealmIds()
                       throws OperationFailedException,
                              PermissionDeniedException

Gets the root realm Ids in this hierarchy.

Returns:

the root realm Ids

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRootRealms

RealmList getRootRealms()
                        throws OperationFailedException,
                               PermissionDeniedException

Gets the root realms in the realm hierarchy. A node with no parents is an orphan. While all realm 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 realms

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

hasParentRealms

boolean hasParentRealms(Id realmId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Tests if the Realm has any parents.

Parameters:

realmId - a realm Id

Returns:

true if the realm has parents, f alse otherwise

Throws:

NotFoundException - realmId is not found

NullArgumentException - realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isParentOfRealm

boolean isParentOfRealm(Id id,
                      Id realmId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Tests if an Id is a direct parent of realm.

Parameters:

id - an Id

realmId - the Id of a realm

Returns:

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

Throws:

NotFoundException - realmId is not found

NullArgumentException - id or realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getParentRealmIds

IdList getParentRealmIds(Id realmId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Gets the parent Ids of the given realm.

Parameters:

realmId - a realm Id

Returns:

the parent Ids of the realm

Throws:

NotFoundException - realmId is not found

NullArgumentException - realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getParentRealms

RealmList getParentRealms(Id realmId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Gets the parent realms of the given id.

Parameters:

realmId - the Id of the Realm to query

Returns:

the parent realms of the id

Throws:

NotFoundException - a Realm identified by Id is not found

NullArgumentException - realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isAncestorOfRealm

boolean isAncestorOfRealm(Id id,
                        Id realmId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Tests if an Id is an ancestor of a realm.

Parameters:

id - an Id

realmId - the Id of a realm

Returns:

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

Throws:

NotFoundException - realmId is not found

NullArgumentException - id or realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

hasChildRealms

boolean hasChildRealms(Id realmId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Tests if a realm has any children.

Parameters:

realmId - a realm Id

Returns:

true if the realmId has children, false otherwise

Throws:

NotFoundException - realmId is not found

NullArgumentException - borealmId is null okId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isChildOfRealm

boolean isChildOfRealm(Id id,
                     Id realmId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Tests if a realm is a direct child of another.

Parameters:

id - an Id

realmId - the Id of a realm

Returns:

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

Throws:

NotFoundException - realmId is not found

NullArgumentException - id or realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getChildRealmIds

IdList getChildRealmIds(Id realmId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Gets the child Ids of the given realm.

Parameters:

realmId - the Id to query

Returns:

the children of the realm

Throws:

NotFoundException - realmId is not found

NullArgumentException - realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getChildRealms

RealmList getChildRealms(Id realmId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Gets the child realms of the given id.

Parameters:

realmId - the Id of the Realm to query

Returns:

the child realms of the id

Throws:

NotFoundException - a Realm identified by Id is not found

NullArgumentException - realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isDescendantOfRealm

boolean isDescendantOfRealm(Id id,
                          Id realmId)
                            throws NotFoundException,
                                   OperationFailedException,
                                   PermissionDeniedException

Tests if an Id is a descendant of a realm.

Parameters:

id - an Id

realmId - the Id of a realm

Returns:

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

Throws:

NotFoundException - realmId is not found

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

getRealmNodeIds

Node getRealmNodeIds(Id realmId,
                   long ancestorLevels,
                   long descendantLevels,
                   boolean includeSiblings)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Gets a portion of the hierarchy for the given realm.

Parameters:

realmId - 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 realm node

Throws:

NotFoundException - realmId is not found

NullArgumentException - realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRealmNodes

RealmNode getRealmNodes(Id realmId,
                      long ancestorLevels,
                      long descendantLevels,
                      boolean includeSiblings)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Gets a portion of the hierarchy for the given realm.

Parameters:

realmId - 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 realm node

Throws:

NotFoundException - realmId is not found

NullArgumentException - realmId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.