Migrating JBoss Messaging 1.4 to HornetQ

[gaohoward]

Migrating JBoss Messaging 1.4 to HornetQ

This article is provided as a general guide for users to migrate their existing JBM applications in JBoss AS 4/5 to HornetQ

General Steps

1. Shutdown client and server

To make the migration easier, make sure there are as few ongoing transactions as possible before shutdown.

2. Back up data

This basically include

a. JBM's database tables
b. JBM's configuration files, including connection factories, destination factories, remoting, jgroups, and
everything else in {jboss-profile}/deploy/messaging (or jboss-messaging.sar in AS 4)
{config}/deploy/messaging and your database data, dest configurations, fact config, bridge config, remoting config,

3. application source code change

If you are using standard JMS in your application, there is no need to change your source code.

4. Removing JBM and installing HornetQ

To remove JBM, simply delete the JBoss profile that containing the JBM.

To install HornetQ, use the scripts provided in HornetQ's binary distribution.

5. configuration migration (queues, etc, cluster)

Here gives the mapping between the configuration of JBM and HornetQ

6. data migration

Here gives the mapping between the database table and the HornetQ's bindings/journal

The main data should be remainging messages and binding informations, and possible long-running transactions.

There should be some tools/scripts to help on this.

[gaohoward]

guys, this is only a sketch to start with. Any comments welcomed.

[clebert.suconic]

- There should be some tools/scripts to help on this.

It should be possible to write a program that reads from JBM Persistent Manager and writes into HornetQ storage manager.

[gaohoward]

+1

[timfox]

Clebert Suconic wrote:

- There should be some tools/scripts to help on this.

It should be possible to write a program that reads from JBM Persistent Manager and writes into HornetQ storage manager.

The JMS bridge can be used to do this.

[gaohoward]

An update. It is still a work in progress. No need for everyone to waste time review now. But a quick scan to make sure I'm on the right track will be appreciated.

Migrating JBoss Messaging 1.4 to HornetQ

This article is provided as a general guide for users to migrate their existing Jboss Messaging applications in JBoss Application Server 4 and 5 to HornetQ 2.0.

General Steps

1. Shutdown client and server

JBoss Messaging uses a database to store its persistent data (unless a null persistence is used). You don't need to shutdown the database for the purpose of migration.

2. Back up data

Before starting the migration, it is important to back up all the data used in your application and JBoss Messaging server.

The following data are used by JBoss Messaging:

a. JBoss Messaging database tables

JBoss Messaging uses the following tables in its database:

JBM_DUAL

CREATE TABLE JBM_MSG_REF

JBM_MSG

JBM_TX

JBM_COUNTER

JBM_ID_CACHE

JBM_TX_EX (since 1.4.0.SP3.CP10 and 1.4.6.GA.SP1)

JBM_POSTOFFICE

JBM_USER

JBM_ROLE

b. JBoss Messaging configuration files.

The location where most configuration files go is under {jboss-profile}/deploy/messaging in AS 5 or {jboss-profile}/deploy/messaging/jboss-messaging.sar in AS 4. For example if your JBOSS_HOME is /home/jboss/jboss-5.1.0.GA and your JBoss Messaging server profile is 'messaging', then the location would be /home/jboss/jboss-5.1.0.GA/messaging/deploy/messaging.

Applications may choose other places to deploy some configuration files than this location.

Below is a list of JBoss Messaging configuration files that you need to migrate to HornetQ

1.Connection Factory service configuration files – these files contain JMS connection factories deployed with JBoss Messaging server.

2.Destination service configuration files – these files contain JMS queues and topics deployed with JBoss Messaging server.

3.Bridge service configuration files – these files contains bridge services deployed with JBoss Messaging server.

Other configuration files such as messaging-service.xml and database persistence configuration file are JBoss Messaging mbean configurations. They are not targets of the migration.

JBoss Messaging also rely on some other services to work. They are JBoss Remoting and Jgroups services. Their configuration files contains settings specific to applications. As HornetQ has a different transport layer and cluster design, you need to map the parameters in those configuration files to their HornetQ equivalents (if any).

3. Application code

If you are using standard JMS in your application, there is no need to change your source code.

If you are using JBoss Messaging proprietary features, such as ordering groups, you need to adapt them to HornetQ equivalent features.

4. Removing JBM and installing HornetQ

To remove JBM, simply delete the JBoss profile that containing the JBM.

To install HornetQ, use the scripts provided in HornetQ's binary distribution ( under config/jboss-as-4

for AS 4 and config/jboss-as-5 for AS 5,  please see  HornetQ Quickstart Guide Chapter 5 for details).

The scripts automatically create two profiles (one non-clustered and clustered) with default configurations. You need to create more if your application requires more nodes. To do this just copy from the corresponding existing profiles.

5. Server Configuration Migration

5.1 non-clustered configuration

5.2 clustered configuration

6. Migrating JMS Administered Objects and Bridges

The ways used by HornetQ to create and deploy JMS connection factories, destinations and bridges are different from those used by JBoss Messaging.

With JBoss Messaging, a JMS object (a connection factory or a JMS queue/topic) or a bridge is configured as a Mbean service within a JBoss Application server, whereas with HornetQ it is implemented as a POJO. Therefore, to migrate the configuration of such an object from JBoss Messaging to HornetQ, you need to know which configuration parameter in JBM maps to which one in HornetQ.

