Skip to end of metadata
Go to start of metadata

Seam 2 Booking Application - Migration of Binaries from EAP5.1 to AS7

This is a step-by-step how-to guide on porting the Seam Booking application binaries from EAP5.1 to AS7. Although there are better approaches for migrating applications, the purpose of this document is to show the types of issues you might encounter when migrating an application and how to debug and resolve those issues.

For this example, the application EAR is deployed to the AS7_HOME/standalone/deployments directory with no changes other than extracting the archives so we can modify the XML files contained within them.

Step 1: Build and deploy the EAP5.1 version of the Seam Booking application

  1. Build the EAR
  2. Copy the EAR to the AS7_HOME deployments directory:
  3. Start the AS7 server and check the log. You will see:
  4. Create an empty file with the name jboss-seam-booking.ear.dodeploy and copy it into the deployments directory. In the log, you will now see the following, indicating that it is deploying:

At this point, you will first encounter your first deployment error. In the next section, we will step through each issue and how to debug and resolve it.

Step 2: Debug and resolve deployment errors and exceptions

First Issue: java.lang.ClassNotFoundException: javax.faces.FacesException

When you deploy the application, the log contains the following error:

What it means:

The ClassNotFoundException indicates a missing dependency. In this case, it can not find the class javax.faces.FacesException and you need to explicitly add the dependency.

How to resolve it:

Find the module name for that class in the AS7_HOME/modules directory by looking for a path that matches the missing class. In this case, you will find 2 modules that match:

Both modules have the same module name: “javax.faces.api” but one in the main directory is for JSF 2.0 and the one located in the 1.2 directory is for JSF 1.2. If there was only one module available, we could simply create a  MANIFEST.MF file and added the module dependency. But in this case, we want to use the JSF 1.2 version and not the 2.0 version in main, so we need to be able to specify one and exclude the other. To do this, we create a jboss-deployment-structure.xml file in the EAR META-INF/ directory that contains the following data:

In the "deployment" section, we add the dependency for the javax.faces.api for the JSF 1.2 module. We also add the dependency for the JSF 1.2 module in the sub-deployment section for the WAR and exclude the module for JSF 2.0.

Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.ear.failed file and creating a blank jboss-seam-booking.ear.dodeploy file in the same directory.

Next Issue: java.lang.ClassNotFoundException: org.apache.commons.logging.Log

When you deploy the application, the log contains the following error:

What it means:

The ClassNotFoundException indicates a missing dependency. In this case, it can not find the class org.apache.commons.logging.Log and you need to explicitly add the dependency.

How to resolve it:

Find the module name for that class in the AS7_HOME/modules/ directory by looking for a path that matches the missing class. In this case, you will find one module that matches the path org/apache/commons/logging/. The module name is “org.apache.commons.logging”.

Modify the jboss-deployment-structure.xml to add the module dependency to the deployment section of the file.

The jboss-deployment-structure.xml should now look like this:

Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.ear.failed file and creating a blank jboss-seam-booking.ear.dodeploy file in the same directory.

Next Issue: java.lang.ClassNotFoundException: org.dom4j.DocumentException

When you deploy the application, the log contains the following error:

What it means:

Again, the ClassNotFoundException indicates a missing dependency. In this case, it can not find the class org.dom4j.DocumentException.

How to resolve it:

Find the module name in the JBOSS_HOME/modules/ directory by looking for the org/dom4j/DocumentException. The module name is “org.dom4j”.

Modify the jboss-deployment-structure.xml to add the module dependency to the deployment section of the file.

The jboss-deployment-structure.xml file should now look like this:

Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.ear.failed file and creating a blank jboss-seam-booking.ear.dodeploy file in the same directory.

Next Issue: java.lang.ClassNotFoundException: org.hibernate.validator.InvalidValue

When you deploy the application, the log contains the following error:

What it means:

Again, the ClassNotFoundException indicates a missing dependency. In this case, it can not find the class org.hibernate.validator.InvalidValue.

How to resolve it:

There is a module “org.hibernate.validator”, but the JAR does not contain the org.hibernate.validator.InvalidValue class, so adding the module dependency will not resolve this issue.

