org.osid.dictionary

Interface DictionaryHierarchySession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

public interface DictionaryHierarchySession
extends OsidSession

This session defines methods for traversing a hierarchy of Dictionary objects. Each node in the hierarchy is a unique Dictionary. The hierarchy may be traversed recursively to establish the tree structure through getParentDIctionaries() and getChildDictionaries(). To relate these Ids to another OSID, getDictionaryNodes() can be used for retrievals that can be used for bulk lookups in other OSIDs. Any Dictionary available in the Dictionary 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 getParentDictionaries() or getChildDictionaries() 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: dictionary 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	canAccessDictionaryHierarchy() Tests if this user can perform hierarchy queries.
DictionaryList	getChildDictionaries(Id dictionaryId) Gets the child dictionaries of the given id.
IdList	getChildDictionaryIds(Id dictionaryId) Gets the child Ids of the given dictionary.
Hierarchy	getDictionaryHierarchy() Gets the hierarchy associated with this session.
Id	getDictionaryHierarchyId() Gets the hierarchy Id associated with this session.
Node	getDictionaryNodeIds(Id dictionaryId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given dictionary.
DictionaryNode	getDictionaryNodes(Id dictionaryId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given dictionary.
DictionaryList	getParentDictionaries(Id dictionaryId) Gets the parent dictionaries of the given id.
IdList	getParentDictionaryIds(Id dictionaryId) Gets the parent Ids of the given dictionary.
DictionaryList	getRootDictionaries() Gets the root subjects in the dictionary hierarchy.
IdList	getRootDictionaryIds() Gets the root dictionary Ids in this hierarchy.
boolean	hasChildDictionaries(Id dictionaryId) Tests if a dictionary has any children.
boolean	hasParentDictionaries(Id dictionaryId) Tests if the Dictionary has any parents.
boolean	isAncestorOfDictionary(Id id, Id dictionaryId) Tests if an Id is an ancestor of a dictionary.
boolean	isChildOfDictionary(Id id, Id dictionaryId) Tests if a dictionary is a direct child of another.
boolean	isDescendantOfDictionary(Id id, Id dictionaryId) Tests if an Id is a descendant of a dictionary.
boolean	isParentOfDictionary(Id id, Id dictionaryId) Tests if an Id is a direct parent of dictionary.
void	useComparativeDictionaryView() The returns from the dictionary methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	usePlenaryDictionaryView() A complete view of the Dictionary 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

getDictionaryHierarchyId

Id getDictionaryHierarchyId()

Gets the hierarchy Id associated with this session.

Returns:

the hierarchy Id associated with this session

Compliance:

mandatory - This method must be implemented.

getDictionaryHierarchy

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

canAccessDictionaryHierarchy

boolean canAccessDictionaryHierarchy()

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.

Returns:

false if hierarchy traversal methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeDictionaryView

void useComparativeDictionaryView()

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

usePlenaryDictionaryView

void usePlenaryDictionaryView()

A complete view of the Dictionary 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.

getRootDictionaryIds

IdList getRootDictionaryIds()
                            throws OperationFailedException,
                                   PermissionDeniedException

Gets the root dictionary Ids in this hierarchy.

Returns:

the root dictionary Ids

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRootDictionaries

DictionaryList getRootDictionaries()
                                   throws OperationFailedException,
                                          PermissionDeniedException

Gets the root subjects in the dictionary hierarchy. A node with no parents is an orphan. While all dictionary Ids are known to the hierarchy, an orphan does not appear in the hierarchy unless explicitly added as a root node or child of another node.

Returns:

the root dictionaries

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

hasParentDictionaries

boolean hasParentDictionaries(Id dictionaryId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Tests if the Dictionary has any parents.

Parameters:

dictionaryId - a dictionary Id

Returns:

true if the dictionary has parents, f alse otherwise

Throws:

NotFoundException - dictionaryId is not found

NullArgumentException - dictionaryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isParentOfDictionary

boolean isParentOfDictionary(Id id,
                           Id dictionaryId)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Tests if an Id is a direct parent of dictionary.

Parameters:

id - an Id

dictionaryId - the Id of a dictionary

Returns:

true if this id is a parent of dictionaryId, f alse otherwise

Throws:

NotFoundException - dictionaryId is not found

NullArgumentException - id or dictionaryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getParentDictionaryIds

IdList getParentDictionaryIds(Id dictionaryId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Gets the parent Ids of the given dictionary.

Parameters:

dictionaryId - a dictionary Id

Returns:

the parent Ids of the dictionary

Throws:

NotFoundException - dictionaryId is not found

NullArgumentException - dictionaryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getParentDictionaries

DictionaryList getParentDictionaries(Id dictionaryId)
                                     throws NotFoundException,
                                            OperationFailedException,
                                            PermissionDeniedException

Gets the parent dictionaries of the given id.

Parameters:

dictionaryId - the Id of the Dictionary to query

Returns:

the parent dictionaries of the id

Throws:

NotFoundException - a Dictionary identified by Id is not found

NullArgumentException - dictionaryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isAncestorOfDictionary

boolean isAncestorOfDictionary(Id id,
                             Id dictionaryId)
                               throws NotFoundException,
                                      OperationFailedException,
                                      PermissionDeniedException

Tests if an Id is an ancestor of a dictionary.

Parameters:

id - an Id

dictionaryId - the Id of a dictionary

Returns:

tru e if this id is an ancestor of dictionaryId, false otherwise

Throws:

NotFoundException - dictionaryId is not found

NullArgumentException - dictionaryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

hasChildDictionaries

boolean hasChildDictionaries(Id dictionaryId)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Tests if a dictionary has any children.

Parameters:

dictionaryId - a dictionary Id

Returns:

true if the dictionaryId has children, false otherwise

Throws:

NotFoundException - dictionaryId is not found

NullArgumentException - dictionaryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isChildOfDictionary

boolean isChildOfDictionary(Id id,
                          Id dictionaryId)
                            throws NotFoundException,
                                   OperationFailedException,
                                   PermissionDeniedException

Tests if a dictionary is a direct child of another.

Parameters:

id - an Id

dictionaryId - the Id of a dictionary

Returns:

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

Throws:

NotFoundException - dictionaryId is not found

NullArgumentException - id or dictionaryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getChildDictionaryIds

IdList getChildDictionaryIds(Id dictionaryId)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Gets the child Ids of the given dictionary.

Parameters:

dictionaryId - the Id to query

Returns:

the children of the dictionary

Throws:

NotFoundException - dictionaryId is not found

NullArgumentException - dictionaryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getChildDictionaries

DictionaryList getChildDictionaries(Id dictionaryId)
                                    throws NotFoundException,
                                           OperationFailedException,
                                           PermissionDeniedException

Gets the child dictionaries of the given id.

Parameters:

dictionaryId - the Id of the Dictionary to query

Returns:

the child dictionaries of the id

Throws:

NotFoundException - a Dictionary identified by Id is not found

NullArgumentException - dictionaryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isDescendantOfDictionary

boolean isDescendantOfDictionary(Id id,
                               Id dictionaryId)
                                 throws NotFoundException,
                                        OperationFailedException,
                                        PermissionDeniedException

Tests if an Id is a descendant of a dictionary.

Parameters:

id - an Id

dictionaryId - the Id of a dictionary

Returns:

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

Throws:

NotFoundException - dictionaryId not found

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

getDictionaryNodeIds

Node getDictionaryNodeIds(Id dictionaryId,
                        long ancestorLevels,
                        long descendantLevels,
                        boolean includeSiblings)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Gets a portion of the hierarchy for the given dictionary.

Parameters:

dictionaryId - 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 dictionary node

Throws:

NotFoundException - dictionaryId is not found

NullArgumentException - dictionaryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getDictionaryNodes

DictionaryNode getDictionaryNodes(Id dictionaryId,
                                long ancestorLevels,
                                long descendantLevels,
                                boolean includeSiblings)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

Gets a portion of the hierarchy for the given dictionary.

Parameters:

dictionaryId - 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 dictionary node

Throws:

NotFoundException - dictionaryId is not found

NullArgumentException - dictionaryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.