Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Migration Guide

Red Hat JBoss A-MQ

Migrating to Red Hat JBoss A-MQ 6.0

Red Hat

Version 6.0

Copyright © 2013 Red Hat, Inc. and/or its affiliates.

13 Oct 2017

Abstract

This guide lays out the issues a user will encounter when upgrading to the latest version of Red Hat JBoss A-MQ.

1.1. Migration Procedure
Copy link

Overview
Copy link

This section summarizes the issues you need to consider when migrating from Fuse MQ Enterprise 7.1 to Red Hat JBoss A-MQ 6.0.

Product dependencies
Copy link

Red Hat JBoss A-MQ 6.0 has upgraded the following dependencies:
  • Apache ActiveMQ is upgraded to version 5.8.0.
  • Spring library is upgraded to version 3.1.3.
  • The MQTT client library is upgraded to version 1.4

Migration procedure
Copy link

To migrate an existing broker to Red Hat JBoss A-MQ 6.0, it is recommended that you follow these steps:
  1. To use your existing activemq.xml file with the new MQ console, edit the settings in the following file: 
    MQInstallDir/etc/org.fusesource.mq.fabric.server-default.cfg
    Copy to Clipboard Toggle word wrap
    By default, the preceding configuration file contains the following property settings: 
    broker-name=amq
openwire-port=${activemq.port}
standalone=true
data=${karaf.data}/amq
config=${karaf.base}/etc/activemq.xml

# Defaults for when joining fabric registry
...
    Copy to Clipboard Toggle word wrap
    The broker-name and data properties are not so important: they define substitutable properties that are used by the default activemq.xml file (located in MQInstallDir/etc/activemq.xml). The important properties are as follows:
    config
    Set this property to the absolute pathname of your existing activemq.xml file. (If you are working on a Windows platform, remember to use the forward slash character, /, for the path separater, as is customary in Java property files.)
    standalone
    This property must be set to true. Do not change it.
    openwire-port
    Overrides the Openwire IP port value specified in your existing activemq.xml file. Delete this property setting, if you want to keep the port value specified in your activemq.xml file.
  2. Ensure that any directories referenced in your existing activemq.xml file are specified as absolute pathnames.
  3. To migrate KahaDB data files from earlier Red Hat JBoss A-MQ versions, please observe the following points:
    • Always make backup copies of your existing KahaDB data files, before upgrading the broker.
    • Upgrading from 5.4.x to 5.8—when you start the 5.8 broker instance for the first time, the KahaDB auto-upgrade feature automatically upgrades the KahaDB data files.
    • Upgrading from 5.3.x to 5.8—due to a recent change in the format of the KahaDB index file, db.data, the KahaDB auto-upgrade feature cannot upgrade 5.3 index files. To upgrade from 5.3, therefore, delete the index and redo files, db.data and db.redo, before starting the 5.8 broker. Now, when you start the 5.8 broker, it recreates the index file as it starts up (if your database is large, this could take a long time, for example 20 to 30 minutes).
  4. Study the rest of this guide, to check whether there are any other issues that could affect your system.
  5. If you are using Fuse HQ to monitor your systems:
    1. See the Installation Guide for directions on installing JBoss Operational Network and the required plug-ins.
    2. See Chapter 4, Migrating from Fuse HQ to JBoss Operations Network for information about migrating alerts and other custom setting from Fuse HQ to JBoss Operational Network.
  6. To start up the MQ console—which automatically launches your broker—enter the following command: 
    bin/amq
    Copy to Clipboard Toggle word wrap

1.2. Key Migration Issues
Copy link

activemq-core component
Copy link

In Apache ActiveMQ version 5.8, the activemq-core component is no longer available. It has been split up into the following components: 
activemq-client
activemq-broker
activemq-jdbc-store
activemq-kahadb-store
activemq-leveldb-store
Copy to Clipboard Toggle word wrap
This enables your applications to be more lightweight and modular. For example, a Java client application now requires only the activemq-client JAR, which is much smaller than the old activemq-core JAR.
If you are using the Apache Maven build system, you must replace the activemq-core artifact by either the activemq-broker artifact or the activemq-client artifact.
Note
The activemq-all component (which encapsulates the whole ActiveMQ runtime) is still available.

JMX MBeans renamed
Copy link

