Skip to end of metadata
Go to start of metadata

The purpose of this guide is to document only those changes that are needed to successfully run and deploy AS 5 applications on AS 7.It provides information on to resolve deployment and runtime problems and how to prevent changes in application behaviour. This is the first step in moving to the new platform. Once the application is successfully deployed and running on the new platform, plans can be made to upgrade individual components to use the new functions and features of AS7.

Migration Overview

JBoss AS7 is structured differently from previous versions of JBoss AS, so you may want do a little research before you attempt to migrate your application. Getting Started with JBoss Application Server 7 in the Getting Started Guide has a lot of useful information, including a table that lists the features that are supported in AS 7.0. If your application uses features that go beyond the Java Enterprise Edition 6 Web Profile specification, you want to make sure you go with AS 7.1 or later (this is when AS7 became EE6 Full Profile compliant). You should also read Getting started with JBoss AS for helpful information about how to install and run the application server.

The rest of this document describes some of the changes you might need to make to your application to successfully deploy and run it on AS7.

Reminder
Before making any modifications to your application, make sure to create a backup copy.

Update Application Dependencies Due to Class Loading Changes

Modular class loading overview

Class loading in AS7 is considerably different than in previous versions of JBoss AS. Class loading is now based on the JBoss Modules project. Instead of the more familiar hierarchical class loading environment, AS7's class loading is based on modules that have to define explicit dependencies on other modules. Deployments in AS7 are also modules, and do not have access to classes that are defined in jars in the application server unless an explicit dependency on those classes is defined.

Even though in AS7 modules are isolated by default, as part of the deployment process some dependencies on modules defined by the application server are set up for you automatically. For instance, if you are deploying a Java EE application, a dependency on the Java EE API's will be added to your module automatically. Similarly if your module contains a beans.xml file, a dependency on Weld will be added automatically, along with any supporting modules that weld needs to operate. For a complete list of the automatic dependencies that are added see Implicit module dependencies for deployments.

Understand module dependencies

The deployers within the server "implicitly" add some commonly used module dependencies, like the javax.api and sun.jdk, to the deployment so that the classes are visible to the deployment at runtime. This way the application developer doesn't have to worry about adding them explicitly. How and when these implicit dependencies are added is explained in Implicit module dependencies for deployments.

For some classes, the modules must be specified explicitly in the MANIFEST.MF as Dependencies: or "Class-Path:" entries or in the jboss-deployment-structure.xml. Otherwise you may see ClassNotFoundExceptions, NoClassDefFoundErrors, or ClassCastExceptions. Tattletale is an excellent tool that can help you identify module dependencies in your application. Tattletale is described later in this document here: Use Tattletale to find application dependencies.

You may also see runtime errors and page redirects to the JBoss Seam Debug Page. Manifest entries are explained in more detail here: Class Loading in AS7.

How to Package EARs and WARs

When you migrate your application, you may have to change the packaging structure of your EAR or WAR due to the class loading changes.

A WAR is a single module and all classes in the WAR are loaded with the same class loader. This means classes packaged in the WEB-INF/lib are treated the same as classes in WEB-INF/classes.

An EAR is different in that it consists of multiple modules. The EAR/lib directory is a single module, and every WAR or EJB jar deployment is also a separate module. Classes will not necessarily have access to other classes in the EAR unless explicit dependencies have been defined.

For more information on EAR and WAR packaging, see "WAR Class Loading" and "EAR Class Loading" in Class Loading in AS7.

Reminder
If you are using maven configure defaultLibBundleDir property to lib directory:

Create or modify files that control class loading in AS7

jboss-web.xml

If you have defined a class-loading element, you need to remove it. The behaviour that this provokes in EAP 5 is now the default class-loading behaviour in AS 7, so it is no longer necessary. If you do not remove this element, you will see a ParseError and XMLStreamException in your server log:

MANIFEST.MF file

Manually edited MANIFEST files

Depending on which components your application uses, you may need to add one or more dependencies to this file. There is more information about these dependencies in the following paragraphs.
The following is an example of MANIFEST.MF file that has been modified to contain dependencies and classpath entries:

If you modify the MANIFEST.MF file, make sure to include a newline character at the end of the file.
How to define MANIFEST.MF file dependencies if you use Maven

If you use Maven, you may need to modify your pom.xml file to generate the dependencies for the MANIFEST.MF file.

If your application uses EJB 3.0, you may have a section in the pom.xml file that looks like the following:

If the EJB 3.0 code uses org.apache.commons.log, you will need to add that dependency to the MANIFEST.MF file. To do that, you will need to modify the plugin element in the pom.xml file as follows:

In the above example, the src/main/resourcres/MANIFEST.MF file only needs to contain the dependency entry:

Maven will generate the complete MANIFEST.MF file:

jboss-deployment-structure.xml

This file is a JBoss specific deployment descriptor that can be used to control class loading in a fine grained manner. Like the MANIFEST.MF, this file can be used to add dependencies. If can also prevent automatic dependencies from being added, define additional modules, change an EAR deployment's isolated class loading behaviour, and add additional resource roots to a module.

For additional information, see jboss-deployment-structure.xml.

application.xml

In previous versions of JBoss AS, you controlled the order of deployments within an EAR through the use of the jboss-app.xml file. This is no longer the case. The Java EE6 spec provides the <initialize-in-order> element in the application.xml which allows control of the order in which the Java EE modules within an EAR are deployed.

In most cases you do not need to specify deployment order. If your application uses dependency injections and resource-refs to refer to components in external modules, in most cases the <initialize-in-order> element is not required because the application server is able to implicitly determine the correct and optimal way of ordering the components.

Assume you have an application that contains a myBeans.jar and a myApp.war within a myApp.ear. A servlet in the myApp.war @EJB injects a bean from myBeans.jar. In this case, the application server has the appropriate knowledge to make sure that the EJB component is available before the servlet is started and you do not have to use the <initialize-in-order> element.

However, if that servlet uses legacy JNDI lookup style remote references like the following to access the bean, you may need to specify module order.

In this case, the server is not able to determine that that EJB component is in the myBeans.jar and you need to enforce that the components in the myBeans.jar are initialized and started before the components in myApp.war. To do this, you set the <initialize-in-order> element to true and specify the order of the myBeans.jar and myApp.war modules in the application.xml file.

The following is an example that uses the <initialize-in-order> element to control deployment order. The myBeans.jar is deployed before the myApp.war.

The schema for the application.xml file can be found here at http://java.sun.com/xml/ns/javaee/application_6.xsd.

You should be aware that setting <initialize-in-order> to true slows down deployment. It is preferable to define proper dependencies using dependency injections or resource-refs since it allows the container more flexibility in optimizing deployments.

Change ResourceBundle location

In previous versions of AS, the JBOSS_HOME/server/<servername>/conf/ was available in the classpath. Hence the properties files in that location were available in the classpath of the application.

