VCLDequeueOperation

Interface: it.greenvulcano.gvesb.virtual.DequeueOperation

public interface DequeueOperation extends Operation
{
    public static final String TYPE  = "dequeue";

    /**
     * Used in the <code>setTimeout()</code> in order to set an infinite
     * timeout.
     */
    public static final long   TO_INDEFINITELY = 0;

    /**
     * Used in the <code>setTimeout()</code> in order to set a non-blocking
     * receive.
     */
    public static final long   TO_NON_BLOCKING = -1;

    /**
     * Return <code>null</code> if no messages are available or timeout occurs.
     *
     * @param gvBuffer
     * @return a <code>GVBuffer</code> or <code>null</code> if no messages are
     *         available or timeout occurs.
     * @throws ConnectionException
     * @throws DequeueException
     * @throws InvalidDataException
     */
    public GVBuffer perform(GVBuffer gvBuffer) throws ConnectionException, DequeueException, InvalidDataException;

    /**
     * This method acknowledge the message identified by the given Id.
     *
     * @param id
     * @throws ConnectionException
     * @throws AcknowledgeException
     */
    public void acknowledge(Id id) throws ConnectionException, AcknowledgeException;

    /**
     * This method acknowledge all the messages.
     *
     * @throws ConnectionException
     * @throws AcknowledgeException
     */
    public void acknowledgeAll() throws ConnectionException, AcknowledgeException;

    /**
     * This method roll-back the dequeue of the message identified by the given
     * Id.
     *
     * @param id
     * @throws ConnectionException
     * @throws AcknowledgeException
     */
    public void rollback(Id id) throws ConnectionException, AcknowledgeException;

    /**
     * This method roll-back the dequeue of all the messages.
     *
     * @throws ConnectionException
     * @throws AcknowledgeException
     */
    public void rollbackAll() throws ConnectionException, AcknowledgeException;

    /**
     * This method set the filter for messages to receive. <br>
     * This filter is valid only for the first perform() invocation.
     * The filter is reset also if perform() terminate with an exception. <br>
     * Despite the GVVCL is a virtual interface, the syntax for the filter is
     * like the syntax for JMS selectors. The concrete implementation must
     * adapt to the underlying MOM.
     *
     * @param filter
     * @throws FilterException
     */
    public void setFilter(String filter) throws FilterException;

    /**
     * This method set the timeout for the receive operation. <br>
     * If 0 then the receive blocks indefinitely. If <nobr>&gt;
     * 0</nobr> then this parameter specify, in milliseconds, the time that the
     * receive must wait for a message. If <nobr>&lt; 0</nobr> then executes a
     * non-blocking receive. <br>
     * This parameter is valid only for the first perform() invocation.
     * The timeout is reset also if perform() terminate with an exception.
     *
     * @param timeout
     *        Specify the receive timeout. If <nobr>&gt; 0</nobr> specifies the
     *        milliseconds for timeout. It is possible to use the
     *        <code>TO_xxx</code> constants in order to specify a non-blocking
     *        receive operation or a indefinitely blocking receive.
     *
     */
    public void setTimeout(long timeout);
}