Skip navigation
2013
This project is read only now. Read more.

HornetQ was introduced in EAP5/AS5.  In that version of the server, HornetQ configuration metadata was spread over a set of XML files.

  • hornetq-configuration.xml
  • connection-factories-service.xml
  • destinations-service.xml
  • messaging-service.xml

 

In compliance with EAP6 and AS7's configuration model its metadata was moved into a "messaging" subsystem[1].  In this new design a 1:1 mapping between old XML and the new could not be maintained.

 

The attached zip file contains Windup rules that will assist migration of your HornetQ configuration data.  The rules check for the old style config files and run the contents through an XSLT transformation whose output can be cut and pasted into the server messaging subsystem.

 

You need a buildable copy of Windup[2].  Unzip the attached zip file in its base directory.  Build Windup and run as directed  here

 

 

Here is the metadata mapping between the old and new systems.

 

HornetQ config filesMessaging subsystem
<configuration> tag<hornetq-server>   ;replaces that tag
configuration.clusteredhornetq-server.clustered    ;Deprecated. .. is considered clustered if it has at least one cluster-connection.
dose not existhornetq-server.security-domain   ; only in subsystem
configuration.password-codecdoes not exist
configuration.mask-passworddoes not exist
configuration.log-delegate-factory-class-namedoes not exist
configuration.paging-directoryhornetq-server.paging-directory relative-to="" path=""  ; attrib additons or relative-to and path
configuration.bindings-directoryhornetq-server.bindings-directory relative-to="" path=""  ; attrib additons or relative-to and path
configuration.journal-directoryhornetq-server.journal-directory relative-to="" path=""  ; attrib additons or relative-to and path
configuration.large-messages-directoryhornetq-server.large-messages-directory relative-to="" path=""  ; attrib additons or relative-to and path

There is a major difference in the connector XML.  All connector def use a single template

      <connector name="##REQUIRED##" >
           <factory-class>##STRING##</factory-class>
           <param key="##REQUIRED##"   value="##REQUIRED##"/>
      </connector>

This XML has 3 different templates depending on the connector type.

 

<netty-connector name="##REQUIRED##"

                         socket-binding="##REQUIRED##">
          <param key="##REQUIRED##" value="##REQUIRED##"/>
</netty-connector>


<in-vm-connector  name="##REQUIRED##"

                           server-id="##OPTIONAL##">
           <param key="##REQUIRED##" value="##REQUIRED##"/>
</in-vm-connector>


<connector name="##REQUIRED##"

                 socket-binding="##OPTIONAL##">
            <param key="##REQUIRED##" value="##REQUIRED##"/>
            <factory-class>##STRING##</factory-class>
</connector>

There is a major difference in the acceptor XML.  All acceptor def use a single template

 

<acceptor name="##OPTIONAL##" >
        <factory-class>##STRING##</factory-class>
         <param key="##REQUIRED##" value="##REQUIRED##"/>
</acceptor>

This XML has 3 different templates depending on the acceptor type.

 

<netty-acceptor name="##OPTIONAL##" socket-binding="##REQUIRED##">
            <param key="##REQUIRED##" value="##REQUIRED##"/>
</netty-acceptor>


<in-vm-acceptor name="##OPTIONAL##"  server-id="##OPTIONAL##">
            <param key="##REQUIRED##" value="##REQUIRED##"/>
</in-vm-acceptor>


<acceptor name="##OPTIONAL##"  server-id="##OPTIONAL##">
            <factory-class>##STRING##</factory-class>
</acceptor>

 

broadcast-group.jgroups-file

broadcast-group.jgroups-stack  ; does this replace jgroups-file?

 

broadcast-group.socket-binding


broadcast-group.local-bind-address  ; Deprecated. use socket-binding instead

broadcast-group.local-bind-port  ; Deprecated. use socket-binding instead

broadcast-group.group-address  ; Deprecated. use socket-binding instead

broadcast-group.group-port  ; Deprecated. use socket-binding instead

discovery-group.jgroups-file

discovery-group.jgroups-stack  ; does this replace jgroups-file?

 

discovery-group.socket-binding


