Added support for Advanced Queueing RAW queues and bulk enqueue/dequeue.

Author: anthony-tuininga

doc/src/aq.rst

@@ -4,6 +4,76 @@
 Advanced Queuing
 ****************
 
+.. note::
+
+    All of these objects are extensions to the DB API.
+
+.. _queue:
+
+------
+Queues
+------
+
+Queues are created using the :meth:`Connection.queue()` method and are used to
+enqueue and dequeue messages.
+
+.. attribute:: Queue.connection
+
+    This read-only attribute returns a reference to the connection object on
+    which the queue was created.
+
+
+.. method:: Queue.deqMany(maxMessages)
+
+    Dequeues up to the specified number of messages from the queue and returns
+    a list of these messages. Each element of the returned list is a
+    :ref:`message property<msgproperties>` object.
+
+
+.. method:: Queue.deqOne()
+
+    Dequeues at most one message from the queue. If a message is dequeued, it
+    will be a :ref:`message property<msgproperties>` object; otherwise, it will
+    be the value None.
+
+.. attribute:: Queue.deqOptions
+
+    This read-only attribute returns a reference to the :ref:`options
+    <deqoptions>` that will be used when dequeuing messages from the queue.
+
+
+.. method:: Queue.enqOne(message)
+
+    Enqueues a single message into the queue. The message must be a
+    :ref:`message property<msgproperties>` object which has had its payload
+    attribute set to a value that the queue supports.
+
+
+.. method:: Queue.enqMany(messages)
+
+    Enqueues multiple messages into the queue. The messages parameter must be a
+    sequence containing :ref:`message property <msgproperties>` objects which
+    have all had their payload attribute set to a value that the queue
+    supports.
+
+
+.. attribute:: Queue.enqOptions
+
+    This read-only attribute returns a reference to the :ref:`options
+    <enqoptions>` that will be used when enqueuing messages into the queue.
+
+
+.. attribute:: Queue.name
+
+    This read-only attribute returns the name of the queue.
+
+
+.. attribute:: Queue.payloadType
+
+    This read-only attribute returns the object type for payloads that can be
+    enqueued and dequeued. If using a raw queue, this returns the value None.
+
+
 .. _deqoptions:
 
 ---------------
@@ -205,6 +275,14 @@ Message Properties
     generated this message.
 
 
+.. attribute:: MessageProperties.payload
+
+    This attribute identifies the payload that will be enqueued or the payload
+    that was dequeued when using a :ref:`queue <queue>`. When enqueuing, the
+    value is checked to ensure that it conforms to the type expected by that
+    queue.
+
+
 .. attribute:: MessageProperties.priority
 
     This attribute specifies the priority of the message. A smaller number

doc/src/connection.rst

@@ -193,6 +193,11 @@ Connection Object
 
     .. versionadded:: 5.3
 
+    .. deprecated:: 7.2
+
+        Use the methods :meth:`Queue.deqOne()` or :meth:`Queue.deqMany()`
+        instead.
+
     .. note::
 
         This method is an extension to the DB API definition.
@@ -205,6 +210,10 @@ Connection Object
 
     .. versionadded:: 5.3
 
+    .. deprecated:: 7.2
+
+        Use the attribute :attr:`Queue.deqOptions` instead.
+
     .. note::
 
         This method is an extension to the DB API definition.
@@ -253,6 +262,11 @@ Connection Object
 
     .. versionadded:: 5.3
 
+    .. deprecated:: 7.2
+
+        Use the methods :meth:`Queue.enqOne()` or :meth:`Queue.enqMany()`
+        instead.
+
     .. note::
 
         This method is an extension to the DB API definition.
@@ -265,6 +279,10 @@ Connection Object
 
     .. versionadded:: 5.3
 
+    .. deprecated:: 7.2
+
+        Use the attribute :attr:`Queue.enqOptions` instead.
+
     .. note::
 
         This method is an extension to the DB API definition.
@@ -447,6 +465,25 @@ Connection Object
         This method is an extension to the DB API definition.
 
 
+.. method:: Connection.queue(name, payloadType=None)
+
+    Creates a :ref:`queue <queue>` which is used to enqueue and dequeue
+    messages in Advanced Queueing.
+
+    The name parameter is expected to be a string identifying the queue in
+    which messages are to be enqueued or dequeued.
+
+    The payloadType parameter, if specified, is expected to be an
+    :ref:`object type <objecttype>` that identifies the type of payload the
+    queue expects. If not specified, RAW data is enqueued and dequeued.
+
+    .. versionadded:: 7.2
+
+    .. note::
+
+        This method is an extension to the DB API definition.
+
+
 .. method:: Connection.rollback()
 
     Rollback any pending transactions.

odpi