In this case, the JAR containing the class was part of the EAP 5.1 deployment. We will look for the JAR that contains the missing class in the EAP5_HOME/jboss-eap-5.1/seam/lib/ directory. To do this, open a console and type the following:

The result shows:

In this case, we need to copy the hibernate-validator.jar to the jboss-seam-booking.ear/lib/ directory:

Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.ear.failed file and creating a blank jboss-seam-booking.ear.dodeploy file in the same directory.

Next Issue: java.lang.InstantiationException: org.jboss.seam.jsf.SeamApplicationFactory

When you deploy the application, the log contains the following error:

What it means:

The com.sun.faces.config.ConfigurationException and java.lang.InstantiationException indicate a dependency issue. In this case, it is not as obvious.

How to resolve it:

We need to find the module that contains the com.sun.faces classes. While there is no com.sun.faces module, there are are two com.sun.jsf-impl modules. A quick check of the jsf-impl-1.2_13.jar in the 1.2 directory shows it contains the com.sun.faces classes.

As we did with the javax.faces.FacesException ClassNotFoundException, we want to use the JSF 1.2 version and not the JSF 2.0 version in main, so we need to be able to specify one and exclude the other. We need to modify the jboss-deployment-structure.xml to add the module dependency to the deployment section of the file. We also need to add it to the WAR subdeployment and exclude the JSF 2.0 module. The file should now look like this:

Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.ear.failed file and creating a blank jboss-seam-booking.ear.dodeploy file in the same directory.

Next Issue: java.lang.ClassNotFoundException: org.apache.commons.collections.ArrayStack

When you deploy the application, the log contains the following error:

What it means:

Again, the ClassNotFoundException indicates a missing dependency. In this case, it can not find the class org.apache.commons.collections.ArrayStack.

How to resolve it:

Find the module name in the JBOSS_HOME/modules/ directory by looking for the org/apache/commons/collections path. The module name is “org.apache.commons.collections”.

Modify the jboss-deployment-structure.xml to add the module dependency to the deployment section of the file.

The jboss-deployment-structure.xml file should now look like this:

Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.ear.failed file and creating a blank jboss-seam-booking.ear.dodeploy file in the same directory.

Next Issue: Services with missing/unavailable dependencies

When you deploy the application, the log contains the following error:

What it means:

When you get a “Services with missing/unavailable dependencies” error, look that the text within the brackets after “missing”.

In this case you see:

The “/em” indicates an Entity Manager and datasource issue.

How to resolve it:

In AS7, datasource configuration has changed and needs to be defined in the standalone/configuration/standalone.xml file. Since AS7 ships with an example database that is already defined in the standalone.xml file, we will modify the persistence.xml file to use that example database. Looking in the standalone.xml file, you can see that the jndi-name for the example database is "java:jboss/datasources/ExampleDS".

Modify the jboss-seam-booking.jar/META-INF/persistence.xml file to comment the existing jta-data-source element and replace it as follows:

Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.ear.failed file and creating a blank jboss-seam-booking.ear.dodeploy file in the same directory.

Next Issue: java.lang.ClassNotFoundException: org.hibernate.cache.HashtableCacheProvider

When you deploy the application, the log contains the following error:

What it means:

The ClassNotFoundException indicates a missing dependency. In this case, it can not find the class org.hibernate.cache.HashtableCacheProvider.

How to resolve it:

There is no module for “org.hibernate.cache”. In this case, the JAR containing the class was part of the EAP 5.1 deployment. We will look for the JAR that contains the missing class in the EAP5_HOME/jboss-eap-5.1/seam/lib/ directory.

To do this, open a console and type the following:

The result shows:

In this case, we need to copy the hibernate-core.jar to the jboss-seam-booking.ear/lib/ directory:

Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.ear.failed file and creating a blank jboss-seam-booking.ear.dodeploy file in the same directory.

Next Issue: java.lang.ClassCastException: org.hibernate.cache.HashtableCacheProvider

When you deploy the application, the log contains the following error:

What it means:

