220 lines
7.0 KiB
ReStructuredText
220 lines
7.0 KiB
ReStructuredText
.. _aq:
|
|
|
|
****************
|
|
Advanced Queuing
|
|
****************
|
|
|
|
.. _deqoptions:
|
|
|
|
---------------
|
|
Dequeue Options
|
|
---------------
|
|
|
|
.. note::
|
|
|
|
This object is an extension to the DB API. It is returned by the
|
|
:meth:`Connection.deqoptions()` call and is used in calls to
|
|
:meth:`Connection.deq()`.
|
|
|
|
|
|
.. attribute:: DeqOptions.condition
|
|
|
|
This attribute specifies a boolean expression similar to the where clause
|
|
of a SQL query. The boolean expression can include conditions on message
|
|
properties, user data properties and PL/SQL or SQL functions. The default
|
|
is to have no condition specified.
|
|
|
|
|
|
.. attribute:: DeqOptions.consumername
|
|
|
|
This attribute specifies the name of the consumer. Only messages matching
|
|
the consumer name will be accessed. If the queue is not set up for multiple
|
|
consumers this attribute should not be set. The default is to have no
|
|
consumer name specified.
|
|
|
|
|
|
.. attribute:: DeqOptions.correlation
|
|
|
|
This attribute specifies the correlation identifier of the message to be
|
|
dequeued. Special pattern-matching characters, such as the percent sign (%)
|
|
and the underscore (_), can be used. If multiple messages satisfy the
|
|
pattern, the order of dequeuing is indeterminate. The default is to have no
|
|
correlation specified.
|
|
|
|
|
|
.. attribute:: DeqOptions.deliverymode
|
|
|
|
This write-only attribute specifies what types of messages should be
|
|
dequeued. It should be one of the values :data:`~cx_Oracle.MSG_PERSISTENT`
|
|
(default), :data:`~cx_Oracle.MSG_BUFFERED` or
|
|
:data:`~cx_Oracle.MSG_PERSISTENT_OR_BUFFERED`.
|
|
|
|
|
|
.. attribute:: DeqOptions.mode
|
|
|
|
This attribute specifies the locking behaviour associated with the dequeue
|
|
operation. It should be one of the values :data:`~cx_Oracle.DEQ_BROWSE`,
|
|
:data:`~cx_Oracle.DEQ_LOCKED`,
|
|
:data:`~cx_Oracle.DEQ_REMOVE` (default), or
|
|
:data:`~cx_Oracle.DEQ_REMOVE_NODATA`.
|
|
|
|
|
|
.. attribute:: DeqOptions.msgid
|
|
|
|
This attribute specifies the identifier of the message to be dequeued. The
|
|
default is to have no message identifier specified.
|
|
|
|
|
|
.. attribute:: DeqOptions.navigation
|
|
|
|
This attribute specifies the position of the message that is retrieved. It
|
|
should be one of the values :data:`~cx_Oracle.DEQ_FIRST_MSG`,
|
|
:data:`~cx_Oracle.DEQ_NEXT_MSG` (default), or
|
|
:data:`~cx_Oracle.DEQ_NEXT_TRANSACTION`.
|
|
|
|
|
|
.. attribute:: DeqOptions.transformation
|
|
|
|
This attribute specifies the name of the transformation that must be
|
|
applied after the message is dequeued from the database but before it is
|
|
returned to the calling application. The transformation must be created
|
|
using dbms_transform. The default is to have no transformation specified.
|
|
|
|
|
|
.. attribute:: DeqOptions.visibility
|
|
|
|
This attribute specifies the transactional behavior of the dequeue request.
|
|
It should be one of the values :data:`~cx_Oracle.DEQ_ON_COMMIT` (default)
|
|
or :data:`~cx_Oracle.DEQ_IMMEDIATE`. This attribute is ignored when using
|
|
the :data:`~cx_Oracle.DEQ_BROWSE` mode.
|
|
|
|
|
|
.. attribute:: DeqOptions.wait
|
|
|
|
This attribute specifies the time to wait, in seconds, for a message
|
|
matching the search criteria to become available for dequeuing. One of the
|
|
values :data:`~cx_Oracle.DEQ_NO_WAIT` or
|
|
:data:`~cx_Oracle.DEQ_WAIT_FOREVER` can also be used. The default is
|
|
:data:`~cx_Oracle.DEQ_WAIT_FOREVER`.
|
|
|
|
|
|
.. _enqoptions:
|
|
|
|
---------------
|
|
Enqueue Options
|
|
---------------
|
|
|
|
.. note::
|
|
|
|
This object is an extension to the DB API. It is returned by the
|
|
:meth:`Connection.enqoptions()` call and is used in calls to
|
|
:meth:`Connection.enq()`.
|
|
|
|
|
|
.. attribute:: EnqOptions.deliverymode
|
|
|
|
This write-only attribute specifies what type of messages should be
|
|
enqueued. It should be one of the values :data:`~cx_Oracle.MSG_PERSISTENT`
|
|
(default) or :data:`~cx_Oracle.MSG_BUFFERED`.
|
|
|
|
|
|
.. attribute:: EnqOptions.transformation
|
|
|
|
This attribute specifies the name of the transformation that must be
|
|
applied before the message is enqueued into the database. The
|
|
transformation must be created using dbms_transform. The default is to have
|
|
no transformation specified.
|
|
|
|
|
|
.. attribute:: EnqOptions.visibility
|
|
|
|
This attribute specifies the transactional behavior of the enqueue request.
|
|
It should be one of the values :data:`~cx_Oracle.ENQ_ON_COMMIT` (default)
|
|
or :data:`~cx_Oracle.ENQ_IMMEDIATE`.
|
|
|
|
|
|
.. _msgproperties:
|
|
|
|
------------------
|
|
Message Properties
|
|
------------------
|
|
|
|
.. note::
|
|
|
|
This object is an extension to the DB API. It is returned by the
|
|
:meth:`Connection.msgproperties()` call and is used in calls to
|
|
:meth:`Connection.deq()` and :meth:`Connection.enq()`.
|
|
|
|
|
|
.. attribute:: MessageProperties.attempts
|
|
|
|
This read-only attribute specifies the number of attempts that have been
|
|
made to dequeue the message.
|
|
|
|
|
|
.. attribute:: MessageProperties.correlation
|
|
|
|
This attribute specifies the correlation used when the message was
|
|
enqueued.
|
|
|
|
|
|
.. attribute:: MessageProperties.delay
|
|
|
|
This attribute specifies the number of seconds to delay an enqueued
|
|
message. Any integer is acceptable but the constant
|
|
:data:`~cx_Oracle.MSG_NO_DELAY` can also be used indicating that the
|
|
message is available for immediate dequeuing.
|
|
|
|
|
|
.. attribute:: MessageProperties.deliverymode
|
|
|
|
This read-only attribute specifies the type of message that was dequeued.
|
|
It will be one of the values :data:`~cx_Oracle.MSG_PERSISTENT` or
|
|
:data:`~cx_Oracle.MSG_BUFFERED`.
|
|
|
|
|
|
.. attribute:: MessageProperties.enqtime
|
|
|
|
This read-only attribute specifies the time that the message was enqueued.
|
|
|
|
|
|
.. attribute:: MessageProperties.exceptionq
|
|
|
|
This attribute specifies the name of the queue to which the message is
|
|
moved if it cannot be processed successfully. Messages are moved if the
|
|
number of unsuccessful dequeue attempts has exceeded the maximum number of
|
|
retries or if the message has expired. All messages in the exception queue
|
|
are in the :data:`~cx_Oracle.MSG_EXPIRED` state. The default value is the
|
|
name of the exception queue associated with the queue table.
|
|
|
|
|
|
.. attribute:: MessageProperties.expiration
|
|
|
|
This attribute specifies, in seconds, how long the message is available for
|
|
dequeuing. This attribute is an offset from the delay attribute. Expiration
|
|
processing requires the queue monitor to be running. Any integer is
|
|
accepted but the constant :data:`~cx_Oracle.MSG_NO_EXPIRATION` can also be
|
|
used indicating that the message never expires.
|
|
|
|
|
|
.. attribute:: MessageProperties.msgid
|
|
|
|
This attribute specifies the id of the message in the last queue that
|
|
generated this message.
|
|
|
|
|
|
.. attribute:: MessageProperties.priority
|
|
|
|
This attribute specifies the priority of the message. A smaller number
|
|
indicates a higher priority. The priority can be any integer, including
|
|
negative numbers. The default value is zero.
|
|
|
|
|
|
.. attribute:: MessageProperties.state
|
|
|
|
This read-only attribute specifies the state of the message at the time of
|
|
the dequeue. It will be one of the values :data:`~cx_Oracle.MSG_WAITING`,
|
|
:data:`~cx_Oracle.MSG_READY`, :data:`~cx_Oracle.MSG_PROCESSED` or
|
|
:data:`~cx_Oracle.MSG_EXPIRED`.
|
|
|