OSID Logo
OSID Specifications
personnel package
Version 3.0.0
Release Candidate Preview
Interfaceosid.personnel.RealmHierarchySession
Implementsosid.OsidSession
Description

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
MethodgetRealmHierarchyId
Description

Gets the hierarchy Id associated with this session.

Returnosid.id.Idthe hierarchy Id associated with this session
CompliancemandatoryThis method must be implemented.
MethodgetRealmHierarchy
Description

Gets the hierarchy associated with this session.

Returnosid.hierarchy.Hierarchythe hierarchy associated with this session
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodcanAccessRealmHierarchy
Description

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.

Returnboolean false if hierarchy traversal methods are not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethoduseComparativeRealmView
Description

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.

CompliancemandatoryThis method is must be implemented.
MethodusePlenaryRealmView
Description

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.

CompliancemandatoryThis method is must be implemented.
MethodgetRootRealmIds
Description

Gets the root realm Ids in this hierarchy.

Returnosid.id.IdListthe root realm Ids
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRootRealms
Description

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.

Returnosid.personnel.RealmListthe root realms
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method is must be implemented.
MethodhasParentRealms
Description

Tests if the Realm has any parents.

Parametersosid.id.IdrealmIda realm Id
Returnboolean true if the realm has parents, f alse otherwise
ErrorsNOT_FOUND realmId is not found
NULL_ARGUMENT realmId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodisParentOfRealm
Description

Tests if an Id is a direct parent of realm.

Parametersosid.id.Ididan Id
osid.id.IdrealmIdthe Id of a realm
Returnboolean true if this id is a parent of realmId, f alse otherwise
ErrorsNOT_FOUND realmId is not found
NULL_ARGUMENT id or realmId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
Provider Notes

If id not found return false.

MethodgetParentRealmIds
Description

Gets the parent Ids of the given realm.

Parametersosid.id.IdrealmIda realm Id
Returnosid.id.IdListthe parent Ids of the realm
ErrorsNOT_FOUND realmId is not found
NULL_ARGUMENT realmId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetParentRealms
Description

Gets the parent realms of the given id.

Parametersosid.id.IdrealmIdthe Id of the Realm to query
Returnosid.personnel.RealmListthe parent realms of the id
ErrorsNOT_FOUNDa Realm identified by Id is not found
NULL_ARGUMENT realmId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodisAncestorOfRealm
Description

Tests if an Id is an ancestor of a realm.

Parametersosid.id.Ididan Id
osid.id.IdrealmIdthe Id of a realm
Returnboolean tru e if this id is an ancestor of realmId, false otherwise
ErrorsNOT_FOUND realmId is not found
NULL_ARGUMENT id or realmId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
Provider Notes

If id not found return false.

MethodhasChildRealms
Description

Tests if a realm has any children.

Parametersosid.id.IdrealmIda realm Id
Returnboolean true if the realmId has children, false otherwise
ErrorsNOT_FOUND realmId is not found
NULL_ARGUMENT borealmId is null okId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodisChildOfRealm
Description

Tests if a realm is a direct child of another.

Parametersosid.id.Ididan Id
osid.id.IdrealmIdthe Id of a realm
Returnboolean true if the id is a child of realmId, false otherwise
ErrorsNOT_FOUND realmId is not found
NULL_ARGUMENT id or realmId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
Provider Notes

If id not found return false.

MethodgetChildRealmIds
Description

Gets the child Ids of the given realm.

Parametersosid.id.IdrealmIdthe Id to query
Returnosid.id.IdListthe children of the realm
ErrorsNOT_FOUND realmId is not found
NULL_ARGUMENT realmId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetChildRealms
Description

Gets the child realms of the given id.

Parametersosid.id.IdrealmIdthe Id of the Realm to query
Returnosid.personnel.RealmListthe child realms of the id
ErrorsNOT_FOUNDa Realm identified by Id is not found
NULL_ARGUMENT realmId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodisDescendantOfRealm
Description

Tests if an Id is a descendant of a realm.

Parametersosid.id.Ididan Id
osid.id.IdrealmIdthe Id of a realm
Returnboolean true if the id is a descendant of the realmId, false otherwise
ErrorsNOT_FOUND realmId is not found
NULL_ARGUMENT id or realmId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
Provider Notes

If id is not found return false.

MethodgetRealmNodeIds
Description

Gets a portion of the hierarchy for the given realm.

Parametersosid.id.IdrealmIdthe Id to query
cardinalancestorLevelsthe maximum number of ancestor levels to include. A value of 0 returns no parents in the node.
cardinaldescendantLevelsthe maximum number of descendant levels to include. A value of 0 returns no children in the node.
booleanincludeSiblings true to include the siblings of the given node, false to omit the siblings
Returnosid.hierarchy.Nodea realm node
ErrorsNOT_FOUND realmId is not found
NULL_ARGUMENT realmId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRealmNodes
Description

Gets a portion of the hierarchy for the given realm.

Parametersosid.id.IdrealmIdthe Id to query
cardinalancestorLevelsthe maximum number of ancestor levels to include. A value of 0 returns no parents in the node.
cardinaldescendantLevelsthe maximum number of descendant levels to include. A value of 0 returns no children in the node.
booleanincludeSiblings true to include the siblings of the given node, false to omit the siblings
Returnosid.personnel.RealmNodea realm node
ErrorsNOT_FOUND realmId is not found
NULL_ARGUMENT realmId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.