public interface LocationHierarchySession extends OsidSession
This session defines methods for traversing a hierarchy of
Location
objects. Each node in the hierarchy is a unique
Location.
The hierarchy may be traversed recursively to establish
the tree structure through getParentLocations()
and
getChildLocations().
To relate these Ids
to another
OSID, getLocationNodes()
can be used for retrievals that
can be used for bulk lookups in other OSIDs. Any Location
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 getParentMLocations()
or getChildLocations()
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.
Modifier and Type | Method and Description |
---|---|
boolean |
canAccessLocationHierarchy()
Tests if this user can perform hierarchy queries.
|
IdList |
getChildLocationIds(Id locationId)
Gets the child
Ids of the given location. |
LocationList |
getChildLocations(Id locationId)
Gets the children of the given location.
|
Hierarchy |
getLocationHierarchy()
Gets the hierarchy associated with this session.
|
Id |
getLocationHierarchyId()
Gets the hierarchy
Id associated with this session. |
Node |
getLocationNodeIds(Id locationId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given location.
|
LocationNode |
getLocationNodes(Id locationId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given location.
|
IdList |
getParentLocationIds(Id locationId)
Gets the parent
Ids of the given location. |
LocationList |
getParentLocations(Id locationId)
Gets the parents of the given location.
|
IdList |
getRootLocationIds()
Gets the root location
Ids in this hierarchy. |
LocationList |
getRootLocations()
Gets the root location in the location hierarchy.
|
boolean |
hasChildLocations(Id locationId)
Tests if a location has any children.
|
boolean |
hasParentLocations(Id locationId)
Tests if the
Location has any parents. |
boolean |
isAncestorOfLocation(Id id,
Id locationId)
Tests if an
Id is an ancestor of a location. |
boolean |
isChildOfLocation(Id id,
Id locationId)
Tests if a location is a direct child of another.
|
boolean |
isDescendantOfLocation(Id id,
Id locationId)
Tests if an
Id is a descendant of a location. |
boolean |
isParentOfLocation(Id id,
Id locationId)
Tests if an
Id is a direct parent of location. |
void |
useComparativeLocationView()
The returns from the location methods may omit or translate elements
based on this session, such as authorization, and not result in an
error.
|
void |
usePlenaryLocationView()
A complete view of the
Locations returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getLocationHierarchyId()
Id
associated with this session. Id
associated with this sessionmandatory
- This method must be implemented. Hierarchy getLocationHierarchy() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canAccessLocationHierarchy()
PERMISSION_DENIED.
This is intended as a hint to an
application that may opt not to offer lookup operations. false
if hierarchy traversal methods are not
authorized, true
otherwisemandatory
- This method must be implemented. void useComparativeLocationView()
mandatory
- This method is must be implemented. void usePlenaryLocationView()
Locations
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.mandatory
- This method is must be implemented. IdList getRootLocationIds() throws OperationFailedException, PermissionDeniedException
Ids
in this hierarchy. Ids
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. LocationList getRootLocations() throws OperationFailedException, PermissionDeniedException
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.OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method is must be implemented. boolean hasParentLocations(Id locationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Location
has any parents.locationId
- a location Id
true
if the location has parents, f alse
otherwiseNotFoundException
- locationId
is not
foundNullArgumentException
- locationId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isParentOfLocation(Id id, Id locationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a direct parent of location.id
- an Id
locationId
- the Id
of a location true
if this id
is a parent of
locationId,
f alse
otherwiseNotFoundException
- locationId
is not
foundNullArgumentException
- id
or
locationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getParentLocationIds(Id locationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given location.locationId
- a location Id
Ids
of the locationNotFoundException
- locationId
is not
foundNullArgumentException
- locationId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. LocationList getParentLocations(Id locationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
locationId
- a location Id
NotFoundException
- locationId
is not
foundNullArgumentException
- locationId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isAncestorOfLocation(Id id, Id locationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is an ancestor of a location.id
- an Id
locationId
- the Id
of a location tru
e if this id
is an ancestor
of locationId,
false
otherwiseNotFoundException
- locationId
is not
foundNullArgumentException
- id
or
locationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
boolean hasChildLocations(Id locationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
locationId
- a location Id
true
if the locationId
has
children, false
otherwiseNotFoundException
- locationId
is not
foundNullArgumentException
- locationId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isChildOfLocation(Id id, Id locationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id
- an Id
locationId
- a location Id
true
if the id
is a child of
locationId,
false
otherwiseNotFoundException
- locationId
is not
foundNullArgumentException
- id
or
locationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getChildLocationIds(Id locationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given location.locationId
- a location Id
NotFoundException
- locationId
is not
foundNullArgumentException
- locationId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. LocationList getChildLocations(Id locationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
locationId
- a location Id
NotFoundException
- locationId
is not
foundNullArgumentException
- locationId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isDescendantOfLocation(Id id, Id locationId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a descendant of a location.id
- an Id
locationId
- the Id
of a location true
if the id
is a descendant
of the locationId,
false
otherwiseNotFoundException
- locationId
not foundNullArgumentException
- id
or
locationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
is not found return false.
Node getLocationNodeIds(Id locationId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
locationId
- the Id
to queryancestorLevels
- 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 siblingsNotFoundException
- locationId
is not
foundNullArgumentException
- locationId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. LocationNode getLocationNodes(Id locationId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
locationId
- the Id
to queryancestorLevels
- 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 siblingsNotFoundException
- locationId
is not
foundNullArgumentException
- locationId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.