[[Messaging_Backward_&_Forward_Compatibility]]
= Backward & Forward Compatibility

WildFly 10 supports both backwards and forwards compatibility with
legacy versions that were using HornetQ as their messaging brokers (such
as JBoss AS7, WildFly {wildflyVersion} & 9). +
These two compatibility modes are provided by the ActiveMQ Artemis
project that supports the HornetQ's CORE protocol:

* backward compatibility: WildFly 10 JMS clients (using Artemis) can
connect to legacy app server (running HornetQ)
* forward compatibility: legacy JMS clients (using HornetQ) can connect
to WildFly 10 app server (running Artemis).

[[forward-compatibility]]
== Forward Compatibility

Forward compatibility requires no code change in legacy JMS clients. It
is provided by WildFly 10 messaging-activemq subsystem and its
resources.

* `legacy-connection-factory` is a subresource of the
`messaging-activemq`'s `server` and can be used to store in JNDI a
HornetQ-based JMS ConnectionFactory.

[source, xml]
----
<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.0"> 
    <server name="default">
        ...
        <legacy-connection-factory name="legacyConnectionFactory-discovery" 
                                   entries="java:jboss/exported/jms/RemoteConnectionFactory"
                                   ... />
    </server>
</subsystem>
----

* Legacy HornetQ-based JMS destinations can also be configured by
providing a `legacy-entries` attribute to the `jms-queue` and
`jms-topic` resource.

[source, xml]
----
    <jms-queue name="myQueue"
               entries="java:jboss/exported/jms/myQueue-new"
               legacy-entries="java:jboss/exported/jms/myQueue" />
    <jms-topic name="testTopic"
               entries="java:jboss/exported/jms/myTopic-new"
               legacy-entries="java:jboss/exported/jms/myTopic" />
----

The `legacy-entries` must be used by legacy JMS clients (using HornetQ)
while the regular `entries` are for WildFly 10 JMS clients (using
Artemis).

The legacy JMS client will then lookup this `legacy` JMS resources to
communicate with WildFly 10. +
To avoid any code change in the legacy JMS clients, the legacy JNDI
entries must match the lookup expected by the legacy JMS client.

[[migration]]
=== Migration

During migration, the legacy `messaging` subsystem will create
`legacy-connection-factory` resource and add `legacy-entries` to the
`jms-queue` and `jms-topic` resource if the boolean attribute
`add-legacy-entries` is set to `true` for its `migrate` operation. If
that is the case, the legacy entries in the migrated
`messaging-activemq` subsystem will correspond to the entries specified
in the legacy `messaging` subsystem and the regular entries will be
created with a `-new` suffix. +
If `add-legacy-entries` is set to `false` during migration, no legacy
resources will be created in the `messaging-activemq` subsystem and
legacy JMS clients will not be able to communicate with WildFly 10
servers.

[[backward-compatibility]]
== Backward Compatibility

Backward compatibility requires no configuration change in the legacy
server. +
WildFly 10 JMS clients do not look up resources on the legacy server but
uses client-side JNDI to create their JMS resources. Artemis JMS client
can then uses these resources to communicate with the legacy server
using the HornetQ CORE protocol.

Artemis supports
http://activemq.apache.org/artemis/docs/1.1.0/using-jms.html#jndi-configuration[Client-side
JNDI] to create JMS resources ( `ConnectionFactory` and `Destination`).

For example, if a WidFly 10 JMS clients wants to communicate with a
legacy server using a JMS queue named `myQueue`, it must use the
following properties to configure its JNDI `InitialContext`:

[source]
----
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
----

It can then use the `jms/ConnectionFactory` name to create the JMS
ConnectionFactory and `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 so
that the Artemis JMS client can communicate with the HornetQ broker in
the legacy server.
