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.

### Nested Class Summary

Nested Classes
`static class` `AQDequeueOptions.DeliveryFilter`
`static class` `AQDequeueOptions.DequeueMode`
`static class` `AQDequeueOptions.NavigationOption`
`static class` `AQDequeueOptions.VisibilityOption`

### Field Summary

Fields
`static int` `DEQUEUE_NO_WAIT`
`static int` `DEQUEUE_WAIT_FOREVER`
`static int` `MAX_RAW_PAYLOAD` Default maximum buffer size of a RAW payload.

### Constructor Summary

Constructors
`AQDequeueOptions()` Constructs the default dequeue options.

### Method Summary

All Methods Instance Methods Concrete Methods
`String` `getCondition()` Returns the dequeue condition.
`String` `getConsumerName()` Returns the consumer name.
`String` `getCorrelation()` Returns the correlation criterion.
`AQDequeueOptions.DeliveryFilter` `getDeliveryFilter()` Returns the delivery option.
`byte[]` `getDequeueMessageId()` Returns the message id of the message the be dequeued.
`AQDequeueOptions.DequeueMode` `getDequeueMode()` Returns the dequeue mode.
`int` `getMaximumBufferLength()` Returns the max buffer size for RAW queues.
`AQDequeueOptions.NavigationOption` `getNavigation()` Returns the position criterion.
`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.
`String` `getTransformation()` Returns the value of transformation option.
`AQDequeueOptions.VisibilityOption` `getVisibility()` Returns the visibility parameter.
`int` `getWait()` Returns the wait option.
`void` `setCondition​(String _condition)` Sets a conditional expression based on the message properties, the message data properties, and PL/SQL functions.
`void` `setConsumerName​(String consumerName)` Specifies a consumer name.
`void` `setCorrelation​(String correlation)` Specifies a correlation criterion (or search criterion) for the dequeue operation.
`void` `setDeliveryFilter​(AQDequeueOptions.DeliveryFilter delivery)` Use this method to dequeue buffered messages only, persistent messages only or both.
`void` `setDequeueMessageId​(byte[] deqMsgId)` Specifies the message identifier of the message to be dequeued.
`void` `setDequeueMode​(AQDequeueOptions.DequeueMode deqMode)` Specifies the locking behavior associated with the dequeue operation.
`void` `setMaximumBufferLength​(int length)` Sets the maximum number of bytes that will be allocated when dequeueing a message from a RAW queue.
`void` `setNavigation​(AQDequeueOptions.NavigationOption navigation)` Specifies the position of the message that will be retrieved.
`void` `setRetrieveMessageId​(boolean retrieveIt)` Set this to true in order to retrieve the message id during dequeue.
`void` `setTransformation​(String _transformation)` Specifies a transformation that will be applied after dequeuing the message.
`void` `setVisibility​(AQDequeueOptions.VisibilityOption visibility)` Specifies whether the message is dequeued as part of the current transaction.
`void` `setWait​(int wait)` Specifies the wait time if there is currently no message available which matches the search criterion.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### DEQUEUE_WAIT_FOREVER

    public static final int DEQUEUE_WAIT_FOREVER

See Also:
  Constant Field Values

#### DEQUEUE_NO_WAIT

    public static final int DEQUEUE_NO_WAIT

See Also:
  Constant Field Values

#### 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`

#### getConsumerName

    public String getConsumerName()

Returns the consumer name.

See Also:
  `setConsumerName(String)`

#### 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:
  `setCorrelation(String)`

#### 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:
  `setDequeueMode(DequeueMode)`

#### 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`

#### getNavigation

    public AQDequeueOptions.NavigationOption getNavigation()

Returns the position criterion.

See Also:
  `setNavigation(NavigationOption)`

#### 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:
  `setVisibility(VisibilityOption)`

#### 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`

#### getDeliveryFilter

    public AQDequeueOptions.DeliveryFilter getDeliveryFilter()

Returns the delivery option.

See Also:
  `setDeliveryFilter(oracle.jdbc.aq.AQDequeueOptions.DeliveryFilter)`

#### 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

#### getTransformation

    public String getTransformation()

Returns the value of transformation option.

See Also:
  `setTransformation(String)`

#### 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:
  `setCondition(String)`