org.osid.messaging

Interface ReceiptNotificationSession

All Superinterfaces:

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

public interface ReceiptNotificationSession
extends OsidSession

This session defines methods to receive notifications on new and changed Receipts in this Mailbox. This also includes existing receipts that may appear or disappear due to changes in the Mailbox hierarchy, This session is intended for consumers needing to synchronize their receipts with this service without the use of polling. Notifications are cancelled when this session is closed.

The two views defined in this session correspond to the views in the ReceiptLookupSession.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canRegisterForReceiptNotifications() Tests if this user can register for Receipt notifications.
Mailbox	getMailbox() Gets the Mailbox associated with this session.
Id	getMailboxId() Gets the Mailbox Id associated with this session.
void	registerForChangedReceipt(Id receiptId) Registers for notification of an updated receipt.
void	registerForChangedReceipts() Registers for notification of updated receipts.
void	registerForChangedReceiptsByRecipient(Id recipientId) Register for notifications of updated receipts for the specified recipient.
void	registerForChangedReceiptsForMessage(Id messageId) Register for notifications of updated receipts for the specified message.
void	registerForDeletedReceipt(Id receiptId) Registers for notification of a deleted receipt.
void	registerForDeletedReceipts() Registers for notification of receipts whose messages have been deleted or removed from this mailbox.
void	registerForDeletedReceiptsByRecipient(Id recipientId) Register for notifications of deleted receipts for the specified recipient.
void	registerForDeletedReceiptsForMessage(Id messageId) Register for notifications of deleted receipts for the specified message.
void	registerForNewReceipts() Register for notifications of new receipts.
void	registerForNewReceiptsByRecipient(Id recipientId) Register for notifications of new receipts for the specified recipient.
void	registerForNewReceiptsForMessage(Id messageId) Register for notifications of new receipts for the specified message.
void	useFederatedMailboxView() Federates the view for methods in this session.
void	useIsolatedMailboxView() Isolates the view for methods in this session.

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.

canRegisterForReceiptNotifications

boolean canRegisterForReceiptNotifications()

Tests if this user can register for Receipt notifications. 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 notification operations.

Returns:

false if notification methods are not authorized, true otherwise

Compliance:

mandatory - This method 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 notifications to this mailbox only.

Compliance:

mandatory - This method is must be implemented.

registerForNewReceipts

void registerForNewReceipts()
                            throws OperationFailedException,
                                   PermissionDeniedException

Register for notifications of new receipts. ReceiptReceiver.newReceipts() is invoked when a new Receipt is appears in this mailbox.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewReceiptsForMessage

void registerForNewReceiptsForMessage(Id messageId)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Register for notifications of new receipts for the specified message. ReceiptReceiver.newReceipts() is invoked when a new Receipt is appears in this mailbox.

Parameters:

messageId - the Id of the Message to monitor

Throws:

NullArgumentException - messageId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForNewReceiptsByRecipient

void registerForNewReceiptsByRecipient(Id recipientId)
                                       throws OperationFailedException,
                                              PermissionDeniedException

Register for notifications of new receipts for the specified recipient. ReceiptReceiver.newReceipst() is invoked when a new Receipt is appears in this mailbox.

Parameters:

recipientId - the Id of the Resource to monitor

Throws:

NullArgumentException - recipientId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedReceipts

void registerForChangedReceipts()
                                throws OperationFailedException,
                                       PermissionDeniedException

Registers for notification of updated receipts. ReceiptReceiver.changedReceipts() is invoked when a receipt in this mailbox is changed.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedReceiptsForMessage

void registerForChangedReceiptsForMessage(Id messageId)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Register for notifications of updated receipts for the specified message. ReceiptReceiver.changedReceipts() is invoked when a Receipt in this mailbox is changed.

Parameters:

messageId - the Id of the Message to monitor

Throws:

NullArgumentException - messageId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedReceiptsByRecipient

void registerForChangedReceiptsByRecipient(Id recipientId)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

Register for notifications of updated receipts for the specified recipient. ReceiptReceiver.changedReceipts() is invoked when a Receipt in this mailbox is changed.

Parameters:

recipientId - the Id of the Resource to monitor

Throws:

NullArgumentException - recipientId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForChangedReceipt

void registerForChangedReceipt(Id receiptId)
                               throws OperationFailedException,
                                      PermissionDeniedException

Registers for notification of an updated receipt. ReceiptReceiver.changedReceipt() is invoked when the specified receipt in this mailbox is changed.

Parameters:

receiptId - the Id of the Receipt to monitor

Throws:

NullArgumentException - receiptId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedReceipts

void registerForDeletedReceipts()
                                throws OperationFailedException,
                                       PermissionDeniedException

Registers for notification of receipts whose messages have been deleted or removed from this mailbox. ReceiptReceiver.deletedReceipts() is invoked when a receipt is deleted or removed from this mailbox.

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedReceiptsForMessage

void registerForDeletedReceiptsForMessage(Id messageId)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Register for notifications of deleted receipts for the specified message. ReceiptReceiver.deletedReceipts() is invoked when a Receipt in this mailbox is removed.

Parameters:

messageId - the Id of the Message to monitor

Throws:

NullArgumentException - messageId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedReceiptsByRecipient

void registerForDeletedReceiptsByRecipient(Id recipientId)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

Register for notifications of deleted receipts for the specified recipient. ReceiptReceiver.deletedReceipts() is invoked when a Receipt in this mailbox is removed.

Parameters:

recipientId - the Id of the Resource to monitor

Throws:

NullArgumentException - recipientId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

registerForDeletedReceipt

void registerForDeletedReceipt(Id receiptId)
                               throws OperationFailedException,
                                      PermissionDeniedException

Registers for notification of a deleted receipt. MessageReceiver.deletedReceipts() is invoked when the specified receipt is deleted or removed from this mailbox.

Parameters:

receiptId - the Id of the Receipt to monitor

Throws:

NullArgumentException - receiptId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.