WebLogic JMS Connector

Overview
Maven Coordinates
Configuration
Usage

Overview

WebLogic JMS Connector extends Helidon JMS connector with special handling for legacy WebLogic T3 thin clients. Legacy versions of thin client can be found in server/lib directory(WL_HOME/server/lib/wlthint3client.jar) of any WebLogic Server installation.

Helidon supports Jakarta EE 10. Legacy versions of javax based thin T3 client will not work correctly when added to the classpath. Legacy thin T3 clients must be loaded from a filesystem location specified by the thin-jar property.

Warning

Do not place legacy wlthint3client.jar on the Helidon classpath. The client library location needs to be configured and loaded by the Helidon messaging connector.

Warning

When using the legacy WebLogic T3 thin clients, make sure to start the Helidon application with --add-opens=java.base/java.io=ALL-UNNAMED to allow reflection with the legacy wlthint3client.

Updated versions of thin T3 clients that are compatible with modern Jakarta runtimes can be downloaded from Oracle Software Delivery Cloud as wlthint3client.jakarta. However, Jakarta based thin clients can be placed on the Helidon classpath and used with this specialized connector or the JMS connector After the download, the thin T3 client artefact needs to be installed in the Maven repository accessible from the application build.

Maven Coordinates

To enable WebLogic JMS connector, add the following dependency to your project’s pom.xml (see Managing Dependencies).

<dependency>
    <groupId>io.helidon.messaging.wls-jms</groupId>
    <artifactId>helidon-messaging-wls-jms</artifactId>
</dependency>

Configuration

Connector name: helidon-weblogic-jms

Table 1. Attributes
`jms-factory`	The 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`); this path can be usually found within the WebLogic Server installation. `WL_HOME/server/lib/wlthint3client.jar`
`principal`	The WebLogic initial context principal (user).
`credentials`	The WebLogic initial context credential (password)
`type`	The possible values are: `queue`, `topic`. Default value is: `topic`
`destination`	The queue or topic name in WebLogic CDI (Create Destination Identifier) Syntax.
`jndi.destination`	JNDI destination identifier. When no such JNDI destination is found, falls back to `destination` with CDI syntax.
`acknowledge-mode`	The 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`	The JMS API message selector expression based on a subset of the SQL92. Expression can access only headers and properties, not the payload.
`client-id`	The client identifier for JMS connection.
`durable`	True for creating durable consumer (only for topic). Default value: `false`
`subscriber-name`	The subscriber name for the durable consumer used to identify subscription.
`non-local`	If `true` then any message that is 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`	The timeout interval (in millis) for polling for the next message in every poll cycle. Default value: `50`
`period-executions`	The period for executing poll cycles in millis. Default value: `100`
`session-group-id`	When multiple channels share the same `session-group-id`, they also share the same JMS session and JDBC connection.
`producer.unit-of-order`	All messages from the 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 the queue with WebLogic CDI Syntax.

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
        # JNDI identifier for the same queue
        jndi.destination: jms/TestQueue

When configuring destination with WebLogic CDI, apply the following syntax:

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.

Usage

Consuming

Consuming one by one unwrapped value:

@Incoming("from-wls")
public void consumeWls(String msg) {
    System.out.println("WebLogic says: " + msg);
}

Consuming one by one, manual ack:

@Incoming("from-wls")
@Acknowledgment(Acknowledgment.Strategy.MANUAL)
public CompletionStage<Void> consumewls(JmsMessage<String> msg) {
    System.out.println("WebLogic says: " + msg.getPayload());
    return msg.ack();
}

Producing

Producing to WebLogic JMS:

@Outgoing("to-wls")
public PublisherBuilder<String> produceToWls() {
    return ReactiveStreams.of("test1", "test2");
}

Example of more advanced producing to WebLogic JMS:

@Outgoing("to-wls")
public PublisherBuilder<Message<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(() -> CompletableFuture.completedStage(null)
                            .thenRun(() -> System.out.println("Acked!")))
                    .build());
}

Example of even more advanced producing to WebLogic JMS with custom mapper:

@Outgoing("to-wls")
public PublisherBuilder<Message<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.