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

Modifier and Type	Class	Description
static class	AQDequeueOptions.DeliveryFilter
static class	AQDequeueOptions.DequeueMode
static class	AQDequeueOptions.NavigationOption
static class	AQDequeueOptions.VisibilityOption

Field Summary

Fields

Modifier and Type	Field	Description
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

Constructor	Description
AQDequeueOptions()	Constructs the default dequeue options.

Method Summary

Modifier and Type	Method	Description
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)