! This is out of date and should not be used as a reference

Work In Progress (Definition)

-

This guide answers questions on how to migrate client code and server side components from JBossMQ (as distributed with JBoss AS 4.0.4 release) to JBossMessaging 1.2. This guide also contains some pointers on how to migrate between JBossMessaging 1.0.x and 1.2.x versions.

Migration from JBoss MQ to JBoss Messaging 1.2

This section lists the changes that appear in configuration and implementation features between JBoss MQ and JBoss Messaging 1.2

Java Compatibility

JBoss Messaging is tested with JDK 1.4 and JDK 1.5.

API Compatibility

JBoss Messaging is compatible with JMS 1.1 and JMS 1.0.2b specifications. Application code that adheres to these specifications will run without code changes with JBoss Messaging.

JMS Client Applications

Applications that connect directly to JBoss MQ server need to upgrade the client classpath when migrating to JBoss Messaging. Replace jbossmq-client.jar with jboss-messaging-client.jar in the client's classpath.

Deploying Messaging Destinations

Destination configuration must be changed from JBoss MQ to JBoss Messaging. The deployable MBean class names have changed and the MBean dependencies in JBoss Messaging differ from JBoss MQ. Also note that by default JBoss Messaging is deployed in its own isolated classloading domain which requires your deployed destinations to register with the same classloading scope.

For more details on JBoss Classloading architecture and configuration, see the ClassLoading page.

Below is an example of a JBoss Messaging topic configuration. You should save the configuration in

XXX-service.xml

file and copy it to your JBoss server deploy directory with JBoss Messaging.

Notice the

<loader-repository>

element to register your destination deployment in the same scoped classloading repository

jboss.messaging:loader=ScopedLoaderRepository

with JBoss Messaging implementation. This is necessary in order for the correct topic or queue classes to be found by the deployer.

The new class name for a topic implementation is

org.jboss.jms.server.destination.TopicService

declared in the

code

attribute. The format for a destination name is the same as with JBoss MQ.

New addition compared to JBoss MQ destination configuration is the

xmbean-dd

element. This points to an XML declaration of the MBean's management interface for the destination. Usually you don't have to modify the management interface definition, just configure either

xmdesc/Topic-xmbean.xml

or

xmdesc/Queue-xmbean.xml

accordingly.

XMBeans are covered in more detail in JBoss JMX Microkernel Wiki pages.

Finally, notice that the dependency to JBoss MQ's DestinationManager has been replaced with a dependency to JBoss Messaging ServerPeer (and "ServerPeer" attribute name accordingly). In addition, new mandatory MBean dependency exists for Topic or Queue PostOffice.

<?xml version="1.0" encoding="UTF-8"?>

<server>
  <loader-repository>jboss.messaging:loader=ScopedLoaderRepository
    <loader-repository-config>java2ParentDelegation=false</loader-repository-config>
  </loader-repository>

  <mbean code = "org.jboss.jms.server.destination.TopicService"
         name = "jboss.messaging.destination:service=Topic,name=XXX"
         xmbean-dd = "xmdesc/Topic-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
      <depends>jboss.messaging:service=PostOffice</depends>
  </mbean>
</server>

Similarly, deploying a new queue to JBoss Messaging version 1.2:

<?xml version="1.0" encoding="UTF-8"?>

<server>
  <loader-repository>jboss.messaging:loader=ScopedLoaderRepository
    <loader-repository-config>java2ParentDelegation=false</loader-repository-config>
  </loader-repository>

  <mbean code = "org.jboss.jms.server.destination.QueueService"
         name = "jboss.messaging.destination:service=Queue,name=XXX"
         xmbean-dd = "xmdesc/Queue-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
      <depends>jboss.messaging:service=PostOffice</depends>
  </mbean>
</server>

ADDITIONAL NOTES:  xxx

-

Migration from JBoss Messaging 1.0.x to 1.2

For those who already made the migration to JBoss Messaging 1.0.x series and are looking to upgrade to 1.2 version there are also some class package and configuration changes.

MBean Classname and Dependency Changes

Notice that the destination configuration has changed between the two versions. The examples from JBoss Messaging User's Guide for version 1.0.x do not deploy correctly without changes on JBoss Messaging version 1.2.

MBean class names for both Topics and Queues must be changed.

For queues, MBean class org.jboss.jms.server.destination.Queue should become

org.jboss.jms.server.destination.QueueService

.

For topics, MBean class org.jboss.jms.server.destination.Topic should become

org.jboss.jms.server.destination.TopicService

.