The following gives the mapping of those configurations between JBoss Messaging and HornetQ.

6.1 JMS Connection Factories

ClientID

JNDIBindings

PrefetchSize

SlowConsumers

StrictTck

SendAcksAsync

DefaultTempQueueFullSize

DefaultTempQueuePageSize

DefaultTempQueueDownCacheSize

DupsOKBatchSize

SupportsLoadBalancing

SupportsFailover

DisableRemotingChecks

LoadBalancingFactory

Connector

EnableOrderingGroup

DefaultOrderingGroupName

Configuration mapping example

6.2 JMS Queues and Topics

6.2.1 Queue configurations

Name

JNDIName

DLQ

ExpiryQueue

RedeliveryDelay

MaxDeliveryAttempts

SecurityConfig

FullSize

PageSize

DownCacheSize

CreatedProgrammatically

MessageCount

ScheduledMessageCount

MaxSize

Clustered

MessageCounter

MessageCounterStatistics

ConsumerCount

DropOldMessageOnRedeploy

Configuration mapping example

6.2.2 Topic configurations

Name

JNDIName

DLQ

ExpiryQueue

RedeliveryDelay

MaxDeliveryAttempts

SecurityConfig

FullSize

PageSize

DownCacheSize

CreatedProgrammatically

MaxSize

Clustered

MessageCounterHistoryDayLimit

MessageCounters

AllMessageCount

DurableMessageCount

NonDurableMessageCount

AllSubscriptionsCount

DurableSubscriptionsCount

NonDurableSubscriptionsCount

DropOldMessageOnRedeploy

Configuration mapping example

6.3 JMS Bridges

SourceProviderLoader

TargetProviderLoader

SourceDestinationLookup

TargetDestinationLookup

SourceUsername

SourcePassword

TargetUsername

TargetPassword

QualityOfServiceMode

Selector

MaxBatchSize

MaxBatchTime

SubName

ClientID

FailureRetryInterval

MaxRetries

AddMessageIDInHeader

Configuration mapping example

7. Other configurations

7.1 Remoting

7.2 Jgroups

8. Migrating Existing Messages

Here gives the mapping between the database table and the HornetQ's bindings/journal

The main data should be remainging messages and binding informations, and possible long-running transactions.

There should be some tools/scripts to help on this.

Using bridge is also a convenient way.

9. Applications that uses management APIs

JBoss Messaging exposes the management API through mbean interfaces. HornetQ has different ways to expose their management API.

10. restart client and server

[bozhidar]

Maybe it would be better if this guide was available in the wiki and you just posted update notifications from time to time so people will review the new version. I'm currently in the process of such a migration and your notes are most welcome. When I'm done with it I'll certainly have some suggestions for the guide.

[gaohoward]

Sure a good idea. I'll put it to wiki. Thanks.

[bozhidar]

Btw section 8 mentions the possibility of a script that can migrate the data in JBM tables to a HornetQ journal. Does such a script exist already or is using a bridge the only way to migrate the data?

[clebert.suconic]

It would be possible to write a tool that will read one StorageManager and write into another. But we haven't done it yet due to timing and resources.

[bozhidar]

A note and a question regarding the JMS migration section. You say that no code changes are necessary, however, the manual says that MDBs should be annotated with @ResourceAdapter("hornetq-ra.rar"), unless you rename the file to jms-ra.rar(which requires the update of some configuration files). I also have problems with some MDBs with durable subscriptions to topics, which worked fine with JBM 1.4 - I get the following exceptions with HornetQ 2.1:

15:51:52,467 ERROR [HornetQActivation] Unable to reconnect org.hornetq.ra.inflow.HornetQActivationSpec(ra=org.hornetq.ra.HornetQResourceAdapter@4a238c1e destination=topic/PickingRequestForTourPlannedTopic destinationType=javax.jms.Topic ack=Auto-acknowledge durable=true clientID=null user=null maxSession=1)

javax.jms.InvalidClientIDException: Cannot create durable subscription for null - client ID has not been set

at org.hornetq.ra.inflow.HornetQMessageHandler.setup(HornetQMessageHandler.java:103)

at org.hornetq.ra.inflow.HornetQActivation.setup(HornetQActivation.java:295)

at org.hornetq.ra.inflow.HornetQActivation.handleFailure(HornetQActivation.java:540)

at org.hornetq.ra.inflow.HornetQActivation$SetupActivation.run(HornetQActivation.java:578)

at org.jboss.resource.work.WorkWrapper.execute(WorkWrapper.java:205)

at org.jboss.util.threadpool.BasicTaskWrapper.run(BasicTaskWrapper.java:260)

at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(ThreadPoolExecutor.java:886)

at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:908)

at java.lang.Thread.run(Thread.java:619)

I understand the nature of the error - a missing client id. There is no id, indeed(either in the ActivationConfigProperty annotation or the configuration files). There was not such id in the JBM configuration as well and everything seemed to work. According to our CTO the client id wasn't needed so I'm pretty puzzled. Any ideas about that?

[clebert.suconic]

I was trying to find this on the wiki and google failed.

Has this ever made to the WIKI?

[nitinkhekare]

Hi

I was also searching for a tool which can help migrating the Messages from JBoss Messaging to HornetQ.

Is there any tool which I can use ?

Thanks

[gaohoward]

I don't remember I had put it to the wiki. I'll check out and put it to wiki if not already.

[gaohoward]

as far as I know there isn't one.