Hierarchy Open Service Interface Definitions hierarchy version 3.0.0
The Hierarchy OSID is an auxiliary service providing a means for
accessing and managing hierarchical relationships among OSID Ids
.
An OSID Id
may have onr or more parents or children and the
hierarchy itself represents a directed acyclic graph. The hierarchy
service defines a set of interfaces used among other OSIDs that utilize
hierarchies and can also be used to abstract hierarchical data into a
standalone service.
Hierarchical queries may be performed using the
HierarchyTraversalSession
. A set of methods exist to query parents,
children, ancestors, and decendants. A Node structure may be retrieved
to access a portion of a hierarchy in bulk. The Node
provides
methods to get parents and children of the node directly.
Hierarchies are federateable by combining nodes. There is no hierarchy service for the hierarchy catalog.
Service Managers¶
Hierarchy Profile¶
-
class
dlkit.services.hierarchy.
HierarchyProfile
¶ Bases:
dlkit.osid.managers.OsidProfile
The hierarchy profile describes the interoperability among hierarchy services.
-
supports_hierarchy_traversal
()¶ Tests if hierarchy traversal is supported.
Returns: true
if hierarchy traversal is supported,false
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
-
supports_hierarchy_design
()¶ Tests if hierarchy design is supported.
Returns: true
if hierarchy design is supported,false
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
-
supports_hierarchy_lookup
()¶ Tests if a hierarchy lookup is supported.
Returns: true
if hierarchy lookup is supported,false
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
-
supports_hierarchy_admin
()¶ Tests if a hierarchy administration is supported.
Returns: true
if hierarchy administration is supported,false
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
-
hierarchy_record_types
¶ Gets the supported
Hierarchy
types.Returns: a list containing the supported Hierarchy
record typesReturn type: osid.type.TypeList
compliance: mandatory – This method must be implemented.
-
hierarchy_search_record_types
¶ Gets the supported
Hierarchy
search record types.Returns: a list containing the supported Hierarchy
search record typesReturn type: osid.type.TypeList
compliance: mandatory – This method must be implemented.
-
Hierarchy Manager¶
-
class
dlkit.services.hierarchy.
HierarchyManager
(proxy=None)¶ Bases:
dlkit.osid.managers.OsidManager
,dlkit.osid.sessions.OsidSession
,dlkit.services.hierarchy.HierarchyProfile
The hierarchy manager provides access sessions to traverse and manage hierrachies of
Ids
.The sessions included in this manager are:
HierarchyTraversalSession:
a basic session traversing a hierarchyHierarchyDesignSession:
a session to design a hierarchyHierarchySequencingSession:
a session to sequence nodes in a hierarchyHierarchyStructureNotificationSession:
a session for notififcations within a hierarchy structureHierarchyLookupSession:
a session looking up hiererachiesHierarchyQuerySession:
a session querying hiererachiesHierarchySearchSession:
a session for searching for hierarchiesHierarchyAdminSession:
a session for creating and deleting hierarchiesHierarchyNotificationSession:
a session for subscribing to changes in hierarchies
Hierarchy Traversal Methods¶
HierarchyManager.
hierarchy_id
¶Gets the hierarchy
Id
associated with this session.
Returns: the hierarchy Id
associated with this sessionReturn type: osid.id.Id
compliance: mandatory – This method must be implemented.
HierarchyManager.
hierarchy
¶Gets the hierarchy associated with this session.
Returns: the hierarchy associated with this session Return type: osid.hierarchy.Hierarchy
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
can_access_hierarchy
()¶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
PermissionDenied
. This is intended as a hint to an application that may opt not to offer lookup operations.
Returns: false
if lookup methods are not authorized,true
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
HierarchyManager.
roots
¶Gets the root nodes of this hierarchy.
Returns: the root nodes Return type: osid.id.IdList
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
has_parents
(id_)¶Tests if this
Id
contains any parents.
Parameters: id ( osid.id.Id
) – theId
to queryReturns: true
if thisId
contains parents,false
otherwiseReturn type: boolean
Raise: NotFound
–id
is not foundRaise: NullArgument
–id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
is_parent
(id_, parent_id)¶Tests if an
Id
is a direct parent of another.
Parameters:
- id (
osid.id.Id
) – theId
to query- parent_id (
osid.id.Id
) – theId
of a parentReturns:
true
if thisparent_id
is a parent ofid,
false
otherwiseReturn type:
boolean
Raise:
NotFound
–id
is not foundRaise:
NullArgument
–id
orparent_id
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented. implementation notes: If
parent_id
not found returnfalse
.
HierarchyManager.
get_parents
(id_)¶Gets the parents of the given
id
.
Parameters: id ( osid.id.Id
) – theId
to queryReturns: the parents of the id
Return type: osid.id.IdList
Raise: NotFound
–id
is not foundRaise: NullArgument
–id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
is_ancestor
(id_, ancestor_id)¶Tests if an
Id
is an ancestor of another.
Parameters:
- id (
osid.id.Id
) – theId
to query- ancestor_id (
osid.id.Id
) – theId
of an ancestorReturns:
true
if thisancestor_id
is a parent ofid,
false
otherwiseReturn type:
boolean
Raise:
NotFound
–id
is not foundRaise:
NullArgument
–id
orancestor_id
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented. implementation notes: If
ancestor_id
not found returnfalse
.
HierarchyManager.
has_children
(id_)¶Tests if this
Id
has any children.
Parameters: id ( osid.id.Id
) – theId
to queryReturns: true
if thisId
has children,false
otherwiseReturn type: boolean
Raise: NotFound
–id
is not foundRaise: NullArgument
–id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
is_child
(id_, child_id)¶Tests if a node is a direct child of another.
Parameters:
- id (
osid.id.Id
) – theId
to query- child_id (
osid.id.Id
) – theId
of a childReturns:
true
if thischild_id
is a child of theId,
false
otherwiseReturn type:
boolean
Raise:
NotFound
–id
is not foundRaise:
NullArgument
–id
orchild_id
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented. implementation notes: If
child_id
not found returnfalse
.
HierarchyManager.
get_children
(id_)¶Gets the children of the given
Id
.
Parameters: id ( osid.id.Id
) – theId
to queryReturns: the children of the id
Return type: osid.id.IdList
Raise: NotFound
–id
is not foundRaise: NullArgument
–id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
is_descendant
(id_, descendant_id)¶Tests if a node is a descendant of another.
Parameters:
- id (
osid.id.Id
) – theId
to query- descendant_id (
osid.id.Id
) – theId
of a descendantReturns:
true
if thisdescendant_id
is a child of theId,
false
otherwiseReturn type:
boolean
Raise:
NotFound
–id
is not foundRaise:
NullArgument
–id
ordescendant
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented. implementation notes: If not found return
false
.
HierarchyManager.
get_nodes
(id_, ancestor_levels, descendant_levels, include_siblings)¶Gets a portion of the hierarchy for the given
Id
.
Parameters:
- id (
osid.id.Id
) – theId
to query- ancestor_levels (
cardinal
) – the maximum number of ancestor levels to include. A value of 0 returns no parents in the node.- descendant_levels (
cardinal
) – the maximum number of descendant levels to include. A value of 0 returns no children in the node.- include_siblings (
boolean
) –true
to include the siblings of the given node,false
to omit the siblingsReturns: a node
Return type:
osid.hierarchy.Node
Raise:
NotFound
–id
is not foundRaise:
NullArgument
–id
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
Hierarchy Design Methods¶
HierarchyManager.
hierarchy_id
Gets the hierarchy
Id
associated with this session.
Returns: the hierarchy Id
associated with this sessionReturn type: osid.id.Id
compliance: mandatory – This method must be implemented.
HierarchyManager.
hierarchy
Gets the hierarchy associated with this session.
Returns: the hierarchy associated with this session Return type: osid.hierarchy.Hierarchy
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
can_modify_hierarchy
()¶Tests if this user can change the hierarchy.
A return of true does not guarantee successful authorization. A return of false indicates that it is known performing any update will result in a
PermissionDenied
. This is intended as a hint to an application that may opt not to offer these operations to an unauthorized user.
Returns: false
if changing this hierarchy is not authorized,true
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
HierarchyManager.
add_root
(id_)¶Adds a root node.
Parameters: id ( osid.id.Id
) – theId
of the nodeRaise: AlreadyExists
–id
is already in hierarchyRaise: NotFound
–id
not foundRaise: NullArgument
–id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
add_child
(id_, child_id)¶Adds a child to a
Id
.
Parameters:
- id (
osid.id.Id
) – theId
of the node- child_id (
osid.id.Id
) – theId
of the new childRaise:
AlreadyExists
–child_id
is already a child ofid
Raise:
NotFound
–id
orchild_id
not foundRaise:
NullArgument
–id
orchild_id
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
remove_root
(id_)¶Removes a root node.
Parameters: id ( osid.id.Id
) – theId
of the nodeRaise: NotFound
–id
was not found or not in hierarchyRaise: NullArgument
–id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
remove_child
(id_, child_id)¶Removes a childfrom an
Id
.
Parameters:
- id (
osid.id.Id
) – theId
of the node- child_id (
osid.id.Id
) – theId
of the child to removeRaise:
NotFound
–id
orchild_id
was not found orchild_id
is not a child ofid
Raise:
NullArgument
–id
orchild_id
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
remove_children
(id_)¶Removes all childrenfrom an
Id
.
Parameters: id ( osid.id.Id
) – theId
of the nodeRaise: NotFound
– an node identified by the givenId
was not foundRaise: NullArgument
–id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
Hierarchy Lookup Methods¶
HierarchyManager.
can_lookup_hierarchies
()¶Tests if this user can perform
Hierarchy
lookups.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
PermissionDenied
. This is intended as a hint to an application that may opt not to offer lookup operations to unauthorized users.
Returns: false
if lookup methods are not authorized,true
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
HierarchyManager.
use_comparative_hierarchy_view
()¶The returns from the lookup 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.
HierarchyManager.
use_plenary_hierarchy_view
()¶A complete view of the
Hierarchy
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.
HierarchyManager.
get_hierarchy
(hierarchy_id)¶Gets the
Hierarchy
specified by itsId
.In plenary mode, the exact
Id
is found or aNotFound
results. Otherwise, the returnedHierarchy
may have a differentId
than requested, such as the case where a duplicateId
was assigned to aHierarchy
and retained for compati
Parameters: hierarchy_id ( osid.id.Id
) – theId
of theHierarchy
to retrieveReturns: the returned Hierarchy
Return type: osid.hierarchy.Hierarchy
Raise: NotFound
– noHierarchy
found with the givenId
Raise: NullArgument
–hierarchy_id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
get_hierarchies_by_ids
(hierarchy_ids)¶Gets a
Hierarchy
corresponding to the givenIdList
.In plenary mode, the returned list contains all of the hierarchies specified in the
Id
list, in the order of the list, including duplicates, or an error results if anId
in the supplied list is not found or inaccessible. Otherwise, inaccessibleHierarchy
objects may be omitted from the list and may present the elements in any order including returning a unique set.
Parameters: hierarchy_ids ( osid.id.IdList
) – the list ofIds
to retrieveReturns: the returned Hierarchy
listReturn type: osid.hierarchy.HierarchyList
Raise: NotFound
– anId was
not foundRaise: NullArgument
–hierarchy_ids
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
get_hierarchies_by_genus_type
(hierarchy_genus_type)¶Gets a
HierarchyList
corresponding to the given genusType
which does not include hierarchies of types derived from the specifiedType
.In plenary mode, the returned list contains all known hierarchies or an error results. Otherwise, the returned list may contain only those hierarchies that are accessible through this session.
Parameters: hierarchy_genus_type ( osid.type.Type
) – a hierarchy genus typeReturns: the returned Hierarchy
listReturn type: osid.hierarchy.HierarchyList
Raise: NullArgument
–hierarchy_genus_type
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
get_hierarchies_by_parent_genus_type
(hierarchy_genus_type)¶Gets a
HierarchyList
corresponding to the given hierarchy genusType
and include any additional hierarchies with types derived from the specifiedType
.In plenary mode, the returned list contains all known hierarchies or an error results. Otherwise, the returned list may contain only those hierarchies that are accessible through this session.
Parameters: hierarchy_genus_type ( osid.type.Type
) – a hierarchy genus typeReturns: the returned Hierarchy
listReturn type: osid.hierarchy.HierarchyList
Raise: NullArgument
–hierarchy_genus_type
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
get_hierarchies_by_record_type
(hierarchy_record_type)¶Gets a
HierarchyList
corresponding to the given hierarchy recordType
.The set of hierarchies implementing the given record type are returned.In plenary mode, the returned list contains all known hierarchies or an error results. Otherwise, the returned list may contain only those hierarchies that are accessible through this session.
Parameters: hierarchy_record_type ( osid.type.Type
) – a hierarchy record typeReturns: the returned Hierarchy
listReturn type: osid.hierarchy.HierarchyList
Raise: NullArgument
–hierarchy_record_type
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
get_hierarchies_by_provider
(resource_id)¶Gets a
HierarchyList
for the given provider ````.The set of hierarchies implementing the given record type are returned.In plenary mode, the returned list contains all known hierarchies or an error results. Otherwise, the returned list may contain only those hierarchies that are accessible through this session.
Parameters: resource_id ( osid.id.Id
) – a resourceId
Returns: the returned Hierarchy
listReturn type: osid.hierarchy.HierarchyList
Raise: NullArgument
–resource_id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
hierarchies
¶Gets all hierarchies.
In plenary mode, the returned list contains all known hierarchies or an error results. Otherwise, the returned list may contain only those hierarchies that are accessible through this session.
Returns: a list of Hierarchies
Return type: osid.hierarchy.HierarchyList
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
Hierarchy Admin Methods¶
HierarchyManager.
can_create_hierarchies
()¶Tests if this user can create
Hierarchy
objects.A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a
Hierarchy
will result in aPermissionDenied
. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.
Returns: false
ifHierarchy
creation is not authorized,true
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
HierarchyManager.
can_create_hierarchy_with_record_types
(hierarchy_record_types)¶Tests if this user can create a single
Hierarchy
using the desired record types.While
HierarchyManager.getHierarchyRecordTypes()
can be used to examine which records are supported, this method tests which record(s) are required for creating a specificHierarchy
. Providing an empty array tests if aHierarchy
can be created with no records.
Parameters: hierarchy_record_types ( osid.type.Type[]
) – array of hierarchy record typesReturns: true
ifHierarchy
creation using the specifiedTypes
is supported,false
otherwiseReturn type: boolean
Raise: NullArgument
–hierarchy_record_types
isnull
compliance: mandatory – This method must be implemented.
HierarchyManager.
get_hierarchy_form_for_create
(hierarchy_record_types)¶Gets the hierarchy form for creating new hierarchies.
A new form should be requested for each create transaction. This method is used for creating new hierarchies, where only the
Hierarchy
Type
is known.
Parameters: hierarchy_record_types ( osid.type.Type[]
) – array of hierarchy record typesReturns: the hierarchy form Return type: osid.hierarchy.HierarchyForm
Raise: NullArgument
–hierarchy_record_types
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failureRaise: Unsupported
– unable to get form for requested record typescompliance: mandatory – This method must be implemented.
HierarchyManager.
create_hierarchy
(hierarchy_form)¶Creates a new
Hierarchy
.
Parameters: hierarchy_form ( osid.hierarchy.HierarchyForm
) – the form for thisHierarchy
Returns: the new Hierarchy
Return type: osid.hierarchy.Hierarchy
Raise: IllegalState
–hierarchy_form
already used in a create transactionRaise: InvalidArgument
– one or more of the form elements is invalidRaise: NullArgument
–hierarchy_form
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failureRaise: Unsupported
–hierarchy_form
did not originate fromget_hierarchy_form_for_create()
compliance: mandatory – This method must be implemented.
HierarchyManager.
can_update_hierarchies
()¶Tests if this user can update
Hierarchy
objects.A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a
Hierarchy
will result in aPermissionDenied
. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.
Returns: false
ifHierarchy
modification is not authorized,true
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
HierarchyManager.
get_hierarchy_form_for_update
(hierarchy_id)¶Gets the hierarchy form for updating an existing hierarchy.
A new hierarchy form should be requested for each update transaction.
Parameters: hierarchy_id ( osid.id.Id
) – theId
of theHierarchy
Returns: the hierarchy form Return type: osid.hierarchy.HierarchyForm
Raise: NotFound
–hierarchy_id
is not foundRaise: NullArgument
–hierarchy_id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
update_hierarchy
(hierarchy_form)¶Updates an existing hierarchy.
Parameters: hierarchy_form ( osid.hierarchy.HierarchyForm
) – the form containing the elements to be updatedRaise: IllegalState
–hierarchy_form
already used in an update transactionRaise: InvalidArgument
– the form contains an invalid valueRaise: NullArgument
–hierarchy_id
orhierarchy_form
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failureRaise: Unsupported
–hierarchy_form
did not originate fromget_hierarchy_form_for_update()
compliance: mandatory – This method must be implemented.
HierarchyManager.
can_delete_hierarchies
()¶Tests if this user can delete
Hierarchy
objects.A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a
Hierarchy
will result in aPermissionDenied
. This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.
Returns: false
ifHierarchy
deletion is not authorized,true
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
HierarchyManager.
delete_hierarchy
(hierarchy_id)¶Deletes a
Hierarchy
.
Parameters: hierarchy_id ( osid.id.Id
) – theId
of theHierarchy
to removeRaise: NotFound
–hierarchy_id
not foundRaise: NullArgument
–hierarchy_id
isnull
Raise: OperationFailed
– unable to complete requestRaise: PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.
HierarchyManager.
can_manage_hierarchy_aliases
()¶Tests if this user can manage
Id
aliases forHierarchy
objects.A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a
PermissionDenied
. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.
Returns: false
ifHierarchy
aliasing is not authorized,true
otherwiseReturn type: boolean
compliance: mandatory – This method must be implemented.
HierarchyManager.
alias_hierarchy
(hierarchy_id, alias_id)¶Adds an
Id
to aHierarchy
for the purpose of creating compatibility.The primary
Id
of theHierarchy
is determined by the provider. The newId
performs as an alias to the primaryId
. If the alias is a pointer to another vault it is reassigned to the given vaultId
.
Parameters:
- hierarchy_id (
osid.id.Id
) – theId
of anHierarchy
- alias_id (
osid.id.Id
) – the aliasId
Raise:
AlreadyExists
–alias_id
is already assignedRaise:
NotFound
–hierarchy_id
not foundRaise:
NullArgument
–hierarchy_id
oralias_id
isnull
Raise:
OperationFailed
– unable to complete requestRaise:
PermissionDenied
– authorization failurecompliance: mandatory – This method must be implemented.