The JMX MBeans exposed by ActiveMQ have been refactored to conform to a hierarchical naming structure. If you have any application code that accesses JMX MBeans, you must re-write your code to use the new ObjectName values. All MBeans now share the type=Broker attribute (where type now starts with a lowercase t). The mapping from old to new ObjectName values is shown in the following table:
Expand
Object TypeOld ObjectNameNew ObjectNamed
BrokerType=Brokertype=Broker
DestinationType=Queue|Topic,Destination=<destination identifier>type=Broker,destinationType=Queue|Topic,destinationName=<destination identifier>
ConnectorType=Connectortype=Broker,connector=clientConnectors
NetworkConnectorType=NetworkConnectortype=Broker,connector=networkConnectors
ConnectionType=Connectiontype=Broker,connector=*,connectionViewType=remoteAddress|clientId

1.3. New Features
Copy link

MQTT transport
Copy link

Red Hat JBoss A-MQ now supports the MQTT (MQ Telemetry Transport) transport. There are three variations of the MQTT transport: plain MQTT (mqtt: URL), MQTT+NIO (mqtt+nio: URL), and MQTT+NIO+SSL (mqtt+nio+ssl: URL).
Note
You cannot use the MQTT transport with the JMS client API, because the provided implementation of the JMS client API supports only the Openwire protocol. You must use a dedicated MQTT client to connect to the broker over the MQTT transport.

Stomp 1.2
Copy link

Red Hat JBoss A-MQ now supports Stomp version 1.2.
Note
You cannot use the Stomp transport with the JMS client API, because the provided implementation of the JMS client API supports only the Openwire protocol. You must use a dedicated Stomp client to connect to the broker over the Stomp transport.

MS SQL JDBC driver 4.0
Copy link

Red Hat JBoss A-MQ now supports using MS SQL JDBC driver 4.0 with the JDBC persistence adapter.

JMS selector expressions
Copy link

In order to be compliant with the JMS specification, String property values are no longer converted automatically into numeric values in ActiveMQ 5.8.
For example, if a message has an age property equal to the string value, 21, the selector, age > 18, will not match the property value in ActiveMQ version 5.8. If you would prefer the property to match the selector in this case (by converting the string to a numeric value), you can use the following selector instead: convert_string_expressions:age > 18.

Published address policy
Copy link

It is now possible to specify whether a broker should advertise its endpoint address using a hostname, numeric IP address, or a fully-qualified domain name (FQDN). You can specify this policy by setting the publishedAddressPolicy attribute on the broker's transportConnector element.

1.4. Feature Previews
Copy link

Technical previews of features in development
Copy link

The following features are included in the JBoss A-MQ 6.0 release in order to let you preview technology that is currently under development. These features are not yet supported and are not suitable for deployment in a production environment.

AMQP protocol
Copy link

Red Hat JBoss A-MQ 6.0 includes a technical preview of the AMQP 1.0 protocol (OASIS Advanced Message Queuing Protocol). You can access the AMQP protocol using a URI of the form, amqp://Hostname:Port. SSL security is also supported.
Important
This is a technical preview only. The AMQP protocol is currently not supported and is not suitable for deployment in a production environment.
Note
You cannot use the AMQP protocol with the JMS client API, because the provided implementation of the JMS client API supports only the Openwire protocol. You must use a dedicated AMQP client to connect to the broker with the AMQP protocol.

LevelDB store (on selected platforms)
Copy link

Red Hat JBoss A-MQ includes a technical preview of the new LevelDB store, which uses Google's LevelDB library to maintain the indexes into the log files. The LevelDB store supports XA transactions in ActiveMQ 5.8. The LevelDB store is available only on Windows, Linux, and Mac OS platforms.
Important
This is a technical preview only. The LevelDB store is currently not supported and is not suitable for deployment in a production environment.

1.5. Transport Protocol Changes
Copy link

XMPP transport
Copy link

The XMPP transport is now deprecated and will be removed in a future release.

Openwire over UDP
Copy link

The Openwire over UDP protocol combination is now deprecated and will be removed in a future release.

1.6. Tooling
Copy link

Maven plug-ins
Copy link

Apache ActiveMQ provides a number of plug-ins to use in the Apache Maven build system. In version 5.8.0, the names of these Maven plug-ins has been changed in order to comply with standard Maven plug-in naming conventions. The artifact IDs of the plug-ins have changed as follows:
Expand
Old Maven Plug-In NameNew Maven Plug-In Name
maven-activemq-pluginactivemq-maven-plugin
maven-activemq-memtest-pluginactivemq-memtest-maven-plugin
maven-activemq-perf-pluginactivemq-perf-maven-plugin

Chapter 2. Persistence Layer
Copy link

Pure master/slave failover mechanism
Copy link