A ClassCastException can be a result of many problems. If you look at this exception in the log, it appears the class org.hibernate.cache.HashtableCacheProvider extends org.hibernate.cache.spi.CacheProvider and is being loaded by a different class loader than the class it extends. The org.hibernate.cache.HashtableCacheProvider class is in in the hibernate-core.jar and is being loaded by the application class loader. The class it extends, org.hibernate.cache.spi.CacheProvider, is in the org/hibernate/main/hibernate-core-4.0.0.Beta1.jar and is implicitly loaded by that module.

This is not obvious, but due to changes in Hibernate 4, this problem is caused by a backward compatibility issue due moving the HashtableCacheProvider class into another package. This class was moved from the org.hibernate.cache package to the org.hibernate.cache.internal package. If you don't remove the hibernate.cache.provider_class property from the persistence.xml file, it will force the Seam application to bundle the old Hibernate libraries, resulting in ClassCastExceptions, In AS7, you should move away from using HashtableCacheProvider and use Infinispan instead.

How to resolve it:

In AS7, you need to comment out the hibernate.cache.provider_class property in the jboss-seam-booking.jar/META-INF persistence.xml file as follows:

Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.ear.failed file and creating a blank jboss-seam-booking.ear.dodeploy file in the same directory.

No more issues: Deployment errors should be resolved

At this point, the application should deploy without errors, but when you access the URL “http://localhost:8080/seam-booking/” in a browser and attempt "Account Login", you will get a runtime error “The page isn't redirecting properly”. In the next section, we will step through each runtime issue and how to debug and resolve it.

Step 3: Debug and resolve runtime errors and exceptions

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

The application deploys successfully, but when you access the URL “http://localhost:8080/seam-booking/” in a browser, you get “The page isn't redirecting properly” and the log contains the following error:

What it means:

A NameNotFoundException indications a JNDI naming issue. JNDI naming rules have changed in AS7 and we need to modify the lookup names to follow the new rules.

How to resolve it:

To debug this, look earlier in the server log trace to what JNDI binding were used. Looking at the server log we see this:

We need to modify the WAR's lib/components.xml file to use the new JNDI bindings. In the log, note the EJB JNDI bindings all start with "java:app/jboss-seam-booking.jar"

Replace the <core:init> element as follows:

Next, we need to add the EjbSynchronizations and TimerServiceDispatcher JNDI bindings. Add the following component elements to the file:

The components.xml file should now look like this:

Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.ear.failed file and creating a blank jboss-seam-booking.ear.dodeploy file in the same directory.

At this point, the application should deploy and run without error. When you access the URL “http://localhost:8080/seam-booking/” in a browser, you will be able to login successfully.

Step 4: Access the application

Access the URL “http://localhost:8080/seam-booking/” in a browser and login with demo/demo. You should the Booking welcome page.

Summary of Changes

Although it would be much more efficient to determine dependencies in advance and add the implicit dependencies in one step, this exercise shows how problems appear in the log and provides some information on how to debug and resolve them.

The following is a summary of changes made to the application when migrating it to AS7:

  1. We created a jboss-deployment-structure.xml file in the EAR's META-INF/ directory. We added "dependencies" and "exclusions" to resolve ClassNotFoundExceptions. This file contains the following data:
  2. We copied the following JARs from the EAP5_HOME/jboss-eap-5.1/seam/lib/ directory to the jboss-seam-booking.ear/lib/ directory to resolve ClassNotFoundExceptions:
  3. We modified the {{jboss-seam-booking.jar/META-INF/persistence.xml} file as follows.
    1. First, we changed the jta-data-source element to use the Example database that ships with AS7:
    2. Next, we commented out the hibernate.cache.provider_class property:
  4. We modified the WAR's lib/components.xml file to use the new JNDI bindings
    1. We replaced the <core:init> existing element as follows:
    2. We added component elements for the "EjbSynchronizations" and "TimerServiceDispatcher" JNDI bindings

The unmodified EAR from EAP 5.1 (jboss-seam-booking-eap51.ear.tar.gz) and the EAR as modified to run on AS7 (jboss-seam-booking-as7.ear.tar.gz) are attached to this document.

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