org.osid.messaging

Interface ReceiptLookupSession

All Superinterfaces:

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

public interface ReceiptLookupSession
extends OsidSession

This session defines methods for retrieving receipts to messages.

This lookup session defines several views:

• comparative view: elements may be silently omitted or re-ordered
• plenary view: provides a complete result set or is an error condition
• isolated mailbox view: All receipt methods in this session operate, retrieve and pertain to receipts and messages defined explicitly in the current mailbox.
• federated mailbox view: All receipt methods in this session operate, retrieve and pertain to all receipts and messages defined in this mailbox and any other messages implicitly available in this mailbox through mailbox inheritence.

The methods useFederatedReceiptView() and useIsolatedReceiptView() behave as a radio group and one should be selected before invoking any lookup methods.

Messages may have an additional records indicated by their respective record types. The record may not be accessed through a cast of the Message.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupReceipts() Tests if this user can perform Receipt lookups.
Mailbox	getMailbox() Gets the Mailbox associated with this session.
Id	getMailboxId() Gets the Mailbox Id associated with this session.
Receipt	getReceipt(Id receiptId) Gets the Receipt specified by its Id.
ReceiptList	getReceipts() Gets all Receipts.
ReceiptList	getReceiptsByGenusType(Type receiptGenusType) Gets a ReceiptList corresponding to the given receipt genus Type which does not include receipts of types derived from the specified Type.
ReceiptList	getReceiptsByIds(IdList receiptIds) Gets a ReceiptList corresponding to the given IdList.
ReceiptList	getReceiptsByParentGenusType(Type receiptGenusType) Gets a ReceiptList corresponding to the given receipt genus Type and include any additional receipts with genus types derived from the specified Type.
ReceiptList	getReceiptsByRecordType(Type receiptRecordType) Gets a ReceiptList containing the given receipt record Type.
ReceiptList	getReceiptsForMessage(Id messageId) Gets a ReceiptList for the given message.
ReceiptList	getReceiptsForMessageAndRecipient(Id messageId, Id resourceId) Gets a list of Receipts for the given message and recipient.
ReceiptList	getReceiptsForRecipient(Id resourceId) Gets a ReceiptList for the given recipient.
void	useComparativeReceiptView() The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	useFederatedMailboxView() Federates the view for methods in this session.
void	useIsolatedMailboxView() Isolates the view for methods in this session.
void	usePlenaryReceiptView() A complete view of the Receipt 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

getMailboxId

Id getMailboxId()

Gets the Mailbox Id associated with this session.

Returns:

the Mailbox Id associated with this session

Compliance:

mandatory - This method must be implemented.

getMailbox

Mailbox getMailbox()
                   throws OperationFailedException,
                          PermissionDeniedException

Gets the Mailbox associated with this session.

Returns:

the Mailbox associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupReceipts

boolean canLookupReceipts()

Tests if this user can perform Receipt lookups. 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 lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeReceiptView

void useComparativeReceiptView()

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

usePlenaryReceiptView

void usePlenaryReceiptView()

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

useFederatedMailboxView

void useFederatedMailboxView()

Federates the view for methods in this session. A federated view will include receipts in mailboxes which are children of this mailbox in the mailbox hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedMailboxView

void useIsolatedMailboxView()

Isolates the view for methods in this session. An isolated view restricts lookups to this mailbox only.

Compliance:

mandatory - This method is must be implemented.

getReceipt

Receipt getReceipt(Id receiptId)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

Gets the Receipt specified by its Id. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Receipt may have a different Id than requested, such as the case where a duplicate Id was assigned to a Receipt and retained for compatibility.

Parameters:

receiptId - the Id of the Receipt to retrieve

Returns:

the returned Receipt

Throws:

NotFoundException - no Receipt found with the given Id

NullArgumentException - receiptId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getReceiptsByIds

ReceiptList getReceiptsByIds(IdList receiptIds)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Gets a ReceiptList corresponding to the given IdList. In plenary mode, the returned list contains all of the receipts specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible Receipts may be omitted from the list and may present the elements in any order including returning a unique set.

Parameters:

receiptIds - the list of Ids to retrieve

Returns:

the returned Receipt list

Throws:

NotFoundException - an Id was not found

NullArgumentException - receiptIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getReceiptsByGenusType

ReceiptList getReceiptsByGenusType(Type receiptGenusType)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Gets a ReceiptList corresponding to the given receipt genus Type which does not include receipts of types derived from the specified Type. In plenary mode, the returned list contains all known receipts or an error results. Otherwise, the returned list may contain only those receipts that are accessible through this session.

Parameters:

receiptGenusType - a receipt genus type

Returns:

the returned Receipts list

Throws:

NullArgumentException - receiptGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getReceiptsByParentGenusType

ReceiptList getReceiptsByParentGenusType(Type receiptGenusType)
                                         throws OperationFailedException,
                                                PermissionDeniedException

Gets a ReceiptList corresponding to the given receipt genus Type and include any additional receipts with genus types derived from the specified Type. In plenary mode, the returned list contains all known receipts or an error results. Otherwise, the returned list may contain only those receipts that are accessible through this session

Parameters:

receiptGenusType - a receipt genus type

Returns:

the returned Receipts list

Throws:

NullArgumentException - receiptGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getReceiptsByRecordType

ReceiptList getReceiptsByRecordType(Type receiptRecordType)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets a ReceiptList containing the given receipt record Type. In plenary mode, the returned list contains all known receipts or an error results. Otherwise, the returned list may contain only those receipts that are accessible through this session.

Parameters:

receiptRecordType - a receipt record type

Returns:

the returned Receipt list

Throws:

NullArgumentException - receiptRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getReceiptsForMessage

ReceiptList getReceiptsForMessage(Id messageId)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Gets a ReceiptList for the given message. In plenary mode, the returned list contains all known receipts or an error results. Otherwise, the returned list may contain only those receipts that are accessible through this session.

Parameters:

messageId - a message Id

Returns:

the returned Receipt list

Throws:

NullArgumentException - messageId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getReceiptsForRecipient

ReceiptList getReceiptsForRecipient(Id resourceId)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets a ReceiptList for the given recipient. In plenary mode, the returned list contains all known receipts or an error results. Otherwise, the returned list may contain only those receipts that are accessible through this session.

Parameters:

resourceId - a resource Id

Returns:

the returned Receipts

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getReceiptsForMessageAndRecipient

ReceiptList getReceiptsForMessageAndRecipient(Id messageId,
                                            Id resourceId)
                                              throws OperationFailedException,
                                                     PermissionDeniedException

Gets a list of Receipts for the given message and recipient. In plenary mode, the returned list contains all known receipts or an error results. Otherwise, the returned list may contain only those receipts that are accessible through this session.

Parameters:

messageId - a message Id

resourceId - a resource Id

Returns:

the returned Receipt

Throws:

NullArgumentException - messageId or recipientId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getReceipts

ReceiptList getReceipts()
                        throws OperationFailedException,
                               PermissionDeniedException

Gets all Receipts. In plenary mode, the returned list contains all known receipts or an error results. Otherwise, the returned list may contain only those receipts that are accessible through this session.

Returns:

the returned Receipt

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.