Interface OntologyHierarchySession

All Superinterfaces:

AutoCloseable, Closeable, OsidSession, OsidSession

public interface OntologyHierarchySession
extends OsidSession

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

Method Summary

Modifier and Type	Method	Description
boolean	canAccessOntologyHierarchy()	Tests if this user can perform hierarchy queries.
OntologyList	getChildOntologies(Id ontologyId)	Gets the children of the given ontology.
IdList	getChildOntologyIds(Id ontologyId)	Gets the child Ids of the given ontology.
Hierarchy	getOntologyHierarchy()	Gets the hierarchy associated with this session.
Id	getOntologyHierarchyId()	Gets the hierarchy Id associated with this session.
Node	getOntologyNodeIds(Id ontologyId, long ancestorLevels, long descendantLevels, boolean includeSiblings)	Gets a portion of the hierarchy for the given ontology.
OntologyNode	getOntologyNodes(Id ontologyId, long ancestorLevels, long descendantLevels, boolean includeSiblings)	Gets a portion of the hierarchy for the given ontology.
OntologyList	getParentOntologies(Id ontologyId)	Gets the parents of the given ontology.
IdList	getParentOntologyIds(Id ontologyId)	Gets the parent Ids of the given ontology.
OntologyList	getRootOntologies()	Gets the root ontologies in this ontology hierarchy.
IdList	getRootOntologyIds()	Gets the root ontology Ids in this hierarchy.
boolean	hasChildOntologies(Id ontologyId)	Tests if an ontology has any children.
boolean	hasParentOntologies(Id ontologyId)	Tests if the Ontology has any parents.
boolean	isAncestorOfOntology(Id id, Id ontologyId)	Tests if an Id is an ancestor of an ontology.
boolean	isChildOfOntology(Id id, Id ontologyId)	Tests if an ontology is a direct child of another.
boolean	isDescendantOfOntology(Id id, Id ontologyId)	Tests if an Id is a descendant of an ontology.
boolean	isParentOfOntology(Id id, Id ontologyId)	Tests if an Id is a direct parent of an ontology.
void	useComparativeOntologyView()	The returns from the ontology methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	usePlenaryOntologyView()	A complete view of the Hierarchy returns is desired.

Methods inherited from interface Closeable

close

Methods inherited from interface OsidSession

close

Modifier and Type	Method	Description
void	close()	Close this session.

Methods inherited from interface OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Modifier and Type	Method	Description
Agent	getAuthenticatedAgent()	Gets the agent authenticated to this session.
Id	getAuthenticatedAgentId()	Gets the Id of the agent authenticated to this session.
BigDecimal	getClockRate()	Gets the rate of the service clock.
Date	getDate()	Gets the service date which may be the current date or the effective date in which this session exists.
Agent	getEffectiveAgent()	Gets the effective agent in use by this session.
Id	getEffectiveAgentId()	Gets the Id of the effective agent in use by this session.
Type	getFormatType()	Gets the DisplayText format Type preference in effect for this session.
Locale	getLocale()	Gets the locale indicating the localization preferences in effect for this session.
boolean	isAuthenticated()	Tests if an agent is authenticated to this session.
Transaction	startTransaction()	Starts a new transaction for this sesson.
boolean	supportsTransactions()	Tests for the availability of transactions.

Method Details

getOntologyHierarchyId

Id getOntologyHierarchyId()

Gets the hierarchy Id associated with this session.

Returns:

the hierarchy Id associated with this session

Compliance:

mandatory - This method must be implemented.

getOntologyHierarchy

Hierarchy getOntologyHierarchy()
                        throws OperationFailedException,
PermissionDeniedException

Gets the hierarchy associated with this session.

Returns:

the hierarchy associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canAccessOntologyHierarchy

boolean canAccessOntologyHierarchy()

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 an application that may wish not to offer traversal operations to unauthorized users.

Returns:

false if hierarchy traversal methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeOntologyView

void useComparativeOntologyView()

The returns from the ontology 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.

usePlenaryOntologyView

void usePlenaryOntologyView()

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.

getRootOntologyIds

IdList getRootOntologyIds()
                   throws OperationFailedException,
PermissionDeniedException

Gets the root ontology Ids in this hierarchy.

Returns:

the root ontology Ids

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRootOntologies

OntologyList getRootOntologies()
                        throws OperationFailedException,
PermissionDeniedException

Gets the root ontologies in this ontology hierarchy.

Returns:

the root ontologies

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

hasParentOntologies

boolean hasParentOntologies(Id ontologyId)
                     throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Tests if the Ontology has any parents.

Parameters:

ontologyId - the Id of an ontology

Returns:

true if the ontology has parents, false otherwise

Throws:

NotFoundException - ontologyId is not found

NullArgumentException - ontologyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isParentOfOntology

boolean isParentOfOntology(Id id,
 Id ontologyId)
                    throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Tests if an Id is a direct parent of an ontology.

Parameters:

id - an Id

ontologyId - the Id of an ontology

Returns:

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

Throws:

NotFoundException - ontologyId is not found

NullArgumentException - id or ontologyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - {@code id} not found return {@code false} .

getParentOntologyIds

IdList getParentOntologyIds(Id ontologyId)
                     throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets the parent Ids of the given ontology.

Parameters:

ontologyId - the Id of an ontology

Returns:

the parent Ids of the ontology

Throws:

NotFoundException - ontologyId is not found

NullArgumentException - ontologyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getParentOntologies

OntologyList getParentOntologies(Id ontologyId)
                          throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets the parents of the given ontology.

Parameters:

ontologyId - the Id of an ontology

Returns:

the parents of the ontology

Throws:

NotFoundException - ontologyId is not found

NullArgumentException - ontologyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isAncestorOfOntology

boolean isAncestorOfOntology(Id id,
 Id ontologyId)
                      throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Tests if an Id is an ancestor of an ontology.

Parameters:

id - an Id

ontologyId - the Id of an ontology

Returns:

true if this id is an ancestor of ontologyId , false otherwise

Throws:

NotFoundException - ontologyId is not found

NullArgumentException - id or ontologyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - {@code id} not found return {@code false} .

hasChildOntologies

boolean hasChildOntologies(Id ontologyId)
                    throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Tests if an ontology has any children.

Parameters:

ontologyId - the Id of an ontology

Returns:

true if the ontologyId has children, false otherwise

Throws:

NotFoundException - ontologyId is not found

NullArgumentException - ontologyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isChildOfOntology

boolean isChildOfOntology(Id id,
 Id ontologyId)
                   throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Tests if an ontology is a direct child of another.

Parameters:

id - an Id

ontologyId - the Id of an ontology

Returns:

true if the id is a child of ontologyId , false otherwise

Throws:

NotFoundException - ontologyId is not found

NullArgumentException - id or ontologyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - {@code id} not found return {@code false} .

getChildOntologyIds

IdList getChildOntologyIds(Id ontologyId)
                    throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets the child Ids of the given ontology.

Parameters:

ontologyId - the Id to query

Returns:

the children of the ontology

Throws:

NotFoundException - ontologyId is not found

NullArgumentException - ontologyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getChildOntologies

OntologyList getChildOntologies(Id ontologyId)
                         throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets the children of the given ontology.

Parameters:

ontologyId - the Id to query

Returns:

the children of the ontology

Throws:

NotFoundException - ontologyId is not found

NullArgumentException - ontologyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isDescendantOfOntology

boolean isDescendantOfOntology(Id id,
 Id ontologyId)
                        throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Tests if an Id is a descendant of an ontology.

Parameters:

id - an Id

ontologyId - the Id of an ontology

Returns:

true if the id is a descendant of the ontologyId , false otherwise

Throws:

NotFoundException - ontologyId is not found

NullArgumentException - id or ontologyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - {@code id} is not found return {@code false} .

getOntologyNodeIds

Node getOntologyNodeIds(Id ontologyId,
 long ancestorLevels,
 long descendantLevels,
 boolean includeSiblings)
                 throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets a portion of the hierarchy for the given ontology.

Parameters:

ontologyId - the Id to query

ancestorLevels - the maximum number of ancestor levels to include. A value of 0 returns no parents in the node.

descendantLevels - the maximum number of descendant levels to include. A value of 0 returns no children in the node.

includeSiblings - true to include the siblings of the given node, false to omit the siblings

Returns:

an ontology node

Throws:

NotFoundException - ontologyId is not found

NullArgumentException - ontologyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getOntologyNodes

OntologyNode getOntologyNodes(Id ontologyId,
 long ancestorLevels,
 long descendantLevels,
 boolean includeSiblings)
                       throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets a portion of the hierarchy for the given ontology.

Parameters:

ontologyId - the Id to query

ancestorLevels - the maximum number of ancestor levels to include. A value of 0 returns no parents in the node.

descendantLevels - the maximum number of descendant levels to include. A value of 0 returns no children in the node.

includeSiblings - true to include the siblings of the given node, false to omit the siblings

Returns:

an ontology node

Throws:

NotFoundException - ontologyId is not found

NullArgumentException - ontologyId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.