OSID Logo
OSID Specifications
control package
Version 3.0.0
Release Candidate Preview
Interfaceosid.control.SystemHierarchySession
Implementsosid.OsidSession
Description

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

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

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

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

Gets the hierarchy Id associated with this session.

Returnosid.id.Idthe hierarchy Id associated with this session
CompliancemandatoryThis method must be implemented.
MethodgetSystemHierarchy
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.
MethodcanAccessSystemHierarchy
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.
MethoduseComparativeSystemView
Description

The returns from the system 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.
MethodusePlenarySystemView
Description

A complete view of the Systems 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.
MethodgetRootSystemIds
Description

Gets the root system Ids in this hierarchy.

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

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

Returnosid.control.SystemListthe root systems
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method is must be implemented.
MethodhasParentSystems
Description

Tests if the System has any parents.

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

Tests if an Id is a direct parent of system.

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

If id not found return false.

MethodgetParentSystemIds
Description

Gets the parent Ids of the given system.

Parametersosid.id.IdsystemIda system Id
Returnosid.id.IdListthe parent Ids of the system
ErrorsNOT_FOUND systemId is not found
NULL_ARGUMENT systemId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetParentSystems
Description

Gets the parents of the given system.

Parametersosid.id.IdsystemIdthe Id to query
Returnosid.control.SystemListthe parents of the system
ErrorsNOT_FOUND systemId not found
NULL_ARGUMENT systemId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodisAncestorOfSystem
Description

Tests if an Id is an ancestor of a system.

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

If id not found return false.

MethodhasChildSystems
Description

Tests if a system has any children.

Parametersosid.id.IdsystemIda system Id
Returnboolean true if the systemId has children, false otherwise
ErrorsNOT_FOUND systemId not found
NULL_ARGUMENT systemId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodisChildOfSystem
Description

Tests if a system is a direct child of another.

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

If id not found return false.

MethodgetChildSystemIds
Description

Gets the child Ids of the given system.

Parametersosid.id.IdsystemIdthe Id to query
Returnosid.id.IdListthe children of the system
ErrorsNOT_FOUND systemId not found
NULL_ARGUMENT systemId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetChildSystems
Description

Gets the children of the given system.

Parametersosid.id.IdsystemIdthe Id to query
Returnosid.control.SystemListthe children of the system
ErrorsNOT_FOUND systemId not found
NULL_ARGUMENT systemId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodisDescendantOfSystem
Description

Tests if an Id is a descendant of a system.

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

If id is not found return false.

MethodgetSystemNodeIds
Description

Gets a portion of the hierarchy for the given system.

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

Gets a portion of the hierarchy for the given system.

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