[4.x] JMS connector update (#5592)

* 4445 JMS connector
 - NACK support #4445
 - WLS custom connector for thin client #5290

Signed-off-by: Daniel Kec <daniel.kec@oracle.com>

bom/pom.xml

@@ -1137,6 +1137,11 @@
                 <artifactId>helidon-messaging-aq</artifactId>
                 <version>${helidon.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.helidon.messaging.wls-jms</groupId>
+                <artifactId>helidon-messaging-wls-jms</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
             <!-- Testing -->
             <dependency>
                 <groupId>io.helidon.microprofile.tests</groupId>

docs/mp/reactivemessaging/weblogic.adoc

@@ -0,0 +1,215 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2022 Oracle and/or its affiliates.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+///////////////////////////////////////////////////////////////////////////////
+
+= Weblogic JMS Connector
+:toc:
+:toc-placement: preamble
+:description: Reactive Messaging support for Weblogic JMS in Helidon MP
+:keywords: helidon, mp, messaging, jms, weblogic, wls, thin
+:feature-name: Weblogic JMS connector
+:microprofile-bundle: false
+:rootdir: {docdir}/../..
+
+include::{rootdir}/includes/mp.adoc[]
+include::{rootdir}/includes/dependencies.adoc[]
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.helidon.messaging.wls-jms</groupId>
+    <artifactId>helidon-messaging-wls-jms</artifactId>
+</dependency>
+----
+
+== Reactive Weblogic JMS Connector
+
+Connecting streams to Weblogic JMS with Reactive Messaging couldn't be easier.
+This connector extends Helidon JMS connector with special handling for Weblogic T3 thin client.
+
+Connecting to Weblogic JMS connection factories requires proprietary T3 thin client library which can be obtained from
+Weblogic installation.
+
+WARNING: Avoid placing `wlthint3client.jar` on Helidon classpath, client library location needs to be
+configured and loaded by Helidon messaging connector.
+
+=== Configuration
+
+Connector name: `helidon-weblogic-jms`
+
+.Attributes
+|===
+|`jms-factory` | JNDI name of the JMS factory configured in Weblogic
+|`url` | t3, t3s or http address of Weblogic server
+|`thin-jar` | Filepath to the Weblogic thin T3 client jar(wlthint3client.jar), can be usually found within Weblogic installation
+`WL_HOME/server/lib/wlthint3client.jar`
+|`principal` | Weblogic initial context principal(user)
+|`credential` | Weblogic initial context credential(password)
+|`type` | Possible values are: `queue`, `topic`. Default value is: `topic`
+|`destination` | Queue or topic name in WebLogic CDI Syntax(CDI stands for Create Destination Identifier)
+|`acknowledge-mode` |Possible values are: `AUTO_ACKNOWLEDGE`- session automatically acknowledges a client’s receipt of a message,
+`CLIENT_ACKNOWLEDGE` - receipt of a message is acknowledged only when `Message.ack()` is called manually,
+`DUPS_OK_ACKNOWLEDGE` - session lazily acknowledges the delivery of messages. Default value: `AUTO_ACKNOWLEDGE`
+|`transacted` | Indicates whether the session will use a local transaction. Default value: `false`
+|`message-selector` | JMS API message selector expression based on a subset of the SQL92.
+Expression can only access headers and properties, not the payload.
+|`client-id` | Client identifier for JMS connection.
+|`client-id` | Client identifier for JMS connection.
+|`durable` | True for creating durable consumer (only for topic). Default value: `false`
+|`subscriber-name` | Subscriber name for durable consumer used to identify subscription.
+|`non-local` | If true then any messages published to the topic using this session's connection,
+or any other connection with the same client identifier,
+will not be added to the durable subscription. Default value: `false`
+|`named-factory` | Select in case factory is injected as a named bean or configured with name.
+|`poll-timeout` | Timeout for polling for next message in every poll cycle in millis. Default value: `50`
+|`period-executions` | Period for executing poll cycles in millis. Default value: `100`
+|`session-group-id` | When multiple channels share same `session-group-id`, they share same JMS session and same JDBC connection as well.
+|`producer.unit-of-order` | All messages from same unit of order will be processed sequentially in the order they were created.
+|===
+
+Configuration is straight forward. Use JNDI for localizing and configuring of JMS ConnectionFactory
+from Weblogic. Notice the destination property which is used to define queue with
+https://docs.oracle.com/cd/E24329_01/web.1211/e24387/lookup.htm#JMSPG915[WebLogic CDI Syntax](CDI stands for Create Destination Identifier).
+
+[source,yaml]
+.Example config:
+----
+mp:
+  messaging:
+    connector:
+      helidon-weblogic-jms:
+        # JMS factory configured in Weblogic
+        jms-factory: jms/TestConnectionFactory
+        # Path to the WLS Thin T3 client jar
+        thin-jar: wlthint3client.jar
+        url: t3://localhost:7001
+    incoming:
+      from-wls:
+        connector: helidon-weblogic-jms
+        # WebLogic CDI Syntax(CDI stands for Create Destination Identifier)
+        destination: ./TestJMSModule!TestQueue
+    outgoing:
+      to-wls:
+        connector: helidon-weblogic-jms
+        destination: ./TestJMSModule!TestQueue
+----
+
+When configuring destination with WebLogic CDI, the following syntax needs to be applied:
+
+.Non-Distributed Destinations
+`jms-server-name/jms-module-name!destination-name`
+
+In our example we are replacing jms-server-name with `.` as we don’t have to look up the server we are connected to.
+
+.Uniform Distributed Destinations (UDDs)
+`jms-server-name/jms-module-name!jms-server-name@udd-name`
+
+Destination for UDD doesn't have `./` prefix, because distributed destinations can be served by multiple servers within a cluster.
+
+=== Consuming
+
+[source,java]
+.Consuming one by one unwrapped value:
+----
+@Incoming("from-wls")
+public void consumeWls(String msg) {
+    System.out.println("Weblogic says: " + msg);
+}
+----
+
+[source,java]
+.Consuming one by one, manual ack:
+----
+@Incoming("from-wls")
+@Acknowledgment(Acknowledgment.Strategy.MANUAL)
+public CompletionStage<?> consumewls(JmsMessage<String> msg) {
+    System.out.println("Weblogic says: " + msg.getPayload());
+    return msg.ack();
+}
+----
+
+=== Producing
+
+[source,java]
+.Producing to Weblogic JMS:
+----
+@Outgoing("to-wls")
+public PublisherBuilder<String> produceToWls() {
+    return ReactiveStreams.of("test1", "test2");
+}
+----
+
+[source,java]
+.Example of more advanced producing to Weblogic JMS:
+----
+@Outgoing("to-wls")
+public PublisherBuilder<String> produceToJms() {
+    return ReactiveStreams.of("test1", "test2")
+                .map(s -> JmsMessage.builder(s)
+                              .correlationId(UUID.randomUUID().toString())
+                              .property("stringProp", "cool property")
+                              .property("byteProp", 4)
+                              .property("intProp", 5)
+                              .onAck(() -> System.out.println("Acked!"))
+                              .build());
+}
+----
+[source,java]
+.Example of even more advanced producing to Weblogic JMS with custom mapper:
+----
+@Outgoing("to-wls")
+public PublisherBuilder<String> produceToJms() {
+    return ReactiveStreams.of("test1", "test2")
+                .map(s -> JmsMessage.builder(s)
+                            .customMapper((p, session) -> {
+                                TextMessage textMessage = session.createTextMessage(p);
+                                textMessage.setStringProperty("custom-mapped-property", "XXX" + p);
+                                return textMessage;
+                            })
+                            .build()
+                    );
+}
+----
+
+=== Secured t3 over SSL(t3s)
+For initiating SSL secured t3 connection, trust keystore with WLS public certificate is needed.
+Standard WLS installation has pre-configured Demo trust store: `WL_HOME/server/lib/DemoTrust.jks`,
+we can store it locally for connecting WLS over t3s.
+
+[source,yaml]
+.Example config:
+----
+mp:
+  messaging:
+    connector:
+      helidon-weblogic-jms:
+        jms-factory: jms/TestConnectionFactory
+        thin-jar: wlthint3client.jar
+        # Notice t3s protocol is used
+        url: t3s://localhost:7002
+----
+
+Helidon application needs to be aware about our WLS SSL public certificate.
+
+[source,bash]
+.Running example with WLS truststore
+----
+java --add-opens=java.base/java.io=ALL-UNNAMED \
+-Djavax.net.ssl.trustStore=DemoTrust.jks \
+-Djavax.net.ssl.trustStorePassword=DemoTrustKeyStorePassPhrase \
+-jar ./target/helidon-wls-jms-demo.jar
+----

docs/sitegen.yaml

@@ -409,6 +409,7 @@ backend:
                   - "kafka.adoc"
                   - "jms.adoc"
                   - "aq.adoc"
+                  - "weblogic.adoc"
                   - "mock.adoc"
               - type: "PAGE"
                 title: "REST Client"

examples/messaging/pom.xml

@@ -39,5 +39,6 @@
         <module>jms-websocket-mp</module>
         <module>jms-websocket-se</module>
         <module>oracle-aq-websocket-mp</module>
+        <module>weblogic-jms-mp</module>
     </modules>
 </project>

examples/messaging/weblogic-jms-mp/README.md

@@ -0,0 +1,24 @@
+# Helidon Messaging with Oracle Weblogic Example
+
+## Prerequisites
+* JDK 17+
+* Maven
+* Docker
+* Account at https://container-registry.oracle.com/ with accepted Oracle Standard Terms and Restrictions for Weblogic.
+
+## Run Weblogic in docker
+1. You will need to do a docker login to Oracle container registry with account which previously
+   accepted Oracle Standard Terms and Restrictions for Weblogic: 
+   `docker login container-registry.oracle.com`
+2. Run `bash buildAndRunWeblogic.sh` to build and run example Weblogic container.
+   * After example JMS resources are deployed, Weblogic console should be available at http://localhost:7001/console with `admin`/`Welcome1`
+3. To obtain wlthint3client.jar necessary for connecting to Weblogic execute 
+   `bash extractThinClientLib.sh`, file will be copied to `./weblogic` folder.
+
+## Build & Run
+To run Helidon with thin client, flag `--add-opens=java.base/java.io=ALL-UNNAMED` is needed to
+open java.base module to thin client internals.
+1. `mvn clean package`
+2. `java --add-opens=java.base/java.io=ALL-UNNAMED --enable-preview -jar ./target/weblogic-jms-mp.jar`
+3. Visit http://localhost:8080 and try to send and receive messages over Weblogic JMS queue.
+

examples/messaging/weblogic-jms-mp/buildAndRunWeblogic.sh

@@ -0,0 +1,53 @@
+#!/bin/bash -e
+#
+# Copyright (c) 2022 Oracle and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+cd ./weblogic
+
+# Attempt Oracle container registry login.
+# You need to accept the licence agreement for Weblogic Server at https://container-registry.oracle.com/
+# Search for weblogic and accept the Oracle Standard Terms and Restrictions
+docker login container-registry.oracle.com
+
+docker build -t wls-admin .
+
+docker run --rm -d \
+  -p 7001:7001 \
+  -p 7002:7002 \
+  --name wls-admin \
+  --hostname wls-admin \
+  wls-admin
+
+printf "Waiting for WLS to start ."
+while true;
+do
+  if docker logs wls-admin | grep -q "Server state changed to RUNNING"; then
+    break;
+  fi
+  printf "."
+  sleep 5
+done
+printf " [READY]\n"
+
+echo Deploying example JMS queues
+docker exec wls-admin \
+/bin/bash \
+/u01/oracle/wlserver/common/bin/wlst.sh \
+/u01/oracle/setupTestJMSQueue.py;
+
+echo Example JMS queues deployed!
+echo Console avaiable at http://localhost:7001/console with admin/Welcome1
+echo 'Stop Weblogic server with "docker stop wls-admin"'

examples/messaging/weblogic-jms-mp/extractThinClientLib.sh

@@ -0,0 +1,22 @@
+#!/bin/bash -e
+#
+# Copyright (c) 2018, 2022 Oracle and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+
+# Copy wlthint3client.jar from docker container
+docker cp wls-admin:/u01/oracle/wlserver/server/lib/wlthint3client.jar ./weblogic/wlthint3client.jar
+# Copy DemoTrust.jks from docker container(needed if you want to try t3s protocol)
+docker cp wls-admin:/u01/oracle/wlserver/server/lib/DemoTrust.jks ./weblogic/DemoTrust.jks