Solace JCA Resource Adapter for Jakarta Messaging Overview

The Solace JCA Resource Adapter for Jakarta Messaging enables Java applications to integrate with Solace event brokers in Jakarta EE application server environments. This resource adapter provides JMS connectivity using the jakarta.* namespace instead of javax.* packages.

Understanding the Javax to Jakarta Transition

Java EE transitioned to Jakarta EE, and all enterprise Java packages changed from the javax.* namespace to jakarta.* as part of this transition. Key aspects of this transition include:

  • Package Names—All enterprise Java packages changed from javax.* to jakarta.*. For example, javax.jms became jakarta.jms, javax.resource became jakarta.resource.
  • Binary Incompatibility—Applications and libraries compiled against javax.* packages are not compatible with Jakarta EE servers that use jakarta.* packages, and the reverse is also true.
  • Application Server Split—Application servers now fall into two categories based on the namespace they support. For more information, see Supported Application Servers.

What is the Solace JCA Resource Adapter for Jakarta Messaging

The Solace JCA Resource Adapter for Jakarta Messaging is a version of the Solace JCA Resource Adapter for JMS that uses the jakarta.* namespace. It provides the same JMS connectivity and enterprise features as the javax.*-based adapter, but is compatible with Jakarta EE application servers.

The adapter is distributed as a standalone, self-contained Resource Adapter Archive (RAR) file that includes:

  • Jakarta-compatible JCA connector implementation
  • All required Solace Messaging API for JMS libraries
  • Configuration descriptors for Jakarta EE environments

The RAR file is self-contained and does not require you to supply additional Solace JARs for deployment.

Prerequisites

Before deploying the Solace JCA Resource Adapter for Jakarta Messaging, ensure that your environment meets the following requirements:

  • Jakarta EE Version—Jakarta EE 10 or later
  • Jakarta Messaging API—Version 3.1 or later (for jakarta.jms namespace support)
  • Jakarta Connectors—Version 2.0 or later
  • Supported Server—One of the supported Jakarta EE application servers (see Supported Application Servers)
  • JVM Version—Java 11 or later
  • JVM Distribution—Compatible with Oracle JDK or OpenJDK distributions

While Jakarta Messaging 3.1 is required for namespace compatibility with Jakarta EE 10 application servers, the Solace JMS implementation provides JMS 1.1 functionality. Applications must use JMS 1.1 methods and interfaces, not JMS 2.0 features.

Supported Application Servers

The Solace JCA Resource Adapter for Jakarta Messaging has been tested and is supported on the following Jakarta EE 9+ application servers:

  • WildFly 27 and later—Including WildFly 35, which is the primary reference platform
  • JBoss EAP 8 and later—Red Hat's enterprise application platform

The Solace JCA Resource Adapter for Jakarta Messaging has been tested specifically with WildFly and JBoss EAP. While the adapter may work with other Jakarta EE 9+ compliant application servers, those platforms have not been validated for this release.

For the complete list of supported environments and version requirements, see Supported Environments.

Using Each Resource Adapter

Choose the appropriate resource adapter based on your application server's Jakarta EE support. If you are migrating to a new Jakarta EE application server, you will need to use the Solace JCA Resource Adapter for Jakarta Messaging.

Resource Adapter Selection Guide
Use This Resource Adapter For These Application Servers

Solace JCA Resource Adapter for JMS

(sol-jms-ra-<version>.rar)

Legacy Java EE servers:

  • WebSphere Traditional
  • WebLogic ≤ 14.1.1
  • JBoss EAP 7
  • WildFly ≤ 26
  • Tomcat 9
  • GlassFish 5

Solace JCA Resource Adapter for Jakarta Messaging

(sol-jms-jakarta-ra-<version>.rar)

Modern Jakarta EE servers:

  • WildFly 27+
  • JBoss EAP 8+

The Solace JCA Resource Adapter for Jakarta Messaging implements JMS 1.1 functionality using the jakarta.jms namespace. While Jakarta Messaging 3.1 is required for namespace compatibility with Jakarta EE 10 servers, the adapter implements JMS 1.1 semantics to maintain compatibility with Solace event brokers. Applications must use JMS 1.1 methods and interfaces (not JMS 2.0 features). For more information, see Supported Environments.

Obtaining the Solace JCA Resource Adapter for Jakarta Messaging