Also, an additional dependency needs to be added for both topics and queues to a PostOffice MBean. For example, the configuration following configuration from JBoss Messaging User's Guide:

<mbean code="org.jboss.jms.server.destination.Queue"
       name="jboss.messaging.destination:service=Queue,name=XXX"
       xmbean-dd="xmdesc/Queue-xmbean.xml">
   <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
</mbean>

must be changed to:

<mbean code = "org.jboss.jms.server.destination.QueueService"
       name = "jboss.messaging.destination:service=Queue,name=XXX"
       xmbean-dd= "xmdesc/Queue-xmbean.xml">
  <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
  <depends>jboss.messaging:service=PostOffice</depends>
</mbean>

Similarly, change topic configurations from:

<mbean code="org.jboss.jms.server.destination.Topic"
       name="jboss.messaging.destination:service=Topic,name=XXX"
       xmbean-dd="xmdesc/Topic-xmbean.xml">
   <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
</mbean>

to

<mbean code = "org.jboss.jms.server.destination.TopicService"
       name = "jboss.messaging.destination:service=Topic,name=XXX"
       xmbean-dd= "xmdesc/Topic-xmbean.xml">
  <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
  <depends>jboss.messaging:service=PostOffice</depends>
</mbean>

\

\

\

\

\

\

-

Troubleshooting

Some common errors in migrating from JBossMQ to JBossMessaging is covered in this section.

JMS Client Exceptions

PROBLEM: When running a client connecting directly to JBoss Messaging services, the following exception is thrown:

javax.naming.CommunicationException Root exception is java.lang.ClassNotFoundException: 
  org.jboss.jms.client.JBossConnectionFactory (no security manager: RMI class loader disabled)
    at org.jnp.interfaces.NamingContext.lookup(NamingContext.java:728)
    at org.jnp.interfaces.NamingContext.lookup(NamingContext.java:587)
    at javax.naming.InitialContext.lookup(InitialContext.java:351)

SOLUTION: You need to add jboss-messaging-client.jar library in the classpath of any client application attempting to connect or lookup JBoss Messaging administered objects directly.

Deployment Errors

PROBLEM: The following error is displayed on JBoss AS console when the server is started or a new JMS destination is deployed:

--- MBeans waiting for other MBeans ---
ObjectName: jboss.mq.destination:service=Topic,name=xxx
  State: CONFIGURED
  I Depend On:
    jboss.mq:service=DestinationManager

SOLUTION: You need to update your JMS destination configuration to match the requirements of JBoss Messaging implementation, including new MBean and class package names.

MBean

jboss.mq:service=DestinationManager

is no longer deployed but is replaced with

jboss.messaging:service=ServerPeer

(injected to "ServerPeer" attribute) . Also, additional dependency to JBoss Messaging PostOffice is required and in case of standard deployments, a correct classloading domain configuration must be present.

See the section on "Deploying Messaging Destinations" above for all the details.

PROBLEM: the following exception is thrown and error message displayed on server console:

23:25:16,038 INFO  [ServiceConfigurator] Problem configuring service
jboss.messaging.destination:service=Topic,name=xxx
org.jboss.deployment.DeploymentException: Exception setting attribute 
  javax.management.Attribute@55108e on mbean 
  jboss.messaging.destination:service=Topic,name=xxx; - nested throwable:
  (javax.management.AttributeNotFoundException: not found: ServerPeer)
    at org.jboss.system.ServiceConfigurator.setAttribute(ServiceConfigurator.java:698)
    at org.jboss.system.ServiceConfigurator.configure(ServiceConfigurator.java:380)
    ...

--- MBeans waiting for other MBeans ---
ObjectName: jboss.messaging.destination:service=Topic,name=xxx
State: FAILED
Reason: org.jboss.deployment.DeploymentException: 
  Exception setting attribute javax.management.Attribute@55108e on mbean 
  jboss.messaging.destination:service=Topic,name=xxx; - nested throwable:
  (javax.management.AttributeNotFoundException: not found: Server Peer)

  I Depend On:
    jboss.messaging:service=ServerPeer

SOLUTION:  Destinations deployed on JBoss Messaging have a mandatory dependency to ServerPeer component.

See the section on "Deploying Messaging Destinations" above for all the details and check your configuration.

PROBLEM: The following error is displayed on server console when attempting to deploy a JBoss Messaging destination:

