Package com.documentum.fc.client.mq

# Interface IDfMessageQueue

public interface IDfMessageQueue
Created by IntelliJ IDEA. User: fanz Date: March 8, 2011 Time: 10:13:25 AM To change this template use File | Settings | File Templates.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `acknowledge(IDfMessage message, boolean success, String description)`
  Acknoeledges to message queue the delivery status of the specified message.
  `void`
  `acknowledge(Collection<IDfMessage> messages, boolean success, String description)`
  Acknowledges to message server the delivery status of the specified message.
  `IDfMessage`
  `acquireNext()`
  Returns the next ready message with the highest priority and the earliest creation_time, sets the message to 'acquired' state.
  `IDfMessage`
  `acquireNext(String recipient)`
  Returns the next available ready message with the highest priority and earliest creation time that is addressed the specified recipient.
  `Collection<IDfMessage>`
  `acquireNextBatch(int batchSize)`
  Returns as a collection the next upto `count` ready messages with the highest priority and earliest creation_time, sets their state to 'acquired'.
  `Collection<IDfMessage>`
  `acquireNextBatch(int batchSize, String recipient)`
  Returns as a collection the next upto `count` ready message whose recipient matches the specified message recipient, sets their state to 'acquired'.
  `IDfMessage`
  `createMessage()`
  Creates a message object that implements IDfMessage.
  `Collection<IDfMessage>`
  `get(int state)`
  Returns as a collection all the messages in the given state. if any, `null` otherwise
  `IDfMessage`
  `get(IDfId msgId)`
  Returns the message for the given message id.
  `Collection<IDfMessage>`
  `get(String predicate)`
  Returns as a collection all the messages that satisfy the specified predicates.
  `IDfMessageQueueConfig`
  `getConfig()`
  Returns the configuration object of this message queue.
  `int`
  `getCount(int state)`
  Returns the number of the messages in the specified state.
  `int`
  `getCount(String predicates)`
  Returns the number of the messages that satisfy the specified predicates
  `int`
  `purge(int state)`
  Deletes from the queue all the messages that are in the specified state.
  `int`
  `purge(IDfId msgId)`
  Deletes the specified message from the queue.
  `int`
  `purgeAll()`
  Deletes all the messages from the queue.
  `void`
  `save(IDfMessage msg)`
  Adds a message to the queue.

