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

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)

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

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

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

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

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.