This document demonstrates how to integrate Solace Java Message Service (JMS) with the WebLogic Application Server for production and consumption of JMS messages. The goal of this document is to outline best practices for this integration to enable efficient use of both the application server and Solace JMS.
The target audience of this document is developers using the WebLogic Application Server with knowledge of both the WebLogic Application Server and JMS in general. As such this document focuses on the technical steps required to achieve the integration.
Note this document provides instructions on configuring and deploying the Solace JCA 1.5 resource adapter using the web console application of WebLogic, as well as instructions on configuring Solace as a Foreign JMS Provider Module. For detailed background on either Solace JMS or the WebLogic Application Server refer to the referenced documents below.
This document is divided into the following sections to cover the Solace JMS integration with WebLogic Application Server:
These links contain information related to this guide:
This tutorial requires access to Solace PubSub+ event broker and requires that you know several connectivity properties about your event broker. Specifically you need to know the following:
This is the address clients use when connecting to the event broker to send and receive messages. (Format:
The event broker Message VPN that this client should connect to.
The client username. (See Notes below)
The client password. (See Notes below)
There are several ways you can get access to Solace messaging and find these required properties.
Solace provides a JCA compliant resource adapter for integrating Java enterprise applications with the Solace JMS event broker. There are two options for integrating Solace with WebLogic for use by Java enterprise applications including embedded and stand-alone deployment. This section will cover instructions on configuring the Resource Adapter Archive (RAR) file for stand-alone deployment, and configuring Solace as a Foreign JMS Provider
In order to illustrate WebLogic Application Server integration, the following sections will highlight the required WebLogic configuration changes and provide sample code for sending and receiving messages using Enterprise Java Beans.
This EJB sample consists of two enterprise beans, a Message Driven Bean and a Session Bean. The MDB is configured to receive a message on a "requests" Queue. When the MDB receives a message it then calls a method of the Session Bean to send a reply message to a "reply" Queue. The EJB sample requires configuration of various J2C entities in WebLogic to support usage of the Solace JCA compliant resource adapter.
The following steps are required to accomplish the above goals of sending and receiving messages using the Solace JMS event broker.
The Solace JCA 1.5 resource adapter is provided as a standalone RAR file and is versioned together with a specific release of the Solace JMS API. The JMS API libraries are bundled inside a single resource adapter RAR file for deployment to the WebLogic application server.
This integration guide will demonstrate the creation of Solace resources and the configuration of the WebLogic Application Server"s managed resources. The section below outlines the resources that are created and used in the subsequent sections.
To illustrate this integration example, all named resources created on the Solace Event Broker will have the following prefixes:
The following Solace event broker resources are required for the integration sample in this document.
Solace Event Broker Host
Refer to section 2- Get Solace Messaging for values
Solace destination for messages consumed by JEE enterprise application
Solace destination for messages produced by JEE enterprise application
JNDI Connection Factory
The JNDI Connection factory for controlling Solace JMS connection properties
JNDI Queue Name
The JNDI name of the queue used in the samples
JNDI Queue Name
The JNDI name of the queue used in the samples
To illustrate this integration example, all named resources created in WebLogic application server will have the following prefixes:
The following WebLogic application server resources are required for the integration example in this document.
The Solace JMS Resource Adapter packaged as a Standalone RAR package (Implements a JCA compliant Resource Adapter)
J2C connection factory
A J2C entity used to access a Solace javax.jms.ConnectionFactory (For Outbound messaging)
J2C administered object
A J2C entity used to perform a JNDI lookup of a javax.jms.Queue on the Solace event broker
J2C administered object
A J2C entity used to perform a JNDI lookup of a javax.jms.Queue on the Solace event broker
The following entities on the Solace event broker need to be configured at a minimum to enable JMS to send and receive messages within the WebLogic Application Server.
The recommended approach for configuring a event broker is using Solace PubSub+ Manager, Solace's browser-based administration console packaged with the Solace PubSub+ event broker. This document uses CLI as the reference to remain concise - look for related settings if using Solace PubSub+ Manager.
For more details related to event broker CLI see Solace-CLI. Wherever possible, default values will be used to minimize the required configuration. The CLI commands listed also assume that the CLI user has a Global Access Level set to Admin. For details on CLI access levels please see User Authentication and Authorization.
This section outlines how to create a message-VPN called "solace_VPN" on the event broker with authentication disabled and 2GB of message spool quota for Guaranteed Messaging. This message-VPN name is required in the configuration when connecting to the messaging event broker. In practice, appropriate values for authentication, message spool and other message-VPN properties should be chosen depending on the end application's use case.
> home > enable # configure (config)# create message-vpn solace_VPN (config-msg-vpn)# authentication (config-msg-vpn-auth)# user-class client (config-msg-vpn-auth-user-class)# basic auth-type none (config-msg-vpn-auth-user-class)# exit (config-msg-vpn-auth)# exit (config-msg-vpn)# no shutdown (config-msg-vpn)# exit (config)# (config)# message-spool message-vpn solace_VPN (config-message-spool)# max-spool-usage 2000 (config-message-spool)# exit (config)#
This section outlines how to update the default client-profile and how to create a client username for connecting to the Solace event broker. For the client-profile, it is important to enable guaranteed messaging for JMS messaging and transacted sessions for the XA-transactions capable Solace JCA Resource Adapter. The chosen client username of "solace_user" will be required by the WebLogic Application Server when connecting to the Solace event broker.
(config)# client-profile default message-vpn solace_VPN (config-client-profile)# message-spool allow-guaranteed-message-receive (config-client-profile)# message-spool allow-guaranteed-message-send (config-client-profile)# message-spool allow-guaranteed-endpoint-create (config-client-profile)# message-spool allow-transacted-sessions (config-client-profile)# exit (config)# (config)# create client-username solace_user message-vpn solace_VPN (config-client-username)# acl-profile default (config-client-username)# client-profile default (config-client-username)# no shutdown (config-client-username)# exit (config)#
This integration guide shows receiving messages and sending reply messages within the WebLogic Application Server using two separate JMS Queues. For illustration purposes, these queues are chosen to be exclusive queues with a message spool quota of 2GB matching quota associated with the message VPN. The queue names chosen are "solace_requests" and "solace_replies".
(config)# message-spool message-vpn solace_VPN (config-message-spool)# create queue solace_requests (config-message-spool-queue)# access-type exclusive (config-message-spool-queue)# max-spool-usage 2000 (config-message-spool-queue)# permission all delete (config-message-spool-queue)# no shutdown (config-message-spool-queue)# exit (config-message-spool)# create queue solace_replies (config-message-spool-queue)# access-type exclusive (config-message-spool-queue)# max-spool-usage 2000 (config-message-spool-queue)# permission all delete (config-message-spool-queue)# no shutdown (config-message-spool-queue)# exit (config-message-spool)# exit (config)#
To enable the JMS clients to connect and look up the queue destination required by WebLogic Application Server, there are three JNDI objects required on the Solace event broker:
direct-transportis disabled for JMS persistent messaging.
They are configured as follows:
Note: this will configure a connection factory without XA support as the default for the XA property is False. See section Enabling XA Support for JMS Connection Factories for XA configuration.
(config)# jndi message-vpn solace_VPN (config-jndi)# create connection-factory JNDI/Sol/CF (config-jndi-connection-factory)# property-list messaging-properties (config-jndi-connection-factory-pl)# property default-delivery-mode persistent (config-jndi-connection-factory-pl)# exit (config-jndi-connection-factory)# property-list transport-properties (config-jndi-connection-factory-pl)# property direct-transport false (config-jndi-connection-factory-pl)# property "reconnect-retry-wait" "3000" (config-jndi-connection-factory-pl)# property "reconnect-retries" "20" (config-jndi-connection-factory-pl)# property "connect-retries-per-host" "5" (config-jndi-connection-factory-pl)# property "connect-retries" "1" (config-jndi-connection-factory-pl)# exit (config-jndi-connection-factory)# exit (config-jndi)# (config-jndi)# create queue JNDI/Sol/Q/requests (config-jndi-queue)# property physical-name solace_requests (config-jndi-queue)# exit (config-jndi)# (config-jndi)# create queue JNDI/Sol/Q/replies (config-jndi-queue)# property physical-name solace_replies (config-jndi-queue)# exit (config-jndi)# (config-jndi)# no shutdown (config-jndi)# exit (config)#
Solace provides a JCA compliant Resource Adapter that can be deployed to the WebLogic application server, allowing Enterprise Java Beans to connect to Solace through a standard JCA interface. This integration guide outlines the steps to deploy the resource adapter which is provided by Solace as a packaged stand-alone RAR file. This is the recommended way of integrating Solace with WebLogic as it provides support for XA transactions.
The following Java system property must be configured in the application server JVM properties:
This allows WebLogic to function correctly with a non-Oracle JMS provider.
Depending on your environment, this can be done by editing the startWebLogic.cmd or startWebLogic.sh file, which can be found in <WL_domain>/bin folder. Add the following at the start of the script:
The following steps will make the Solace resource adapter have access to the Solace JMS libraries. Steps to place the Solace libraries into the WebLogic CLASSPATH:
The following steps will make the Solace resource adapter available to all enterprise applications (Refer to the above section "Description of Resources Required" for the file location of the Solace JCA 1.5 Resource Adapter RAR file).
Steps to deploy the Solace JMS Resource Adapter:
Connecting to the Solace event broker through the Solace JMS Resource Adapter requires configuration of additional resources in WebLogic. Two key pieces of information are required including connectivity information to the Solace event broker and client authentication data.
The above information is specified across one or more J2C entities depending on your application"s JMS message flow (Inbound, Outbound, or both).
The Solace resource adapter includes several custom properties for specifying connectivity and authentication details to the Solace Event Broker. Setting these properties at the Resource Adapter level makes the information available to all child J2C entities like J2C connection factory, and J2C administered objects. The properties can also be overridden at the J2C entity level allowing connectivity to multiple Solace event brokers.
Please refer to [WL-REF] and [JCA-1.5] for more details on configuring general JEE authentication options. The Authentication section below discusses configuration of Solace specific authentication in more detail.
Steps to configure the Solace JMS Resource Adapter:
In the "Configuration > General" tab, add a JNDI name for the solace resource adapter.
In the "Configuration > Properties" tab, edit the connectivity properties for the Solace JMS Resource Adapter. Values entered here will be inherited by the adapter"s outbound connection pools and admin objects. Values are entered by clicking in the "Property Value" column and confirming each value with the Enter key.
The following table summarizes the values used for the resource adapter"s bean properties.
The connection URL to the Solace event broker of the form: `tcp://__IP:Port__` (Update the value "__IP:Port__" with the actual Solace event broker message-backbone VRF IP)
A Message VPN, or virtual event broker, to scope the integration on the Solace event broker.
The client username credentials on the Solace Event Broker
Optional password of the Client Username on the Solace Event Broker
Semicolon-separated list for [advanced control of the connection](https://docs.solace.com/Solace-JMS-API/JMS-Properties-Reference.htm) . For this example, leave empty. Supported values are shown below.
Extended Properties Supported Values:
Enter the local JNDI name for the destination and click Finish.
Enter the remote JNDI name for the destination and "Save" to save your configuration.
The following table summarizes the values used for the J2C connection factory custom properties.
The JNDI name of the JMS connection factory as configured on the Solace event broker.
Enable the validation of connections. While not strictly necessary, it is recommended to set it to "true".
The Connection Pool tab allows the configuration of the amount of concurrent connections that are run between the WebLogic server and the Solace Event Broker. Those connections are shared between the requests coming from the applications, therefore the resources can be used more efficiently (limited number of connections) and optimized for performance (pre-initialized connections).
The amounts to be set vary, depending on the demand of the WebLogic application(s). Capacity planning and load testing should identify the appropriate values. E.g. if only every 3rd request is using messaging, the pool size can be reduced approximately by that factor from the maximum amount of concurrent requests.
The most relevant values are:
Number of connections to the Solace Event Broker initially available in the pool for this connection factory.
Maximum number of connection created for this pool.
The number of connections created when the demand exceeds the current amount of connections. A higher value meets demand spikes more efficiently but can use more resources.
Connections can be released if demand is low, freeing up resources.
Highest Num Unavailable
Size of a list for connections that failed creation. Attempts to reconnect are periodically made for entries on this list.
Highest Num of Waiters
Number of clients that can wait for a connection if all available connections are currently in use. This controls the "overflow" size for client requests before an "unavailable resource" exception is thrown.
Save and return to the resource adapter configuration page.
In the "Deployments" page, select the checkbox for the resource adapter and click on Update. Select "Redeploy this application using the following deployment files" and click on Finish. This redeploys the adapter so that all of the above changes become active.
If a resource adapter is not used, the following steps should be followed in order to set up Solace as a foreign JMS provider on the WebLogic server.
This option is deprecated and does not support XA transactions. New deployments should deploy using the resource adapter.
JNDI Initial Context Factory
JNDI Connection URL
tcp://HOST:PORT e.g. tcp://188.8.131.52:22234
JNDI Properties Credentials
Password of the Client Username for Solace.
Individual custom properties. Properties are delimited by the Enter key and are set as Key=Value pairs. The following 2 properties must be set: java.naming.security.principal=%CLIENT_USERNAME%, Solace_JMS_VPN=%VPN_NAME%
Desired local name of the Destination
Local JNDI Name
This is the JNDI name which MDBs and other resources deployed on WebLogic will use to publish and subscribe to Destinations
Remote JNDI Name
This is the JNDI name for the Destination as configured on the Solace Event Broker for the Endpoint. This can be configured using SolAdmin from the JMS Tab
Any text name, not used in code
Local JNDI Name
This is the JNDI name which MDBs and other resources deployed on WebLogic will use to lookup the connection factory to connect to Solace
Remote JNDI Name
This is the JNDI name for the Connection Factory as configured on the Solace Event Broker. This can be configured using CLI or through SolAdmin from the JMS Tab
The sample code linked below shows the implementation of a message-driven bean (ConsumerMDB) which listens for JMS messages to arrive on the configured Solace JCA destination. Upon receiving a message, the MDB calls the method sendMessage() of the ProducerSB session bean which in turn sends a reply message to a "reply" Queue destination.
This sample code can be used with the Solace Resource Adapter or Solace as a Foreign Server, assuming the configuration is correct.
Note that it is possible to perform JNDI lookups either on WebLogic"s local JNDI store, or perform lookups directly on the Solace broker by specifying the resourceAdapterJndiName activation configuration property. The sample provides examples for both methods.
There are associated files you can use for reference:
For general tuning including EJBs / MDBs, refer to https://docs.oracle.com/middleware/11119/wls/PERFM/toc.htm
In particular, enabling concurrent MDB instances may not mean that messages are processed in parallel. When using Exclusive Queues or Durable Topics, messages are processed by a single instance of an MDB even if there are multiple configured instances.
If using XA, it is strongly recommended to set total time for low level connection retries to be longer than the transaction timeout, but shorter than the maximum duration of XA calls. These settings can be found in 3 locations:
JVM threads that have been running for more than a certain configurable time (default 600 seconds), will be marked as STUCK in Weblogic. If using Spring Framework with Weblogic, a DefaultMessageListenerContainer using a standard TaskExecutor will continue reusing a thread indefinitely. This will cause threads to become marked as STUCK. We recommend setting MaxMessagesPerTask in the DMLC to a finite value in order to avoid this.
The Solace Messaging API for JMS section "Establishing Connection and Creating Sessions" provides details on how to enable the Solace JMS connection to automatically reconnect to the standby event broker in the case of a HA failover of a Solace event broker. By default Solace JMS connections will reconnect to the standby event broker in the case of an HA failover.
In general the Solace documentation contains the following note regarding reconnection:
Note: When using HA redundant event brokers, a fail-over from one event broker to its mate will typically occur in less than 30 seconds, however, applications should attempt to reconnect for at least five minutes.
In "Setting up Solace JNDI References", the Solace CLI commands correctly configured the required JNDI properties to reasonable values. These commands are repeated here for completeness.
(config)# jndi message-vpn solace_VPN (config-jndi)# create connection-factory JNDI/Sol/CF (config-jndi-connection-factory)# property-list transport-properties (config-jndi-connection-factory-pl)# property "reconnect-retry-wait" "3000" (config-jndi-connection-factory-pl)# property "reconnect-retries" "20" (config-jndi-connection-factory-pl)# property "connect-retries-per-host" "5" (config-jndi-connection-factory-pl)# property "connect-retries" "1" (config-jndi-connection-factory-pl)# exit (config-jndi-connection-factory)# exit (config-jndi)# exit (config)#
In addition to configuring the above properties for connection factories, care should be taken to configure connection properties for performing JNDI lookups to the Solace event broker. These settings can be configured in the WebLogic application server globally by setting them at the Solace resource adapter level or within individual J2C entities.
To configure JNDI connection properties for JNDI lookups, set the corresponding Solace JMS property values (as a semicolon-separated list of name=value pairs) through the "ExtendedProps" custom property of the Solace resource adapter or J2C administered objects.
The key component for debugging integration issues with the Solace JMS API is to enable API logging. Enabling API logging from WebLogic Application Server is described below.
The Solace JMS API and Solace Resource Adapter use Jarkarta Commons Logging to support different logging frameworks.
When using log4j with WebLogic, the directory in which the log4j.properties file and log4j jar file exist is on the classpath. A sample log4j.properties setup is shown below:
# Log4j configuration properties used log4j.appender.A1=org.apache.log4j.ConsoleAppender log4j.appender.A1.layout=org.apache.log4j.PatternLayout log4j.appender.A1.layout.ConversionPattern=%d %-5p [%c] %m%n # Second appender is set by default to level log4j.appender.A2=org.apache.log4j.net.SocketAppender log4j.appender.A2.RemoteHost=localhost log4j.appender.A2.Port=4445 # Categories log4j.additivity=false log4j.logger.com.solacesystems=ERROR, A1 log4j.additivity.com.solacesystems=false log4j.logger.com.solacesystems.jcsmp=WARN, A1 log4j.additivity.com.solacesystems.jcsmp=false log4j.logger.com.solacesystems.jms=WARN, A1 log4j.additivity.com.solacesystems.jms=false
The integration example illustrated in Section 3 of this guide uses the authentication information specified in the custom properties of the Solace resource adapter. These authentication properties are used whenever Application Managed authentication is specified for a JCA resource. No matter the authentication mode (Application-Managed or Container-Managed) specified for a resource, the Solace "MessageVPN" information for a connection is always retrieved from the Solace resource adapter configured properties (or the configured properties of the respective J2C resource).
WebLogic supports configuration of Container-Managed authentication for J2C resources. The administrator of an EJB application can configure Solace event broker sign-on credentials using a J2C authentication alias that is assigned to either a J2C activation specification or J2C connection factory . Solace JCA resource adapter supports authentication using the "DefaultPrincipalMapping "mapping configuration alias. Refer to [WL-REF] for more details on configuring J2C authentication data aliases.
The Solace event broker supports a variety of client authentications schemes as described in [Solace-FG] in the Section "Client Authentication and Authorization". The Solace JCA resource adapter supports a subset of these schemes including "Basic" authentication and "SSL Client Certificate" authentication. The default authentication scheme used by the Solace JMS Resource Adapter is AUTHENTICATION_SCHEME_BASIC.
The value of the Solace resource adapter custom property "extendedProps" is used to specify an alternate authentication scheme such as
AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE. The value of the custom property "extendedProps" consists of a semicolon-separated list of Solace JMS property / value pairs (SOLACE_PROPERTY=value). You can specify the required properties for an alternate authentication scheme using this technique. Refer to the document Solace JMS API Online Reference Documentation for further details on the required JMS properties for configuring SSL client certificate authentication.
Although the authentication scheme 1AUTHENTICATION_SCHEME_BASIC1 is the default scheme, that scheme could also have been specified using the "extendedProps" custom property of the resource adapter.
This section outlines how to update the Solace event broker and WebLogic Application Server configuration to switch the client connection to using secure connections with the Solace event broker. For the purposes of illustration, this section uses a server certificate on the Solace event broker and basic client authentication. It is possible to configure Solace JMS to use client certificates instead of basic authentication. This is done using configuration steps that are very similar to those outlined in this document. The Solace Feature Guide and Solace Messaging API for JMS outline the extra configuration items required to switch from basic authentication to client certificates.
To change a WebLogic Application Server from using a plain text connection to a secure connection, first the Solace event broker configuration must be updated as outlined in above and the Solace JMS configuration within the WebLogic Application Server must be updated as outlined in above.
To enable secure connections to the Solace event broker, the following configuration must be updated on the Solace event broker.
Before starting, here is some background information on the server certificate required by the event broker. This is from the Solace documentation:
To enable TLS/SSL-encryption, you must set the TLS/SSL server certificate file that the Solace PubSub+ event broker is to use. This server certificate is presented to clients during TLS/SSL handshakes. The server certificate must be an x509v3 certificate and include a private key. The server certificate and key use an RSA algorithm for private key generation, encryption and decryption, and they both must be encoded with a Privacy Enhanced Mail (PEM) format.
To configure the server certificate, first copy the server certificate to the Solace event broker. For the purposes of this example, assume the server certificate file is named "mycert.pem".
# copy sftp://[<username>@]<ip-addr>/<remote-pathname>/mycert.pem /certs <username>@<ip-addr>'s password: #
Then set the server certificate for the Solace event broker.
(config)# ssl server-certificate mycert.pem (config)#
By default, the Solace event broker accepts secure messaging client connections on port 55443. If this port is acceptable then no further configuration is required and this section can be skipped. If a non-default port is desired, then follow the steps below. Note this configuration change will disrupt service to all clients of the Solace event broker and should therefore be performed during a maintenance window when this client disconnection is acceptable. This example assumes that the new port should be 55403.
(config)# service smf (config-service-smf)# shutdown All SMF and WEB clients will be disconnected. Do you want to continue (y/n)? y (config-service-smf)# listen-port 55403 ssl (config-service-smf)# no shutdown (config-service-smf)# exit (config)#
By default within Solace message VPNs both the plain-text and SSL services are enabled. If the Message VPN defaults remain unchanged, then this section can be skipped. However, if within the current application VPN, this service has been disabled, then for secure communication to succeed it should be enabled. The steps below show how to enable SSL within the SMF service to allow secure client connections from the WebLogic Application Server.
(config)# message-vpn solace_VPN (config-msg-vpn)# service smf (config-msg-vpn-service-smf)# ssl (config-msg-vpn-service-ssl)# no shutdown (config-msg-vpn-service-ssl)# exit (config-msg-vpn-service-smf)# exit (config-msg-vpn-service)# exit (config-msg-vpn)# exit (config)#
Secure connections to the Solace JMS provider require configuring SSL parameters on one or more J2C entities. While using the Solace Resource Adapter, these two parameters include changes to the Solace J2C custom properties "ConnectionURL" and "ExtendedProps". Note that the property values for "ConnectionURL" and "ExtendedProps" are inherited by J2C connection factory,,and J2C administered objects from their parent Resource Adapter. Thus, unless you are connecting to multiple Solace event brokers, a best practice is to configure values for "ConnectionURL" and "ExtendedProps" in the Solace Resource Adapter, otherwise the SSL related changes should be duplicated across custom properties for all of the J2C entities you want to secure.
The required SSL parameters include modifications to the URL scheme of "ConnectionURL" (from "tcp" to "tcps"), and setting additional SSL attributes through the custom property "ExtendedProps". The following sections describe the required changes in more detail.
While using Solace as a Foreign Server module, the "ConnectionURL " parameter refered to above maps to "JNDI Connection URL" in the general properties configuration page of the Foreign Server in the WebLogic Administration Console. "ExtendedProps" maps to "JNDI Properties".
In order to signal to the Solace JMS API that the connection should be a secure connection, the protocol must be updated in the URI scheme. The Solace JMS API has a URI format as follows:
<URI Scheme>://[username]:[password]@<IP address>[:port]
Recall from above, originally, the "ConnectionURL" was as follows:
This specified a URI scheme of "smf" which is the plaint-text method of communicating with the Solace event broker. This should be updated to "tcps" to switch to secure communication giving you the following configuration:
The Solace JMS API must be able to validate the server certificate of the Solace event broker in order to establish a secure connection. To do this, the following trust store parameters need to be provided.
First the Solace JMS API must be given a location of a trust store file so that it can verify the credentials of the Solace event broker server certificate during connection establishment. This parameter takes a URL or Path to the trust store file.
Specifying a value for the parameter "Solace_JMS_SSL_TrustStore" is accomplished by modifying the Solace J2C custom property "ExtendedProps". The value for the property is comprised of a semicolon-separated list of Solace JMS parameters.
A trust store password may also be specified. This password allows the Solace JMS API to validate the integrity of the contents of the trust store. This is done through the Solace JMS parameter "Solace_JMS_SSL_TrustStorePassword".
There are multiple formats for the trust store file. By default Solace JMS assumes a format of Java Key Store (JKS). So if the trust store file follows the JKS format then this parameter may be omitted. Solace JMS supports two formats for the trust store: "jks" for Java Key Store or "pkcs12". Setting the trust store format is done through the parameter "Solace_JMS_SSL_TrustStoreFormat":
In a similar fashion, the authentication scheme used to connect to Solace may be specified using the parameter "Solace_JMS_Authentication_Scheme":
The integration examples in this guide use basic authentication (the default authentication scheme):
This section demonstrates how to configure the Solace event broker to support the transaction processing capabilities of the Solace JCA Resource Adapter. In addition, code examples are provided showing JMS message consumption and production over both types of Enterprise Java Bean transactions: Container-Managed-Transactions (CMT) and Bean-Managed-Transaction (BMT) configuration.
Both BMT and CMT transactions are mapped to Solace JCA Resource Adapter XA Transactions. XA transactions are supported from the general-availability release of SolOS version 7.1.
Note: BMT is using one-phase-commit and for CMT it is up to the container to use one-phase or two-phase-commit.
In addition to the standard XA Recovery functionality provided through the Solace JCA Resource Adapter, the Solace event broker provides XA transaction administration facilities in the event that customers must perform manual failure recovery. For full details refer to the Solace documentation on administering and configuring XA Transaction on the Solace event broker.
When using CMT or BMT transactions, XA transaction support must be enabled for the specific JMS connection factories: the customer needs to configure XA support property for the respective JNDI connection factory on the Solace event broker using the Solace PubSub+ Manager admin console or the CLI as follows:
(config)# jndi message-vpn solace_VPN (config-jndi)# connection-factory JNDI/Sol/CF (config-jndi-connection-factory)# property-list messaging-properties (config-jndi-connection-factory-pl)# property xa true (config-jndi-connection-factory-pl)# exit (config-jndi-connection-factory)# exit (config-jndi)#
The following examples demonstrate how to receive and send messages using EJB transactions. Examples are given for both BMT and CMT in GitHub:
The following code is similar to the above example but specifies Container-Managed XA Transaction support for inbound messages. In this example, the Message-Driven-Bean (MDB) - "XAConsumerMDB" is configured such that the EJB container will provision and start an XA transaction prior to calling the onMessage() method and finalize or rollback the transaction when onMessage() exits (Rollback typically occurs when an unchecked exception is caught by the Container).
Note that it is important to limit the maximum number of XAConsumerMDB in the pool to ensure that the maximum per client concurrent transaction session count on the Solace broker is not exceeded. The maximum concurrent transacted sessioncount can be configured on the client-profile on the Solace broker.
<?xml version="1.0" encoding="UTF-8"?> <wls:weblogic-ejb-jar xmlns:wls="http://xmlns.oracle.com/weblogic/weblogic-ejb-jar" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd http://xmlns.oracle.com/weblogic/weblogic-ejb-jar http://xmlns.oracle.com/weblogic/weblogic-ejb-jar/1.7/weblogic-ejb-jar.xsd"> <wls:weblogic-enterprise-bean> <wls:ejb-name>XAConsumerMDB</wls:ejb-name> <wls:message-driven-descriptor> <wls:pool> <wls:max-beans-in-free-pool>10</wls:max-beans-in-free-pool> <wls:initial-beans-in-free-pool>1</wls:initial-beans-in-free-pool> </wls:pool> </wls:message-driven-descriptor> </wls:weblogic-enterprise-bean> </wls:weblogic-ejb-jar>
The following code is similar to the EJB example from above but configures Container-Managed XA Transaction support for outbound messaging. In this example, the Session Bean "XAProducerSB" method "SendMessage()" requires that the caller have an existing XA Transaction context. In this example, the "SendMessage()" method is called from the MDB - "XAConsumerMDB" in the above example where the EJB container has created an XA Transaction context for the inbound message. When the method sendMessage() completes the EJB container will either finalize the XA transaction or perform a rollback operation.
EJB code can use the UserTransaction interface (Bean-Managed) to provision and control the lifecycle of an XA transaction. The EJB container will not provision XA transactions when the EJB class"s "TransactionManagement" type is designated as "BEAN" managed. In the following example, the session Bean "XAProducerBMTSB" starts a new XA Transaction and performs an explicit "commit()" operation after successfully sending the message. If a runtime error is detected, then an explicit "rollback()" operation is executed. If the rollback operation fails, then the EJB code throws an EJBException() to allow the EJB container to handle the error.
The Solace Feature Guide section "Disaster Recovery" contains a sub-section on "Application Implementation" which details items that need to be considered when working with Solace"s Data Center Replication feature. This integration guide will show how the following items required to have a WebLogic Application Server successfully connect to a backup data center using the Solace Data Center Replication feature.
As described in Solace Feature Guide , the host list provides the address of the backup data center. This is configured within the WebLogic application server through the ConnectionURL custom property value (of a respective J2C entity) as follows:
The active site and standby site addresses are provided as a comma-separated list of "Connection URIs". When connecting, the Solace JMS connection will first try the active site and if it is unable to successfully connect to the active site, then it will try the standby site. This is discussed in much more detail in the referenced Solace documentation
In order to enable applications to successfully reconnect to the standby site in the event of a data center failure, it is required that the Solace JMS connection be configured to attempt connection reconnection for a sufficiently long time to enable the manual switch-over to occur. This time is application specific depending on individual disaster recovery procedures and can range from minutes to hours depending on the application. In general it is best to tune the reconnection by changing the "reconnect retries" parameter within the Solace JNDI to a value large enough to cover the maximum time to detect and execute a disaster recovery switch over. If this time is unknown, it is also possible to use a value of "-1" to force the Solace JMS API to reconnect indefinitely.
The reconnect retries is tuned in the Solace event broker CLI as follows:
(config)# jndi message-vpn solace_VPN (config-jndi)# connection-factory JNDI/Sol/CF (config-jndi-connection-factory)# property-list transport-properties (config-jndi-connection-factory-pl)# property "reconnect-retries" "-1" (config-jndi-connection-factory-pl)# exit (config-jndi-connection-factory)# exit (config-jndi)# exit (config)#
When a disaster recovery switch-over occurs, the Solace JMS API must establish a new connection to the Solace event brokers in the standby data center. Because this is a new connection there are some special considerations worth noting. The [Solace-FG] contains the following notes: Java and JMS APIs
For client applications using the Java or JMS APIs, any sessions on which the clients have published Guaranteed messages will be destroyed after the switch‑over. To indicate the disconnect and loss of publisher flow:
The Java API will generate an exception from the JCSMPStreamingPublishCorrelatingEventHandler.handleErrorEx() that contains a subcode of JCSMPErrorResponseSubcodeEx.UNKNOWN_FLOW_NAME. The JMS API will generate an exception from the javax.jms.ExceptionListener that contains the error code SolJMSErrorCodes.EC_UNKNOWN_FLOW_NAME_ERROR.
Upon receiving these exceptions the client application will know to create a new session.
After a new session is established, the client application can republish any Guaranteed messages that had been sent but not acked on the previous session, as these message might not have been persisted and replicated.
To avoid out-of-order messages, the application must maintain an unacked list that is added to before message publish and removed from on receiving an ack from the event broker. If a connection is re‑established to a different host in the hostlist, the unacked list must be resent before any new messages are published.
Note: When sending persistent messages using the JMS API, a producer"s send message will not return until an acknowledgment is received from the event broker. Once received, it is safe to remove messages from the unacked list.
Alternatively, if the application has a way of determining the last replicated message—perhaps by reading from a last value queue—then the application can use that to determine where to start publishing. For integration with WebLogic, it"s important to consider this interaction in the context of a Message Driven Bean and Session Bean.
There is no special processing required during a disaster recovery switch-over specifically for applications receiving messages. After successfully reconnecting to the standby site, it is possible that the application will receive some duplicate messages. The application should apply normal duplicate detection handling for these messages.
For WebLogic applications that are sending messages, there is nothing specifically required to reconnect the Solace JMS connection. However, any messages that were in the process of being sent will receive an error from the Solace Resource Adapter. These messages must be retransmitted as possibly duplicated. The application should catch and handle any of the following exceptions: