org.osid.messaging

Interface ReceiptAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

ReceiptBatchAdminSession

public interface ReceiptAdminSession
extends OsidSession

This session updates Receipts. A receipt exists for all messages where receipts are supported. The data for the update is provided by the consumer via the form object. OsidForms are requested for each update and may not be reused.

ReciptForms are requested to the Receipt Id that is to be updated using getReciptFormForUpdate(). Similarly, the ReceiptForm has metadata about the data that can be updated and it can perform validation before submitting the update. The RecieptForm can only be used once for a successful update and cannot be reused.

This session includes an Id aliasing mechanism to assign an external Id to an internally assigned Id.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canUpdateReceipts() Tests if this user can update Receipts.
Mailbox	getMailbox() Gets the Mailbox associated with this session.
Id	getMailboxId() Gets the Mailbox Id associated with this session.
ReceiptForm	getReceiptFormForUpdate(Id receiptId) Gets the receipt form for updating an existing receipt.
void	updateReceipt(ReceiptForm receiptForm) Updates an existing receipt.

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.

canUpdateReceipts

boolean canUpdateReceipts()

Tests if this user can update Receipts. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Receipt will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer update operations to an unauthorized user.

Returns:

false if Receipt modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getReceiptFormForUpdate

ReceiptForm getReceiptFormForUpdate(Id receiptId)
                                    throws NotFoundException,
                                           OperationFailedException,
                                           PermissionDeniedException

Gets the receipt form for updating an existing receipt. A new receipt form should be requested for each update transaction.

Parameters:

receiptId - the Id of the Message

Returns:

the receipt form

Throws:

NotFoundException - receiptId is not found

NullArgumentException - receiptId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateReceipt

void updateReceipt(ReceiptForm receiptForm)
                   throws OperationFailedException,
                          PermissionDeniedException

Updates an existing receipt.

Parameters:

receiptForm - the form containing the elements to be updated

Throws:

IllegalStateException - receiptForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - receiptForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - receiptForm did not originate from getReceiptFormForUpdate()

Compliance:

mandatory - This method must be implemented.