In AS7, to get those properties available in the classpath, package them within your application. For example, if you are deploying a .war then package those properties in WAR WEB-INF/classes/ folder. If you want those properties accessible to all components in a .ear, then package them at the root of some .jar and place that jar in EAR lib/ folder.

Where to Find Additional Information

For more information about the class loading changes in AS7, see Class Loading in AS7.
For more information about modular class loading, see the Module Compatible Classloading Guide.
For information about deployment module dependencies, see Deployment Module Dependencies.

Update the DataSource Configuration

Overview

In previous versions of the application server, the JCA data source configuration was defined in a file with a suffix of *-ds.xml. This file was then deployed in the server's deploy directory. The JDBC driver was copied to the server lib/ directory or packaged in the application's WEB-INF/lib/ directory.

In AS7, this has all changed. You will no longer package the JDBC driver with the application or in the server/lib directory. The *-ds.xml file is now obsolete and the datasource configuration information is now defined in the standalone/configuration/standalone.xml or in the domain/configuration/domain.xml file. The IronJacamar distribution features a migration tool that can help you convert your previous datasource configuration file into the new format. You can find more information about the tool here: IronJacamar Datasource and Resource Adapter Migration Tool .

A JDBC 4-compliant driver can be installed as a deployment or as a core module. A driver that is JDBC 4-compliant contains a META-INF/services/java.sql.Driver file that specifies the driver class name. A driver that is not JDBC 4-compliant requires additional steps, as noted below.

Define the datasource

In AS7, a datasource is configured in the server configuration file. If you are running in domain mode, the configuration file is the domain/configuration/domain.xml file. If you are running in standalone mode, you will configure the datasource in the standalone/configuration/standalone.xml file. Schema reference information, which is the same for both modes, can be found here: Datasource Descriptors.

First, you will need to create a datasource element and a driver element for your JDBC driver and datasource information in the standalone.xml or domain.xml file. You will use some of the same information that was previously defined in the *-ds.xml file.

The following is an example of a MySQL datasource element:

A JAR that is JDBC 4-compliant contains a META-INF/services/java.sql.Driver file that specifies the driver class name. This is used by the server to find name of the class(es) of the Drivers which exist in that JAR.

This is an example of the driver element for a JDBC 4-compliant MySQL driver.

This is an example of the driver element for driver that is not JDBC 4-compliant. The driver-class must be specified since it there is no META-INF/services/java.sql.Driver file that specifies the driver class name.

For more information on how to add a MySQL driver, see Adding a MySQL datasource to JBoss AS 7.

Install the JDBC driver

The JDBC driver can be installed into the container in one of two ways: either as a deployment or as a core module. There are pros and cons to each approach, which will be outlined below. For a detailed explanation how to deploy JDBC 4-compliant driver jar, please refer to the DataSources chapter of the Admin Guide.

Install the JDBC driver as a deployment

When you install the JDBC driver as a deployment, it is deployed as a regular JAR. This is the recommended way to install the driver. When you run your application server in domain mode, deployments are automatically propagated to all servers to which the deployment applies; thus distribution of the driver JAR is one less thing for administrators to worry about.

Any JDBC 4-compliant driver will automatically be recognized and installed into the system by name and version. A JDBC 4-compliant JAR is identified using the Java service provider mechanism. It contains a text a file named "META-INF/services/java.sql.Driver", which contains the name of the class(es) of the Drivers which exist in that JAR. If your JDBC driver JAR is not JDBC 4-compliant, it can be made deployable by adding the java.sql.Driver file to the JAR or by deploying the JAR with an overlay. More information on that topic can be found here: Installing a JDBC Driver as a Deployment.

In AS7 standalone mode, you simply copy the JDBC 4-compliant JAR into the AS7_HOME/standalone/deployments directory. Here is an example of a MySQL JDBC driver installed as a deployment:

    AS7_HOME/standalone/deployments/mysql-connector-java-5.1.15.jar

If the JDBC driver consists of more than one JAR, for example a JAR with the driver and a dependent license JAR, you can not install the driver as a deployment. You must install the JDBC driver as a core module.

Install the JDBC driver as a core module

To install the driver as a module, you will need to create a directory structure under the modules folder. This structure will contain the driver and a module.xml file to define the module.

For example, using the MySQL JDBC driver above, you would create a directory structure as follows:

    AS7_HOME/modules/com/mysql/main

In the main directory, you then create the following module.xml file:

The module name, "com.mysql", matches the directory structure for this module. Under dependencies, you specify the module's dependencies on other modules. In this case, as the case with all JDBC data sources, it is dependent on the Java JDBC APIs which are defined in another module named javax.api that is located under modules/javax/api/main.

Make sure you do NOT have a space at the beginning of module.xml file or you will get a "New missing/unsatisfied dependencies" error for this driver.

Configure the datasource for Hibernate or JPA

If your application uses JPA and currently bundles the Hibernate JARs, you may want to use the Hibernate that is included with AS7. You should remove the Hibernate jars from your application. You should also remove the "hibernate.transaction.manager_lookup_class" property from your persistence.xml as this is not needed.

Where to Find Additional Information

DataSource Configuration in AS7
DataSource Descriptors
Admin Guide - DataSource Configuration
How to create and manage datasources in AS7
Adding a MySQL datasource to JBoss AS 7.

Update the Resource Adapter Configuration

TODO: The following section on Resource adapters needs to be reviewed

Overview

In previous versions of the application server, the resource adapter configuration was defined in a file with a suffix of *-ds.xml.

In AS7, a resource adapter is configured in the server configuration file. If you are running in domain mode, the configuration file is the domain/configuration/domain.xml file. If you are running in standalone mode, you will configure the resource adapter in the standalone/configuration/standalone.xml file. Schema reference information, which is the same for both modes, can be found here: Resource adapter descriptors. The IronJacamar distribution features a migration tool that can help you convert your previous datasource configuration file into the new format. You can find more information about the tool here: IronJacamar Datasource and Resource Adapter Migration Tool .

Define the resource adapter

The resource adapter descriptor information is defined under the <subsystem xmlns="urn:jboss:domain:resource-adapters:1.0"/> element in the server configuration file. You will use some of the same information that was previously defined in the *-ds.xml file.

The following is an example of a resource adapter element in the server configuration file:

TODO: The above section on Resource adapters needs to be reviewed

Update application JNDI namespace names

Overview

EJB 3.1 introduced a standardized global JNDI namespace and a series of related namespaces that map to the various scopes of a Java EE application. The three JNDI namespaces used for portable JNDI lookups are java:global, java:module, and java:app. If you use JNDI lookups in your application, you will need to change them to follow the new standardized JNDI namespace convention.

To conform to the new portable JNDI namespace rules, you will need to review the JNDI namespace rules and modify the application code to follow these rules.