The Solace JCA Resource Adapter for Jakarta Messaging is available through multiple distribution channels.

Maven Central Repository

To include the Jakarta resource adapter in your Maven project, add the following dependency to your pom.xml file:

<dependency>
    <groupId>com.solacesystems</groupId>
    <artifactId>sol-jms-jakarta-ra</artifactId>
    <version>10.30.0</version>
</dependency>

For detailed information about using Maven with the Solace JMS API, see Building JMS Projects with Maven.

Direct Download

You can download the resource adapter archive (sol-jms-jakarta-ra-<version>.rar) from:

Deploying the Resource Adapter

The Solace JCA Resource Adapter for Jakarta Messaging is deployed as a Resource Adapter Archive (RAR) file to your Jakarta EE application server. The examples use WildFly as the reference platform. While the configuration concepts may apply to other Jakarta EE 9+ compliant servers with platform-specific variations, only WildFly and JBoss EAP have been tested and validated for this release.

To deploy the resource adapter on WildFly:

  1. Obtain the resource adapter archive file (sol-jms-jakarta-ra-<version>.rar) as described in Obtaining the Solace JCA Resource Adapter for Jakarta Messaging.

  2. Copy the RAR file to the WildFly deployments directory:

    cp sol-jms-jakarta-ra-<version>.rar $WILDFLY_HOME/standalone/deployments/

  3. Verify deployment by checking the server logs for confirmation messages.

For JBoss EAP 8+, the deployment process is similar but may use the JBoss CLI or management console. See the application server's documentation for specific deployment procedures.

Configuring the Resource Adapter

After deploying the resource adapter, configure the JMS resources, connection pooling, and transaction support required by your applications. Configuration is typically done through the application server's configuration files (such as standalone.xml for WildFly) or management tools.

Connection Factories

Define connection factories that specify how applications connect to the Solace event broker:

<connection-definitions>
  <connection-definition class-name="com.solacesystems.jms.ra.outbound.ManagedJMSConnectionFactory"
                         jndi-name="java:/jms/SolaceConnectionFactory"
                         enabled="true"
                         pool-name="SolaceConnectionPool">
    <config-property name="ConnectionFactoryJndiName">JNDI/CF/SolaceConnectionFactory</config-property>
  </connection-definition>
</connection-definitions>

Administered Objects

Configure administered objects (queues and topics) for your messaging destinations:

<admin-objects>
  <admin-object class-name="com.solacesystems.jms.ra.outbound.TopicProxy"
                jndi-name="java:/jms/topic/Notifications"
                use-java-context="false"
                pool-name="NotificationsPool">
    <config-property name="Destination">JNDI/Topic/Notifications</config-property>
  </admin-object>
  <admin-object class-name="com.solacesystems.jms.ra.outbound.QueueProxy"
                jndi-name="java:/jms/queue/Orders"
                use-java-context="false"
                pool-name="OrdersPool">
    <config-property name="Destination">JNDI/Queue/Orders</config-property>
  </admin-object>
</admin-objects>

JNDI Bindings

JMS resources are bound to JNDI names using the jndi-name attribute in the connection factory and administered object definitions shown above. Applications can then look up these resources using standard JNDI lookups (see Application Development with Jakarta APIs).

The JNDI configuration on the event broker side remains unchanged from the Solace JCA Resource Adapter for JMS.

Connection Pooling

For Message-Driven Beans, configure connection pooling using activation configuration properties in the jboss-ejb-jar.xml deployment descriptor:

<activation-config-property>
  <activation-config-property-name>
    maxPoolSize
  </activation-config-property-name>
  <activation-config-property-value>
    8
  </activation-config-property-value>
</activation-config-property>

For outbound connection factories, pooling is configured within the <xa-pool> or <pool> elements in the resource adapter configuration as shown in the XA transaction example below.

XA Transactions

The Solace JCA Resource Adapter for Jakarta Messaging supports XA transactions for distributed transaction processing. Configure XA transaction support in the WildFly standalone.xml file within the resource adapters subsystem:

