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:NotFound – id is not found Raise:NullArgument – id 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:

NotFound – id is not found

Raise:

NullArgument – id 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:NotFound – id is not found Raise:NullArgument – id 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:

NotFound – id is not found

Raise:

NullArgument – id 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:NotFound – id is not found Raise:NullArgument – id 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:

NotFound – id is not found

Raise:

NullArgument – id 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:NotFound – id is not found Raise:NullArgument – id 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:

NotFound – id is not found

Raise:

NullArgument – id 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:

NotFound – id is not found

Raise:

NullArgument – id 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:AlreadyExists – id is already in hierarchy Raise:NotFound – id not found Raise:NullArgument – id 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:

AlreadyExists – child_id is already a child of id

Raise:

NotFound – id or child_id not found

Raise:

NullArgument – id 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:NotFound – id was not found or not in hierarchy Raise:NullArgument – id 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:

NotFound – id or child_id was not found or child_id is not a child of id

Raise:

NullArgument – id 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:NullArgument – id 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:NullArgument – hierarchy_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:NullArgument – hierarchy_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:NullArgument – hierarchy_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:NullArgument – hierarchy_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:NullArgument – hierarchy_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:NullArgument – resource_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:NullArgument – hierarchy_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:NullArgument – hierarchy_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:IllegalState – hierarchy_form already used in a create transaction Raise:InvalidArgument – one or more of the form elements is invalid Raise:NullArgument – hierarchy_form is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure Raise:Unsupported – hierarchy_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:NotFound – hierarchy_id is not found Raise:NullArgument – hierarchy_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:IllegalState – hierarchy_form already used in an update transaction Raise:InvalidArgument – the form contains an invalid value Raise:NullArgument – hierarchy_id or hierarchy_form is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure Raise:Unsupported – hierarchy_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:NotFound – hierarchy_id not found Raise:NullArgument – hierarchy_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:

AlreadyExists – alias_id is already assigned

Raise:

NotFound – hierarchy_id not found

Raise:

NullArgument – hierarchy_id or alias_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.