Review the JNDI Namespace Rules

AS7 has tightened up on JNDI namespace names to provide predictable and consistent rules for every name bound in the application server and to prevent future compatibility issues. This means you might run into issues with the current namespaces in your application if they don't follow the new rules.

Namespaces should follow these rules:

  1. Unqualified relative names like "ExampleDS" or "jdbc/ExampleDS"
    should be qualified relative to "java:comp/env", "java:module/env", or
    "java:jboss/env", depending on the context.
  2. Unqualified "absolute" names like "/jdbc/ExampleDS" should be
    qualified relative to a "java:jboss/root" name.
  3. Qualified "absolute" names like "java:/jdbc/ExampleDS" should be
    qualified the same way as #2.
  4. The special "java:jboss" namespace is shared across the entire AS
    server instance.
  5. Any "relative" name with a "java:" lead-in must be in one of the five
    namespaces: "comp", "module", "app", "global", or our proprietary
    "jboss". Any name starting with "java:xxx" where "xxx" is a name which
    is not equal to one of the above five would result in an invalid name error.

Modify your application code to follow the new JNDI namespace rules

Here's an example of a JNDI lookup in EAP 5.1. This code is usually found in an initialization method. Note the lookup name is: "OrderManagerApp/ProductManagerBean/local".

Old - EAP 5.1

Here is an example of how the same lookup would be coded in AS7. This code is defined as member variables. The lookup name now uses the new portable java:app JNDI namespace: "java:app/OrderManagerEJB/ProductManagerBean!services.ejb.ProductManager"

New - AS 7

Examples of JNDI mappings in previous releases and how they might look now

(This needs input!)

Previous Namespace New Namespaces
OrderManagerApp/ProductManagerBean/local java:module/ProductManagerBean!services.ejb.ProductManager (EE6 standard binding, only accessible within the same module)
OrderManagerApp/ProductManagerBean/local java:app/OrderManagerEJB/ProductManagerBean!services.ejb.ProductManager (EE6 standard binding, only accessible within the same application)
OrderManagerApp/ProductManagerBean/local java:global/OrderManagerApp/OrderManagerEJB/ProductManagerBean!services.ejb.ProductManager (EE6 standard binding, globally accessible)
java:comp/UserTransaction java:comp/UserTransaction (This will not be accessible for non EE threads, e.g. Threads your application directly creates)
java:comp/UserTransaction java:jboss/UserTransaction (Globally accessible, use this if java:comp/UserTransaction is not available)
java:/TransactionManager java:jboss/TransactionManager
java:/TransactionSynchronizationRegistry java:jboss/TransactionSynchronizationRegistry

Where to Find Additional Information

Java EE6 Tutorial - Portable JNDI Syntax
Application-specified Portable JNDI Names

Migrate remote EJB clients to the AS7 client API

TODO: complete this section

Migrate EAP 5 Deployed Applications That Make Remote Invocations to AS 7

Overview

In AS 7, there are two ways to make remote invocations to the server:

  1. You can use the new JBoss specific EJB client API to do the invocation.
  2. You can use JNDI to lookup a proxy for your bean and invoke on that returned proxy.

This section covers option 2: coding changes required for clients that use JNDI.

In EAP 5, the EJB remote interface was bound in JNDI, by default, under the name "ejbName/local" for local interfaces, and "ejbName/remote" for the remote interfaces. The client application then looked up the stateful bean using "ejbName/remote".

In AS 7, you use the ejb: namespace for remote access to EJBs with the following syntax:
For stateless beans:

For stateful beans:

The values to be substituted in the above syntax are:

  • <app-name> - the application name of the deployed EJBs. This is typically the ear name without the .ear suffix, however, the name can be overridden in the application.xml file. If the application is not deployed as a .ear, this value is an empty string. Assume this example was not deployed as an EAR.
  • <module-name> - the module name of the deployed EJBs on the server. This is typically the jar name of the EJB deployment, without the .jar suffix, but can be overridden via the ejb-jar.xml. In this example, assume the EJBs were deployed in a jboss-as-ejb-remote-app.jar, so the module name is jboss-as-ejb-remote-app.
  • <distinct-name> - an optional distinct name for the EJB. This example doesn't use a distinct name, so it uses an empty string.
  • <bean-name> - by default, is the simple class name of the bean implementation class.
  • <fully-qualified-classname-of-the-remote-interface> - the remote view fully qualified class name.

Update the Client Code

Assume you have deployed the following stateless EJB to an AS 7 server. Note that it exposes a remote view for the bean.

In EAP 5, the client EJB lookup and invocation was coded something like this:

In AS 7, using the information described above, the client lookup and invocation is coded like this:

If your client is accessing a stateful EJB, you must append “?stateful” to the end of the context lookup like this:

A complete working example, including both server and client code, can be found at the github repo here https://github.com/jbossas/quickstart/tree/master/ejb-remote.

For more information on remote invocations using JNDI, see EJB invocations from a remote client using JNDI.

Modify logging dependencies

Overview

JBoss LogManager supports front ends for all logging frameworks, so you can keep your current logging code or move to the new JBoss logging infrastructure. Regardless of your decision, because of the modular class loading changes, you will probably need to modify your application to add the required dependencies.

Update your application code for third-party logging frameworks

As of 7.1.0.Final logging dependencies are added by default. There is one caveat to this. If you're using log4j and you don't want to use the logging subsystem to configure your handlers (appenders), then you need to exclude the server copy of log4j. See the logging documentation

Modify code to use the New JBoss Logging Framework

To use the new framework, you will need the change your imports and code as follows to achieve the same results as above:

The JAR containing the JBoss Logging classes is located in the module named "org.jboss.logging". Your MANIFEST-MF file will look like this:

    Dependencies: org.jboss.logging

For more information on how to find the module dependency, please see “How to Resolve ClassNotFoundExceptions” under the “Modular Class Loading” above.

Where to Find Additional Information

JBoss AS7 Logging
JBoss Logging Tooling

Configure changes for applications that use Hibernate and JPA

Overview

If your application contains a persistence.xml file or the code uses @PersistenceContext or @PersistenceUnit, AS7 will detect this during deployment and assume the application uses JPA. It will implicitly add Hibernate 4 and a few other dependencies to your application classpath.

If your application currently uses Hibernate 3 libraries, in most cases, this will not be a problem. You will be able to deploy and run successfully using Hibernate 4. However, if  you see a ClassNotFoundExceptions when deploying your application you can try one of two following approaches:

  1. You may be able to resolve the issue by copying the specific Hibernate 3 JARs containing those classes into the application "/lib" directory or by adding them to the classpath using some other method. In some cases this may result in ClassCastExceptions or other class loading issues due to the mixed use of the Hibernate versions, so you will need to use the second approach.
  2. You need to tell the server to use only the Hibernate 3 libraries and you will need to add exclusions for the Hibernate 4 libraries. Details on how to do this are described here: JPA Reference Guide.

