Package oracle.jdbc.aq

Class AQDequeueOptions

  • public class AQDequeueOptions
extends Object
    Specifies the options available for the dequeue operation.

    • Field Detail

      • MAX_RAW_PAYLOAD

        public static final int MAX_RAW_PAYLOAD
        Default maximum buffer size of a RAW payload.
        See Also:
        Constant Field Values

    • Constructor Detail

      • AQDequeueOptions

        public AQDequeueOptions()
        Constructs the default dequeue options.

    • Method Detail

      • setConsumerName

        public void setConsumerName​(String consumerName)
                     throws SQLException
        Specifies a consumer name. Only those messages matching the consumer name are accessed. If a queue is not set up for multiple consumers, this field should be set to null.
        Parameters:
        consumerName - the consumer name
        Throws:
        SQLException

      • setCorrelation

        public void setCorrelation​(String correlation)
                    throws SQLException
        Specifies a correlation criterion (or search criterion) for the dequeue operation. Special pattern matching characters, such as the percent sign (%) and the underscore (_) can be used. If more than one message satisfies the pattern, the order of dequeuing is undetermined.

        For example, if you want to dequeue only messages whose correlation identifier starts with an upper-case "W.", you would set the correlation criterion to:

               dequeueOptions.setCorrelation("W%");
        Parameters:
        correlation - the correlation criterion
        Throws:
        SQLException

      • setDequeueMode

        public void setDequeueMode​(AQDequeueOptions.DequeueMode deqMode)
                    throws SQLException
        Specifies the locking behavior associated with the dequeue operation.
        Parameters:
        deqMode - The only valid dequeue modes are:
        • DequeueMode.BROWSE
        • DequeueMode.LOCKED
        • DequeueMode.REMOVE
        • DequeueMode.REMOVE_NODATA
        Throws:
        SQLException

      • setDequeueMessageId

        public void setDequeueMessageId​(byte[] deqMsgId)
                         throws SQLException
        Specifies the message identifier of the message to be dequeued. This can be used to dequeue a unique message whose id is known.
        Parameters:
        deqMsgId - message identifier. Can be 'null' to disable dequeue based on a particular message id.
        Throws:
        SQLException

      • getDequeueMessageId

        public byte[] getDequeueMessageId()
        Returns the message id of the message the be dequeued. If 'null', then the dequeue operation will not be based on a particular message id.
        See Also:
        setDequeueMessageId(byte[])

      • setNavigation

        public void setNavigation​(AQDequeueOptions.NavigationOption navigation)
                   throws SQLException
        Specifies the position of the message that will be retrieved. First, the position is determined. Second, the search criterion is applied. Finally, the message is retrieved.

        The default behavior is to retrieve the next message which is available and matches the seatch criterion.

        Parameters:
        navigation - The position criterion can be any of the following:
        • NavigationOption.FIRST_MESSAGE
        • NavigationOption.NEXT_MESSAGE
        • NavigationOption.NEXT_TRANSACTION
        navigation - the position criterion
        Throws:
        SQLException

      • setVisibility

        public void setVisibility​(AQDequeueOptions.VisibilityOption visibility)
                   throws SQLException
        Specifies whether the message is dequeued as part of the current transaction. The visibility parameter is ignored when using the BROWSE mode.
        Parameters:
        visibility - can be:
        • VisibilityOption.ON_COMMIT
        • VisibilityOption.IMMEDIATE
        Throws:
        SQLException

      • setWait

        public void setWait​(int wait)
             throws SQLException
        Specifies the wait time if there is currently no message available which matches the search criterion. This parameter is ignored if messages in the same group are being dequeued.

        Valid Values : Any int, but the following predefined constants are provided:

        • DEQUEUE_WAIT_FOREVER ( = -1) - wait forever. This is the default.
        • DEQUEUE_NO_WAIT ( = 0) - do not wait.

        If you use DEQUEUE_WAIT_FOREVER the dequeue operation will not return until a message which mathces the seach criterion is available in the queue. You can however interrupt the dequeue operation by calling connection.cancel();.

        Parameters:
        wait - the wait option
        Throws:
        SQLException

      • getWait

        public int getWait()
        Returns the wait option.
        See Also:
        setWait(int)

      • setMaximumBufferLength

        public void setMaximumBufferLength​(int length)
                            throws SQLException
        Sets the maximum number of bytes that will be allocated when dequeueing a message from a RAW queue. The default maximum is DEFAULT_MAX_PAYLOAD_LENGTH but it can be changed to any other non zero value. This is to avoid allocating a huge buffer knowing that a message from a RAW queue can contain up to 4G bytes. If the buffer is not large enough to contain the entire message, the exceeding bytes will be silently ignored.
        Parameters:
        length - the max buffer size
        Throws:
        SQLException

      • getMaximumBufferLength

        public int getMaximumBufferLength()
        Returns the max buffer size for RAW queues.
        See Also:
        setMaximumBufferLength(int)

      • setDeliveryFilter

        public void setDeliveryFilter​(AQDequeueOptions.DeliveryFilter delivery)
                       throws SQLException
        Use this method to dequeue buffered messages only, persistent messages only or both. By default the dequeue method will dequeue persistent messages only.

        Possible valid options are:

        • DeliveryFilter.PERSISTENT - to dequeue persistent messages only (this is the default).
        • DeliveryFilter.BUFFERED - to dequeue buffered messages only.
        • DeliveryFilter.PERSISTENT_OR_BUFFERED - to dequeue buffered or persistent messages.
        Parameters:
        delivery - the delivery options
        Throws:
        SQLException

      • setRetrieveMessageId

        public void setRetrieveMessageId​(boolean retrieveIt)
        Set this to true in order to retrieve the message id during dequeue. By default the server won't return the message id.
        Parameters:
        retrieveIt - retrieve message id or not?

      • getRetrieveMessageId

        public boolean getRetrieveMessageId()
        Returns the value of the option that can be set to force the server to return the id of the message during dequeue.
        See Also:
        setRetrieveMessageId(boolean)

      • setTransformation

        public void setTransformation​(String _transformation)
        Specifies a transformation that will be applied after dequeuing the message. The source type of the transformation must match the type of the queue.

        Transformations must be created in PLSQL using DBMS_TRANSFORM.CREATE_TRANSFORMATION(...).

        For example if the transformation 'OBJ2XML' has been created under the schema 'SCOTT' then it can be specified in the dequeue option with dequeueOption.setTransformation("SCOTT.OBJ2XML").

        Parameters:
        _transformation - the transformation

      • setCondition

        public void setCondition​(String _condition)
        Sets a conditional expression based on the message properties, the message data properties, and PL/SQL functions.

        A dequeue condition is specified as a Boolean expression using syntax similar to the WHERE clause of a SQL query. This Boolean expression can include conditions on message properties, user data properties (object payloads only), and PL/SQL or SQL functions (as specified in the WHERE clause of a SQL query). Message properties include priority, corrid and other columns in the queue table

        To specify dequeue conditions on a message payload (object payload), use attributes of the object type in clauses. You must prefix each attribute with tab.user_data as a qualifier to indicate the specific column of the queue table that stores the payload. The dequeue condition parameter cannot exceed 4000 characters. If more than one message satisfies the dequeue condition, then the order of dequeuing is undetermined.

        Parameters:
        _condition - the dequeue condition