OSID - osid.hierarchy.HierarchyTraversalSession Service Interface Definition

Interface	osid.hierarchy.HierarchyTraversalSession
Implements	`osid.OsidSession`
Description	This session defines methods for traversing a hierarchy. Each node in the hierarchy is a unique OSID `Id.` The hierarchy may be traversed recursively to establish the tree structure through `getParents()` and `getChildren().` To relate these `Ids` to another OSID, `getNodes()` can be used for retrievals that can be used for bulk lookups in other OSIDs. Any Id available in an associated OSID is known to this hierarchy. A lookup up a particular `Id` in this hierarchy for the purposes of establishing a starting point for traversal or determining relationships should use the `Id` returned from the corresponding OSID object, not an Id that has been stored, to avoid problems with `Id` translation or aliasing. 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 `getParents()` or `getChildren()` in lieu of a `PERMISSION_DENIED` error that may disrupt the traversal through authorized pathways.
Method	getHierarchyId
Description	Gets the hierarchy `Id` associated with this session.
Return	`osid.id.Id`		the hierarchy `Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getHierarchy
Description	Gets the hierarchy associated with this session.
Return	`osid.hierarchy.Hierarchy`		the hierarchy associated with this session
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canAccessHierarchy
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.
Return	`boolean`		`false` if lookup methods are not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getRoots
Description	Gets the root nodes of this hierarchy.
Return	`osid.id.IdList`		the root nodes
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	hasParents
Description	Tests if this `Id` contains any parents.
Parameters	`osid.id.Id`	`id`	the `Id` to query
Return	`boolean`		`true` if this `Id` contains parents, `false` otherwise
Errors	NOT_FOUND		`id` is not found
	NULL_ARGUMENT		`id` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	isParent
Description	Tests if an `Id` is a direct parent of another.
Parameters	`osid.id.Id`	`id`	the `Id` to query
Parameters	`osid.id.Id`	`parentId`	the `Id` of a parent
Return	`boolean`		`true` if this `parentId` is a parent of `id,` `false` otherwise
Errors	NOT_FOUND		`id` is not found
	NULL_ARGUMENT		`id` or `parentId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Provider Notes	If `parentId` not found return `false.`
Method	getParents
Description	Gets the parents of the given `id.`
Parameters	`osid.id.Id`	`id`	the `Id` to query
Return	`osid.id.IdList`		the parents of the `id`
Errors	NOT_FOUND		`id` is not found
	NULL_ARGUMENT		`id` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	isAncestor
Description	Tests if an `Id` is an ancestor of another.
Parameters	`osid.id.Id`	`id`	the `Id` to query
Parameters	`osid.id.Id`	`ancestorId`	the `Id` of an ancestor
Return	`boolean`		`true` if this `ancestorId` is a parent of `id,` `false` otherwise
Errors	NOT_FOUND		`id` is not found
	NULL_ARGUMENT		`id` or `ancestorId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Provider Notes	If `ancestorId` not found return `false.`
Method	hasChildren
Description	Tests if this `Id` has any children.
Parameters	`osid.id.Id`	`id`	the `Id` to query
Return	`boolean`		`true` if this `Id` has children, `false` otherwise
Errors	NOT_FOUND		`id` is not found
	NULL_ARGUMENT		`id` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	isChild
Description	Tests if a node is a direct child of another.
Parameters	`osid.id.Id`	`id`	the `Id` to query
Parameters	`osid.id.Id`	`childId`	the `Id` of a child
Return	`boolean`		`true` if this `childId` is a child of the `Id,` `false` otherwise
Errors	NOT_FOUND		`id` is not found
	NULL_ARGUMENT		`id` or `childId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Provider Notes	If `childId` not found return `false.`
Method	getChildren
Description	Gets the children of the given `Id.`
Parameters	`osid.id.Id`	`id`	the `Id` to query
Return	`osid.id.IdList`		the children of the `id`
Errors	NOT_FOUND		`id` is not found
	NULL_ARGUMENT		`id` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	isDescendant
Description	Tests if a node is a descendant of another.
Parameters	`osid.id.Id`	`id`	the `Id` to query
Parameters	`osid.id.Id`	`descendantId`	the `Id` of a descendant
Return	`boolean`		`true` if this `descendantId` is a child of the `Id,` `false` otherwise
Errors	NOT_FOUND		`id` is not found
	NULL_ARGUMENT		`id` or `descendant` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Provider Notes	If not found return `false.`
Method	getNodes
Description	Gets a portion of the hierarchy for the given `Id.`
Parameters	`osid.id.Id`	`id`	the `Id` to query
	`cardinal`	`ancestorLevels`	the maximum number of ancestor levels to include. A value of 0 returns no parents in the node.
	`cardinal`	`descendantLevels`	the maximum number of descendant levels to include. A value of 0 returns no children in the node.
	`boolean`	`includeSiblings`	`true` to include the siblings of the given node, `false` to omit the siblings
Return	`osid.hierarchy.Node`		a node
Errors	NOT_FOUND		`id` is not found
	NULL_ARGUMENT		`id` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.