For more information on Hibernate and JPA, see JPA Reference Guide.

Update your Hibernate 3 application to use Hibernate 4

Changes for Hibernate 3.3 applications

  1. Hibernate "text" type now maps to JDBC LONGVARCHAR
    In pre-3.5 versions of Hibernate, text type were mapped to JDBC CLOB. A new Hibernate type, "materialized_clob", was added to map Java String properties to JDBC CLOB. If an application has properties configured as type="text" that are intended to be mapped to JDBC CLOB, they should be changed to type="materialized_clob" in hbm mapping files, or, if using annotations, @Type(type = "text") should be replaced by @Lob.
  2. Numeric aggregate Criteria projections now return the same value type as their HQL counterparts. As a result, the return type from the following projections in org.hibernate.criterion have changed:
    1. "count" and "count distinct" projections now return a Long value (due to changes in CountProjection, Projections.rowCount(), Projections.count( propertyName ), and Projections.countDistinct( propertyName )).
    2. "sum" projections return a value type that depends on the property type due to changes in Projections.sum( propertyName ). Failure to modify your application code may result in a java.lang.ClassCastException.
      1. for properties mapped as Long, Short, Integer, or primitive integer types, a Long value is returned;
      2. for properties mapped as Float, Double, or primitive floating point types, a Double value is returned.

Changes for Hibernate 3.5 applications

  1. AnnotationConfigration must be merged into Configuration
    Aside from the fact that AnnotationConfiguration is now deprecated, this usually is not of concern. However, if you are still using an hbm.xml file, you should be aware that AS7 now uses the org.hibernate.cfg.EJB3NamingStrategy in AnnotationConfigration instead of the older org.hibernate.cfg.DefaultNamingStrategy that was previously used in Configuration. This can result in naming mismatches. If you rely on the naming strategy to default the name of a association (many-to-many and collections of elements) table, you may see this issue. To resolve it, you can tell Hibernate to use the the legacy org.hibernate.cfg.DefaultNamingStrategy by calling Configuration#setNamingStrategy and passing it org.hibernate.cfg.DefaultNamingStrategy#INSTANCE
  2. The namespaces for the Hibernate DTD files have changed.
  3. If you are using Oracle, the global environment variable "hibernate.jdbc.use_streams_for_binary" must be set to true if you are using "materialized_clob" or "materialized_blob" properties.
  4. If you are using PostgreSQL, the global environment variable "hibernate.jdbc.use_streams_for_binary" must be set to false if you are using CLOB or BLOB properties.

General Changes when migrating to Hibernate 4

In Hibernate 4.0 there is a new IdentifierGenerator implementations.

Hibernate 4.0 supplies a property that is called hibernate.id.new_generator_mappings and hibernate documentation states that it defaults to false for backward compatibility reasons - however in AS 7.1 this value defaults to true.

consider setting the value to false in persistence.xml in case you don't see the behaviour you had in your app in previous versions.

for more information - read about 5.1.2 Identifiers in general and about 5.1.2.2. Identifier generator more specifically* *here

Changes in JPA container managed behaviour

To comply with the JPA 2.0 specification section 7.6.3.1 requirements for persistence context propagation, jira AS7-1663 (An extended persistence context should not be propagated if there is no JTA transaction) was fixed in AS 7.02.  If a SFSB with an extended persistence context, invokes another bean (not in an active JTA transaction) and the other bean uses a transactional entity manager.  The extended persistence context will not be propagated to the transactional entity manager (propagation will occur if invoked with an active JTA transaction).  If your application expects the extended persistence context to be propagated to the bean with the transactional entity manager, you need to change your app to do the invocation with an active JTA transaction.

Infinispan as Second Level Cache

Overview

JBoss Cache has been replaced by Infinispan for 2nd level cache (even for non-clustered use). This requires a change to the persistence.xml file. The syntax is slightly different, depending on if you're using JPA or Hibernate APIs. These examples assume you are using JPA.

Infinispan second-level cache settings

Here's an example of the persistence.xml file in EAP 5.1:

Here is what is needed to configure the same thing for a JPA application using Infinispan with AS7:

Here is what is needed to configure the same thing for a native Hibernate application using Infinispan with AS7:

Since JPA applications use Infinispan by default, fewer properties are needed to be specified.  For native Hibernate applications you need to:

  • Select the correct Hibernate transaction factory using the hibernate.transaction.factory_class property.
  • Select the correct Hibernate transaction manager lookup class using the hibernate.transaction.manager_lookup_class property.
  • Configure the Infinispan cache region factory using one of the two options below:
    • If the Infinispan CacheManager is bound to JNDI, select JndiInfinispanRegionFactory as the cache region factory and add the cache manager’s JNDI name
    • If running JPA/Hibernate and Infinispan standalone or within third party application server, select InfinispanRegionFactory as the cache region factory

Migrate to Hibernate 4 Validator

Migrating from Hibernate Validator 3.x to 4.x means switching to a completely new code base and new API - the JSR 303 (Bean Validation). The good news is that this migration should be straight forward. Let's have a look at the different parts which needs updating.

Accessing the default ValidatorFactory

AS7 binds a default ValidatorFactory to the JNDI context under the name java:comp/ValidatorFactory.

Life cycle triggered validation

When used in combination with Hibernate 4 life-cycle based validation will be automatically enabled by Hibernate Core. Validation will occur on entity INSERT, UPDATE and DELETE operations. You can configure the groups to be validated per event type using the properties javax.persistence.validation.group.pre-persist, javax.persistence.validation.group.pre-update, and javax.persistence.validation.group.pre-remove. The values of these properties are the comma-separated, fully specified class names of the groups to validate. The validation groups feature is part of the Bean Validation specification and it is recommended you get familiar with this new functionality. For a pure migration however, you can ignore groups as Hibernate Validator 3 did not have such a feature.

You can also disable life-cycle based validation by setting the javax.persistence.validation.mode to none. Other values are auto, callback and ddl, where auto is the default.

Manual validation

In case you want to manually validate, you need to create a Validator instance from the ValidatorFactory via ValidatorFactory.getValidator. or get Validator injected in your EJB, CDI bean or any other Java EE injectable resource. You can customize your Validator instance by using a fluent API starting with ValidatorFactory.usingContext. Using this API you can configure a custom MessageInterpolator, TraverableResolver and ConstraintValidatorFactory. All these interfaces are new to Hibernate Validator and are specified in the Bean Validation specification.

Once you have your Validator instance, use the validate methods to either validate your whole entity or just a single property. A call to any validate method will return a set of ConstraintViolation instances (in contrast to an array of InvalidValue instances in Validator 3). An empty set indicates a successful validation without any constraint violations.