discovery-group.local-bind-address  ; Deprecated. use socket-binding instead

discovery-group.local-bind-port  ; Deprecated. use socket-binding instead

discovery-group.group-address  ; Deprecated. use socket-binding instead

discovery-group.group-port  ; Deprecated. use socket-binding instead

bridges.failover-on-server-shutdown  ; Deprecated. ignored
bridges.reconnect-attempts-same-nodedoes not exist
address-settings.address-setting.expiry-delaynot supported
address-settings.address-setting.redelivery-delay-multipliernot supported
address-settings.address-setting.max-redelivery-delaynot supported
address-settings.address-setting.max-delivery-attemptsnot supported
address-settings.address-setting.address-full-policy  ; an ENUM defines legal valuesENUM value 'FAIL' is not offered.
configuration is the tagjms-connection-factories    ;the tag being used.
<connection-factory name=""  "signature="">

<connection-factory name=""  "signature="">   ; attribute removed

 

jms-connection-factories.connection-factory.factory-type  ; new in subsystem.  It is an ENUM.  Does it replace attribute signature?

configuration.jmx-domaindoes not exist
connection-factory.xadoes not exist
connection-factory.failover-on-server-shutdownDeprecated. and ignored
jms-connection-factories.connection-factory.group-id
jms-connection-factories.pooled-connection-factory
hornetq-server.jms-destinations
jms-bridge

 

 

 

Resources

[1] $SERVER_HOME/docs/schema/jboss-as-messaging_1_3.xsd.

[2] http://windup.jboss.org

Introduction

 

Tubame and Windup are Java EE application migration productivity tools.  Each simplifies the migration of applications from other containers to the current release of JBoss application server.   Both tools analyze application code and produce a report of found issues.  They are both open source projects.  This survey compares the features of these two tools.

 

 

History

 

Tubame was developed by Nippon Telegraph and Telephone,(NTT).  It has been used by its internal engineering teams for several years.  It is a set of 6 Eclipse plugins.  In Sep 2013 NTT made 3 of the plugins available to the public via the open source project Tubame [1].

 

Windup was developed at Red Hat.  Internally it was known as project Cake and was used by Red Hat consultants.  Windup is a standalone Java application. It was made available to the public Jun 2013 via the open source project Windup [2].

 

 

 

Tool Design

 

 

Overview

 

Tubame is a set of 3 Eclipse plugins and an single external, customizable rules file.  The tool analyzes the source code based on the set of rules provided in the rules file.  The analysis is only preformed on text based, Java, JSP, and XML files provided in the project directory.  The results are saved to a file and subsequently formatted and displayed as a report in a custom Eclipse perspective, KnowledgeBase Search Tool.  Tubame enables the user to customize the external rules file and issue advise through its Knowledge Manager Tool perspective. The views in this perspective guide the user through editing the fields of the rules file.

 

Windup is a standalone Java application.  It loads multiple external, customizable rules files.  It analyzes files both in a directory structure and in archive files.  It analyzes text based Java, JSP, and XML files, as well as, compiled classes if a decompiler library is provided.   The report is a set of HTML documents.  The user can customize existing rules files and provide new ones, using any XML file editor.

 

 

Rules

 

Tubame and Windup are rules-based tools. Each has defined its own namespace and metadata format for its XML rules file [3],[4].  Each has a predefined, set of rules against which code is evaluated and a rules engine that preforms the analysis.  Both  provide a means for the user to add rules to the default set without having to rebuild the tool.

 

Windup's rule definitions are a small set of custom Spring beans.  Each bean takes several input parameters.  The key parameter is a search pattern defined by either a Regular Expression, (regex) or an XPath expression.  The rules engine uses Spring dependency injection to load its rules and Java regex and xpath utilities when evaluating the source files.

 

Tubame uses a single custom schema type for all its rules.  JAXB is used to load the rules into the engine.  The schema has defined 2 fields in which search text can be entered. The fields accept regex and XPath expressions.  There is a field to specify a custom Python object to execute during the code analysis phase.  When no custom Python object is present in the rule, the engine executes a default set of Python objects in its code analysis.

 

 

Reports

 

