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 Jakarta Messaging clients using HornetQ can connect to a JBoss EAP 7 server running ActiveMQ Artemis.
  • Backward compatibility: JBoss EAP 7 Jakarta Messaging clients using JBoss EAP messaging can connect to the legacy JBoss EAP 6 server running HornetQ.

32.1. Forward Compatibility

Forward compatibility requires no code changes to legacy JBoss EAP 6 Jakarta Messaging 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)
  • 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)
  • Set up a legacy messaging socket-binding that listens on port 5445.

    /socket-binding-group=standard-sockets/socket-binding=legacy-messaging:add(port=5445)
  • 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)
  • Create a legacy HornetQ Jakarta Messaging 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])
  • Create legacy HornetQ Jakarta Messaging 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]

    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])

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

    Note

    To avoid any code change in the legacy Jakarta Messaging clients, the legacy JNDI entries configured in the messaging-activemq subsystem must match the lookup expected by the legacy Jakarta Messaging 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 Jakarta Messaging clients will not be able to communicate with the JBoss EAP 7 servers.

32.2. Backward Compatibility

Backward compatibility requires no configuration change in the legacy JBoss EAP 7 servers. JBoss EAP 7 Jakarta Messaging clients do not look up resources on the legacy server, but instead use client-side JNDI to create Jakarta Messaging resources. JBoss EAP 7 Jakarta Messaging 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 Jakarta Messaging ConnectionFactory and Destination resources.

For example, if a JBoss EAP 7 Jakarta Messaging client wants to communicate with a legacy server using a Jakarta Messaging 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

The client can then use the jms/ConnectionFactory name to create the Jakarta Messaging ConnectionFactory and use the jms/myQueue to create the Jakarta Messaging 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 Jakarta Messaging client to communicate with the HornetQ broker in the legacy server.