<subsystem xmlns="urn:jboss:domain:resource-adapters:7.1">
  <resource-adapters>
    <resource-adapter id="sol-jms-jakarta-ra">
      <archive>
        sol-jms-jakarta-ra-<version>.rar
      </archive>
      <config-property name="ConnectionURL">tcp://solace-broker.example.com:55555</config-property>
      <config-property name="MessageVPN">default</config-property>
      <config-property name="UserName">default</config-property>
      <config-property name="Password">secret</config-property>
      <transaction-support>XATransaction</transaction-support>
      <connection-definitions>
        <connection-definition class-name="com.solacesystems.jms.ra.outbound.ManagedJMSConnectionFactory"
                               enabled="true"
                               jndi-name="java:/jms/XAConnectionFactory"
                               pool-name="SolaceXAPool">
          <config-property name="ConnectionValidationEnabled">
            true
          </config-property>
          <config-property name="ConnectionFactoryJndiName">
            JNDI/CF/XAConnectionFactory
          </config-property>
          <xa-pool>
            <min-pool-size>
              0
            </min-pool-size>
            <max-pool-size>
              10
            </max-pool-size>
            <prefill>
              false
            </prefill>
            <use-strict-min>
              false
            </use-strict-min>
            <flush-strategy>
              FailingConnectionOnly
            </flush-strategy>
            <pad-xid>
              false
            </pad-xid>
            <wrap-xa-resource>
              true
            </wrap-xa-resource>
          </xa-pool>
          <security>
            <application>
            </application>
          </security>
          <validation>
            <background-validation>
              false
            </background-validation>
          </validation>
        </connection-definition>
      </connection-definitions>
    </resource-adapter>
  </resource-adapters>
</subsystem>

For detailed information about using XA transactions with the Solace JMS API, see Using XA Transactions.

Application Development with Jakarta APIs

When developing applications that use the Solace JCA Resource Adapter for Jakarta Messaging, ensure that your code uses the Jakarta namespace.

Import Statements

Use jakarta.* packages instead of javax.*:

import jakarta.jms.ConnectionFactory;
import jakarta.jms.Queue;
import jakarta.jms.Message;
import jakarta.ejb.MessageDriven;
import jakarta.ejb.ActivationConfigProperty;
import jakarta.resource.ResourceException;

Message-Driven Beans

Define Message-Driven Beans using Jakarta annotations and activation specs:

@MessageDriven(
    name = "SolaceMessageMDB",
    activationConfig = {
        @ActivationConfigProperty(
            propertyName = "destination",
            propertyValue = "queue/myQueue"
        ),
        @ActivationConfigProperty(
            propertyName = "destinationType",
            propertyValue = "jakarta.jms.Queue"
        )
    }
)
public class SolaceMessageMDB implements jakarta.jms.MessageListener {

    @Override
    public void onMessage(jakarta.jms.Message message) {
        // Process message
    }
}

JNDI Lookups

Applications can look up connection factories and destinations using standard JNDI:

InitialContext ctx = new InitialContext();
ConnectionFactory cf = (ConnectionFactory) ctx.lookup("java:/jms/SolaceConnectionFactory");
Queue queue = (Queue) ctx.lookup("java:/jms/queue/myQueue");

Runtime Behavior

At runtime, the Solace JCA Resource Adapter for Jakarta Messaging manages all interactions between your applications and the Solace event broker:

  • Connection Management—The adapter creates and manages connections to the event broker, including connection pooling and lifecycle management.
  • Message Delivery to MDBs—The adapter receives messages from Solace queues and topics and delivers them to Message-Driven Beans configured with activation specs.
  • Outbound Messaging—Applications can send messages through the adapter using Jakarta JMS APIs and JNDI-bound connection factories.
  • Transaction Coordination—For XA-enabled connections, the adapter participates in distributed transactions coordinated by the application server's transaction manager.
  • Resource Pooling—The application server manages connection and session pools according to the configured resource adapter settings.

Behavioral Parity with Solace JCA Resource Adapter for JMS

The Solace JCA Resource Adapter for Jakarta Messaging maintains behavioral parity with the Solace JCA Resource Adapter for JMS for all core JMS functionality:

  • Connection establishment and management
  • Message publishing and consumption
  • Transaction semantics (both local and XA)
  • Message acknowledgment modes
  • Guaranteed and Direct message delivery

Configuration concepts and connection properties remain consistent between the two adapters, with the primary difference being the Jakarta namespace used in code and deployment descriptors.

While the connection properties are identical between the Solace JCA Resource Adapter for JMS and the Solace JCA Resource Adapter for Jakarta Messaging, the configuration mechanisms may differ due to changes in application server platforms and their configuration modes. Consult your application server's documentation for platform-specific configuration procedures.