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 otherwise
Return 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 otherwise
Return 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 otherwise
Return 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 otherwise
Return 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 types
Return 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 types
Return 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 hierarchy
  • HierarchyDesignSession: a session to design a hierarchy
  • HierarchySequencingSession: a session to sequence nodes in a hierarchy
  • HierarchyStructureNotificationSession: a session for notififcations within a hierarchy structure
  • HierarchyLookupSession: a session looking up hiererachies
  • HierarchyQuerySession: a session querying hiererachies
  • HierarchySearchSession: a session for searching for hierarchies
  • HierarchyAdminSession: a session for creating and deleting hierarchies
  • HierarchyNotificationSession: 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 session
Return 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 request
Raise:PermissionDenied – authorization failure

compliance: 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 otherwise
Return 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 request
Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

HierarchyManager.has_parents(id_)

Tests if this Id contains any parents.

Parameters:id (osid.id.Id) – the Id to query
Returns:true if this Id contains parents, false otherwise
Return type:boolean
Raise:NotFoundid is not found
Raise:NullArgumentid is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: 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) – the Id to query
  • parent_id (osid.id.Id) – the Id of a parent
Returns:

true if this parent_id is a parent of id, false otherwise

Return type:

boolean

Raise:

NotFoundid is not found

Raise:

NullArgumentid or parent_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented. implementation notes: If parent_id not found return false.

HierarchyManager.get_parents(id_)

Gets the parents of the given id.

Parameters:id (osid.id.Id) – the Id to query
Returns:the parents of the id
Return type:osid.id.IdList
Raise:NotFoundid is not found
Raise:NullArgumentid is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: 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) – the Id to query
  • ancestor_id (osid.id.Id) – the Id of an ancestor
Returns:

true if this ancestor_id is a parent of id, false otherwise

Return type:

boolean

Raise:

NotFoundid is not found

Raise:

NullArgumentid or ancestor_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented. implementation notes: If ancestor_id not found return false.

HierarchyManager.has_children(id_)

Tests if this Id has any children.

Parameters:id (osid.id.Id) – the Id to query
Returns:true if this Id has children, false otherwise
Return type:boolean
Raise:NotFoundid is not found
Raise:NullArgumentid is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: 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) – the Id to query
  • child_id (osid.id.Id) – the Id of a child
Returns:

true if this child_id is a child of the Id, false otherwise

Return type:

boolean

Raise:

NotFoundid is not found

Raise:

NullArgumentid or child_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented. implementation notes: If child_id not found return false.

HierarchyManager.get_children(id_)

Gets the children of the given Id.

Parameters:id (osid.id.Id) – the Id to query
Returns:the children of the id
Return type:osid.id.IdList
Raise:NotFoundid is not found
Raise:NullArgumentid is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: 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) – the Id to query
  • descendant_id (osid.id.Id) – the Id of a descendant
Returns:

true if this descendant_id is a child of the Id, false otherwise

Return type:

boolean

Raise:

NotFoundid is not found

Raise:

NullArgumentid or descendant is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: 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) – the Id 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 siblings
Returns:

a node

Return type:

osid.hierarchy.Node

Raise:

NotFoundid is not found

Raise:

NullArgumentid is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: 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 session
Return 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 request
Raise:PermissionDenied – authorization failure

compliance: 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 otherwise
Return type:boolean

compliance: mandatory – This method must be implemented.

HierarchyManager.add_root(id_)

Adds a root node.

Parameters:id (osid.id.Id) – the Id of the node
Raise:AlreadyExistsid is already in hierarchy
Raise:NotFoundid not found
Raise:NullArgumentid is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

HierarchyManager.add_child(id_, child_id)

Adds a child to a Id.

Parameters:
  • id (osid.id.Id) – the Id of the node
  • child_id (osid.id.Id) – the Id of the new child
Raise:

AlreadyExistschild_id is already a child of id

Raise:

NotFoundid or child_id not found

Raise:

NullArgumentid or child_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

HierarchyManager.remove_root(id_)

Removes a root node.

Parameters:id (osid.id.Id) – the Id of the node
Raise:NotFoundid was not found or not in hierarchy
Raise:NullArgumentid is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

HierarchyManager.remove_child(id_, child_id)

Removes a childfrom an Id.

Parameters:
  • id (osid.id.Id) – the Id of the node
  • child_id (osid.id.Id) – the Id of the child to remove
Raise:

NotFoundid or child_id was not found or child_id is not a child of id

Raise:

NullArgumentid or child_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

HierarchyManager.remove_children(id_)

Removes all childrenfrom an Id.

Parameters:id (osid.id.Id) – the Id of the node
Raise:NotFound – an node identified by the given Id was not found
Raise:NullArgumentid is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: 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 otherwise
Return 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 its Id.

In plenary mode, the exact Id is found or a NotFound results. Otherwise, the returned Hierarchy may have a different Id than requested, such as the case where a duplicate Id was assigned to a Hierarchy and retained for compati

Parameters:hierarchy_id (osid.id.Id) – the Id of the Hierarchy to retrieve
Returns:the returned Hierarchy
Return type:osid.hierarchy.Hierarchy
Raise:NotFound – no Hierarchy found with the given Id
Raise:NullArgumenthierarchy_id is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

HierarchyManager.get_hierarchies_by_ids(hierarchy_ids)

Gets a Hierarchy corresponding to the given IdList.

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 an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible Hierarchy 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 of Ids to retrieve
Returns:the returned Hierarchy list
Return type:osid.hierarchy.HierarchyList
Raise:NotFound – an Id was not found
Raise:NullArgumenthierarchy_ids is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

HierarchyManager.get_hierarchies_by_genus_type(hierarchy_genus_type)

Gets a HierarchyList corresponding to the given genus Type which does not include hierarchies of types derived from the specified Type.

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 type
Returns:the returned Hierarchy list
Return type:osid.hierarchy.HierarchyList
Raise:NullArgumenthierarchy_genus_type is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

HierarchyManager.get_hierarchies_by_parent_genus_type(hierarchy_genus_type)

Gets a HierarchyList corresponding to the given hierarchy genus Type and include any additional hierarchies with types derived from the specified Type.

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 type
Returns:the returned Hierarchy list
Return type:osid.hierarchy.HierarchyList
Raise:NullArgumenthierarchy_genus_type is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

HierarchyManager.get_hierarchies_by_record_type(hierarchy_record_type)

Gets a HierarchyList corresponding to the given hierarchy record Type.

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 type
Returns:the returned Hierarchy list
Return type:osid.hierarchy.HierarchyList
Raise:NullArgumenthierarchy_record_type is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: 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 resource Id
Returns:the returned Hierarchy list
Return type:osid.hierarchy.HierarchyList
Raise:NullArgumentresource_id is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: 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 request
Raise:PermissionDenied – authorization failure

compliance: 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 a PermissionDenied. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.

Returns:false if Hierarchy creation is not authorized, true otherwise
Return 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 specific Hierarchy. Providing an empty array tests if a Hierarchy can be created with no records.

Parameters:hierarchy_record_types (osid.type.Type[]) – array of hierarchy record types
Returns:true if Hierarchy creation using the specified Types is supported, false otherwise
Return type:boolean
Raise:NullArgumenthierarchy_record_types is null

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 types
Returns:the hierarchy form
Return type:osid.hierarchy.HierarchyForm
Raise:NullArgumenthierarchy_record_types is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure
Raise:Unsupported – unable to get form for requested record types

compliance: mandatory – This method must be implemented.

HierarchyManager.create_hierarchy(hierarchy_form)

Creates a new Hierarchy.

Parameters:hierarchy_form (osid.hierarchy.HierarchyForm) – the form for this Hierarchy
Returns:the new Hierarchy
Return type:osid.hierarchy.Hierarchy
Raise:IllegalStatehierarchy_form already used in a create transaction
Raise:InvalidArgument – one or more of the form elements is invalid
Raise:NullArgumenthierarchy_form is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure
Raise:Unsupportedhierarchy_form did not originate from get_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 a PermissionDenied. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.

Returns:false if Hierarchy modification is not authorized, true otherwise
Return 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) – the Id of the Hierarchy
Returns:the hierarchy form
Return type:osid.hierarchy.HierarchyForm
Raise:NotFoundhierarchy_id is not found
Raise:NullArgumenthierarchy_id is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: 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 updated
Raise:IllegalStatehierarchy_form already used in an update transaction
Raise:InvalidArgument – the form contains an invalid value
Raise:NullArgumenthierarchy_id or hierarchy_form is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure
Raise:Unsupportedhierarchy_form did not originate from get_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 a PermissionDenied. This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.

Returns:false if Hierarchy deletion is not authorized, true otherwise
Return type:boolean

compliance: mandatory – This method must be implemented.

HierarchyManager.delete_hierarchy(hierarchy_id)

Deletes a Hierarchy.

Parameters:hierarchy_id (osid.id.Id) – the Id of the Hierarchy to remove
Raise:NotFoundhierarchy_id not found
Raise:NullArgumenthierarchy_id is null
Raise:OperationFailed – unable to complete request
Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

HierarchyManager.can_manage_hierarchy_aliases()

Tests if this user can manage Id aliases for Hierarchy 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 if Hierarchy aliasing is not authorized, true otherwise
Return type:boolean

compliance: mandatory – This method must be implemented.

HierarchyManager.alias_hierarchy(hierarchy_id, alias_id)

Adds an Id to a Hierarchy for the purpose of creating compatibility.

The primary Id of the Hierarchy is determined by the provider. The new Id performs as an alias to the primary Id. If the alias is a pointer to another vault it is reassigned to the given vault Id.

Parameters:
  • hierarchy_id (osid.id.Id) – the Id of an Hierarchy
  • alias_id (osid.id.Id) – the alias Id
Raise:

AlreadyExistsalias_id is already assigned

Raise:

NotFoundhierarchy_id not found

Raise:

NullArgumenthierarchy_id or alias_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.