- ## Method Details

  - ### createMessage

    IDfMessage createMessage() throws DfException
    Creates a message object that implements IDfMessage.
    Returns:
      A message object that implements IDfMessage.
    Throws:
      `DfException` - if a server error occurs

  - ### save

    void save(IDfMessage msg) throws DfException
    Adds a message to the queue. This causes the message to be persisted in the underlying database.
    Parameters:
      `msg` - A message object.
    Throws:
      `DfException` - if a server error occurs

  - ### acquireNext

    IDfMessage acquireNext() throws DfException
    Returns the next ready message with the highest priority and the earliest creation_time, sets the message to 'acquired' state.
    Returns:
      A message object if available, `null` if there is no such a message available.
    Throws:
      `DfException` - if a server error occurs

  - ### acquireNext

    IDfMessage acquireNext(String recipient) throws DfException
    Returns the next available ready message with the highest priority and earliest creation time that is addressed the specified recipient. Sets the message to 'acquired' state.
    Parameters:
      `recipient` - Message recipient.
    Returns:
      A message object if one with matching recipient available, `null` otherwise.
    Throws:
      `DfException` - if a server error occurs

  - ### acquireNextBatch

    Collection<IDfMessage> acquireNextBatch(int batchSize) throws DfException
    Returns as a collection the next upto `count` ready messages with the highest priority and earliest creation_time, sets their state to 'acquired'. Returns `null` if there are no ready messages.
    Parameters:
      `batchSize` - Number of messages to acquire.
    Returns:
      Returns as a collection the next upto `count` messages, `null` if there are no ready messages.
    Throws:
      `DfException` - if a server error occurs

  - ### acquireNextBatch

    Collection<IDfMessage> acquireNextBatch(int batchSize, String recipient) throws DfException
    Returns as a collection the next upto `count` ready message whose recipient matches the specified message recipient, sets their state to 'acquired'.

    If there are more than `count` matching messages available, return the ones with the highest priority and earliest creation_time. Returns `null` if there are no matching messages available.
    Parameters:
      `recipient` - Message recipient name.
      `batchSize` - Number of messages to acquire.
    Returns:
      A collection of message objects if any available, `null` if no messages available.
    Throws:
      `DfException` - if a server error occurs

  - ### acknowledge

    void acknowledge(IDfMessage message, boolean success, String description) throws DfException
    Acknoeledges to message queue the delivery status of the specified message. If delivery succeeds, the message is deleted from the queue immediatly. If delivery fails and the queue is configured to redeliver, and the redelivery count has not excceeded the configured retry limit, the message is set to ready state for redelivery. If delivery fails and the queue is configured not to redeliver or the redelivery count has excceeded the configured retry limit, the message is deleted from the queue.
    Parameters:
      `message` - A message object.
      `success` - Whether message delivery is successful `true` or not `false`
      `description` - A text string describing why message delivery failed. `null` in case message delivery succeeds.
    Throws:
      `DfException` - if a server error occurs

  - ### acknowledge

    void acknowledge(Collection<IDfMessage> messages, boolean success, String description) throws DfException
    Acknowledges to message server the delivery status of the specified message. If delivery succeeds, the message is deleted from the queue immediatly. If delivery fails and the queue is configured to redeliver, and the redelivery count has not exceeded the configured retry limit, the message is set to ready state for redelivery. If delivery fails and the queue is configured not to redeliver or the redelivery count has exceeded the configured retry limit, the message will be deleted from the queue.

    This is the batch version of @acknowledge

    Note that this method can be used only if all messages have the same delivery status, i.e., either all succeed or fail.
    Parameters:
      `messages` - A collection of of message objects.
      `success` - Whether message delivery is successful `true` or not `false`
      `description` - A text string describing why message delivery failed. `null` in case message delivery succeeds.
    Throws:
      `DfException` - if a server error occurs

  - ### get

    Collection<IDfMessage> get(String predicate) throws DfException
    Returns as a collection all the messages that satisfy the specified predicates.

    This operation does not change message state. A message returned by this method is not guranteed to remain in the queue after the method return. It may be acquired or purged by aother session.
    Parameters:
      `predicate` - A predicate that can be used in the where clause of a SQL statement. For instance, "msg_state=2 AND msg_recipient='tuser2'".
    Returns:
      A collection of message objects.
    Throws:
      `DfException` - if a server error occurs

  - ### get

    IDfMessage get(IDfId msgId) throws DfException
    Returns the message for the given message id.

    This operation does not change message state. A message returned by this method is not guranteed to remain in the queue after the method return. It may be acquired or purged by aother session.
    Parameters:
      `msgId` - Message object id.
    Returns:
      The message for the given message id.
    Throws:
      `DfException` - if a server error occurs

  - ### get

    Collection<IDfMessage> get(int state) throws DfException
    Returns as a collection all the messages in the given state. if any, `null` otherwise

    This operation does not change message state. A message returned by this method is not guranteed to remain in the queue after the method return. It may be acquired or purged by aother session.
    Parameters:
      `state` - An integer value indicating message state: Valiad values are: 1(ready), 2(acquired), 3(dead), and 4(unknow)
    Returns:
      A collection of all the messages.
    Throws:
      `DfException` - if a server error occurs

  - ### purge

    int purge(IDfId msgId) throws DfException
    Deletes the specified message from the queue.
    Parameters:
      `msgId` - The message object id.
    Returns:
      1 if the message is deleted, 0 otherwise.
    Throws:
      `DfException` - if a server error occurs

  - ### purge

    int purge(int state) throws DfException
    Deletes from the queue all the messages that are in the specified state.

    Can be called by users with administer privilede only.
    Parameters:
      `state` - Message state
    Returns:
      Number of messages deleted.
    Throws:
      `DfException` - if a server error occurs

  - ### purgeAll

    int purgeAll() throws DfException
    Deletes all the messages from the queue.

    Can be called by users with administer privilede only.
    Returns:
      Number of messages deleted.
    Throws:
      `DfException` - if a server error occurs

  - ### getCount

    int getCount(int state) throws DfException
    Returns the number of the messages in the specified state.
    Parameters:
      `state` - Message state
    Returns:
      The number of the messages in the specified state.
    Throws:
      `DfException` - if a server error occurs

  - ### getCount

    int getCount(String predicates) throws DfException
    Returns the number of the messages that satisfy the specified predicates
    Parameters:
      `predicates` - Predicates used in where clause
    Returns:
      The number of the messages that satisfy the specified predicate.
    Throws:
      `DfException` - if a server error occurs

  - ### getConfig

    IDfMessageQueueConfig getConfig() throws DfException
    Returns the configuration object of this message queue.
    Returns:
      Message queue configuration object.
    Throws:
      `DfException` - if a server error occurs