public interface AddressBookHierarchySession extends OsidSession
This session defines methods for traversing a hierarchy of
AddressBook
objects. Each node in the hierarchy is a unique
AddressBook.
The hierarchy may be traversed recursively to
establish the tree structure through getParentAddressBooks()
and getChildAddressBooks().
To relate these
Ids
to another OSID, getAddressBookNodes()
can be
used for retrievals that can be used for bulk lookups in other OSIDs. Any
AddressBook
available in the Contact 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 getParentAddressBooks()
or getChildAddressBooks()
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 |
canAccessAddressBookHierarchy()
Tests if this user can perform hierarchy queries.
|
Hierarchy |
getAddressBookHierarchy()
Gets the hierarchy associated with this session.
|
Id |
getAddressBookHierarchyId()
Gets the hierarchy
Id associated with this session. |
Node |
getAddressBookNodeIds(Id addressBookId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given address book.
|
AddressBookNode |
getAddressBookNodes(Id addressBookId,
long ancestorLevels,
long descendantLevels,
boolean includeSiblings)
Gets a portion of the hierarchy for the given address book.
|
IdList |
getChildAddressBookIds(Id addressBookId)
Gets the child
Ids of the given address book. |
AddressBookList |
getChildAddressBooks(Id addressBookId)
Gets the child address books of the given
id. |
IdList |
getParentAddressBookIds(Id addressBookId)
Gets the parent
Ids of the given address book. |
AddressBookList |
getParentAddressBooks(Id addressBookId)
Gets the parent address books of the given
id. |
IdList |
getRootAddressBookIds()
Gets the root address book
Ids in this hierarchy. |
AddressBookList |
getRootAddressBooks()
Gets the root address books in the address book hierarchy.
|
boolean |
hasChildAddressBooks(Id addressBookId)
Tests if an address book has any children.
|
boolean |
hasParentAddressBooks(Id addressBookId)
Tests if the
AddressBook has any parents. |
boolean |
isAncestorOfAddressBook(Id id,
Id addressBookId)
Tests if an
Id is an ancestor of an address book. |
boolean |
isChildOfAddressBook(Id id,
Id addressBookId)
Tests if an address book is a direct child of another.
|
boolean |
isDescendantOfAddressBook(Id id,
Id addressBookId)
Tests if an
Id is a descendant of an address book. |
boolean |
isParentOfAddressBook(Id id,
Id addressBookId)
Tests if an
Id is a direct parent of address book. |
void |
useComparativeAddressBookView()
The returns from the address book methods may omit or translate
elements based on this session, such as authorization, and not result
in an error.
|
void |
usePlenaryAddressBookView()
A complete view of the
AddressBook returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getAddressBookHierarchyId()
Id
associated with this session. Id
associated with this sessionmandatory
- This method must be implemented. Hierarchy getAddressBookHierarchy() throws OperationFailedException, PermissionDeniedException
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canAccessAddressBookHierarchy()
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 useComparativeAddressBookView()
mandatory
- This method is must be implemented. void usePlenaryAddressBookView()
AddressBook
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 getRootAddressBookIds() throws OperationFailedException, PermissionDeniedException
Ids
in this hierarchy. Ids
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. AddressBookList getRootAddressBooks() 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 hasParentAddressBooks(Id addressBookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
AddressBook
has any parents.addressBookId
- an address book Id
true
if the address book has parents, f
alse
otherwiseNotFoundException
- addressBookId
is not
foundNullArgumentException
- addressBookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isParentOfAddressBook(Id id, Id addressBookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a direct parent of address book.id
- an Id
addressBookId
- the Id
of an address book true
if this id
is a parent of
addressBookId,
f alse
otherwiseNotFoundException
- addressBookId
is not
foundNullArgumentException
- id
or
addressBookId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getParentAddressBookIds(Id addressBookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given address book.addressBookId
- an address book Id
Ids
of the address bookNotFoundException
- addressBookId
is not
foundNullArgumentException
- addressBookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. AddressBookList getParentAddressBooks(Id addressBookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id.
addressBookId
- the Id
of the AddressBook
to query id
NotFoundException
- an AddressBook
identified by Id is
not foundNullArgumentException
- addressBookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isAncestorOfAddressBook(Id id, Id addressBookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is an ancestor of an address book.id
- an Id
addressBookId
- the Id
of an address book tru
e if this id
is an ancestor
of addressBookId,
false
otherwiseNotFoundException
- addressBookId
is not
foundNullArgumentException
- id
or
addressBookId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
boolean hasChildAddressBooks(Id addressBookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
addressBookId
- an address book Id
true
if the addressBookId
has
children, false
otherwiseNotFoundException
- addressBookId
is not
foundNullArgumentException
- addressBookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isChildOfAddressBook(Id id, Id addressBookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id
- an Id
addressBookId
- the Id
of an address book true
if the id
is a child of
addressBookId,
false
otherwiseNotFoundException
- addressBookId
is not
foundNullArgumentException
- id
or
addressBookId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
not found return false.
IdList getChildAddressBookIds(Id addressBookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Ids
of the given address book.addressBookId
- the Id
to queryNotFoundException
- addressBookId
is not
foundNullArgumentException
- addressBookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. AddressBookList getChildAddressBooks(Id addressBookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
id.
addressBookId
- the Id
of the AddressBook
to query id
NotFoundException
- an AddressBook
identified by Id is
not foundNullArgumentException
- addressBookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean isDescendantOfAddressBook(Id id, Id addressBookId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Id
is a descendant of an address book.id
- an Id
addressBookId
- the Id
of an address book true
if the id
is a descendant
of the addressBookId,
false
otherwiseNotFoundException
- addressBookId
is not
foundNullArgumentException
- id
or
addressBookId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. If
- id
is not found return false.
Node getAddressBookNodeIds(Id addressBookId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
addressBookId
- 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
- addressBookId
is not
foundNullArgumentException
- addressBookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. AddressBookNode getAddressBookNodes(Id addressBookId, long ancestorLevels, long descendantLevels, boolean includeSiblings) throws NotFoundException, OperationFailedException, PermissionDeniedException
addressBookId
- 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
- addressBookId
is not
foundNullArgumentException
- addressBookId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.