Using the new Bean Validation constraints

This is the most visible change fro Hibernate Validator 3 constraints in your code base. To upgrade to Hibernate Validator 4 you have to use the constraints in the javax.validation.constraints and org.hibernate.validator.constraints packages. The former contains the standardized Bean Validation constraints whereas the latter contains some Hibernate Validator specific constraints. All constraints which existed in Validator 3 are available in Validator 4. You just need to import the right class and in some cases change the name and/or type of a constraint parameter.

Custom constraints

In Validator 3 a custom constraint needed to implement org.hibernate.validator.Validator. In Validator 4 the interface to implement is javax.validation.ConstraintValidator which contains the same methods as the old interface, namely initialize and isValid. Only the method signature is slightly different. Note that support for DDL alteration is no longer part of Hibernate Validator 4 but very few users made use of this feature.

Where to Find Additional Information

Infinispan
Using Infinspan as JPA/Hibernate Second Level Cache Provider
HIBERNATE - RelationalPersistence for Idiomatic Java

Changes you need to make for Security

Configure Security for Basic Authentication

The UsersRolesLoginModule has always looked for the properties files in the classpath. In previous versions of AS, files in the JBOSS_HOME/server/SERVER_NAME/conf directory were on classpath so you could put your properties files there. In AS7 the directory structure has changed, so you need to package the properties within the application to make them available in the classpath.

To configure security for basic authentication, add a new security domain under security-domains to your standalone.xml configuration file :

<security-domain name="example">
    <authentication>
        <login-module code="UsersRoles" flag="required">
            <module-option name="usersProperties" value="${jboss.server.config.dir}/example-users.properties"/>
            <module-option name="rolesProperties" value="${jboss.server.config.dir}/example-roles.properties"/>
        </login-module>
    </authentication>
</security-domain>

If you are running in standalone mode, ${jboss.server.config.dir} refers to JBOSS_HOME/standalone/configuration/

A list of available login modules can be found in the admin guide.

Modify security domain names

In AS7 security domains no longer use the prefix java:/jaas/ in their names. Remove this prefix from the security domain configurations in jboss-web.xml for web applications and jboss.xml for enterprise applications.

Configure JAX-RS / Resteasy changes

AS7 sets up Resteasy for you, so there is no need to set it up yourself.

You should remove all of the resteasy configuration from your web.xml and replace it with one of the following three options:

  • Subclass javax.ws.rs.core.Application and use @ApplicationPath
    This is the easiest way and does not require any xml configuration. Simply include a subclass of javax.ws.rs.core.Application in your application, and annotate it with the path that you want your JAX-RS classes to be available. For example:

This will make your JAX-RS resources available under /mywebappcontext/mypath.

