Interface SubjectHierarchySession

All Superinterfaces:

AutoCloseable, Closeable, OsidSession, OsidSession

public interface SubjectHierarchySession
extends OsidSession

This session defines methods for traversing a hierarchy of Subject objects. Each node in the hierarchy is a unique Subject . The hierarchy may be traversed recursively to establish the tree structure through getSubjectNodes() . To relate these Ids to another OSID, getAncestorSubjects() and getDescendantSubjects() can be used for retrievals that can be used for bulk lookups in other OSIDs. Any Subject 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 getParentSubjects() or getChildSubjects() 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: subject 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	canAccessSubjectHierarchy()	Tests if this user can perform hierarchy queries.
IdList	getChildSubjectIds(Id subjectId)	Gets the child Ids of the given subject.
SubjectList	getChildSubjects(Id subjectId)	Gets the children of the given subject.
IdList	getParentSubjectIds(Id subjectId)	Gets the parent Ids of the given subject.
SubjectList	getParentSubjects(Id subjectId)	Gets the parents of the given subject.
IdList	getRootSubjectIds()	Gets the root subject Ids in this hierarchy.
SubjectList	getRootSubjects()	Gets the root subjects in this subject hierarchy.
Hierarchy	getSubjectHierarchy()	Gets the hierarchy associated with this session.
Id	getSubjectHierarchyId()	Gets the hierarchy Id associated with this session.
Node	getSubjectNodeIds(Id subjectId, long ancestorLevels, long descendantLevels, boolean includeSiblings)	Gets a portion of the hierarchy for the given subject.
SubjectNode	getSubjectNodes(Id subjectId, long ancestorLevels, long descendantLevels, boolean includeSiblings)	Gets a portion of the hierarchy for the given subject.
boolean	hasChildSubjects(Id subjectId)	Tests if a subject has any children.
boolean	hasParentSubjects(Id subjectId)	Tests if the Subject has any parents.
boolean	isAncestorOfSubject(Id id, Id subjectId)	Tests if an Id is an ancestor of a subject.
boolean	isChildOfSubject(Id id, Id subjectId)	Tests if a subject is a direct child of another.
boolean	isDescendantOfSubject(Id id, Id subjectId)	Tests if an Id is a descendant of a subject.
boolean	isParentOfSubject(Id id, Id subjectId)	Tests if an Id is a direct parent of a subject.
void	useComparativeSubjectView()	The returns from the subject methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	usePlenarySubjectView()	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

getSubjectHierarchyId

Id getSubjectHierarchyId()

Gets the hierarchy Id associated with this session.

Returns:

the hierarchy Id associated with this session

Compliance:

mandatory - This method must be implemented.

getSubjectHierarchy

Hierarchy getSubjectHierarchy()
                       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.

canAccessSubjectHierarchy

boolean canAccessSubjectHierarchy()

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 traversal operations.

Returns:

false if hierarchy traversal methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeSubjectView

void useComparativeSubjectView()

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

usePlenarySubjectView

void usePlenarySubjectView()

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.

getRootSubjectIds

IdList getRootSubjectIds()
                  throws OperationFailedException,
PermissionDeniedException

Gets the root subject Ids in this hierarchy.

Returns:

the root subject Ids

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRootSubjects

SubjectList getRootSubjects()
                     throws OperationFailedException,
PermissionDeniedException

Gets the root subjects in this subject hierarchy.

Returns:

the root subjects

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

hasParentSubjects

boolean hasParentSubjects(Id subjectId)
                   throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Tests if the Subject has any parents.

Parameters:

subjectId - the Id of a subject

Returns:

true if the subject has parents, false otherwise

Throws:

NotFoundException - subjectId is not found

NullArgumentException - subjectId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isParentOfSubject

boolean isParentOfSubject(Id id,
 Id subjectId)
                   throws NotFoundException,
OperationFailedException,
PermissionDeniedException

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

Parameters:

id - an Id

subjectId - the Id of a subject

Returns:

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

Throws:

NotFoundException - subjectId is not found

NullArgumentException - id or subjectId 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} .

getParentSubjectIds

IdList getParentSubjectIds(Id subjectId)
                    throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets the parent Ids of the given subject.

Parameters:

subjectId - the Id of a subject

Returns:

the parent Ids of the subject

Throws:

NotFoundException - subjectId is not found

NullArgumentException - subjectId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getParentSubjects

SubjectList getParentSubjects(Id subjectId)
                       throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets the parents of the given subject.

Parameters:

subjectId - the Id of a subject

Returns:

the parents of the subject

Throws:

NotFoundException - subjectId is not found

NullArgumentException - subjectId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isAncestorOfSubject

boolean isAncestorOfSubject(Id id,
 Id subjectId)
                     throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Tests if an Id is an ancestor of a subject.

Parameters:

id - an Id

subjectId - the Id of a subject

Returns:

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

Throws:

NotFoundException - subjectId is not found

NullArgumentException - id or subjectId 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} .

hasChildSubjects

boolean hasChildSubjects(Id subjectId)
                  throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Tests if a subject has any children.

Parameters:

subjectId - the Id of a subject

Returns:

true if the subjectId has children, false otherwise

Throws:

NotFoundException - subjectId is not found

NullArgumentException - subjectId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isChildOfSubject

boolean isChildOfSubject(Id id,
 Id subjectId)
                  throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Tests if a subject is a direct child of another.

Parameters:

id - an Id

subjectId - the Id of a subject

Returns:

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

Throws:

NotFoundException - subjectId is not found

NullArgumentException - id or subjectId 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} .

getChildSubjectIds

IdList getChildSubjectIds(Id subjectId)
                   throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets the child Ids of the given subject.

Parameters:

subjectId - the Id to query

Returns:

the children of the subject

Throws:

NotFoundException - subjectId is not found

NullArgumentException - subjectId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getChildSubjects

SubjectList getChildSubjects(Id subjectId)
                      throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets the children of the given subject.

Parameters:

subjectId - the Id to query

Returns:

the children of the subject

Throws:

NotFoundException - subjectId is not found

NullArgumentException - subjectId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isDescendantOfSubject

boolean isDescendantOfSubject(Id id,
 Id subjectId)
                       throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Tests if an Id is a descendant of a subject.

Parameters:

id - an Id

subjectId - the Id of a subject

Returns:

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

Throws:

NotFoundException - subjectId is not found

NullArgumentException - id or subjectId 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} .

getSubjectNodeIds

Node getSubjectNodeIds(Id subjectId,
 long ancestorLevels,
 long descendantLevels,
 boolean includeSiblings)
                throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets a portion of the hierarchy for the given subject.

Parameters:

subjectId - 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:

a subject node

Throws:

NotFoundException - subjectId is not found

NullArgumentException - subjectId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getSubjectNodes

SubjectNode getSubjectNodes(Id subjectId,
 long ancestorLevels,
 long descendantLevels,
 boolean includeSiblings)
                     throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets a portion of the hierarchy for the given subject.

Parameters:

subjectId - 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:

a subject node

Throws:

NotFoundException - subjectId is not found

NullArgumentException - subjectId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.