Oracle JDBC API Reference
11g Release 2 ("11.2.0.3.0")

oracle.jdbc.aq
Class AQDequeueOptions

java.lang.Object
  extended by oracle.jdbc.aq.AQDequeueOptions

public class AQDequeueOptions
extends java.lang.Object

Specifies the options available for the dequeue operation.


Nested Class Summary
static class AQDequeueOptions.DeliveryFilter
           
static class AQDequeueOptions.DequeueMode
           
static class AQDequeueOptions.NavigationOption
           
static class AQDequeueOptions.VisibilityOption
           
 
Field Summary
static java.lang.String BUILD_DATE
           
static int DEQUEUE_NO_WAIT
           
static int DEQUEUE_WAIT_FOREVER
           
static int MAX_RAW_PAYLOAD
          Default maximum buffer size of a RAW payload.
static boolean TRACE
           
 
Constructor Summary
AQDequeueOptions()
          Constructs the default dequeue options.
 
Method Summary
 java.lang.String getCondition()
          Returns the dequeue condition.
 java.lang.String getConsumerName()
          Returns the consumer name.
 java.lang.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.
 java.lang.String getTransformation()
          Returns the value of transformation option.
 AQDequeueOptions.VisibilityOption getVisibility()
          Returns the visibility parameter.
 int getWait()
          Returns the wait option.
 void setCondition(java.lang.String _condition)
          Sets a conditional expression based on the message properties, the message data properties, and PL/SQL functions.
 void setConsumerName(java.lang.String consumerName)
          Specifies a consumer name.
 void setCorrelation(java.lang.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(java.lang.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
equals, 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

BUILD_DATE

public static final java.lang.String BUILD_DATE
See Also:
Constant Field Values

TRACE

public static final boolean TRACE
See Also:
Constant Field Values
Constructor Detail

AQDequeueOptions

public AQDequeueOptions()
Constructs the default dequeue options.

Method Detail

setConsumerName

public void setConsumerName(java.lang.String consumerName)
                     throws java.sql.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:
java.sql.SQLException

getConsumerName

public java.lang.String getConsumerName()
Returns the consumer name.

See Also:
setConsumerName(String)

setCorrelation

public void setCorrelation(java.lang.String correlation)
                    throws java.sql.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:
java.sql.SQLException

getCorrelation

public java.lang.String getCorrelation()
Returns the correlation criterion.

See Also:
setCorrelation(String)

setDequeueMode

public void setDequeueMode(AQDequeueOptions.DequeueMode deqMode)
                    throws java.sql.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:
java.sql.SQLException

getDequeueMode

public AQDequeueOptions.DequeueMode getDequeueMode()
Returns the dequeue mode.

See Also:
setDequeueMode(DequeueMode)

setDequeueMessageId

public void setDequeueMessageId(byte[] deqMsgId)
                         throws java.sql.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:
java.sql.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 java.sql.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:
java.sql.SQLException

getNavigation

public AQDequeueOptions.NavigationOption getNavigation()
Returns the position criterion.

See Also:
setNavigation(NavigationOption)

setVisibility

public void setVisibility(AQDequeueOptions.VisibilityOption visibility)
                   throws java.sql.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:
java.sql.SQLException

getVisibility

public AQDequeueOptions.VisibilityOption getVisibility()
Returns the visibility parameter.

See Also:
setVisibility(VisibilityOption)

setWait

public void setWait(int wait)
             throws java.sql.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:

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:
java.sql.SQLException

getWait

public int getWait()
Returns the wait option.

See Also:
setWait(int)

setMaximumBufferLength

public void setMaximumBufferLength(int length)
                            throws java.sql.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:
java.sql.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 java.sql.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:

Parameters:
delivery - the delivery options
Throws:
java.sql.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(java.lang.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 java.lang.String getTransformation()
Returns the value of transformation option.

See Also:
setTransformation(String)

setCondition

public void setCondition(java.lang.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 java.lang.String getCondition()
Returns the dequeue condition.

See Also:
setCondition(String)

Oracle JDBC API Reference
11g Release 2 ("11.2.0.3.0")

Copyright © 1998, 2007, Oracle. All rights reserved.