Tubame and Windup use different reporting frameworks but provide similar information.  Both reports group issues into categories, link to the offending source code, provide advise for issue resolution, and estimate the work effort.  Tubame uses a custom Eclipse perspective for its report.  The perspective provides a set of views.  There is a view that displays the analysis results, the detail advise for rules, and monitors work status.  Windup generates a set of HTML documents for its report.  There is a top level summary page and a detailed page for each file containing issue(s) to be addressed and advise on how to resolve the issue(s).  The reports differ in that Tubame lists all the rules it processes in its report.  The user must search the list for flagged issues.  Windup lists only the issues that need to be addressed.  Tubame and Windup use a different unit of measure for work effort.  Tubame uses man-hours.  Windup uses story points, a measure indicating level of complexity or difficultly.  It is left to the user to specify the man-hours base upon task complexity and their skill level.

 

 

Building

 

Tubame and Windup both require Java 1.6 or higher.  Windup uses a maven multi-module archtype.  The project sources can be built from the command-line or with any IDE that supports maven.  Tubame plugins must be built from within Eclipse.  It is a multi-step process requiring compiling several foundational projects, manually copying JAR files into the plugin projects, and running the plugin-wizard on each plugin.

 

 

Documentation

 

Windup's project wiki provides guides for building and running the tool, and customizing rules.  There is also a video overview of the tool, a detailed look at the report and walk through of enhancing the rule set.

 

Tubame's project wiki pages provides guides for building and installing the plugins, using the custom perspectives and adding rules to the project.

 

 

 

Feature Comparison

 

CategoryTubameWindup
Tool TypeEclipse PluginsStandalone Java Application
Open Source Projecthttps://github.com/TUBAMEhttp://windup.jboss.org

Open Source License

Apache License, Version 2.0Eclipse Public License v1.0
OS Supported

Windows XP/7,

Linux

Any platform that runs Java 1.6
JREJRE/JDK 1.6 or higherJRE/JDK 1.6 or higher

Execution Env

Eclipse 3.7 Indigo ONLY  (Juno and Kepler not supported)

Command-line

(Optional Eclipse plugin available)

Project Technology Dependencies

Java

XML

Eclipse (Indigo) API

Python 2.7

lxml

regex

XPath

Java

XML

Spring API  (3.1.0.RELEASE)

JDT api

Freemarker

HTML

XSLT

regex

XPath

Input Data Formats

Text files: Java, JSP, XML in an Eclipse Java Project

Text files, archive files: Java, JSP, XML, class* provided in a directory structure.

* user must provide decompiler library

Output Formats

custom .jbm file

csv

HTML

Excel

Default Rules Files
JBossMigrationKnowhowEAP4toEAP6-En.xml

java-jbpm-config.windup.xml

java-persistence-config.windup.xml

java-websphere-config.windup.xml

java-jboss-config.windup.xml

java-ejb-config.windup.xml

java-jdk-config.windup.xml

java-seam-to-cdi.windup.xml

java-jboss-esb-config.windup.xml

java-weblogic-config.windup.xml

java-webservice-config.windup.xml

xml-weblogic-config.windup.xml

xml-webservice-config.windup.xml

xml-orion-config.windup.xml

xml-persistence-config.windup.xml

xml-spring-config.windup.xml

xml-glassfish-config.windup.xml

xml-jboss-config.windup.xml

xml-jboss-esb-config.windup.xml

xml-resin-config.windup.xml

xml-jrun-config.windup.xml

xml-ejb-config.windup.xml

xml-base-config.windup.xml

xml-jonas-config.windup.xml

xml-websphere-config.windup.xml

manifest-config.windup.xml

pom-config.windup.xml

Build TechnologyJava and Eclipse plugin build processJava and Maven multi-module archtype
DocumentationGuides

Guides

Videos

Bug Feporting

Forum

Email

GitHub project

in-progress

in-progress

GitHub project

Windup Forum

Windup email list

Download Archive Formatmultiple zip filessingle jar file

 

 

 

 

Resources

[1] Tubame project page

[2] Windup project page

[3] Tubame Rules Schema

[4] Windup Rules Schema

