org.osid.mapping

Interface MapHierarchySession

All Superinterfaces:

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

public interface MapHierarchySession
extends OsidSession

This session defines methods for traversing a hierarchy of Map objects. Each node in the hierarchy is a unique Map. The hierarchy may be traversed recursively to establish the tree structure through getParentMaps() and getChildMaps(). To relate these Ids to another OSID, getMapNodes() can be used for retrievals that can be used for bulk lookups in other OSIDs. Any Map available in the Mapping OSID is known to this hierarchy but does not appear in the hierarchy traversal until added as a root location or a child of another location.

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 getParentMaps() or getChildMaps() 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 map view: map elements may be silently omitted or re-ordered
• plenary map view: provides a complete set or is an error condition

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canAccessMapHierarchy() Tests if this user can perform hierarchy queries.
IdList	getChildMapIds(Id mapId) Gets the child Ids of the given map.
MapList	getChildMaps(Id mapId) Gets the children of the given map.
Hierarchy	getMapHierarchy() Gets the hierarchy associated with this session.
Id	getMapHierarchyId() Gets the hierarchy Id associated with this session.
Node	getMapNodeIds(Id mapId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given map.
MapNode	getMapNodes(Id mapId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given map.
IdList	getParentMapIds(Id mapId) Gets the parent Ids of the given map.
MapList	getParentMaps(Id mapId) Gets the parents of the given map.
IdList	getRootMapIds() Gets the root map Ids in this hierarchy.
MapList	getRootMaps() Gets the root map in the map hierarchy.
boolean	hasChildMaps(Id mapId) Tests if a map has any children.
boolean	hasParentMaps(Id mapId) Tests if the Map has any parents.
boolean	isAncestorOfMap(Id id, Id mapId) Tests if an Id is an ancestor of a map.
boolean	isChildOfMap(Id id, Id mapId) Tests if a map is a direct child of another.
boolean	isDescendantOfMap(Id id, Id mapId) Tests if an Id is a descendant of a map.
boolean	isParentOfMap(Id id, Id mapId) Tests if an Id is a direct parent of map.
void	useComparativeMapView() The returns from the map methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	usePlenaryMapView() A complete view of the Maps 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

getMapHierarchyId

Id getMapHierarchyId()

Gets the hierarchy Id associated with this session.

Returns:

the hierarchy Id associated with this session

Compliance:

mandatory - This method must be implemented.

getMapHierarchy

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

canAccessMapHierarchy

boolean canAccessMapHierarchy()

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.

useComparativeMapView

void useComparativeMapView()

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

usePlenaryMapView

void usePlenaryMapView()

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

getRootMapIds

IdList getRootMapIds()
                     throws OperationFailedException,
                            PermissionDeniedException

Gets the root map Ids in this hierarchy.

Returns:

the root map Ids

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRootMaps

MapList getRootMaps()
                    throws OperationFailedException,
                           PermissionDeniedException

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

Returns:

the root maps

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

hasParentMaps

boolean hasParentMaps(Id mapId)
                      throws NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

Tests if the Map has any parents.

Parameters:

mapId - a map Id

Returns:

true if the map has parents, f alse otherwise

Throws:

NotFoundException - mapId is not found

NullArgumentException - mapId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isParentOfMap

boolean isParentOfMap(Id id,
                    Id mapId)
                      throws NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

Tests if an Id is a direct parent of map.

Parameters:

id - an Id

mapId - the Id of a map

Returns:

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

Throws:

NotFoundException - mapId is not found

NullArgumentException - id or mapId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getParentMapIds

IdList getParentMapIds(Id mapId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Gets the parent Ids of the given map.

Parameters:

mapId - a map Id

Returns:

the parent Ids of the map

Throws:

NotFoundException - mapId is not found

NullArgumentException - mapId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getParentMaps

MapList getParentMaps(Id mapId)
                      throws NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

Gets the parents of the given map.

Parameters:

mapId - the Id to query

Returns:

the parents of the map

Throws:

NotFoundException - mapId not found

NullArgumentException - mapId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isAncestorOfMap

boolean isAncestorOfMap(Id id,
                      Id mapId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Tests if an Id is an ancestor of a map.

Parameters:

id - an Id

mapId - the Id of a map

Returns:

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

Throws:

NotFoundException - mapId not found

NullArgumentException - mapId or id is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

hasChildMaps

boolean hasChildMaps(Id mapId)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Tests if a map has any children.

Parameters:

mapId - a map Id

Returns:

true if the mapId has children, false otherwise

Throws:

NotFoundException - mapId not found

NullArgumentException - mapId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isChildOfMap

boolean isChildOfMap(Id id,
                   Id mapId)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Tests if a map is a direct child of another.

Parameters:

id - an Id

mapId - the Id of a map

Returns:

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

Throws:

NotFoundException - mapId not found

NullArgumentException - id or mapId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getChildMapIds

IdList getChildMapIds(Id mapId)
                      throws NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

Gets the child Ids of the given map.

Parameters:

mapId - the Id to query

Returns:

the children of the map

Throws:

NotFoundException - mapId not found

NullArgumentException - mapId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getChildMaps

MapList getChildMaps(Id mapId)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Gets the children of the given map.

Parameters:

mapId - the Id to query

Returns:

the children of the map

Throws:

NotFoundException - mapId not found

NullArgumentException - mapId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isDescendantOfMap

boolean isDescendantOfMap(Id id,
                        Id mapId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Tests if an Id is a descendant of a map.

Parameters:

id - an Id

mapId - the Id of a map

Returns:

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

Throws:

NotFoundException - mapId not found

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

getMapNodeIds

Node getMapNodeIds(Id mapId,
                 long ancestorLevels,
                 long descendantLevels,
                 boolean includeSiblings)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

Gets a portion of the hierarchy for the given map.

Parameters:

mapId - the Id to query

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

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

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

Returns:

a map node

Throws:

NotFoundException - mapId not found

NullArgumentException - mapId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getMapNodes

MapNode getMapNodes(Id mapId,
                  long ancestorLevels,
                  long descendantLevels,
                  boolean includeSiblings)
                    throws NotFoundException,
                           OperationFailedException,
                           PermissionDeniedException

Gets a portion of the hierarchy for the given map.

Parameters:

mapId - the Id to query

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

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

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

Returns:

a map node

Throws:

NotFoundException - mapId not found

NullArgumentException - mapId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.