Note that that the path is /mypath not /mypath/*
  • Subclass javax.ws.rs.core.Application and use web.xml
    If you do not wish to use @ApplicationPath but still need to subclass Application you can set up the JAX-RS mapping in web.xml:

This will make your JAX-RS resources available under /mywebappcontext/hello.

You can also use this approach to override an application path set with the @ApplicationPath annotation.
  • Modify web.xml
    If you don't want to subclass Application you can set the JAX-RS mapping in web.xml as follows:

    This will make your JAX-RS resources available under /mywebappcontext/hello.

    Note that you only have to add the mapping, not the corresponding servlet. The server is responsible for adding the corresponding servlet automatically.

For more information, see the JAX-RS Reference Guide.

Configure LDAP security realm changes

In previous releases of JBoss AS, the LDAP realm was configured as an application-policy in the login-config.xml file. The following is an example of configuration in a previous release:

In AS7, the LDAP realm is configured as a security-domain in the standalone/configuration/standalone.xml file if you are running a standalone server or in the domain/configuration/domain.xml file if you are running your server in a managed domain. The following is an example of configuration in AS7:

The XML parser has also changed in AS7. In previous releases, you specified the module options as element content like this:

In AS7, the module options must be specified as element attributes with "value=" as follows:

Migrate from JBoss Messaging to HornetQ

JBoss Messaging will no longer be included in EAP 6. If your application uses JBoss Messaging as the messaging provider, you will need to make changes to your application to use HornetQ.

Before you start

  1. Shut down the client and server.
  2. Make a backup of any JBoss Messaging data.  Message data is stored in a database, and the tables are prefixed with "JBM_".  Backup these tables as necessary.

Transfer configurations

Transfer the existing JBoss Messaging configurations to the AS7 configuration. These configurations are located in deployment descriptors on the server running JBoss Messaging. This includes the following configurations:

  • Connection Factory service configuration files - these files contain JMS connection factories deployed with JBoss Messaging. JBoss Messaging stores these files in a file called connection-factories-service.xml in the deploy/messaging directory of your application server.
  • Destination service configurations - these files contain JMS queues and topics deployed with JBoss Messaging. By default, these are stored in a destinations-service.xml in the deploy/messaging directory of your application server.
  • Message bridge service configurations - these files contain bridge services deployed with JBoss Messaging. No bridges are deployed by default, so the name of the deployment file will vary, depending on your JBoss Messaging installation.  Note: AS7 doesn't currently support JMS bridges configured in standalone*.xml.  This will change in a future version.

Refer to Messaging configuration for details on HornetQ configurations.

Modify application code

If the application code uses standard JMS, no code changes are required.  However, if the application will be connecting to a cluster (which is outside the scope of the JMS specification) please carefully review the HornetQ documentation on clustering semantics as HornetQ and JBoss Messaging have taken substantially different approaches in their respective implementations of clustering functionality.

If the application code uses features specific to JBoss Messaging, modify the code to use equivalent features available in HornetQ (if available).

Migrate existing messages

Move any messages in the JBoss Messaging database to the HornetQ journal via a JMS bridge.  Instructions for this are available here.

For more information on HornetQ, see HornetQ Project Documentation and the HornetQ homepage.

Changes you need to make for Clustering

Starting AS7 with clustering enabled

To enable clustering in AS5 and AS6, you needed to start your server instances using the "all" profile (or some derivation of it).
e.g.

$ ./bin/run.sh -c all

In AS7, the method of enabling clustering depends on whether your servers are started via the domain controller, or as standalone servers.
To enable clustering for servers started via the domain controller, update your domain.xml and designate a server group to use the "ha" profile and "ha-sockets" socket binding group:
e.g.

To enable clustering for standalone servers, start the server using the appropriate configuration file:

$ ./bin/standalone.sh --server-config=standalone-ha.xml -Djboss.node.name=UNIQUE_NODE_NAME

Specifying the bind address

In AS5 and AS6, you would typically indicate the bind address used for clustering via the "-b" command line argument.
e.g.

$ ./bin/run.sh -c all -b 192.168.0.2

In AS7, bind addresses are explicitly defined by the relevant socket bindings within the AS7 configuration files. For servers started via the domain controller, bind addresses are specified within domain/configuration/host.xml. For standalone servers, bind addresses are specified within the standalone-ha.xml:
e.g.

In the example above, the "public" interface is specified as the default interface for all sockets within the "ha-sockets" socket binding group.

Configure jvmRoute to support mod_jk and mod_proxy

In previous releases, the web server jvmRoute was configured using a property in the server.xml file. In AS 7, the jvmRoute attribute is configured in the web subsystem of the server configuration file using the instance-id attribute as follows:

The JVM_ROUTE_SERVER above should be replaced by the jvmRoute server ID.

Specifying multicast address/port

In AS5 and AS6, you could specify the multicast address and port used for intra-cluster communication using the command line arguments "-u" and "-m", respectively.
e.g.

./bin/run.sh -c all -u 228.11.11.11 -m 45688

In AS7, the multicast address and port used for intra-cluster communication are defined by the socket-binding referenced by the relevant JGroups protocol stack.
e.g.

If you prefer to specify the multicast address and port in the command line, you can define the multicast address and ports as system properties and then use those properties on the command line when you start the server. In the following example, "jboss.mcast.addr" is the variable for the multicast address and "jboss.mcast.port" is the variable for the port.

You can then start your server using the following command line arguments:

$ ./bin/domain.sh -Djboss.mcast.addr=228.11.11.11 -Djboss.mcast.port=45688

Using an alternate protocol stack

In AS5 & AS6, you could manipulate the default protocol stack used for all clustering services via the "jboss.default.jgroups.stack" system property.
e.g.

./bin/run.sh -c all -Djboss.default.jgroups.stack=tcp

In AS7, the default protocol stack is defined by the JGroups subsystem within domain.xml or standalone-ha.xml.
e.g.

HA Singleton Deployment

TODO: This topic needs content

Additional changes you may need to make

Change Maven plugin name

The jboss-maven-plugin has not been updated and does not work In AS7. You must use org.jboss.as.plugins:jboss-as-maven-plugin to deploy to the correct directory.

Update Applications That Use Service-style Deployments

Although AS 7 no longer uses service-style descriptors, the container supports these service-style deployments without change where possible. This means that if you used jboss-service.xml or jboss-beans.xml deployment descriptors in your AS5/AS6 application, they should run with little or no modification in AS 7. You can continue to package the files in the EAR or SAR, or you can place the files directly in the deployments directory. If you are running a standalone server, the deployments directory is located here: JBOSS_HOME/standalone/deployments/

Debug and Resolve Migration Issues

Debug and resolve ClassNotFoundExceptions and NoCLassDefFoundErrors

ClassNotFoundExceptions can occur due to application packaging issues, unresolved dependencies, or missing archives. If the class specified is a class you have created in your application, the problem is mostly likely a packaging issue. If the class is is external to your project, you may need to explicitly define the dependencies on other modules or possibly copy an archive from a previous framework.

Change the application structure to find classes within the application

If the class specified in the exception is a class written specifically for the application, for example, a business class, you may need to change the packaging of the application. Due to modular class loading changes, your application may no longer be able to find classes within the EAR or WAR. In his case, you may need to move JARs to a different location within the application archive or modify class-path information so classes can be found. For more information on EAR and WAR packaging, see "WAR Class Loading" and "EAR Class Loading" in Class Loading in AS7.

How to find the JBoss module dependency

For other classes, to resolve the dependency you will find the JAR that contains the class specified by the ClassNotFoundException by looking in the JBoss AS7 modules directory. If you find a module for the class, you must add a dependency to the manifest entry.

For example, if you see this ClassNotFoundException trace in the log:

    Caused by: java.lang.ClassNotFoundException: org.apache.commons.logging.Log from [Module "deployment.TopicIndex.war:main" from Service Module Loader]
        at org.jboss.modules.ModuleClassLoader.findClass(ModuleClassLoader.java:188)

Find the JBoss module containing this class by doing one of the following:

  1. You can use Tattletale to find the JBoss module name. See the section: Use Tattletale to find application dependencies.
  2. You can manually find the module dependencies.
    1. First determine if there is an obvious module for the class
      1. Navigate to the AS7_HOME/modules directory and look for the module path.
      2. in this case, under modules, there is org/apache/commons/logging
      3. Open the AS7_HOME/modules/org/apache/commons/logging/main/module.xml file and find the module name.
      4. Add the module name to the Dependencies in the MANIFEST.MF file:
    2. If there is no obvious module path for the class
      1. Determine which JAR contains the class.
      2. Find the module containing the JAR in the AS7_HOME/modules directory and determine the module name.
      3. The module name to the Dependencies in the MANIFEST.MF file

How to find the JAR in previous install

If the class is not found in a JAR packaged in a module defined by the AS7 server, find the JAR in your EAP 5.x install or your prior server's lib directory and copy it to your application's lib/ directory.

For example, when you migrate the Seam Booking appliation from EAP 5.1, you see this ClassNotFoundException in the log:
        Caused by: java.lang.NoClassDefFoundError: org/hibernate/validator/ClassValidator
            at java.lang.Class.getDeclaredMethods0(Native Method) [:1.6.0_25]

  1. Open a terminal and navigate to the EAP5_HOME/ directory.
  2. Issue the command:
  3. You should see this (one of many) for the result: Binary file ./jboss-eap-5.1/seam/lib/hibernate-validator.jar matches
  4. Copy this JAR to the application's lib/ directory.
  5. Rebuild and redeploy the application

Debug and resolve ClassCastExceptions

This usually happens because the class is being loaded by a different class loader than the class it extends. It can also be a result of the same class existing in multiple JARs.

Remove any unnecessary JARs from the Application archive

First find the JAR that contains the class and determine how it is being loaded. Often you need to find and remove the JAR from the application's WAR or EAR. Then you must find the dependent JBoss module containing the class, and explicitly define the dependency in the MANIFEST.MF file.

Exclude any conflicting dependencies using the jboss-deployment-structure.xml file

There are cases where you will need to copy in older JARs for your applcation. If the newer JARs are loaded as automatic dependencies in AS7, you may see ClassCastExceptions and need to exclude the conflicting module dependencies. This will prevent the server from adding the dependencies. This is an example of the exclusions element in the jboss-deployment-structure.xml file:

Debug and resolve class loading issues

If you are not able to figure out how the classes are loaded, you can often resolve the problem by printing class loader information to the log. For example, if you see the following ClassCastException in the log:

In your code, print the class loader information by logging

The ModuleClassLoader information in the log will show which modules are loading the classes and, based on your application, you will need to determine the best approach to resolve the issue. You might have to remove or move a conflicting JARs, add dependencies through the MANIFEST.MF or jboss-deployment-structure.xml file or excluding dependencies in the jboss-deployment-structure.xml file.

Debug and resolve NoSuchMethodExceptions

A NoSuchMethodException indicates a class version mismatch between JAR files. It indicates your application's calling class was compiled using a different version of the JAR than the one used by the application server runtime.  This can occur when you package different versions of common libraries your application, for example Hibernate. This can also happen if you migrate between versions of JBoss EAP and do not recompile your application against the updated EAP jars. To resolve this problem, remove any common JARs from your application archive, add any dependencies as described above, recompile and deploy your application.

Debug and resolve DuplicateServiceExceptions

If you get a DuplicateServiceException for a subdeployment of a JAR or a message that the WAR application has already been installed when you deploy your EAR in AS7, it may be due to the way JBoss WS handles the deployment. In AS6, JBossWS introduced a Context Root Mapping Algorithm or rules for servlet based endpoints to allow it to become seamlessly compatible with TCK6. This means that if you have a WAR and a JAR with the same name within an EAR, it may create a web context with the same name as the JAR which will conflict with the WAR context. You can resolve this issue in one of the following ways:

  • Rename the JAR file to a name that is different than the WAR.
  • Provide a <context-root> element in the in jboss-web.xml file.
  • Provide a <context-root> element in the in jboss-webservices.xml file.
  • Customize the <context-root> for the WAR in the application.xml file.

Debug and resolve JBoss Seam debug page errors.

Usually the root cause of the exception can be found in one of the links on this page, for example, under the Component org.jboss.seam.caughtException. Use the same technique above under “How to Resolve ClassNotFoundExceptions or NoCLassDefFoundErrors” to resolve the dependencies.

EJB 2.x Support

As 7.1 provides support for EJB 2.1, however, you need to make a few code modifications and must start the server with the full profile.

Modify the Code to Use the New JNDI Namespace Rules

Like EJB 3.0, you must use the full JNDI prefix with EJB 2.1. For more information on the new JNDI namespace rules and code examples, see the section 'Update application JNDI namespace names' above.

Replace JBoss AOP Interceptors

JBoss AOP (Aspect Oriented Programming) is no longer included in JBoss AS 7. In previous releases, JBoss AOP was used by the EJB container. However, in AS 7, the EJB container uses a new mechanism. If your application uses JBoss AOP, you need modify your application code as follows.

  • Standard EJB3 configurations that were made in the ejb3-interceptors-aop.xml file are now done in the server configuration file. For a standalone server, this is the standalone/configuration/standalone.xml file. If you are running your server in a managed domain, this is the domain/configuration/domain.xml file.
  • Applications that integrate AOP interceptors into the EJB layer must be redesigned to use EJB3 interceptors and CDI. Server side interceptors can be changed to EJB3 interceptors, but there is no client side interceptor in AS 7.

Modify the jboss-web.xml File Descriptor

Modify the <jndi-name> for each <ejb-ref> to use the new JNDI fully qualified lookup format.

Replace the jboss.xml deployment descriptor file

The jboss-ejb3.xml deployment descriptor replaces the jboss.xml deployment descriptor to override and add to the features provided by the Java Enterprise Edition (EE) defined ejb3-jar.xml deployment descriptor. The new file is incompatible with jboss.xml, and the jboss.xml is now ignored in deployments.

Start the Server with the Full Profiles

EJB 2.1 requires the Java Enterprise Edition 6 Full Profile. To start AS 7 with the full profile, pass the argument "-c standalone-full.xml" on the command line when you start the server.

Migration required for other components

ToDo: Conplete this section

How to migrate Seam 2 archives to JBoss AS 7

Overview

When you migrate a Seam 2 application, you will follow the steps outlined in the migration guide. You will need to configure the datasource as noted above. You will need to specify any module dependencies. You will also need to determine if the application has any dependencies on archives that do not ship with AS7 and copy any dependent JARs into the application lib/ directory.

Update the datasource configuration

Some Seam 2 examples use a default JDBC datasource named java:/ExampleDS. The easiest way is to define this datasource is to add the following datasource definition to the <jbossas7_dir>/standalone/configuration/standalone.xml file the :

This definition is a copy of the default HSQL datasource defined in JBoss AS 7.

You can also add the datasource using the jboss-cli command line interface:

$ <jboss-as7>/bin/jboss-cli.sh --connect
[standalone@localhost:9999 /] data-source add --name=ExampleDS --jndi-name=java:/ExampleDS --connection-url=jdbc:h2:mem:test;DB_CLOSE_DELAY=-1 --driver-name=h2 --user-name=sa --password=sa

Add any required dependencies

Since Seam 2 applications use JSF 1.2, you will need to add dependencies for the JSF 1.2 modules and exclude the JSF 2.0 modules. You will need to create a jboss-deployment-structure.xml file in the EAR META-INF/ directory that contains the following data:

If your application uses any third-party logging frameworks you will need add dependencies as described in that section of the migration guide.

Copy dependent archives from outside frameworks or other locations

Even if your Seam 2 application uses Hibernate 3, you may still be able to run with the Hibernate 4 module packaged in AS7. Some hibernate classes are no longer available and you may need to copy one or more of the older hibernate JARs into the /lib directory. If you end up with ClassNotFoundExceptions or ClassCastExceptions involving hibernate classes, you may have to exclude the hibernate module in the deployments section of the META-INF/jboss-deployment-structure.xml

Seam 2 JPA example deployment on JBoss AS 7

  1. Remove the jboss-web.xml file from the jboss-seam-jpa.war/WEB-INF/ directory - Defined class loading in jboss-web.xml is now default behaviour.
  2. Comment or remove hibernate property in jboss-seam-jpa.war/WEB-INF/classes/META-INF/persistence.xml:

    <!- <property name="hibernate.cache.provider_class" value="org.hibernate.cache.HashtableCacheProvider"/> ->

  3. Add the following dependencies from seam distribution (seam/lib directory) into
    jboss-seam-jpa.war/WEB-INF/lib directory, which were in JBoss AS 5/6 and are upgraded in JBoss AS7 to higher major version:
    • slf4j-api.jar
    • slf4j-log4j12.jar
    • hibernate-entitymanager.jar
    • hibernate-core.jar
    • hibernate-annotations.jar
    • hibernate-commons-annotations.jar
    • hibernate-validator.jar
  4. Add jboss-deployment-structure.xml to jboss-seam-jpa.war/WEB-INF/ with the following content in it:
    Name Size Creator Creation Date Comment  
    XML File jboss-deployment-structure.xml 0.6 kB Marek Novotny Jul 18, 2011 04:50 jboss-deployment-structure.xml for Seam 2 JPA example migration  

How to debug and resolve Seam 2 JNDI errors

When you migrate a Seam 2 application, you may see javax.naming.NameNotFoundException errors in the log like the following:

        javax.naming.NameNotFoundException: Name 'jboss-seam-booking' not found in context ''

If you don't want to modify JNDI lookups throughout the code, you can modify the application's components.xml file.

  1. First, you will need to replace the existing core-init element as follows:
  2. Next, find the JNDI binding INFO messages that are printed in the server log when the application is deployed. The JNDI binding messages should look similar to this:
                  15:01:16,138 INFO [org.jboss.as.ejb3.deployment.processors.EjbJndiBindingsDeploymentUnitProcessor] (MSC service thread 1-1) JNDI bindings for session bean
                   named AuthenticatorAction in   deployment unit subdeployment "jboss-seam-booking.jar" of deployment "jboss-seam-booking.ear" are as follows:
                            java:global/jboss-seam-booking/jboss-seam-booking.jar/AuthenticatorAction!org.jboss.seam.example.booking.Authenticator
                            java:app/jboss-seam-booking.jar/AuthenticatorAction!org.jboss.seam.example.booking.Authenticator
                            java:module/AuthenticatorAction!org.jboss.seam.example.booking.Authenticator
                            java:global/jboss-seam-booking/jboss-seam-booking.jar/AuthenticatorAction
                            java:app/jboss-seam-booking.jar/AuthenticatorAction
                           java:module/AuthenticatorAction
  3. For each JNDI binding INFO message in the log, add a matching component element to the components.xml file:

Running Seam 3 archives on JBoss AS 7

ToDo: Complete this section

Migrating Spring applications

For information on how to migrate Spring applications, see details at the Spring applications development and migration guide.

Tools That Can Assist with Migration

Use Tattletale to find application dependencies

Due to the modular class loading changes, you might run into ClassNotFoundExceptions or ClassCastExceptions when you migrate your application. To resolve these dependencies, you will need to find the JARs that contain the classes specified by the exceptions.

Tattletale is an excellent tool that recursively scans your application and provides detailed reports about its contents. Tattletale 1.2.0.Beta2 or later contains additional support to help with the new JBoss Modules class loading used in AS7. Tattletale's "JBoss AS7" report can be used to to automatically identify and specify dependent module names in your application's jboss-deployment-structure.xml file.

Install Tattletale

  1. Download Tattletale version 1.2.0.Beta2 or newer from http://sourceforge.net/projects/jboss/files/JBoss%20Tattletale/.
  2. Unzip the file into the directory of your choice.
  3. Modify the TATTLETALE_HOME/jboss-tattletale.properties file by adding jbossas7 to the "profiles" property.
  4. Uncomment scan and reports in the properties file.

Create and review the Tattletale report

  1. Create the Tattletale report by issuing the command:

    For example:

  2. In a browser, open the OUTPUT_DIRECTORY/index.html file and click on "JBoss A7" under the "Reports" section.
    1. The column on the left lists the archives used by the application. Click on the ARCHIVE_NAME link to view details about the archive, such as its location, manifest information, and classes it contains.
    2. The jboss-deployment-structure.xml link in the column on the right shows how to specify the module dependency for the archive in the left column. Click on this link to see how to define the deployment dependency module information for this archive.
Tattletale will only find dependencies on the application classes. It will not find dependencies that may be required by classes your application calls or by classes in other JARs included under your application's WEB-INF/lib directory. To identify external dependencies, you will need to look at the "Depends On" report.

IronJacamar Datasource and Resource Adapter Migration Tool

Summary

In previous versions of the application server, datasources and resource adapters were configured and deployed using a file with a suffix of *-ds.xml. The IronJacamar 1.1 distribution contains a migration tool that can be used to convert the datasource and resource adapter configuration files from previous releases into the configuration format expected by the AS7 server. The tool parses the source configuration file from the previous release, then creates and writes an XML snippet in the appropriate format that can be copied and pasted under the correct subsystem in the server configuration file.

Download and install IronJacamar

  1. Download IronJacamar 1.1 from here: http://www.jboss.org/ironjacamar/downloads/ .
  2. Unzip the file into a directory of your choice.
  3. The converter script can be found in the IRONJACAMAR distribution in the following locations:
    1. Linux script: IRONJACAMAR_HOME/doc/as/converter.sh
    2. Windows batch file: IRONJACAMAR_HOME/doc/as/converter.bat
The tool will do a best effort to convert all old attributes and elements to the new format. It will be necessary to make additional changes to the generated file. In the following examples, we will need to make a few changes to the resulting XML. Please, consult this documentation for additional information.

Use the IronJacamar Migration Tool to convert a datasource configuration file.

  1. Open a terminal or command prompt and CD to the IRONJACAMAR_HOME/docs/as/ directory.
  2. For Linux, run the converter script by typing the following command in the terminal:

    For Windows, type:

  3. Copy the XML snippet from the target file into the server configuration file under the subsystem xmlns="urn:jboss:domain:datasources:1.0" datasources element.
    1. If you are running in domain mode, you need to copy the XML snippet into the domain/configuration/domain.xml file.
    2. If you are running in standalone mode, you need to copy the XML snippet into the standalone/configuration/standalone.xml file.
      The tool generates the datasources and datasource element. If you have existing datasources, you need only copy the datasource element into the configuration file.

Here is an example of the datasource configuration file for the Seam Booking example that shipped with EAP 5.x:

The generated file will contain a driver-class element. The preferred way to define the driver class is using a drivers element. Here is the converted XML with the driver-class and drivers modifications as configured in the AS7 configuration file:

Use the IronJacamar Migration Tool to convert a resource adapter configuration file.

  1. Open a terminal or command prompt and CD to the IRONJACAMAR_HOME/docs/as/ directory.
  2. For Linux, run the converter script by typing the following command in the terminal:

    For Windows, type:

  3. Copy the XML snippet from the target file into the server configuration file under the subsystem xmlns="urn:jboss:domain:resource-adapters:1.0" element.
    1. If you are running in domain mode, you need to copy the XML snippet into the domain/configuration/domain.xml file.
    2. If you are running in standalone mode, you need to copy the XML snippet into the standalone/configuration/standalone.xml file.
      The tool generates the resource-adapters and resource-adapter element. If you have existing resource-adapters, you need to copy only the resource-adapter element into the configuration file.

Here is an example of the mttestadapter-ds.xml resource-adapter configuration file from the EAP-5.x TestSuite.:

You will need to replace the class-name attribute "FIXME_MCF_CLASS_NAME" in the generated XML snippet with the class name of the managed connection factory, in this case, "org.jboss.test.jca.adapter.TestManagedConnectionFactory". Here is the server configuration file with the newly generated and edited configuration data:

For more information about this migration tool, go to IronJacamar Migration Tool .

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jan 30, 2012

    Moved to more appropriate place.

  2. Jun 23, 2013

    Check out and contribute to automatic AS config migration tool:

    https://github.com/OndraZizka/jboss-migration/wiki