|
| 1 | +/////////////////////////////////////////////////////////////////////////////// |
| 2 | + |
| 3 | + Copyright (c) 2022 Oracle and/or its affiliates. |
| 4 | + |
| 5 | + Licensed under the Apache License, Version 2.0 (the "License"); |
| 6 | + you may not use this file except in compliance with the License. |
| 7 | + You may obtain a copy of the License at |
| 8 | + |
| 9 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 10 | + |
| 11 | + Unless required by applicable law or agreed to in writing, software |
| 12 | + distributed under the License is distributed on an "AS IS" BASIS, |
| 13 | + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 14 | + See the License for the specific language governing permissions and |
| 15 | + limitations under the License. |
| 16 | + |
| 17 | +/////////////////////////////////////////////////////////////////////////////// |
| 18 | +
|
| 19 | += Weblogic JMS Connector |
| 20 | +:toc: |
| 21 | +:toc-placement: preamble |
| 22 | +:description: Reactive Messaging support for Weblogic JMS in Helidon MP |
| 23 | +:keywords: helidon, mp, messaging, jms, weblogic, wls, thin |
| 24 | +:feature-name: Weblogic JMS connector |
| 25 | +:microprofile-bundle: false |
| 26 | +:rootdir: {docdir}/../.. |
| 27 | +
|
| 28 | +include::{rootdir}/includes/mp.adoc[] |
| 29 | +include::{rootdir}/includes/dependencies.adoc[] |
| 30 | +
|
| 31 | +[source,xml] |
| 32 | +---- |
| 33 | +<dependency> |
| 34 | + <groupId>io.helidon.messaging.wls-jms</groupId> |
| 35 | + <artifactId>helidon-messaging-wls-jms</artifactId> |
| 36 | +</dependency> |
| 37 | +---- |
| 38 | +
|
| 39 | +== Reactive Weblogic JMS Connector |
| 40 | +
|
| 41 | +Connecting streams to Weblogic JMS with Reactive Messaging couldn't be easier. |
| 42 | +This connector extends Helidon JMS connector with special handling for Weblogic T3 thin client. |
| 43 | +
|
| 44 | +Connecting to Weblogic JMS connection factories requires proprietary T3 thin client library which can be obtained from |
| 45 | +Weblogic installation. |
| 46 | +
|
| 47 | +WARNING: Avoid placing `wlthint3client.jar` on Helidon classpath, client library location needs to be |
| 48 | +configured and loaded by Helidon messaging connector. |
| 49 | +
|
| 50 | +=== Configuration |
| 51 | +
|
| 52 | +Connector name: `helidon-weblogic-jms` |
| 53 | +
|
| 54 | +.Attributes |
| 55 | +|=== |
| 56 | +|`jms-factory` | JNDI name of the JMS factory configured in Weblogic |
| 57 | +|`url` | t3, t3s or http address of Weblogic server |
| 58 | +|`thin-jar` | Filepath to the Weblogic thin T3 client jar(wlthint3client.jar), can be usually found within Weblogic installation |
| 59 | +`WL_HOME/server/lib/wlthint3client.jar` |
| 60 | +|`principal` | Weblogic initial context principal(user) |
| 61 | +|`credential` | Weblogic initial context credential(password) |
| 62 | +|`type` | Possible values are: `queue`, `topic`. Default value is: `topic` |
| 63 | +|`destination` | Queue or topic name in WebLogic CDI Syntax(CDI stands for Create Destination Identifier) |
| 64 | +|`acknowledge-mode` |Possible values are: `AUTO_ACKNOWLEDGE`- session automatically acknowledges a client’s receipt of a message, |
| 65 | +`CLIENT_ACKNOWLEDGE` - receipt of a message is acknowledged only when `Message.ack()` is called manually, |
| 66 | +`DUPS_OK_ACKNOWLEDGE` - session lazily acknowledges the delivery of messages. Default value: `AUTO_ACKNOWLEDGE` |
| 67 | +|`transacted` | Indicates whether the session will use a local transaction. Default value: `false` |
| 68 | +|`message-selector` | JMS API message selector expression based on a subset of the SQL92. |
| 69 | +Expression can only access headers and properties, not the payload. |
| 70 | +|`client-id` | Client identifier for JMS connection. |
| 71 | +|`client-id` | Client identifier for JMS connection. |
| 72 | +|`durable` | True for creating durable consumer (only for topic). Default value: `false` |
| 73 | +|`subscriber-name` | Subscriber name for durable consumer used to identify subscription. |
| 74 | +|`non-local` | If true then any messages published to the topic using this session's connection, |
| 75 | +or any other connection with the same client identifier, |
| 76 | +will not be added to the durable subscription. Default value: `false` |
| 77 | +|`named-factory` | Select in case factory is injected as a named bean or configured with name. |
| 78 | +|`poll-timeout` | Timeout for polling for next message in every poll cycle in millis. Default value: `50` |
| 79 | +|`period-executions` | Period for executing poll cycles in millis. Default value: `100` |
| 80 | +|`session-group-id` | When multiple channels share same `session-group-id`, they share same JMS session and same JDBC connection as well. |
| 81 | +|`producer.unit-of-order` | All messages from same unit of order will be processed sequentially in the order they were created. |
| 82 | +|=== |
| 83 | +
|
| 84 | +Configuration is straight forward. Use JNDI for localizing and configuring of JMS ConnectionFactory |
| 85 | +from Weblogic. Notice the destination property which is used to define queue with |
| 86 | +https://docs.oracle.com/cd/E24329_01/web.1211/e24387/lookup.htm#JMSPG915[WebLogic CDI Syntax](CDI stands for Create Destination Identifier). |
| 87 | +
|
| 88 | +[source,yaml] |
| 89 | +.Example config: |
| 90 | +---- |
| 91 | +mp: |
| 92 | + messaging: |
| 93 | + connector: |
| 94 | + helidon-weblogic-jms: |
| 95 | + # JMS factory configured in Weblogic |
| 96 | + jms-factory: jms/TestConnectionFactory |
| 97 | + # Path to the WLS Thin T3 client jar |
| 98 | + thin-jar: wlthint3client.jar |
| 99 | + url: t3://localhost:7001 |
| 100 | + incoming: |
| 101 | + from-wls: |
| 102 | + connector: helidon-weblogic-jms |
| 103 | + # WebLogic CDI Syntax(CDI stands for Create Destination Identifier) |
| 104 | + destination: ./TestJMSModule!TestQueue |
| 105 | + outgoing: |
| 106 | + to-wls: |
| 107 | + connector: helidon-weblogic-jms |
| 108 | + destination: ./TestJMSModule!TestQueue |
| 109 | +---- |
| 110 | +
|
| 111 | +When configuring destination with WebLogic CDI, the following syntax needs to be applied: |
| 112 | +
|
| 113 | +.Non-Distributed Destinations |
| 114 | +`jms-server-name/jms-module-name!destination-name` |
| 115 | +
|
| 116 | +In our example we are replacing jms-server-name with `.` as we don’t have to look up the server we are connected to. |
| 117 | +
|
| 118 | +.Uniform Distributed Destinations (UDDs) |
| 119 | +`jms-server-name/jms-module-name!jms-server-name@udd-name` |
| 120 | +
|
| 121 | +Destination for UDD doesn't have `./` prefix, because distributed destinations can be served by multiple servers within a cluster. |
| 122 | +
|
| 123 | +=== Consuming |
| 124 | +
|
| 125 | +[source,java] |
| 126 | +.Consuming one by one unwrapped value: |
| 127 | +---- |
| 128 | +@Incoming("from-wls") |
| 129 | +public void consumeWls(String msg) { |
| 130 | + System.out.println("Weblogic says: " + msg); |
| 131 | +} |
| 132 | +---- |
| 133 | +
|
| 134 | +[source,java] |
| 135 | +.Consuming one by one, manual ack: |
| 136 | +---- |
| 137 | +@Incoming("from-wls") |
| 138 | +@Acknowledgment(Acknowledgment.Strategy.MANUAL) |
| 139 | +public CompletionStage<?> consumewls(JmsMessage<String> msg) { |
| 140 | + System.out.println("Weblogic says: " + msg.getPayload()); |
| 141 | + return msg.ack(); |
| 142 | +} |
| 143 | +---- |
| 144 | +
|
| 145 | +=== Producing |
| 146 | +
|
| 147 | +[source,java] |
| 148 | +.Producing to Weblogic JMS: |
| 149 | +---- |
| 150 | +@Outgoing("to-wls") |
| 151 | +public PublisherBuilder<String> produceToWls() { |
| 152 | + return ReactiveStreams.of("test1", "test2"); |
| 153 | +} |
| 154 | +---- |
| 155 | +
|
| 156 | +[source,java] |
| 157 | +.Example of more advanced producing to Weblogic JMS: |
| 158 | +---- |
| 159 | +@Outgoing("to-wls") |
| 160 | +public PublisherBuilder<String> produceToJms() { |
| 161 | + return ReactiveStreams.of("test1", "test2") |
| 162 | + .map(s -> JmsMessage.builder(s) |
| 163 | + .correlationId(UUID.randomUUID().toString()) |
| 164 | + .property("stringProp", "cool property") |
| 165 | + .property("byteProp", 4) |
| 166 | + .property("intProp", 5) |
| 167 | + .onAck(() -> System.out.println("Acked!")) |
| 168 | + .build()); |
| 169 | +} |
| 170 | +---- |
| 171 | +[source,java] |
| 172 | +.Example of even more advanced producing to Weblogic JMS with custom mapper: |
| 173 | +---- |
| 174 | +@Outgoing("to-wls") |
| 175 | +public PublisherBuilder<String> produceToJms() { |
| 176 | + return ReactiveStreams.of("test1", "test2") |
| 177 | + .map(s -> JmsMessage.builder(s) |
| 178 | + .customMapper((p, session) -> { |
| 179 | + TextMessage textMessage = session.createTextMessage(p); |
| 180 | + textMessage.setStringProperty("custom-mapped-property", "XXX" + p); |
| 181 | + return textMessage; |
| 182 | + }) |
| 183 | + .build() |
| 184 | + ); |
| 185 | +} |
| 186 | +---- |
| 187 | +
|
| 188 | +=== Secured t3 over SSL(t3s) |
| 189 | +For initiating SSL secured t3 connection, trust keystore with WLS public certificate is needed. |
| 190 | +Standard WLS installation has pre-configured Demo trust store: `WL_HOME/server/lib/DemoTrust.jks`, |
| 191 | +we can store it locally for connecting WLS over t3s. |
| 192 | +
|
| 193 | +[source,yaml] |
| 194 | +.Example config: |
| 195 | +---- |
| 196 | +mp: |
| 197 | + messaging: |
| 198 | + connector: |
| 199 | + helidon-weblogic-jms: |
| 200 | + jms-factory: jms/TestConnectionFactory |
| 201 | + thin-jar: wlthint3client.jar |
| 202 | + # Notice t3s protocol is used |
| 203 | + url: t3s://localhost:7002 |
| 204 | +---- |
| 205 | +
|
| 206 | +Helidon application needs to be aware about our WLS SSL public certificate. |
| 207 | +
|
| 208 | +[source,bash] |
| 209 | +.Running example with WLS truststore |
| 210 | +---- |
| 211 | +java --add-opens=java.base/java.io=ALL-UNNAMED \ |
| 212 | +-Djavax.net.ssl.trustStore=DemoTrust.jks \ |
| 213 | +-Djavax.net.ssl.trustStorePassword=DemoTrustKeyStorePassPhrase \ |
| 214 | +-jar ./target/helidon-wls-jms-demo.jar |
| 215 | +---- |
0 commit comments