public interface BookHierarchySession extends OsidSession
This session defines methods for traversing a hierarchy of Book
objects. Each node in the hierarchy is a unique Book.
The hierarchy may be traversed recursively to establish the tree
structure through getParentBooks()
and
getChildBooks().
To relate these Ids
to another
OSID, getBookNodes()
can be used for retrievals that can be
used for bulk lookups in other OSIDs. Any Book
available in
the Commenting 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 getParentBooks()
or getChildBooks()
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 |
canAccessBookHierarchy()
Tests if this user can perform hierarchy queries.
|
Hierarchy |
getBookHierarchy()
Gets the hierarchy associated with this session.
|
Id |
getBookHierarchyId()
Gets the hierarchy
Id associated with this session. |
Node |
getBookNodeIds(Id bookId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given book.
|
BookNode |
getBookNodes(Id bookId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given book.
|
IdList |
getChildBookIds(Id bookId)
Gets the child
Ids of the given book. |
BookList |
getChildBooks(Id bookId)
Gets the child books of the given
id. |
IdList |
getParentBookIds(Id bookId)
Gets the parent
Ids of the given book. |
BookList |
getParentBooks(Id bookId)
Gets the parent books of the given
id. |
IdList |
getRootBookIds()
Gets the root book
Ids in this hierarchy. |
BookList |
getRootBooks()
Gets the root books in the book hierarchy.
|
boolean |
hasChildBooks(Id bookId)
Tests if a book has any children.
|
boolean |
hasParentBooks(Id bookId)
Tests if the
Book has any parents. |
boolean |
isAncestorOfBook(Id id,
Id bookId)
Tests if an
Id is an ancestor of a book. |
boolean |
isChildOfBook(Id id,
Id bookId)
Tests if a book is a direct child of another.
|
boolean |
isDescendantOfBook(Id id,
Id bookId)
Tests if an
Id is a descendant of a book. |
boolean |
isParentOfBook(Id id,
Id bookId)
Tests if an
Id is a direct parent of book. |
void |
useComparativeBookView()
The returns from the book methods may omit or translate elements based
on this session, such as authorization, and not result in an error.
|
void |
usePlenaryBookView()
A complete view of the
Book returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getBookHierarchyId()
Id
associated with this session. Id
associated with this sessionmandatory
- This method must be implemented. Hierarchy getBookHierarchy() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canAccessBookHierarchy()
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 useComparativeBookView()
mandatory
- This method is must be implemented. void usePlenaryBookView()
Book
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 getRootBookIds() throws OperationFailedException, PermissionDeniedException
Ids
in this hierarchy. Ids
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. BookList getRootBooks() 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 hasParentBooks(Id bookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Book
has any parents.bookId
- a book Id
true
if the book has parents, f alse
otherwiseNotFoundException
- bookId
is not foundNullArgumentException
- bookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isParentOfBook(Id id, Id bookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a direct parent of book.id
- an Id
bookId
- the Id
of a book true
if this id
is a parent of
bookId,
f alse
otherwiseNotFoundException
- bookId
is not foundNullArgumentException
- id
or
bookId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getParentBookIds(Id bookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given book.bookId
- a book Id
Ids
of the bookNotFoundException
- bookId
is not foundNullArgumentException
- bookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. BookList getParentBooks(Id bookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id.
bookId
- the Id
of the Book
to
query id
NotFoundException
- a Book
identified by
Id is
not foundNullArgumentException
- bookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isAncestorOfBook(Id id, Id bookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is an ancestor of a book.id
- an Id
bookId
- the Id
of a book tru
e if this id
is an ancestor
of bookId,
false
otherwiseNotFoundException
- bookId
is not foundNullArgumentException
- id
or
bookId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
boolean hasChildBooks(Id bookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
bookId
- a book Id
true
if the bookId
has children,
false
otherwiseNotFoundException
- bookId
is not foundNullArgumentException
- bookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isChildOfBook(Id id, Id bookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id
- an Id
bookId
- the Id
of a book true
if the id
is a child of
bookId,
false
otherwiseNotFoundException
- bookId
is not foundNullArgumentException
- id
or
bookId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getChildBookIds(Id bookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given book.bookId
- the Id
to queryNotFoundException
- bookId
is not foundNullArgumentException
- bookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. BookList getChildBooks(Id bookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id.
bookId
- the Id
of the Book
to
query id
NotFoundException
- a Book
identified by
Id is
not foundNullArgumentException
- bookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isDescendantOfBook(Id id, Id bookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a descendant of a book.id
- an Id
bookId
- the Id
of a book true
if the id
is a descendant
of the bookId,
false
otherwiseNotFoundException
- bookId
is not foundNullArgumentException
- id
or
bookId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
is not found return false.
Node getBookNodeIds(Id bookId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
bookId
- 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
- bookId
is not foundNullArgumentException
- bookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. BookNode getBookNodes(Id bookId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
bookId
- 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
- bookId
is not foundNullArgumentException
- bookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.