Interface ReceiptLookupSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, 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 Details

    • 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.