@@ -0,0 +1,77 @@
+#------------------------------------------------------------------------------
+# Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+#
+# Portions Copyright 2007-2015, Anthony Tuininga. All rights reserved.
+#
+# Portions Copyright 2001-2007, Computronix (Canada) Ltd., Edmonton, Alberta,
+# Canada. All rights reserved.
+#------------------------------------------------------------------------------
+
+#------------------------------------------------------------------------------
+# BulkAQ.py
+#   This script demonstrates how to use bulk enqueuing and dequeuing of
+# messages with advanced queuing using cx_Oracle. It makes use of a RAW queue
+# created in the sample setup.
+#
+# This script requires cx_Oracle 7.2 and higher.
+#------------------------------------------------------------------------------
+
+from __future__ import print_function
+
+import cx_Oracle
+import SampleEnv
+
+QUEUE_NAME = "DEMORAW"
+PAYLOAD_DATA = [
+    "The first message",
+    "The second message",
+    "The third message",
+    "The fourth message",
+    "The fifth message",
+    "The sixth message",
+    "The seventh message",
+    "The eighth message",
+    "The ninth message",
+    "The tenth message",
+    "The eleventh message",
+    "The twelfth and final message"
+]
+
+# connect to database
+connection = cx_Oracle.connect(SampleEnv.GetMainConnectString())
+cursor = connection.cursor()
+
+# create queue
+queue = connection.queue(QUEUE_NAME)
+queue.deqOptions.wait = cx_Oracle.DEQ_NO_WAIT
+queue.deqOptions.navigation = cx_Oracle.DEQ_FIRST_MSG
+
+# dequeue all existing messages to ensure the queue is empty, just so that
+# the results are consistent
+while queue.deqOne():
+    pass
+
+# enqueue a few messages
+print("Enqueuing messages...")
+batchSize = 6
+dataToEnq = PAYLOAD_DATA
+while dataToEnq:
+    batchData = dataToEnq[:batchSize]
+    dataToEnq = dataToEnq[batchSize:]
+    messages = [connection.msgproperties(payload=d) for d in batchData]
+    for data in batchData:
+        print(data)
+    queue.enqMany(messages)
+connection.commit()
+
+# dequeue the messages
+print("\nDequeuing messages...")
+batchSize = 8
+while True:
+    messages = queue.deqMany(batchSize)
+    if not messages:
+        break
+    for props in messages:
+        print(props.payload.decode())
+connection.commit()
+print("\nDone.")

samples/AdvancedQueuing.py

@@ -0,0 +1,68 @@
+#------------------------------------------------------------------------------
+# Copyright (c) 2016, 2019, Oracle and/or its affiliates. All rights reserved.
+#
+# Portions Copyright 2007-2015, Anthony Tuininga. All rights reserved.
+#
+# Portions Copyright 2001-2007, Computronix (Canada) Ltd., Edmonton, Alberta,
+# Canada. All rights reserved.
+#------------------------------------------------------------------------------
+
+#------------------------------------------------------------------------------
+# ObjectAQ.py
+#   This script demonstrates how to use advanced queuing with objects using
+# cx_Oracle. It makes use of a simple type and queue created in the sample
+# setup.
+#
+# This script requires cx_Oracle 7.2 and higher.
+#------------------------------------------------------------------------------
+
+from __future__ import print_function
+
+import cx_Oracle
+import SampleEnv
+import decimal
+
+BOOK_TYPE_NAME = "UDT_BOOK"
+QUEUE_NAME = "BOOKS"
+BOOK_DATA = [
+    ("The Fellowship of the Ring", "Tolkien, J.R.R.",
+            decimal.Decimal("10.99")),
+    ("Harry Potter and the Philosopher's Stone", "Rowling, J.K.",
+            decimal.Decimal("7.99"))
+]
+
+# connect to database
+connection = cx_Oracle.connect(SampleEnv.GetMainConnectString())
+cursor = connection.cursor()
+
+# create queue
+booksType = connection.gettype(BOOK_TYPE_NAME)
+queue = connection.queue(QUEUE_NAME, booksType)
+queue.deqOptions.wait = cx_Oracle.DEQ_NO_WAIT
+queue.deqOptions.navigation = cx_Oracle.DEQ_FIRST_MSG
+
+# dequeue all existing messages to ensure the queue is empty, just so that
+# the results are consistent
+while queue.deqOne():
+    pass
+
+# enqueue a few messages
+print("Enqueuing messages...")
+for title, authors, price in BOOK_DATA:
+    book = booksType.newobject()
+    book.TITLE = title
+    book.AUTHORS = authors
+    book.PRICE = price
+    print(title)
+    queue.enqOne(connection.msgproperties(payload=book))
+connection.commit()
+
+# dequeue the messages
+print("\nDequeuing messages...")
+while True:
+    props = queue.deqOne()
+    if not props:
+        break
+    print(props.payload.TITLE)
+connection.commit()
+print("\nDone.")