OSID Logo
OSID Specifications
dictionary package
Version 3.0.0
Release Candidate Preview
Interfaceosid.dictionary.DictionaryHierarchySession
Implementsosid.OsidSession
Description

This session defines methods for traversing a hierarchy of Dictionary objects. Each node in the hierarchy is a unique Dictionary. The hierarchy may be traversed recursively to establish the tree structure through getParentDIctionaries() and getChildDictionaries(). To relate these Ids to another OSID, getDictionaryNodes() can be used for retrievals that can be used for bulk lookups in other OSIDs. Any Dictionary available in the Dictionary 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 getParentDictionaries() or getChildDictionaries() 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: dictionary elements may be silently omitted or re-ordered
  • plenary view: provides a complete set or is an error condition
MethodgetDictionaryHierarchyId
Description

Gets the hierarchy Id associated with this session.

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

The returns from the dictionary 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.
MethodusePlenaryDictionaryView
Description

A complete view of the Dictionary 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.
MethodgetRootDictionaryIds
Description

Gets the root dictionary Ids in this hierarchy.

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

Gets the root subjects in the dictionary hierarchy. A node with no parents is an orphan. While all dictionary 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.dictionary.DictionaryListthe root dictionaries
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method is must be implemented.
MethodhasParentDictionaries
Description

Tests if the Dictionary has any parents.

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

Tests if an Id is a direct parent of dictionary.

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

If id not found return false.

MethodgetParentDictionaryIds
Description

Gets the parent Ids of the given dictionary.

Parametersosid.id.IddictionaryIda dictionary Id
Returnosid.id.IdListthe parent Ids of the dictionary
ErrorsNOT_FOUND dictionaryId is not found
NULL_ARGUMENT dictionaryId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetParentDictionaries
Description

Gets the parent dictionaries of the given id.

Parametersosid.id.IddictionaryIdthe Id of the Dictionary to query
Returnosid.dictionary.DictionaryListthe parent dictionaries of the id
ErrorsNOT_FOUNDa Dictionary identified by Id is not found
NULL_ARGUMENT dictionaryId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodisAncestorOfDictionary
Description

Tests if an Id is an ancestor of a dictionary.

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

If id not found return false.

MethodhasChildDictionaries
Description

Tests if a dictionary has any children.

Parametersosid.id.IddictionaryIda dictionary Id
Returnboolean true if the dictionaryId has children, false otherwise
ErrorsNOT_FOUND dictionaryId is not found
NULL_ARGUMENT dictionaryId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodisChildOfDictionary
Description

Tests if a dictionary is a direct child of another.

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

If id not found return false.

MethodgetChildDictionaryIds
Description

Gets the child Ids of the given dictionary.

Parametersosid.id.IddictionaryIdthe Id to query
Returnosid.id.IdListthe children of the dictionary
ErrorsNOT_FOUND dictionaryId is not found
NULL_ARGUMENT dictionaryId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetChildDictionaries
Description

Gets the child dictionaries of the given id.

Parametersosid.id.IddictionaryIdthe Id of the Dictionary to query
Returnosid.dictionary.DictionaryListthe child dictionaries of the id
ErrorsNOT_FOUNDa Dictionary identified by Id is not found
NULL_ARGUMENT dictionaryId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodisDescendantOfDictionary
Description

Tests if an Id is a descendant of a dictionary.

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

If id is not found return false.

MethodgetDictionaryNodeIds
Description

Gets a portion of the hierarchy for the given dictionary.

Parametersosid.id.IddictionaryIdthe 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 dictionary node
ErrorsNOT_FOUND dictionaryId is not found
NULL_ARGUMENT dictionaryId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetDictionaryNodes
Description

Gets a portion of the hierarchy for the given dictionary.

Parametersosid.id.IddictionaryIdthe 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.dictionary.DictionaryNodea dictionary node
ErrorsNOT_FOUND dictionaryId is not found
NULL_ARGUMENT dictionaryId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.