org.osid.messaging

Interface MailboxHierarchySession

All Superinterfaces:

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

public interface MailboxHierarchySession
extends OsidSession

This session defines methods for traversing a hierarchy of Mailbox objects. Each node in the hierarchy is a unique Mailbox. The hierarchy may be traversed recursively to establish the tree structure through getParentMailboxes() and getChildMailboxes(). To relate these Ids to another OSID, getMailboxNodes() can be used for retrievals that can be used for bulk lookups in other OSIDs. Any Mailbox available in the Mailbox 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 getParentMailboxes() or getChildMailboxes() 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 view: mailbox elements may be silently omitted or re-ordered
• plenary view: provides a complete set or is an error condition

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canAccessMailboxHierarchy() Tests if this user can perform hierarchy queries.
MailboxList	getChildMailboxes(Id mailboxId) Gets the children of the given mailbox.
IdList	getChildMailboxIds(Id mailboxId) Gets the child Ids of the given mailbox.
Hierarchy	getMailboxHierarchy() Gets the hierarchy associated with this session.
Id	getMailboxHierarchyId() Gets the hierarchy Id associated with this session.
Node	getMailboxNodeIds(Id mailboxId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given mailbox.
MailboxNode	getMailboxNodes(Id mailboxId, long ancestorLevels, long descendantLevels, boolean includeSiblings) Gets a portion of the hierarchy for the given mailbox.
MailboxList	getParentMailboxes(Id mailboxId) Gets the parents of the given mailbox.
IdList	getParentMailboxIds(Id mailboxId) Gets the parent Ids of the given mailbox.
MailboxList	getRootMailboxes() Gets the root mailboxes in the mailbox hierarchy.
IdList	getRootMailboxIds() Gets the root mailbox Ids in this hierarchy.
boolean	hasChildMailboxes(Id mailboxId) Tests if a mailbox has any children.
boolean	hasParentMailboxes(Id mailboxId) Tests if the Mailbox has any parents.
boolean	isAncestorOfMailbox(Id id, Id mailboxId) Tests if an Id is an ancestor of a mailbox.
boolean	isChildOfMailbox(Id id, Id mailboxId) Tests if a mailbox is a direct child of another.
boolean	isDescendantOfMailbox(Id id, Id mailboxId) Tests if an Id is a descendant of a mailbox.
boolean	isParentOfMailbox(Id id, Id mailboxId) Tests if an Id is a direct parent of a mailbox.
void	useComparativeMailboxView() The returns from the mailbox methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	usePlenaryMailboxView() A complete view of the Mailbox 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

getMailboxHierarchyId

Id getMailboxHierarchyId()

Gets the hierarchy Id associated with this session.

Returns:

the hierarchy Id associated with this session

Compliance:

mandatory - This method must be implemented.

getMailboxHierarchy

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

canAccessMailboxHierarchy

boolean canAccessMailboxHierarchy()

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.

useComparativeMailboxView

void useComparativeMailboxView()

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

usePlenaryMailboxView

void usePlenaryMailboxView()

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

getRootMailboxIds

IdList getRootMailboxIds()
                         throws OperationFailedException,
                                PermissionDeniedException

Gets the root mailbox Ids in this hierarchy.

Returns:

the root mailbox Ids

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRootMailboxes

MailboxList getRootMailboxes()
                             throws OperationFailedException,
                                    PermissionDeniedException

Gets the root mailboxes in the mailbox hierarchy. A node with no parents is an orphan. While all mailbox 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.

Returns:

the root mailboxes

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

hasParentMailboxes

boolean hasParentMailboxes(Id mailboxId)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Tests if the Mailbox has any parents.

Parameters:

mailboxId - a mailbox Id

Returns:

true if the mailbox has parents, false otherwise

Throws:

NotFoundException - mailboxId is not found

NullArgumentException - mailboxId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isParentOfMailbox

boolean isParentOfMailbox(Id id,
                        Id mailboxId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Tests if an Id is a direct parent of a mailbox.

Parameters:

id - an Id

mailboxId - a mailbox Id

Returns:

true if this id is a parent of mailboxId, false otherwise

Throws:

NotFoundException - mailboxId is not found

NullArgumentException - id or mailboxId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

getParentMailboxIds

IdList getParentMailboxIds(Id mailboxId)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Gets the parent Ids of the given mailbox.

Parameters:

mailboxId - a mailbox Id

Returns:

the parent Ids of the mailbox

Throws:

NotFoundException - mailboxId is not found

NullArgumentException - mailboxId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getParentMailboxes

MailboxList getParentMailboxes(Id mailboxId)
                               throws NotFoundException,
                                      OperationFailedException,
                                      PermissionDeniedException

Gets the parents of the given mailbox.

Parameters:

mailboxId - the Id to query

Returns:

the parents of the mailbox

Throws:

NotFoundException - mailboxId not found

NullArgumentException - mailboxId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isAncestorOfMailbox

boolean isAncestorOfMailbox(Id id,
                          Id mailboxId)
                            throws NotFoundException,
                                   OperationFailedException,
                                   PermissionDeniedException

Tests if an Id is an ancestor of a mailbox.

Parameters:

id - an Id

mailboxId - the Id of a mailbox

Returns:

true if this id is an ancestor of mailboxId, false otherwise

Throws:

NotFoundException - mailboxId not found

NullArgumentException - mailboxId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

If - id not found return false.

hasChildMailboxes

boolean hasChildMailboxes(Id mailboxId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Tests if a mailbox has any children.

Parameters:

mailboxId - a mailboxId

Returns:

true if the mailboxId has children, false otherwise

Throws:

NotFoundException - mailboxId not found

NullArgumentException - mailboxId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isChildOfMailbox

boolean isChildOfMailbox(Id id,
                       Id mailboxId)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Tests if a mailbox is a direct child of another.

Parameters:

id - an Id

mailboxId - the Id of a mailbox

Returns:

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

Throws:

NotFoundException - mailboxId not found

NullArgumentException - mailboxId 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.

getChildMailboxIds

IdList getChildMailboxIds(Id mailboxId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

Gets the child Ids of the given mailbox.

Parameters:

mailboxId - the Id to query

Returns:

the children of the mailbox

Throws:

NotFoundException - mailboxId not found

NullArgumentException - mailboxId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getChildMailboxes

MailboxList getChildMailboxes(Id mailboxId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Gets the children of the given mailbox.

Parameters:

mailboxId - the Id to query

Returns:

the children of the mailbox

Throws:

NotFoundException - mailboxId not found

NullArgumentException - mailboxId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

isDescendantOfMailbox

boolean isDescendantOfMailbox(Id id,
                            Id mailboxId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Tests if an Id is a descendant of a mailbox.

Parameters:

id - an Id

mailboxId - the Id of a mailbox

Returns:

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

Throws:

NotFoundException - mailboxId not found

NullArgumentException - mailboxId 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.

getMailboxNodeIds

Node getMailboxNodeIds(Id mailboxId,
                     long ancestorLevels,
                     long descendantLevels,
                     boolean includeSiblings)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Gets a portion of the hierarchy for the given mailbox.

Parameters:

mailboxId - the Id to query

ancestorLevels - 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 siblings

Returns:

a mailbox node

Throws:

NotFoundException - mailboxId not found

NullArgumentException - mailboxId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getMailboxNodes

MailboxNode getMailboxNodes(Id mailboxId,
                          long ancestorLevels,
                          long descendantLevels,
                          boolean includeSiblings)
                            throws NotFoundException,
                                   OperationFailedException,
                                   PermissionDeniedException

Gets a portion of the hierarchy for the given mailbox.

Parameters:

mailboxId - the Id to query

ancestorLevels - 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 siblings

Returns:

a mailbox node

Throws:

NotFoundException - mailboxId not found

NullArgumentException - mailboxId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.