The pure master/slave failover mechanism, which was previously deprecated, has been removed from version 5.8. It is recommended that you migrate such a system to use either the shared filesystem mechanism or the shared database mechanism instead.

AMQ message store
Copy link

The AMQ message store is now deprecated and will be removed in a future release.

Kaha message store
Copy link

The Kaha message store is now deprecated and will be removed in a future release.
Note
The Kaha message store is not the same as the KahaDB message store. The Kaha store represents an earlier generation of technology. The KahaDB message store is still supported (and recommended).

Recommended message stores
Copy link

If you are using one of the deprecated message stores, it is recommended that you migrate to one of the following message stores instead:
  • KahaDB message store.
  • JDBC message store.

Chapter 3. Migrating Clients
Copy link

In general, it is recommended that you update your Red Hat JBoss A-MQ clients at the same time that you update the brokers, in order to guarantee compatibility between clients and brokers.
It is possible, in some cases, that older client versions might be interoperable with later broker versions. The Openwire protocol supports version negotiation, such that an old client can negotiate the lowest common version with its peer and use that version. But JBoss A-MQ does not have a comprehensive test suite for testing compatibility between all of the different versions of Apache ActiveMQ. Hence, to be sure of compatibility, it is recommended that you upgrade your clients along with your brokers to use the same version.

Abstract

While Fuse HQ and JBoss Operations Network share the same heritage, they have some important differences.

Overview
Copy link

The major differences between Fuse HQ and JBoss Operations Network(JBoss ON) include:
  • The resource tree is flatter
  • JBoss ON server and agent installations are separate
  • Database support
  • JBoss ON has better automatic discovery
  • Different Java APIs
  • Different scripting languages

Database support
Copy link

Regardless of the database you are currently using, JBoss ON will require you to create all new tables for the monitoring data as part of the server installation process.
JBoss ON supports the following databases:
Expand
DatabaseVersion
Oracle
11g R2 RA
11g R2
11g R1 RAC
11g R1
10g R2 (deprecated)
10g R1 (deprecated)
PostgreSQL
9.1.x
9.0.x
8.4.x
8.3.x

Installing
Copy link

To install JBoss ON, download the server from the Red Hat Customer Portal and follow the instructions for installing on your platform. See the Installation Guide.
JBoss ON agents and monitoring plug-ins are installed from the JBoss ON Web UI.

Configuration
Copy link

JBoss ON agents and servers are configured differently from Fuse HQ agents and servers. For details see the Configuring JBoss ON Servers and Agents.

Scripting
Copy link

JON scripting is different from Fuse HQ scripting. To update your scripts see the Writing JBoss ON Command-Line Scripts.

More information
Copy link

For more information see the JBoss ON Documentation.

Legal Notice
Copy link

Trademark Disclaimer

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Apache, ServiceMix, Camel, CXF, and ActiveMQ are trademarks of Apache Software Foundation. Any other names contained herein may be trademarks of their respective owners.

Legal Notice
Copy link

Third Party Acknowledgements

One or more products in the Red Hat JBoss A-MQ release includes third party components covered by licenses that require that the following documentation notices be provided:
  • JLine (http://jline.sourceforge.net) jline:jline:jar:1.0
    License: BSD (LICENSE.txt) - Copyright (c) 2002-2006, Marc Prud'hommeaux
    All rights reserved.
    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
    • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    • Neither the name of JLine nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  • Stax2 API (http://woodstox.codehaus.org/StAX2) org.codehaus.woodstox:stax2-api:jar:3.1.1
    License: The BSD License (http://www.opensource.org/licenses/bsd-license.php)
    Copyright (c) <YEAR>, <OWNER> All rights reserved.
    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
    • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  • jibx-run - JiBX runtime (http://www.jibx.org/main-reactor/jibx-run) org.jibx:jibx-run:bundle:1.2.3
    License: BSD (http://jibx.sourceforge.net/jibx-license.html) Copyright (c) 2003-2010, Dennis M. Sosnoski.
    All rights reserved.
    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
    • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    • Neither the name of JiBX nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  • JavaAssist (http://www.jboss.org/javassist) org.jboss.javassist:com.springsource.javassist:jar:3.9.0.GA:compile
    License: MPL (http://www.mozilla.org/MPL/MPL-1.1.html)
  • HAPI-OSGI-Base Module (http://hl7api.sourceforge.net/hapi-osgi-base/) ca.uhn.hapi:hapi-osgi-base:bundle:1.2
    License: Mozilla Public License 1.1 (http://www.mozilla.org/MPL/MPL-1.1.txt)
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

© 2026 Red HatBack to top