Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 32. Backward and Forward Compatibility

JBoss EAP supports both backward and forward compatibility with legacy versions of JBoss EAP that were using HornetQ as their messaging brokers, such as JBoss EAP 6. These two compatibility modes are provided by the JBoss EAP built-in messaging server, ActiveMQ Artemis, that supports the HornetQ’s core protocol.

  • Forward compatibility: Legacy JMS clients using HornetQ can connect to a JBoss EAP 7 server running ActiveMQ Artemis.
  • Backward compatibility: JBoss EAP 7 JMS clients using JBoss EAP messaging can connect to the legacy JBoss EAP 6 server running HornetQ.

32.1. Forward Compatibility
Copy link

Forward compatibility requires no code changes to legacy JBoss EAP 6 JMS clients. Support is provided by the JBoss EAP messaging-activemq subsystem and its resources. To enable support of forward compatibility make the following changes to the configuration of the JBoss EAP 7 server. Example management CLI commands for a standalone server are provided for each step.

  • Create a socket-binding the listens on port 4447 for remote legacy clients. 

    /socket-binding-group=standard-sockets/socket-binding=legacy-remoting:add(port=4447)
    Copy to Clipboard Toggle word wrap

  • Create a legacy remote-connector that will use the socket-binding created in the previous step. This is required for JNDI lookups. 

    /subsystem=remoting/connector=legacy-remoting-connector:add(socket-binding=legacy-remoting)
    Copy to Clipboard Toggle word wrap

  • Set up a legacy messaging socket-binding that listens on port 5445. 

    /socket-binding-group=standard-sockets/socket-binding=legacy-messaging:add(port=5445)
    Copy to Clipboard Toggle word wrap

  • Set up a remote-connector and a remote-acceptor in the messaging-activemq subsystem that use the binding from the previous step. 

    /subsystem=messaging-activemq/server=default/remote-connector=legacy-messaging-connector:add(socket-binding=legacy-messaging)

/subsystem=messaging-activemq/server=default/remote-acceptor=legacy-messaging-acceptor:add(socket-binding=legacy-messaging)
    Copy to Clipboard Toggle word wrap

  • Create a legacy HornetQ JMS ConnectionFactory in the legacy-connection-factory element of the messaging-activemq subsystem. 

    /subsystem=messaging-activemq/server=default/legacy-connection-factory=legacy-discovery:add(entries=[java:jboss/exported/jms/LegacyRemoteConnectionFactory], connectors=[legacy-messaging-connector])
    Copy to Clipboard Toggle word wrap

  • Create legacy HornetQ JMS destinations and include legacy-entries attributes to the jms-queue or jms-topic resources. 

    jms-queue add --queue-address=myQueue --entries=[java:jboss/exported/jms/myQueue-new] --legacy-entries=[java:jboss/exported/jms/myQueue]

jms-topic add --topic-address=myTopic --entries=[java:jboss/exported/jms/myTopic-new] --legacy-entries=[java:jboss/exported/jms/myTopic]
    Copy to Clipboard Toggle word wrap

    You can add legacy-entries to an existing queue or topic by following the below example. 

    /subsystem=messaging-activemq/server=default/jms-queue=myQueue:write-attribute(name=legacy-entries,value=[java:jboss/exported/jms/myQueue])
    Copy to Clipboard Toggle word wrap

    While the entries attributes are used by JBoss EAP messaging JMS clients, the legacy-entries are used by the legacy HornetQ JMS clients. Legacy JMS clients look up this legacy JMS resource to communicate with JBoss EAP 7.

    Note

    To avoid any code change in the legacy JMS clients, the legacy JNDI entries configured in the messaging-activemq subsystem must match the lookup expected by the legacy JMS client.

Management CLI migrate Operation

When you run the management CLI migrate operation to update your messaging subsystem configuration, if the boolean argument add-legacy-entries is set to true, the messaging-activemq subsystem creates the legacy-connection-factory resource and adds legacy-entries to the jms-queue and jms-topic resources. The legacy entries in the migrated messaging-activemq subsystem will correspond to the entries specified in the legacy messaging subsystem and the regular entries are created with a -new suffix.

If the boolean argument add-legacy-entries is set to false when you run the migrate operation, no legacy resources are created in the messaging-activemq subsystem and legacy JMS clients will not be able to communicate with the JBoss EAP 7 servers.

32.2. Backward Compatibility
Copy link

Backward compatibility requires no configuration change in the legacy JBoss EAP 7 servers. JBoss EAP 7 JMS clients do not look up resources on the legacy server, but instead use client-side JNDI to create JMS resources. JBoss EAP 7 JMS clients can then use these resources to communicate with the legacy server using the HornetQ core protocol.

Warning

JBoss EAP 7 client connections to a JBoss EAP 5 server are currently not supported.

JBoss EAP messaging supports client-side JNDI to create JMS ConnectionFactory and Destination resources.

For example, if a JBoss EAP 7 JMS client wants to communicate with a legacy server using a JMS queue named "myQueue", it must use the following properties to configure its JNDI InitialContext: 

java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory
connectionFactory.jms/ConnectionFactory=tcp://<legacy server address>:5445? \
    protocolManagerFactoryStr=org.apache.activemq.artemis.core.protocol.hornetq.client.HornetQClientProtocolManagerFactory
queue.jms/myQueue=myQueue
Copy to Clipboard Toggle word wrap

The client can then use the jms/ConnectionFactory name to create the JMS ConnectionFactory and use the jms/myQueue to create the JMS Queue. Note that the property protocolManagerFactoryStr=org.apache.activemq.artemis.core.protocol.hornetq.client.HornetQClientProtocolManagerFactory is mandatory when specifying the URL of the legacy connection factory. This allows the JBoss EAP messaging JMS client to communicate with the HornetQ broker in the legacy server.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat