Package oracle.jdbc.aq

Class AQDequeueOptions

java.lang.Object
oracle.jdbc.aq.AQDequeueOptions
public class AQDequeueOptions extends Object
Specifies the options available for the dequeue operation.

  • Field Details

    • DEQUEUE_WAIT_FOREVER

      public static final int DEQUEUE_WAIT_FOREVER
      See Also:

    • DEQUEUE_NO_WAIT

      public static final int DEQUEUE_NO_WAIT
      See Also:

    • MAX_RAW_PAYLOAD

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

  • Constructor Details

    • AQDequeueOptions

      public AQDequeueOptions()
      Constructs the default dequeue options.

  • Method Details

    • 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

    • getConsumerName

      public String getConsumerName()
      Returns the consumer name.
      See Also:

    • setShardNum

      public void setShardNum(int shNum)
      Set the shard number from which messages will be consumed default: -1 (consume from any shard)
      Parameters:
      shNum - the actual shard number

    • getShardNum

      public int getShardNum()
      Returns the shard number to consume messages from
      See Also:

    • 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

    • getCorrelation

      public String getCorrelation()
      Returns the correlation criterion.
      See Also:

    • 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

    • getDequeueMode

      public AQDequeueOptions.DequeueMode getDequeueMode()
      Returns the dequeue mode.
      See Also:

    • 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 to be dequeued. If 'null', then the dequeue operation will not be based on a particular message id.
      See Also:

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

    • getNavigation

      public AQDequeueOptions.NavigationOption getNavigation()
      Returns the position criterion.
      See Also:

    • 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

    • getVisibility

      public AQDequeueOptions.VisibilityOption getVisibility()
      Returns the visibility parameter.
      See Also:

    • 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 matches the search 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:

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

    • 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

    • getDeliveryFilter

      public AQDequeueOptions.DeliveryFilter getDeliveryFilter()
      Returns the delivery option.
      See Also:

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

    • 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

    • getTransformation

      public String getTransformation()
      Returns the value of transformation option.
      See Also:

    • 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

    • getCondition

      public String getCondition()
      Returns the dequeue condition.
      See Also:

    • toString

      public String toString()
      Overrides:
      toString in class Object