public interface CatalogueHierarchySession extends OsidSession
This session defines methods for traversing a hierarchy of
Catalogue
objects. Each node in the hierarchy is a unique
Catalogue.
The hierarchy may be traversed recursively to establish
the tree structure through getParentCatalogues()
and
getChildCatalogues().
To relate these Ids
to
another OSID, getCatalogueNodes()
can be used for
retrievals that can be used for bulk lookups in other OSIDs. Any
Catalogue
available in the Offering 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 getParentCatalogues()
or getChildCatalogues()
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 |
canAccessCatalogueHierarchy()
Tests if this user can perform hierarchy queries.
|
Hierarchy |
getCatalogueHierarchy()
Gets the hierarchy associated with this session.
|
Id |
getCatalogueHierarchyId()
Gets the hierarchy
Id associated with this session. |
Node |
getCatalogueNodeIds(Id catalogueId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given catalogue.
|
CatalogueNode |
getCatalogueNodes(Id catalogueId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given catalogue.
|
IdList |
getChildCatalogueIds(Id catalogueId)
Gets the child
Ids of the given catalogue. |
CatalogueList |
getChildCatalogues(Id catalogueId)
Gets the child catalogues of the given
id. |
IdList |
getParentCatalogueIds(Id catalogueId)
Gets the parent
Ids of the given catalogue. |
CatalogueList |
getParentCatalogues(Id catalogueId)
Gets the parent catalogues of the given
id. |
IdList |
getRootCatalogueIds()
Gets the root catalogue
Ids in this hierarchy. |
CatalogueList |
getRootCatalogues()
Gets the root catalogues in the catalogue hierarchy.
|
boolean |
hasChildCatalogues(Id catalogueId)
Tests if a catalogue has any children.
|
boolean |
hasParentCatalogues(Id catalogueId)
Tests if the
Catalogue has any parents. |
boolean |
isAncestorOfCatalogue(Id id,
Id catalogueId)
Tests if an
Id is an ancestor of a catalogue. |
boolean |
isChildOfCatalogue(Id id,
Id catalogueId)
Tests if a catalogue is a direct child of another.
|
boolean |
isDescendantOfCatalogue(Id id,
Id catalogueId)
Tests if an
Id is a descendant of a catalogue. |
boolean |
isParentOfCatalogue(Id id,
Id catalogueId)
Tests if an
Id is a direct parent of catalogue. |
void |
useComparativeCatalogueView()
The returns from the catalogue methods may omit or translate elements
based on this session, such as authorization, and not result in an
error.
|
void |
usePlenaryCatalogueView()
A complete view of the
Catalogue returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getCatalogueHierarchyId()
Id
associated with this session. Id
associated with this sessionmandatory
- This method must be implemented. Hierarchy getCatalogueHierarchy() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canAccessCatalogueHierarchy()
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 useComparativeCatalogueView()
mandatory
- This method is must be implemented. void usePlenaryCatalogueView()
Catalogue
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 getRootCatalogueIds() throws OperationFailedException, PermissionDeniedException
Ids
in this hierarchy. Ids
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. CatalogueList getRootCatalogues() throws OperationFailedException, PermissionDeniedException
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.OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method is must be implemented. boolean hasParentCatalogues(Id catalogueId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Catalogue
has any parents.catalogueId
- a catalogue Id
true
if the catalogue has parents, f
alse
otherwiseNotFoundException
- catalogueId
is not
foundNullArgumentException
- catalogueId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isParentOfCatalogue(Id id, Id catalogueId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a direct parent of catalogue.id
- an Id
catalogueId
- the Id
of a catalogue true
if this id
is a parent of
catalogueId,
f alse
otherwiseNotFoundException
- catalogueId
is not
foundNullArgumentException
- id
or
catalogueId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getParentCatalogueIds(Id catalogueId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given catalogue.catalogueId
- a catalogue Id
Ids
of the catalogueNotFoundException
- catalogueId
is not
foundNullArgumentException
- catalogueId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. CatalogueList getParentCatalogues(Id catalogueId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id.
catalogueId
- the Id
of the Catalogue
to query id
NotFoundException
- a Catalogue
identified by Id is
not foundNullArgumentException
- catalogueId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isAncestorOfCatalogue(Id id, Id catalogueId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is an ancestor of a catalogue.id
- an Id
catalogueId
- the Id
of a catalogue tru
e if this id
is an ancestor
of catalogueId,
false
otherwiseNotFoundException
- catalogueId
is not
foundNullArgumentException
- id
or
catalogueId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
boolean hasChildCatalogues(Id catalogueId) throws NotFoundException, OperationFailedException, PermissionDeniedException
catalogueId
- a catalogue Id
true
if the catalogueId
has
children, false
otherwiseNotFoundException
- catalogueId
is not
foundNullArgumentException
- bocatalogueId is null
okId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isChildOfCatalogue(Id id, Id catalogueId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id
- an Id
catalogueId
- the Id
of a catalogue true
if the id
is a child of
catalogueId,
false
otherwiseNotFoundException
- catalogueId
is not
foundNullArgumentException
- id
or
catalogueId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getChildCatalogueIds(Id catalogueId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given catalogue.catalogueId
- the Id
to queryNotFoundException
- catalogueId
is not
foundNullArgumentException
- catalogueId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. CatalogueList getChildCatalogues(Id catalogueId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id.
catalogueId
- the Id
of the Catalogue
to query id
NotFoundException
- a Catalogue
identified by Id is
not foundNullArgumentException
- catalogueId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isDescendantOfCatalogue(Id id, Id catalogueId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a descendant of a catalogue.id
- an Id
catalogueId
- the Id
of a catalogue true
if the id
is a descendant
of the catalogueId,
false
otherwiseNotFoundException
- catalogueId
is not
foundNullArgumentException
- id
or
catalogueId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
is not found return false.
Node getCatalogueNodeIds(Id catalogueId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
catalogueId
- the Id
to queryancestorLevels
- 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 siblingsNotFoundException
- catalogueId
is not
foundNullArgumentException
- catalogueId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. CatalogueNode getCatalogueNodes(Id catalogueId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
catalogueId
- the Id
to queryancestorLevels
- 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 siblingsNotFoundException
- catalogueId
is not
foundNullArgumentException
- catalogueId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.