--- Incompletely deployed packages ---
org.jboss.deployment.DeploymentInfo@cbdafb9c { 
url=file:/C:/jboss-4.0.4/server/messaging/deploy/MyDestination-service.xml }
  deployer: org.jboss.deployment.SARDeployer@9be79a
  status: Deployment FAILED reason: 
    No ClassLoaders found for:  org.jboss.jms.server.destination.TopicService; - nested throwable: 
      (java.lang.ClassNotFoundException: No ClassLoaders found for:
       org.jboss.jms.server.destination.TopicService)
  state: FAILED
  watch: file:/C:/jboss-4.0.4/server/messaging/deploy/MyDestination-service.xml

SOLUTION:  By default JBoss Messaging is deployed in a scoped classloading domain. The class scope includes the definitions for Queue and Topic service instances bound to JMX. If you deploy your destinations outside the JBoss Messaging SAR package you must declare the same classloading scope in your service definition.

See the section on "Deploying Messaging Destinations" above for all the details and check your configuration.

PROBLEM:

17:18:49,660 ERROR (MainDeployer) Could not create deployment: file:/C:/jboss-4.0.4/server/messaging/deploy/MyDestination-service.xml org.jboss.deployment.DeploymentException: Class does not expose a management interface: java.lang.Object; - nested throwable: (javax.management.NotCompliantMBeanException: Class does not expose a management interface: java.lang.Object)

SOLUTION: In our case when editing the mq queue and topic definitions to match the format JBoss Messaging needs, the person forgot to add in the *  xmbean-dd * property in the mbean definition

  <mbean code = "org.jboss.jms.server.destination.TopicService"
         name = "jboss.messaging.destination:service=Topic,name=XXX"

         xmbean-dd = "xmdesc/Topic-xmbean.xml">

      <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
      <depends>jboss.messaging:service=PostOffice</depends>
  </mbean>

PROBLEM:

13:40:16 WARN [DeploymentInfo] Only the root deployment can set the loader repository, 
              ignoring config=LoaderRepositoryConfig(
              repositoryName: jboss.messaging:loader=ScopedLoaderRepository,
              repositoryClassName: org.jboss.mx.loading.HeirarchicalLoaderRepository3,
              configParserClassName: org.jboss.mx.loading.HeirarchicalLoaderRepository3ConfigParser,
              repositoryConfig: java2ParentDelegation=false)

SOLUTION: xxx

Runtime Errors and Warnings

PROBLEM:

17:11:16,008 WARN  (SimpleConnectionManager) A problem has been detected with the connection to remote client 5c4o1x-oipvqm-eteeirwb-1-eteeitdg-4. It is possible the client has exited without closing its connection(s) or there is a network problem. All connection resources corresponding to that client process will now be removed.

SOLUTION: xxx

-

User submitted content

Migrating JBossMQ is easy and primarilly a minor configuration task. However, you might need to change your software in how the JNDI is used.

Installation

The installation procedure is well described in the JBoss Messaging documentation. Use the ant installation procedure that comes with JBoss Messaging. I presume JBoss, jdk and ant is installed with JBOSS_HOME, JAVA_HOME and ANT_HOME variables set.

The installation can be executed on a running server. What the ant procedure does is, it creates a copy of your 'default' installation to a new 'messaging' installation. JBossMQ will be removed and JBoss Messaging will be added. The old 'default' configuration will remain intact and running during that process.

When you are finished testing you can remove the 'default' installation and rename 'messaging' to 'default'. An upgrade in the production environment can be executed with minimal downtime.

Configuration

The next thing that needs to be done is set up a few configuration files.

JNDI

I assume you had JBossMQ configured default to connect to JNDI. If not, you need to edit connection-factories-service.xml.

Destinations

You need to recreate the destinations, the installation only delivers default settings. Edit destinations-service.xml. Notice that this file has changed from jbossmq-destinations-service.xml, so you need to rewrite it. But the file is like the JBossMQ version: simple.

Persistence

Delete the hsqldb-persistence-service.xml file and pick the appropriate version from the example directory of JBoss Messaging distribution. Logically you cannot use the JBossMQ version of this file. The example files assume you have java:/DefaultDS setup as database.

Software

You can have a look at some example code in the JBoss Messaging distribution, but there might be one noticable change needed in your software. JBossMQ will allow JNDI lookups from both Context and InitialContext, while JBoss Messaging will only work with InitialContext. Do a search/replace for it in your code.

J2EE descriptor files for MDB's can be used unchanged, also files generated by XDoclet are still adequate.

Finally

When you have changed the configuration and added the updated ear's and war's in the 'messaging' deploy folder. You can start the server by:

$ /bin/run.sh -c messaging

Referenced by: