WIP: Update sample code (oracle#440)

* update doc, etc.

Signed-off-by: Mark Nelson <[email protected]>

code-teq/javaTeq/pom.xml

@@ -1,17 +1,19 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!--  Copyright (c) 2022, Oracle and/or its affiliates. -->
+<!--  Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl. -->
 <project xmlns="http://maven.apache.org/POM/4.0.0"
 	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 	<modelVersion>4.0.0</modelVersion>
 
-
 	<groupId>com.oracle.example</groupId>
 	<artifactId>teq</artifactId>
 	<version>0.0.1-SNAPSHOT</version>
 	<name>teq</name>
 	<description>TEQ examples</description>
 
 	<properties>
+        <!-- Use Java 8 or later -->
         <maven.compiler.target>17</maven.compiler.target>
         <maven.compiler.source>17</maven.compiler.source>
 	</properties>

code-teq/javaTeq/src/main/java/com/oracle/example/ConsumeTEQ.java

@@ -1,3 +1,9 @@
+// Copyright (c) 2022, Oracle and/or its affiliates.
+// Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
+
+// This is an example of how to consume a message from a TEQ using Java.
+// Please see the Maven POM file for dependencies.
+
 package com.oracle.example;
 
 import java.sql.SQLException;

code-teq/javaTeq/src/main/java/com/oracle/example/CreateTEQ.java

@@ -1,3 +1,9 @@
+// Copyright (c) 2022, Oracle and/or its affiliates.
+// Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
+
+// This is an example of how to create a TEQ using Java.
+// Please see the Maven POM file for dependencies.
+
 package com.oracle.example;
 
 import java.sql.SQLException;

code-teq/javaTeq/src/main/java/com/oracle/example/PublishTEQ.java

@@ -1,3 +1,9 @@
+// Copyright (c) 2022, Oracle and/or its affiliates.
+// Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
+
+// This is an example of how to publish a message onto a TEQ using Java.
+// Please see the Maven POM file for dependencies.
+
 package com.oracle.example;
 
 import java.sql.SQLException;

code-teq/nodeTeq/dequeueTEQ.js

@@ -1,11 +1,15 @@
+// Copyright (c) 2022, Oracle and/or its affiliates.
+// Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
+
 //
-//  This sample demonstrates how to enqueue a message onto a TEQ using PL/SQL
+//  This sample demonstrates how to dequeue a message from a TEQ using JavaScript/Node
 //
 
 //  There are various payload types supported, including user-defined object, raw, JMS and JSON.
 //  This sample uses the RAW payload type.
 
 //  Execute permission on dbms_aq is required.
+//  The node module 'oracledb' must be installed, e.g. with npm
 
 const oracledb = require('oracledb');
 

code-teq/nodeTeq/enqueueTEQ.js

@@ -1,11 +1,15 @@
+// Copyright (c) 2022, Oracle and/or its affiliates.
+// Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
+
 //
-//  This sample demonstrates how to enqueue a message onto a TEQ using PL/SQL
+//  This sample demonstrates how to enqueue a message onto a TEQ using JavaScript/Node
 //
 
 //  There are various payload types supported, including user-defined object, raw, JMS and JSON.
 //  This sample uses the RAW payload type.
 
 //  Execute permission on dbms_aq is required.
+//  The node module 'oracledb' must be installed, e.g. with npm
 
 const oracledb = require('oracledb');
 

code-teq/plsqlTeq/cleanupTEQ.sql

@@ -1,3 +1,6 @@
+-- Copyright (c) 2022, Oracle and/or its affiliates.
+-- Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
+
 --
 --  This sample demonstrates how to remove (clean up) a TEQ using PL/SQL
 --

code-teq/plsqlTeq/createTEQ.sql

@@ -1,3 +1,6 @@
+-- Copyright (c) 2022, Oracle and/or its affiliates.
+-- Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
+
 --
 --  This sample demonstrates how to create a TEQ using PL/SQL
 --

code-teq/plsqlTeq/dequeueTEQ.sql

@@ -1,5 +1,7 @@
+-- Copyright (c) 2022, Oracle and/or its affiliates.
+-- Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
 --
---  This sample demonstrates how to enqueue a message onto a TEQ using PL/SQL
+--  This sample demonstrates how to dequeue a message from a TEQ using PL/SQL
 --
 
 --  There are various payload types supported, including user-defined object, raw, JMS and JSON.

code-teq/plsqlTeq/enqueueTEQ.sql

@@ -1,3 +1,6 @@
+-- Copyright (c) 2022, Oracle and/or its affiliates.
+-- Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
+
 --
 --  This sample demonstrates how to enqueue a message onto a TEQ using PL/SQL
 --

code-teq/pythonTeq/dequeueTEQ.py

@@ -1,33 +1,41 @@
+# Copyright (c) 2022, Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
+
 #
-#  This sample demonstrates how to enqueue a message onto a TEQ using PL/SQL
+#  This sample demonstrates how to enqueue a message onto a TEQ using Python
 #
 
 #  There are various payload types supported, including user-defined object, raw, JMS and JSON.
-#  This sample uses the JSON payload type.
+#  This sample uses the JMS payload type.
 
 #  Execute permission on dbms_aq is required.
+#  The python package 'oracledb' must be installed (e.g. with pip)
 
 import oracledb
 from os import environ as env
 
 # initialize the oracledb library, this will put us into 'thick mode' which is reqiured to use types
 oracledb.init_oracle_client()
 
-topicName = "my_teq"
+topicName = "my_jms_q"
 consumerName = "my_subscriber"
 
 # make sure that you set the environment variable DB_PASSWORD before running this
 connection = oracledb.connect(dsn='localhost:1521/pdb1',user='pdbadmin',password=env.get('DB_PASSWORD'))
 
-# get the JMS type
+# get the JMS types
 jmsType = connection.gettype("SYS.AQ$_JMS_TEXT_MESSAGE")
 headerType = connection.gettype("SYS.AQ$_JMS_HEADER")
 userPropType = connection.gettype("SYS.AQ$_JMS_USERPROPARRAY")
 
-queue = connection.queue(topicName) #, jmsType)
+# get the TEQ and set up the dequeue options
+queue = connection.queue(topicName, jmsType)
 queue.deqOptions.consumername = consumerName
-queue.deqOptions.wait = 10
+queue.deqOptions.wait = 10  # wait 10 seconds before giving up if no message received 
 
+# perform the dequeue
 message = queue.deqOne()
 connection.commit()
-print("message: ", message.payload.decode(connection.encoding)) #TEXT_VC)
+
+# print out the payload
+print("message: ", message.payload.TEXT_VC)

code-teq/pythonTeq/enqueueTEQ.py

@@ -1,31 +1,41 @@
+# Copyright (c) 2022, Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
+
 #
-#  This sample demonstrates how to enqueue a message onto a TEQ using PL/SQL
+#  This sample demonstrates how to enqueue a message onto a TEQ using Python
 #
 
 #  There are various payload types supported, including user-defined object, raw, JMS and JSON.
-#  This sample uses the JSON payload type.
+#  This sample uses the JMS payload type.
 
 #  Execute permission on dbms_aq is required.
+#  The python package 'oracledb' must be installed (e.g. with pip)
 
-import cx_Oracle
+import oracledb
 from os import environ as env
 
+# initialize the oracledb library, this will put us into 'thick mode' which is reqiured to use types
+oracledb.init_oracle_client()
+
 # make sure that you set the environment variable DB_PASSWORD before running this
-connection = cx_Oracle.connect(dsn='localhost:1521/pdb1',user='pdbadmin',password=env.get('DB_PASSWORD'))
+connection = oracledb.connect(dsn='localhost:1521/pdb1',user='pdbadmin',password=env.get('DB_PASSWORD'))
 
 # get the JMS type
 jmsType = connection.gettype("SYS.AQ$_JMS_TEXT_MESSAGE")
 headerType = connection.gettype("SYS.AQ$_JMS_HEADER")
 userPropType = connection.gettype("SYS.AQ$_JMS_USERPROPARRAY")
 
-queue = connection.queue("my_json_teq", jmsType)
+# get the TEQ
+queue = connection.queue("my_jms_q", jmsType)
 
+# prepare the message and headers
 text = jmsType.newobject()
 text.HEADER = headerType.newobject()
 text.TEXT_VC = "hello from python"
 text.TEXT_LEN = len(text.TEXT_VC)
 text.HEADER.TYPE = "MyHeader"
 text.HEADER.PROPERTIES = userPropType.newobject()
 
-queue.enqOne(connection.msgproperties(payload=text))
+# enqueue the message
+queue.enqOne(connection.msgproperties(payload=text,recipients=["my_subscriber"]))
 connection.commit()