Here is an example of a Windup xpath-value rule checking XML statements for non-default values.  Most users only write rules to flag a statement when a specific value is found.  The example is doing the opposite.

 

Here is the XML that the rule will evaluate.

 

<Server>

    <Service>

        <!-- +++ This element is using all the default values. +++ -->

        <Connector port="8009" address="${jboss.bind.address}" protocol="AJP/1.3"

         emptySessionPath="true" enableLookups="false" redirectPort="8443" />

 

        <!-- +++ This element is using a non-default port number. +++ -->

        <Connector port="5995" address="${jboss.bind.address}" protocol="AJP/1.3"

         emptySessionPath="true" enableLookups="false" redirectPort="8443" />

 

    </Service>

</Server>

 

 

The first connector statement is using all the default values of the element.  The second connector is using a custom port.  I am going to provide a rule that determines that the first connector is using all the default settings and therefore will not be flagged, but flags the second connector as needing attention because a non-default value was found.

 

Here is the rule.  It uses a fairly complex XPath construct but it does the job.

 

<windup:xpath-value

    description="A custom connector attribute setting has been detected."

    xpath="//Server/Service/Connector[@protocol = 'AJP/1.3'

        and @port != '8009'

        or @address != '${jboss.bind.address}'

        or @emptySessionPath != 'true'

        or @enableLookups != 'false'

        or @redirectPort != '8443']"

        inline="true" effort="1">

</windup:xpath-value>

 

 

 

If I was only interested in the connectors in a named service?

 

 

<Server>

    <Service name="jboss.web">

        <!-- +++ This element is using all the default values. +++ -->

        <Connector port="8009" address="${jboss.bind.address}" protocol="AJP/1.3"

         emptySessionPath="true" enableLookups="false" redirectPort="8443" />

 

        <!-- +++ This element is using a non-default port number. +++ -->

        <Connector port="5995" address="${jboss.bind.address}" protocol="AJP/1.3"

         emptySessionPath="true" enableLookups="false" redirectPort="8443" />

 

    </Service>

</Server>

 

 

The rule would be

 

<windup:xpath-value

    description="A custom connector attribute setting has been detected."

    xpath="//Server/Service[@name = 'jboss.web']/Connector[@protocol = 'AJP/1.3'

        and @port != '8009'

        or @address != '${jboss.bind.address}'

        or @emptySessionPath != 'true'

        or @enableLookups != 'false'

        or @redirectPort != '8443']"

        inline="true" effort="1">

</windup:xpath-value>

 

 

 

 

If I was interested only in services not named 'jboss.web'?

 

<Server>

    <Service name="my.new.web">

        .....

 

    </Service>

</Server>

 

 

The rule would be

 

<windup:xpath-value

    description="A custom connector attribute setting has been detected."

    xpath="//Server/Service[@name != 'jboss.web']/Connector[@protocol = 'AJP/1.3'

        and @port != '8009'

        or @address != '${jboss.bind.address}'

        or @emptySessionPath != 'true'

        or @enableLookups != 'false'

        or @redirectPort != '8443']"

        inline="true" effort="1">

</windup:xpath-value>

Migrating a whole running Java EE environment from one Java EE server implementation to another is like moving from one IDE to another.  All IDEs do pretty much the same thing.  All IDEs UI are similar yet different enough to be bothersome until you develop a sufficient familiarity. A majority of their underlying functionality is also the same yet each has its own nuances.  To help you make the transition from other Java EE server implementations to the current JBoss EAP or community releases, Red Hat JBoss provides a micro web-site, Migration Center. The web-site provides the following,

  • Migration planning and preparation advise 
  • Guides for becoming familiar with JBoss' server UI and features 
  • Vendor specific migration assistance, for example there is advise for replacing Oracle WebLogic's CommonJ Framework and the Work Manager API. 
  • Tools that simplify the migration of applications and server configuration settings.
    • Windup, a Java application that simplifies Java application migrations
    • WindRide, a JBoss server configuration migration tool
    • Tubame, a set of Eclipse plugins that assists in migrating Java EE applications
  • Access to the JBoss open source community for discussions, assistance, and topic contributions
    • Migration fourm
    • Migration IRC channel
    • Migration project repositories
  • Access to Red Hat Consulting Services, the JBoss migration professionals

