org.osid.ontology

Interface OntologyHierarchySession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, 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

Methods

Modifier and Type	Method and 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 org.osid.OsidSession

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

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

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 - id not found return 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 - id not found return 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 - id not found return 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 - id is not found return 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.