AS 7's default persistence provider is Hibernate 4.   It is provided as a module.   A different persistence provider can be added to the server via a module definition.  Lets add Hibernate 3 to the server.   Lets find the Hibernate 4 module definiton and use it as the model to add a Hibernate 3 module.  Look for hibernate in your  ${JBOSS_HOME}/modules directory.

 

          cd ${JBOSS_HOME}

         find modules -name "*hibernate*"

 

 

         modules/javax/persistence/api/main/hibernate-jpa-2.0-api-1.0.1.Final.jar

          modules/javax/persistence/api/main/hibernate-jpa-2.0-api-1.0.1.Final.jar.index

          modules/org/hibernate

          modules/org/hibernate/main/hibernate-commons-annotations-4.0.1.Final.jar

          modules/org/hibernate/main/hibernate-entitymanager-4.0.1.Final.jar.index

          modules/org/hibernate/main/hibernate-core-4.0.1.Final.jar

          modules/org/hibernate/main/hibernate-entitymanager-4.0.1.Final.jar

          modules/org/hibernate/main/hibernate-core-4.0.1.Final.jar.index

          modules/org/hibernate/main/hibernate-commons-annotations-4.0.1.Final.jar.index

          modules/org/hibernate/main/hibernate-infinispan-4.0.1.Final.jar

          modules/org/hibernate/main/hibernate-infinispan-4.0.1.Final.jar.index

          modules/org/hibernate/envers/main/hibernate-envers-4.0.1.Final.jar

          modules/org/hibernate/envers/main/hibernate-envers-4.0.1.Final.jar.index

          modules/org/hibernate/validator/main/hibernate-validator-4.2.0.Final.jar

          modules/org/hibernate/validator/main/hibernate-validator-4.2.0.Final.jar.index

          modules/org/jboss/as/jpa/hibernate

          modules/org/jboss/as/jpa/hibernate/main/jboss-as-jpa-hibernate4-7.1.1.Final.jar

          modules/org/jboss/as/jpa/hibernate/4/jboss-as-jpa-hibernate4-7.1.1.Final.jar.index

 

As you can see there are quit a few hibernate achives present.  Lets ferret out the one that is of interest to us.  But first I should tell you  there is a directory naming convention for modules.  Part or all of the package name of the APIs that make up the module's content is used as the directory path.  The dot-separated segments of the package's name are given as the directory name.  In addition a path ending with the name "main" indicates that it  is to be used as the default module.  When the last name is other than "main" it is the definition of a "slot" name.  The "slot" name is called out in the application to reference the module to be use.

 

With this information we can summize from the directory and jar file names that, modules/javax/persistence/api/main/hibernate-jpa-2.0-api-1.0.1.Final.jar is the java spec API for JPA, modules/org/hibernate/main/hibernate-commons-annotations-4.0.1.Final.jar are annotation related APIs, modules/org/hibernate/envers/main/hibernate-envers-4.0.1.Final.jar are support APIs, modules/org/hibernate/validator/main/hibernate-validator-4.2.0.Final.jar are the validator APIs, and modules/org/jboss/as/jpa/hibernate/main/jboss-as-jpa-hibernate4-7.1.1.Final.jar are the core APIs in which we are interested.  Lets look at the contents of directory, modules/org/jboss/as/jpa/hibernate/main.

 

 

     ls modules/org/jboss/as/jpa/hibernate/main

 

     jboss-as-jpa-hibernate4-7.1.1.Final.jar       

     module.xml

     jboss-as-jpa-hibernate4-7.1.1.Final.jar.index

 

The directory contains 2 required files and 1 optional file. The JAR archive and the module.xml file are required.   The JAR file contains the APIs being referenced.  The module.xml file is the module descriptor; it describes the structure, content, dependencies, filtering, and other attributes of the module.  We will need to provide a Hibernate 3 jar file and create the corresponding module.xml file.

 

The index file is optional.  It is generated by the jandex utility, which processes Java annotations within a directory or jar file, and saves the resulting metadata in an index file.  This information fosters faster loading of the module.   You do not need to generate this file.  The application server will generated it for you the first time the module is loaded. 

 

Let create a Hibernate 3-7.1.2 module. The jar file can be downloaded from

http://grepcode.com/snapshot/repository.jboss.org/nexus/content/repositories/releases/org.jboss.as/jboss-as-jpa-hibernate3/7.1.2.Final/

 

 

Following the naming convention our Hibernate 3 module should have a directory path name of modules/org/jboss/as/jpa/hibernate.   We need to define an end directory name.  This will be the slot name for this module.  Lets name it 3.

 

     mkdir modules/org/jboss/as/jpa/hibernate/3

 

Copy the jar into this directory

 

    cp /tmp/jboss-as-jpa-hibernate3-7.1.2.Final.jar modules/org/jboss/as/jpa/hibernate/3

 

The module descriptor for this archive will be nearly the same as for Hibernate 4.  Copy the module.xml file from modules/org/jboss/as/jpa/hibernate/main into modules/org/jboss/as/jpa/hibernate/3 and edit it.

 

    cp  modules/org/jboss/as/jpa/hibernate/main/module.xml modules/org/jboss/as/jpa/hibernate/3

 

     <!-- contains the JPA integration classes for Hibernate 4.x -->

     <module xmlns="urn:jboss:module:1.1" name="org.jboss.as.jpa.hibernate">

         <properties>

             <property name="jboss.api" value="private"/>

         </properties>

 

         <resources>

             <resource-root path="jboss-as-jpa-hibernate4-7.1.1.Final.jar"/>

             <!-- Insert resources here -->

         </resources>

 

         <dependencies>

             <module name="javax.annotation.api"/>

             <module name="javax.persistence.api"/>

             <module name="javax.transaction.api"/>

             <module name="org.hibernate" services="import"/>

             <module name="org.hibernate.validator"/>

             <module name="org.infinispan"/>

             <module name="org.jboss.as.clustering.infinispan"/>

             <module name="org.jboss.as.controller"/>

             <module name="org.jboss.as.jpa.spi"/>

             <module name="org.jboss.as.jpa.util"/>

             <module name="org.jboss.as.naming"/>

             <module name="org.jboss.as.server"/>

             <module name="org.jboss.jandex"/>

             <module name="org.jboss.logging"/>

             <module name="org.jboss.msc"/>

             <module name="org.jboss.vfs"/>

         </dependencies>

     </module>

 

 

Add attribute slot="3" to the module element.  Change the name of archive from jboss-as-jpa-hibernate4-7.1.1.Final.jar to jboss-as-jpa-hibernate3-7.1.2.Final.jar and save the file.

 

    <module xmlns="urn:jboss:module:1.1" name="org.jboss.as.jpa.hibernate" slot="3">

 

             :

 

         <resources>

             <resource-root path="jboss-as-jpa-hibernate3-7.1.2.Final.jar "/>

             <!-- Insert resources here -->

         </resources>

 

 

The last step is to enable your application to reference the Hibernate 3 module.  Change your  application's persistence.xml file.  Add a property element to the persistence-unit element.  The name of the property is jboss.as.jpa.providerModule.  The value is the name of the module as defined by the name attribute of the module in the module.xml file.  In addition, because this module has a slot name, append ":" followed by the slot name to the reference name.

 

 

     <persistence-unit name="${your unit name}">

              <description>Hibernate 3 persistence unit.</description>

              <jta-data-source>${your jpa src}</jta-data-source>

              <properties>

                       <property name="jboss.as.jpa.providerModule"

                                          value="org.jboss.as.jpa.hibernate:3"/>

               </properties>

     </persistence-unit>

 

Your application should now run using Hibernate 3.

 

References

[1] Drop in a Hibernate 3.6.6.Final module:  http://relation.to/21601.lace

[2] JBoss Modules, Introduction:  https://docs.jboss.org/author/display/MODULES/Introduction

[3] How to Run JBoss Jandex: http://javahowto.blogspot.com/2012/08/how-to-run-jboss-jandex.html