<subsystem xmlns="urn:jboss:domain:ee:1.0" > <ear-subdeployments-isolated>false</ear-subdeployments-isolated> </subsystem>
This guide is still under development, check back soon!
How do I migrate my application from JBoss AS 5 or AS 6 to JBoss AS 7?
Packaging the Hibernate 3.5 or greater 3.x JPA persistence provider with your application
Sharing the Hibernate 3.5 or greater JPA persistence provider between multiple applications
Packaging a different version of Hibernate 4.x jars with the application
Updating the Hibernate 4.x jars to a different Hibernate 4.x version
Injection of Hibernate Session and SessionFactoryInjection of Hibernate Session and SessionFactory
Java Developers
You are looking at old version of document, for JBoss AS 7.1 please see https://docs.jboss.org/author/display/AS71/Class+Loading+in+AS7
Class loading in AS7 is considerably different to previous versions of JBoss AS. Class loading is 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.
Module names for top level deployments follow the format deployment.myarchive.war while sub deployments are named like deployment.myear.ear.mywar.war.
This means that it is possible for a deployment to import classes from another deployment using the other deployments module name, the details of how to add an explicit module dependency are explained below.
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 this page.
Automatic dependencies can be excluded through the use of jboss-deployment-structure.xml.
A common source of errors in Java applications is including API classes in a deployment that are also provided by the container. This can result in multiple versions of the class being created and the deployment failing to deploy properly. To prevent this in AS7, module dependencies are added in a specific order that should prevent this situation from occurring.
In order of highest priority to lowest priority
System Dependencies - These are dependencies that are added to the module automatically by the container, including the Java EE api's.
User Dependencies - These are dependencies that are added through jboss-deployment-structure.xml or through the Dependencies: manifest entry.
Local Resource - Class files packaged up inside the deployment itself, e.g. class files from WEB-INF/classes or WEB-INF/lib of a war.
Inter deployment dependencies - These are dependencies on other deployments in an ear deployment. This can include classes in an ear's lib directory, or classes defined in other ejb jars.
The war is considered to be a single module, so classes defined in WEB-INF/lib are treated the same as classes in WEB-INF/classes. All classes packaged in the war will be loaded with the same class loader.
Ear deployments are multi-module deployments. This means that not all classes inside an ear will necessarily have access to all other classes in the ear, unless explicit dependencies have been defined. By default the EAR/lib directory is a single module, and every WAR or EJB jar deployment is also a separate module. Sub deployments (wars and ejb-jars) always have a dependency on the parent module, which gives them access to classes in EAR/lib, however they do not always have an automatic dependency on each other. This behaviour is controlled via the ear-subdeployments-isolated setting in the ee subsystem configuration:
<subsystem xmlns="urn:jboss:domain:ee:1.0" > <ear-subdeployments-isolated>false</ear-subdeployments-isolated> </subsystem>
By default this is set to false, which allows the sub-deployments to see classes belonging to other sub-deployments within the .ear.
For example, consider the following .ear deployment:
myapp.ear | |--- web.war | |--- ejb1.jar | |--- ejb2.jar
If the ear-subdeployments-isolated is set to false, then the classes in web.war can access classes belonging to ejb1.jar and ejb2.jar. Similarly, classes from ejb1.jar can access classes from ejb2.jar (and vice-versa).
The ear-subdeployments-isolated element value has no effect on the isolated classloader of the .war file(s). i.e. irrespective of whether this flag is set to true or false, the .war within a .ear will have an isolated classloader and other sub-deployments within that .ear will not be able to access classes from that .war. This is as per spec.
If the ear-subdeployments-isolated is set to true then no automatic module dependencies between the sub-deployments are set up. User must manually setup the dependency with Class-Path entries, or by setting up explicit module dependencies.
The Java EE specification says that portable applications should not rely on sub deployments having access to other sub deployments unless an explicit Class-Path entry is set in the MANIFEST.MF. So portable applications should always use Class-Path entry to explicitly state their dependencies.
It is also possible to override the ear-subdeployments-isolated element value at a per deployment level. See the section on jboss-deployment-structure.xml below.
Dependencies: Manifest Entries
Deployments (or more correctly modules within a deployment) may set up dependencies on other modules by adding a Dependencies: manifest entry. This entry consists of a comma separated list of module names that the deployment requires. The available modules can be seen under the modules directory in the application server distribution. For example to add a dependency on javassist and apache velocity you can add a manifest entry as follows:
Dependencies: org.javassist export,org.apache.velocity export services,org.antlr
Each dependency entry may also specify some of the following parameters by adding them after the module name:
export This means that the dependencies will be exported, so any module that depends on this module will also get access to the dependency.
services By default items in META-INF of a dependency are not accessible, this makes items from META-INF/services accessible so services in the modules can be loaded.
optional If this is specified the deployment will not fail if the module is not available.
annotations If a jandex index has be created for the module these annotations will be merged into the deployments annotation index. The Jandex index can be generated using the Jandex ant task , and must be named META-INF/jandex.idx. Note that it is not necessary to break open the jar being indexed to add this to the modules class path, a better approach is to create a jar containing just this index, and adding it as an additional resource root in the module.xml file.
Using the export parameter it is possible to add a dependency to all sub deployments in an ear. If a module is exported from a Dependencies: entry in the top level of the ear (or by a jar in the ear/lib directory) it will be available to all sub deployments as well.
To generate a MANIFEST.MF entry when using maven put the following in your pom.xml:
<build>
...
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<configuration>
<archive>
<manifestEntries>
<Dependencies>org.slf4j</Dependencies>
</manifestEntries>
</archive>
</configuration>
</plugin>
</plugins>
</build>
If your deployment is a jar you must use the maven-jar-plugin rather than the maven-war-plugin.
It is also possible to add module dependencies on other modules inside the deployment using the Class-Path manifest entry. This can be used within an ear to set up dependencies between sub deployments, and also to allow modules access to additional jars deployed in an ear that are not sub deployments and are not in the EAR/lib directory. If a jar in the EAR/lib directory references a jar via Class-Path: then this additional jar is merged into the parent ear's module, and is accessible to all sub deployments in the ear.
It is also possible to set up global modules, that are accessible to all deployments. This is done by modifying the configuration file (standalone/domain.xml).
For example, to add javassist to all deployments you can use the following XML:
<subsystem xmlns="urn:jboss:domain:ee:1.0" >
<global-modules>
<module name="org.javassist" slot="main" />
</global-modules>
</subsystem>
Note that the slot field is optional and defaults to main.
jboss-deployment-structure.xml is a JBoss specific deployment descriptor that can be used to control class loading in a fine grained manner. It should be placed in the top level deployment, in META-INF (or WEB-INF for web deployments). It can do the following:
Prevent automatic dependencies from being added
Add additional dependencies
Define additional modules
Change an EAR deployments isolated class loading behaviour
Add additional resource roots to a module
To exclude subsystem within a module, you will will want to exclude the entire module and then add back in each of the subsystems that make the module minus the subsystem that needs to be excluded.
e.g. exclude javax.ws.rs.api from javaee.api module
<?xml version="1.0"?>
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<deployment>
<exclusions>
<module name="javaee.api"/>
</exclusions>
<dependencies>
<module name="javax.activation.api" export="true"/>
<module name="javax.annotation.api" export="true"/>
<module name="javax.ejb.api" export="true"/>
<module name="javax.el.api" export="true"/>
<module name="javax.enterprise.api" export="true"/>
<module name="javax.enterprise.deploy.api" export="true"/>
<module name="javax.inject.api" export="true"/>
<module name="javax.interceptor.api" export="true"/>
<module name="javax.jms.api" export="true"/>
<module name="javax.jws.api" export="true"/>
<module name="javax.mail.api" export="true"/>
<module name="javax.management.j2ee.api" export="true"/>
<module name="javax.persistence.api" export="true"/>
<module name="javax.resource.api" export="true"/>
<module name="javax.rmi.api" export="true"/>
<module name="javax.security.auth.message.api" export="true"/>
<module name="javax.security.jacc.api" export="true"/>
<module name="javax.servlet.api" export="true"/>
<module name="javax.servlet.jsp.api" export="true"/>
<module name="javax.transaction.api" export="true"/>
<module name="javax.validation.api" export="true"/>
<!-- <module name="javax.ws.rs.api" export="true" services="export"/> -->
<module name="javax.xml.bind.api" export="true"/>
<module name="javax.xml.registry.api" export="true"/>
<module name="javax.xml.soap.api" export="true"/>
<module name="javax.xml.ws.api" export="true"/>
<!-- This one always goes last. -->
<module name="javax.api" export="true"/>
</dependencies>
</deployment>
</jboss-deployment-structure>
An example of a complete jboss-deployment-structure.xml file for an ear deployment is as follows:
<jboss-deployment-structure>
<!-- Make sub deployments isolated by default, so they cannot see each others classes without a Class-Path entry -->
<ear-subdeployments-isolated>true</ear-subdeployments-isolated>
<!-- This corresponds to the top level deployment. For a war this is the war's module, for an ear -->
<!-- This is the top level ear module, which contains all the classes in the EAR's lib folder -->
<deployment>
<!-- Exclusions allow you to prevent the server from automatically adding some dependencies -->
<exclusions>
<module name="org.javassist" />
</exclusions>
<!-- This allows you to define additional dependencies, it is the same as using the Dependencies: manifest attribute -->
<dependencies>
<module name="deployment.javassist.proxy" />
<module name="deployment.myjavassist" />
</dependencies>
<!-- These add additional classes to the module. In this case it is the same as including the jar in the EAR's lib directory -->
<resources>
<resource-root path="my-library.jar" />
</resources>
</deployment>
<sub-deployment name="myapp.war">
<!-- This corresponds to the module for a web deployment -->
<!-- it can use all the same tags as the <deployment> entry above -->
<dependencies>
<!-- Adds a dependency on a ejb jar. This could also be done with a Class-Path entry -->
<module name="deployment.myear.ear.myejbjar.jar" />
</dependencies>
</sub-deployment>
<!-- Now we are going to define two additional modules -->
<!-- This one is a different version of javassist that we have packaged -->
<module name="deployment.myjavassist" >
<resources>
<resource-root path="javassist.jar" >
<!-- We want to use the servers version of javassist.util.proxy.* so we filter it out-->
<filter>
<exclude path="javassist/util/proxy" />
</filter>
</resource-root>
</resources>
</module>
<!-- This is a module that re-exports the containers version of javassist.util.proxy -->
<!-- This means that there is only one version of the Proxy classes defined -->
<module name="deployment.javassist.proxy" >
<dependencies>
<module name="org.javassist" >
<imports>
<include path="javassist/util/proxy" />
<exclude path="/**" />
</imports>
</module>
</dependencies>
</module>
</jboss-deployment-structure>
The xsd for jboss-deployment-structure.xml is available at http://www.jboss.org/schema/jbossas/jboss-deployment-structure-1_0.xsd
As explained in the ClassLoading in AS7 article, JBoss AS7 is based on module classloading. A class within a module B isn't visible to a class within a module A, unless module B adds a dependency on module A. Module dependencies can be explicitly (as explained in that classloading article) or can be "implicit". This article will explain what implicit module dependencies mean and how, when and which modules are added as implicit dependencies.
Consider an application deployment which contains EJBs. EJBs typically need access to classes from the javax.ejb.* package and other Java EE API packages. The jars containing these packages are already shipped in JBoss AS and are available as "modules". The module which contains the javax.ejb.* classes has a specific name and so does the module which contains all the Java EE API classes. For an application to be able to use these classes, it has to add a dependency on the relevant modules. Forcing the application developers to add module dependencies like these (i.e. dependencies which can be "inferred") isn't a productive approach. Hence, whenever an application is being deployed, the deployers within the server, which are processing this deployment "implicitly" add these module dependencies to the deployment so that these 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 the next section.
When a deployment is being processed by the server, it goes through a chain of "deployment processors". Each of these processors will have a way to check if the deployment meets a certain criteria and if it does, the deployment processor adds a implicit module dependency to that deployment. Let's take an example - Consider (again) an EJB3 deployment which has the following class:
@Stateless
public class MySuperDuperBean {
...
}
As can be seen, we have a simple @Stateless EJB. When the deployment containing this class is being processed, the EJB deployment processor will see that the deployment contains a class with the @Stateless annotation and thus identifies this as a EJB deployment. This is just one of the several ways, various deployment processors can identify a deployment of some specific type. The EJB deployment processor will then add an implicit dependency on the Java EE API module, so that all the Java EE API classes are visible to the deployment.
Some subsystems will always add a API classes, even if the trigger condition is not met. These are listed separately below.
In the next section, we'll list down the implicit module dependencies that are added to a deployment, by various deployers within JBoss AS.
|
Subsystem responsible for adding the implicit dependency |
Dependencies that are always added |
Dependencies that are added if a trigger condition is met |
Trigger which leads to the implicit module dependency being added |
|
Core Server |
|
|
|
|
EE Subsystem |
|
|
|
|
EJB3 subsystem |
|
|
The presence of ejb-jar.xml (in valid locations in the deployment, as specified by spec) or the presence of annotation based EJBs (ex: @Stateless, @Stateful, @MessageDriven etc) |
|
JAX-RS (Resteasy) subsystem |
|
|
The presence of JAX-RS annotations in the deployment |
|
JCA sub-system |
|
|
If the deployment is a resource adaptor (RAR) deployment. |
|
JPA (Hibernate) subsystem |
|
|
The presence of an @PersistenceUnit or @PersistenceContext annotation, or a <persistence-unit-ref> or <persistence-context-ref> in a deployment descriptor. |
|
SAR Subsystem |
|
|
The deployment is a SAR archive |
|
Security Subsystem |
|
|
|
|
Web Subsystem |
|
|
The deployment is a WAR archive. JSF is only added if used. Multiple version options exist for mojarra. |
|
Web Services Subsystem |
|
|
|
|
Weld (CDI) Subsystem |
|
|
If a beans.xml file is detected in the deployment |
You are looking ad old version of migration document for JBoss AS 7.1 see https://docs.jboss.org/author/display/AS71/How+do+I+migrate+my+application+from+AS5+or+AS6+to+AS7
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 how 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.
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 may want to postpone migration until release of AS 7.1 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.
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.
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. Otherwise you may see ClassNotFoundExceptions, NoClassDefFoundErrors, or ClassCastExceptions. 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.
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.
Due to the modular class loading changes, when you migrate your application you might run into ClassNotFoundExceptions or ClassCastExceptions. 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. Here we use Tattletale's "Class Location" report to find the class dependency information.
This 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.
Download Tattletale here.
Unzip the file into the directory of your choice.
Modify the TATTLETALE_HOME/jboss-tattletale.properties file by adding ee6 to the "profiles"
profiles=java5, java6, ee6
Uncomment scan and reports in the properties file
Extract or unzip your application WAR file into a folder.
Open a terminal and navigate the extracted WAR's WEB-INF/classes/ directory.
Create a JAR containing all of the files in the WEB-INF/classes/ directory and place it in the WEB-INF/lib/ directory as shown in the next steps.
Open a terminal and navigate to the application's WEB-INF/classes/ directory.
Create a JAR in the WEB-INF/lib/ directory that contains all the files in the WEB-INF/classes/ directory by typing:
jar cvf ../lib/foo.jar *
Following the Tattletale documentation, create the TattleTale report by issuing the command:
java -jar TATTLETALE_HOME/tattletale.jar <application-directory>/WEB-INF/lib <output-directory>
In a browser, open the <output-directory>/index.html file and click on "Depends on" under Dependencies.
Fully qualified class names can be found in italics under the “Depends On” column.
The JAR containing that class will be located to its left under the “Archive” column.
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:
javax.xml.stream.XMLStreamException: ParseError at [row,col]:[5,5]
Message: Unexpected element 'class-loading' encountered
at org.jboss.metadata.parser.util.MetaDataElementParser.unexpectedElement(MetaDataElementParser.java:109)
at org.jboss.metadata.parser.jbossweb.JBossWebMetaDataParser.parse(JBossWebMetaDataParser.java:182)
at org.jboss.as.web.deployment.JBossWebParsingDeploymentProcessor.deploy(JBossWebParsingDeploymentProcessor.java:64)
... 5 more
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.
If you modify the MANIFEST.MF file, make sure to include a newline character at the end of the file.
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 File.
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.
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.
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.
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 the following:
First determine if there is an obvious module for the class
Navigate to the AS7_HOME/modules directory and look for the module path.
in this case, under modules, there is org/apache/commons/logging
Open the AS7_HOME/modules/org/apache/commons/logging/main/module.xml file and find the module name.
Add the module name to the Dependencies in the MANIFEST.MF file:
Dependencies: org.apache.commons.logging
If there is no obvious module path for the class
Find the archive that contains the class in the Tattletale report.
Find the module containing the JAR in the AS7_HOME/modules directory and determine the module name.
The module name to the Dependencies in the MANIFEST.MF file
Dependencies: org.dom4j,org.slf4j.jcl-over-slf4j
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]
Open a terminal and navigate to the EAP5_HOME/ directory.
Issue the command:
grep 'org.hibernate.validator.ClassValidator' `find . \-name '*.jar'`
You should see this (one of many) for the result: Binary file ./jboss-eap-5.1/seam/lib/hibernate-validator.jar matches
Copy this JAR to the application's lib/ directory.
Rebuild and redeploy the application
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.
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.
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:
<exclusions>
<module name="org.javassist" />
</exclusions>
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:
java.lang.ClassCastException: com.example1.Foo1 cannot be cast to com.example2.Foo2
In your code, print the class loader information by logging
logger.info("Class loader for foo1: " + com.example1.Foo1.getClass().getClassLoader().toString());
logger.info("Class loader for foo2: " + com.example2.Foo2.getClass().getClassLoader().toString());
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.
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.
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.
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. To resolve this issue, either rename the JAR or modify the context for the WAR in the application.xml file.
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.
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.
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.
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.
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:
<datasource jndi-name="java:/YourDatasourceName" pool-name="YourDatasourceName"
enabled="true" use-java-context="true">
<connection-url>jdbc:mysql://localhost:3306/YourApplicationURL</connection-url>
<driver-class> com.mysql.jdbc.Driver </driver-class>
<driver> mysql-connector-java-5.1.15.jar </driver>
<transaction-isolation> TRANSACTION_READ_COMMITTED </transaction-isolation>
<pool>
<min-pool-size> 200 </min-pool-size>
<max-pool-size> 300</max-pool-size>
<prefill> true </prefill>
<use-strict-min> false </use-strict-min>
</pool>
<security>
<user-name> USERID </user-name>
<password> PASSWORD</password>
</security>
<validation>
<validate-on-match> false </validate-on-match>
<background-validation> false </background-validation>
<useFastFail> false </useFastFail>
</validation>
<statement>
<prepared-statement-cache-size> 100 </prepared-statement-cache-size>
<share-prepared-statements/>
</statement>
</datasource>
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.
<driver name="mysql-connector-java-5.1.15.jar" module="com.mysql"/>
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.
<driver name="mysql-connector-java-5.1.15.jar" module="com.mysql">
<driver-class>com.mysql.jdbc.Driver</driver-class>
</driver>
For more information on how to add a MySQL driver, see Adding a MySQL datasource to JBoss AS 7.
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.
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.
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:
<?xml version="1.0" encoding="UTF-8"?>
<!--
~ JBoss, Home of Professional Open Source.
~ Copyright 2010, Red Hat, Inc., and individual contributors as indicated by the @author tags. See the copyright.txt file in the
~ distribution for a full listing of individual contributors.
~
~ This is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as
~ published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
~
~ This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
~
~ You should have received a copy of the GNU Lesser General Public License along with this software; if not, write to the Free
~ Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-->
<module xmlns="urn:jboss:module:1.0" name="com.mysql">
<resources>
<resource-root path="mysql-connector-java-5.1.15.jar"/>
</resources>
<dependencies>
<module name="javax.api"/>
</dependencies>
</module>
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.
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.
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.
In AS7 there is no possibility for custom JNDI names of EJB beans and it's not planned for 7.1.
Therefor the annotation @RemoteBindings and @LocalBindings are not available.
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:
Unqualified relative names like "DefaultDS" or "jdbc/DefaultDS"
should be qualified relative to "java:comp/env", "java:module/env", or
"java:jboss/env", depending on the context.
Unqualified "absolute" names like "/jdbc/DefaultDS" should be
qualified relative to a "java:jboss/root" name.
Qualified "absolute" names like "java:/jdbc/DefaultDS" should be
qualified the same way as #2.
The special "java:jboss" namespace is shared across the entire AS
server instance.
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.
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”.
private ProductManager productManager;
try {
context = new InitialContext();
productManager = (ProductManager) context.lookup("OrderManagerApp/ProductManagerBean/local");
}
catch(Exception lookupError) {
throw new ServletException("Unable to find the ProductManager bean", lookupError);
}
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”
@EJB(lookup=“java:app/OrderManagerEJB/ProductManagerBean!services.ejb.ProductManager") private ProductManager productManager;
(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 |
Java EE6 Tutorial - Portable JNDI Syntax
Application-specified Portable JNDI Names
TODO: complete this section
TODO: complete this section
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.
If you are using the old Apache/Jakarta Commons Logging, your API code will look something like the following:
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
private static Log log = LogFactory.getLog(MyClass.class.toString());
if (log.isTraceEnabled()) {
log.trace("Starting...");
}
To avoid a ClassNotFoundException, you will need to add a dependency for the module that contains those classes. The module name for Apache Commons Logging is "org.apache.commons.logging", so your MANIFEST.MF file will look like this:
Dependencies: org.apache.commons.logging
If you are creating a deployment which uses Apache Log4j, you must add a dependency on the appropriate module. The Log4j module is called "org.apache.log4j", so your MANIFEST.MF should look like this:
Dependencies: org.apache.log4j
If you are creating a deployment which uses SLF4J, you must add a dependency on the appropriate module. The Log4j module is called "org.slf4j", so your MANIFEST.MF should look like this:
Dependencies: org.slf4j
If your deployment uses JDK logging, no changes need to be made to your application.
If your deployment includes modules which use more than one logging framework, it is permissible to include multiple dependencies:
Dependencies: org.slf4j, org.apache.log4j, org.apache.commons.logging
To use the new framework, you will need the change your imports and code as follows to achieve the same results as above:
import org.jboss.logging.Level;
import org.jboss.logging.Logger;
private static final Logger logger = Logger.getLogger(MyClass.class.toString());
if(logger.isLoggable(Level.TRACE)) {
logger.log(Level.TRACE, "Starting...");
}
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.
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 your application uses Hibernate 3 classes that are not available in Hibernate 4, for example, some of the validator or search classes, you may see ClassNotFoundExceptions when you deploy your application. If you encounter this problem, you can try one of two approaches:
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.
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.
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.
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:
"count" and "count distinct" projections now return a Long value (due to changes in CountProjection, Projections.rowCount(), Projections.count( propertyName ), and Projections.countDistinct( propertyName )).
"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.
for properties mapped as Long, Short, Integer, or primitive integer types, a Long value is returned;
for properties mapped as Float, Double, or primitive floating point types, a Double value is returned.
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
The namespaces for the Hibernate DTD files have changed.
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.
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.
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 second level cache. These examples assume you are using JPA.
Here's an example of the persistence.xml file in EAP 5.1:
<property name="hibernate.cache.region.factory_class"
value="org.hibernate.cache.jbc2.JndiMultiplexedJBossCacheRegionFactory"/>
<property name="hibernate.cache.region.jbc2.cachefactory" value="java:CacheManager"/>
<property name="hibernate.cache.use_second_level_cache" value="true"/>
<property name="hibernate.cache.use_minimal_puts" value="true"/>
<property name="hibernate.cache.region.jbc2.cfg.entity" value="mvcc-entity"/>
<property name="hibernate.cache.region_prefix" value="services"/>
Here is what is needed to configure the same thing for a JPA application using Infinispan with AS7:
<property name="hibernate.cache.use_second_level_cache" value="true"/> <property name="hibernate.cache.use_minimal_puts" value="true"/>
Here is what is needed to configure the same thing for a native Hibernate application using Infinispan with AS7:
<property name="hibernate.cache.region.factory_class"
value="org.hibernate.cache.infinispan.JndiInfinispanRegionFactory"/>
<property name="hibernate.cache.infinispan.cachemanager"
value="java:jboss/infinispan/hibernate"/>
<property name="hibernate.transaction.manager_lookup_class"
value="org.hibernate.transaction.JBossTransactionManagerLookup"/>
<property name="hibernate.cache.use_second_level_cache" value="true"/>
<property name="hibernate.cache.use_minimal_puts" value="true"/>
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
Infinispan
Using Infinspan as JPA/Hibernate Second Level Cache Provider
HIBERNATE - RelationalPersistence for Idiomatic Java
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"> |
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.
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.
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:
@ApplicationPath("/mypath")
public class MyApplication extends Application {
}
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:
public class MyApplication extends Application {
}
<servlet-mapping> <servlet-name>com.acme.MyApplication</servlet-name> <url-pattern>/hello/*</url-pattern> </servlet-mapping>
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:
<servlet-mapping> <servlet-name>javax.ws.rs.core.Application</servlet-name> <url-pattern>/hello/*</url-pattern> </servlet-mapping>
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.
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.
Shut down the client and server.
Make a backup of any JBoss Messaging data.
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 server. JBoss Messaging stores these files in a file called connection-factories-service.xml in the deployment directory of your application server.
Destination service configurations - these files contain JMS queues and topics deployed with JBoss Messaging server. By default, these are stored in a file called destinations-service.xml in the deployment directory of your application server.
Message bridge service configurations - these files contain bridge services deployed with JBoss Messaging server. No bridges are deployed by default, so the name of the deployment file will vary, depending on your JBoss Messaging installation.
Refer to Messaging configuration for details on HornetQ configurations.
If the application code uses standard JMS, no code changes are required.
If the application code uses features specific to JBoss Messaging, modify the code to use equivalent features available in HornetQ.
JBoss Messaging uses a Managed Bean service to configure bridges and JMS objects such as connection factories, queues, and topics. HornetQ uses a POJO (Plain Old Java Object) to configure these objects instead. Update any configuration parameters to use equivalent parameters in HornetQ.
Move any messages in the JBoss Messaging database to HornetQ bindings.
For more information on HornetQ, see HornetQ Project Documentation and the HornetQ homepage.
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.
<server-groups>
<server-group name="main-server-group" profile="ha">
<jvm name="default">
<heap size="64m" max-size="512m"/>
</jvm>
<socket-binding-group ref="ha-sockets"/>
</server-group>
</server-group>
To enable clustering for standalone servers, start the server using the appropriate configuration file:
$ ./bin/standalone.sh --server-config=standalone-ha.xml
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.
<interfaces>
<interface name="management">
<inet-address value="192.168.0.2"/>
</interface>
<interface name="public">
<inet-address value="192.168.0.2"/>
</interface>
</interfaces>
<socket-binding-groups>
<socket-binding-group name="ha-sockets" default-interface="public">
<!-- ... -->
</socket-binding-group>
</socket-binding-groups>
In the example above, the "public" interface is specified as the default interface for all sockets within the "ha-sockets" socket binding group.
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.
<subsystem xmlns="urn:jboss:domain:jgroups:1.0" default-stack="udp">
<stack name="udp">
<transport type="UDP" socket-binding="jgroups-udp"/>
<!-- ... -->
</stack>
</subsystem>
<socket-binding-groups>
<socket-binding-group name="ha-sockets" default-interface="public">
<!-- ... -->
<socket-binding name="jgroups-udp" port="55200" multicast-address="228.11.11.11" multicast-port="45688"/>
<!-- ... -->
</socket-binding-group>
</socket-binding-groups>
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.
<subsystem xmlns="urn:jboss:domain:jgroups:1.0" default-stack="udp">
<stack name="udp">
<!-- ... -->
</stack>
</subsystem>
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.
TODO: complete this section
TODO: complete this section
EJB 2.x support is not available in AS 7.0 but should be implemented in AS 7.1.
ToDo: Conplete this section
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.
Some Seam 2 examples use a default JDBC datasource named java:/DefaultDS. 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 :
<datasource jndi-name="java:/DefaultDS" pool-name="DefaultDS_Pool" enabled="true" jta="true" use-java-context="true" use-ccm="true">
<connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
<driver>h2</driver>
<security>
<user-name>sa</user-name>
<password>sa</password>
</security>
</datasource>
This definition is a copy of the default HSQL datasource defined in JBoss AS 7.
You can also add the datasource using the jboss-admin command line interface:
$ <jboss-as7>/bin/jbossadmin.sh --connect [standalone@localhost:9999 /] add-data-source --jndi-name=java:/DefaultDS --connection-url=jdbc:h2:mem:test;DB_CLOSE_DELAY=-1 --username=sa --password=sa --pool-name=DefaultDS_pool --driver-name=h2
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:
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0">
<deployment>
<dependencies>
<module name="javax.faces.api" slot="1.2" export="true"/>
<module name="com.sun.jsf-impl" slot="1.2" export="true"/>
</ dependencies>
</deployment>
<sub-deployment name="jboss-seam-booking.war">
<exclusions>
<module name="javax.faces.api" slot="main"/>
<module name="com.sun.jsf-impl" slot="main"/>
</exclusions>
<dependencies>
<module name="javax.faces.api" slot="1.2"/>
<module name="com.sun.jsf-impl" slot="1.2"/>
</dependencies>
</sub-deployment>
</jboss-deployment-structure>
If your application uses any third-party logging frameworks you will need add dependencies as described in that section of the migration guide.
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
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0">
<deployment>
<exclusions>
<module name="org.hibernate"/>
</exclusions>
<deployment>
</jboss-deployment-structure>
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.
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"/> -->
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
Add jboss-deployment-structure.xml to jboss-seam-jpa.war/WEB-INF/ with the following content in it:
<jboss-deployment-structure>
<deployment>
<exclusions>
<module name="javax.faces.api" slot="main"/>
<module name="com.sun.jsf-impl" slot="main"/>
</exclusions>
<dependencies>
<module name="org.apache.log4j" />
<module name="org.dom4j" />
<module name="org.apache.commons.logging" />
<module name="org.apache.commons.collections" />
<module name="javax.faces.api" slot="1.2"/>
<module name="com.sun.jsf-impl" slot="1.2"/>
</dependencies>
</deployment>
</jboss-deployment-structure>
|
Creator |
Comment |
|
|||
|
XML File jboss-deployment-structure.xml |
0.6 kB |
Jul 18, 2011 10:50 |
jboss-deployment-structure.xml for Seam 2 JPA example migration |
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.
First, you will need to replace the existing core-init element as follows:
<!-- <core:init jndi-pattern="jboss-seam-booking/#{ejbName}/local" debug="true" distributable="false"/> -->
<core:init debug="true" distributable="false"/>
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
For each JNDI binding INFO message in the log, add a matching component element to the components.xml file:
<component class="org.jboss.seam.example.booking.AuthenticatorAction" jndi-name="java:app/jboss-seam-booking.jar/AuthenticatorAction" />
ToDo: Complete this section
For information on how to migrate Spring applications, see details at the Spring applications development and migration guide.
This chapter details the extensions that are available when developing Enterprise Java Beans tm on JBoss Application Server 7.
Currently there is no support for configuring the extensions using an implementation specific descriptor file.
Each Message Driven Bean must be connected to a resource adapter.
The ResourceAdapter annotation is used to specify the resource adapter with which the MDB should connect.
The value of the annotation is the name of the deployment unit containing the resource adapter. For example jms-ra.rar.
For example:
@MessageDriven(messageListenerInterface = PostmanPat.class)
@ResourceAdapter("ejb3-rar.rar")
Whenever a run-as role is specified for a given method invocation the default anonymous principal is used as the caller principal. This principal can be overridden by specifying a run-as principal.
The RunAsPrincipal annotation is used to specify the run-as principal to use for a given method invocation.
The value of the annotation specifies the name of the principal to use. The actual type of the principal is undefined and should not be relied upon.
Using this annotation without specifying a run-as role is considered an error.
For example:
@RunAs("admin")
@RunAsPrincipal("MyBean")
Each Enterprise Java Bean tm can be associated with a security domain. Only when an EJB is associated with a security domain will authentication and authorization be enforced.
The SecurityDomain annotation is used to specify the security domain to associate with the EJB.
The value of the annotation is the name of the security domain to be used.
For example:
@SecurityDomain("other")
For any newly started transaction a transaction timeout can be specified in seconds.
When a transaction timeout of 0 is used, then the actual transaction timeout will default to the domain configured default.
TODO: add link to tx subsystem
Although this is only applicable when using transaction attribute REQUIRED or REQUIRES_NEW the application server will not detect invalid setups.
Take care that even when transaction attribute REQUIRED is specified, the timeout will only be applicable if a new transaction is started.
The TransactionTimeout annotation is used to specify the transaction timeout for a given method.
The value of the annotation is the timeout used in the given unit granularity. It must be a positive integer or 0. Whenever 0 is specified the default domain configured timeout is used.
The unit specifies the granularity of the value. The actual value used is converted to seconds. Specifying a granularity lower than SECONDS is considered an error, even when the computed value will result in an even amount of seconds.
For example:
@TransactionTimeout(value = 10, unit = TimeUnit.SECONDS)
The trans-timeout element is used to define the transaction timeout for business, home, component, and message-listener interface methods; no-interface view methods; web service endpoint methods; and timeout callback methods.
The trans-timeout element resides in the urn:trans-timeout namespace and is part of the standard container-transaction element as defined in the jboss namespace.
For the rules when a container-transaction is applicable please refer to EJB 3.1 FR 13.3.7.2.1.
<jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:tx="urn:trans-timeout"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-ejb3-2_0.xsd
http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd
urn:trans-timeout http://www.jboss.org/j2ee/schema/trans-timeout-1_0.xsd"
version="3.1"
impl-version="2.0">
<assembly-descriptor>
<container-transaction>
<method>
<ejb-name>BeanWithTimeoutValue</ejb-name>
<method-name>*</method-name>
<method-intf>Local</method-intf>
</method>
<tx:trans-timeout>
<tx:timeout>10</tx:timeout>
<tx:unit>Seconds</tx:unit>
</tx:trans-timeout>
</container-transaction>
</assembly-descriptor>
</jboss:ejb-jar>
The JBoss Application Server JPA subsystem implements the JPA 2.0 container-managed requirements. Deploys the persistence unit definitions, the persistence unit/context annotations and persistence unit/context references in the deployment descriptor. JPA Applications use the Hibernate (core) 4.0 persistence provider, that is included with JBoss AS. The JPA subsystem uses the standard SPI (javax.persistence.spi.PersistenceProvider) to access the Hibernate persistence provider and some additional extensions as well.
During application deployment, JPA use is detected (e.g. persistence.xml or @PersistenceContext/Unit annotations) and injects Hibernate dependencies into the application deployment. This makes it easy to deploy JPA applications.
In the remainder of this documentation, ”entity manager” refers to an instance of the javax.persistence.EntityManager class. Javadoc for the JPA interfaces http://download.oracle.com/javaee/6/api/javax/persistence/package-summary.html and JPA 2.0 specification. The Hibernate documentation (work in progress) will describe the JPA 2.0 entity manager in greater detail (devguide will be here).
The entity manager is similar to the Hibernate Session class; applications use it to create/read/update/delete data (and related operations). Applications can use application-managed or container-managed entity managers. Keep in mind that the entity manager is not expected to be thread safe (don't inject it into a servlet class variable which is visible to multiple threads).
Application-managed entity managers provide direct access to the underlying persistence provider (org.hibernate.ejb.HibernatePersistence). The scope of the application-managed entity manager is from when the application creates it and lasts until the app closes it. Use the @PersistenceUnit annotation to inject a persistence unit into a javax.persistence.EntityManagerFactory. The EntityManagerFactory can return an application-managed entity manager.
Container-managed entity managers auto-magically manage the underlying persistence provider for the application. Container-managed entity managers may use transaction-scoped persistence contexts or extended persistence contexts. The container-managed entity manager will create instances of the underlying persistence provider as needed. Every time that a new underlying persistence provider (org.hibernate.ejb.HibernatePersistence) instance is created, a new persistence context is also created (as an implementation detail of the underlying persistence provider).
The JPA persistence context contains the entities managed by the persistence provider. The persistence context acts like a first level (transactional) cache for interacting with the datasource. Loaded entities are placed into the persistence context before being returned to the application. Entities changes are also placed into the persistence context (to be saved in the database when the transaction commits).
The transaction-scoped persistence context coordinates with the (active) JTA transaction. When the transaction commits, the persistence context is flushed to the datasource (entity objects are detached but may still be referenced by application code). All entity changes that are expected to be saved to the datasource, must be made during a transaction. Entities read outside of a transaction will be detached immediately (since there is no transaction to coordinate with). Example transaction-scoped persistence context is below.
@Stateful // will use container managed transactions
public class CustomerManager {
@PersistenceContext(unitName = "customerPU") // default type is PersistenceContextType.TRANSACTION
EntityManager em;
public customer createCustomer(String name, String address) {
Customer customer = new Customer(name, address);
em.persist(customer); // persist new Customer when JTA transaction completes (when method ends).
// internally:
// 1. Look for existing "customerPU" persistence context in active JTA transaction and use if found.
// 2. Else create new "customerPU" persistence context (e.g. instance of org.hibernate.ejb.HibernatePersistence)
// and put in current active JTA transaction.
return customer; // return Customer entity (will be detached from the persistence context when caller gets control)
} // Transaction.commit will be called, Customer entity will be persisted to the database and "customerPU" persistence context closed
The Container-managed extended persistence context can span multiple transactions and allows data modifications to be queued up (like a shopping cart), without an active JTA transaction (to be applied during the next JTA TX). The Container-managed extended persistence context can only be injected into a stateful session bean.
@PersistenceContext(type = PersistenceContextType.EXTENDED, unitName = "inventoryPU") EntityManager em;
JPA 2.0 makes it easy to use your (pojo) plain old Java class to represent a database table row.
@PersistenceContext EntityManager em;
Integer bomPk = getIndexKeyValue();
BillOfMaterials bom = em.find(BillOfMaterials.class, bomPk); // read existing table row into BillOfMaterials class
BillOfMaterials createdBom = new BillOfMaterials("..."); // create new entity
em.persist(createdBom); // createdBom is now managed and will be saved to database when the current JTA transaction completes
The entity lifecycle is managed by the underlying persistence provider.
New (transient): an entity is new if it has just been instantiated using the new operator, and it is not associated with a persistence context. It has no persistent representation in the database and no identifier value has been assigned.
Managed (persistent): a managed entity instance is an instance with a persistent identity that is currently associated with a persistence context.
Detached: the entity instance is an instance with a persistent identity that is no longer associated with a persistence context, usually because the persistence context was closed or the instance was evicted from the context.
Removed: a removed entity instance is an instance with a persistent identity, associated with a persistence context, but scheduled for removal from the database.
The persistence.xml contains the persistence unit configuration (e.g. datasource name) and as described in the JPA 2.0 spec (section 8.2), the jar file or directory whose META-INF directory contains the persistence.xml file is termed the root of the persistence unit. In Java EE environments, the root of a persistence unit must be one of the following:
"
an EJB-JAR file
the WEB-INF/classes directory of a WAR file
a jar file in the WEB-INF/lib directory of a WAR file
a jar file in the EAR library directory
an application client jar file
The persistence.xml can specify either a JTA datasource or a non-JTA datasource. The JTA datasource is expected to be used within the EE environment (even when reading data without an active transaction). If a datasource is not specified, the default-datasource will instead be used (must be configured).
NOTE: Java Persistence 1.0 supported use of a jar file in the root of the EAR as the root of a persistence unit. This use is no longer supported. Portable applications should use the EAR library directory for this case instead.
"
Question: Can you have a EAR/META-INF/persistence.xml?
Answer: No, the above may deploy but it could include other archives also in the EAR, so you may have deployment issues for other reasons. Better to put the persistence.xml in an EAR/lib/somePuJar.jar.
The “org.jboss.as.jpa” logging can be enabled to get the following information:
INFO - when persistence.xml has been parsed, starting of persistence unit service (per deployed persistence.xml), stopping of persistence unit service
DEBUG - informs about entity managers being injected, creating/reusing transaction scoped entity manager for active transaction
TRACE - shows how long each entity manager operation took in milliseconds, application searches for a persistence unit, parsing of persistence.xml
To enable TRACE, open the as/standalone/configuration/standalone.xml (or as/domain/configuration/domain.xml) file. Search for <subsystem xmlns="urn:jboss:domain:logging:1.0"> and add the org.jboss.as.jpa category :
<subsystem xmlns="urn:jboss:domain:logging:1.0">
<console-handler name="CONSOLE">
<level name="TRACE" />
...
</console-handler>
<periodic-rotating-file-handler name="FILE">
<level name="TRACE" />
.
.
</periodic-rotating-file-handler>
<logger category="com.arjuna">
<level name="WARN" />
</logger>
<logger category="org.jboss.as.jpa">
<level name="TRACE" />
</logger>
<logger category="org.apache.tomcat.util.modeler">
<level name="WARN" />
</logger>
...
Hibernate 4 is packaged with the AS and is the default persistence provider.
AS 7.0.1 allows the packaging of Hibernate 3.5 (or greater) persistence provider jars with the application. The JPA deployer will detect the presence of a persistence provider in the application and jboss.as.jpa.providerModule needs to be set to hibernate3-bundled.
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
<persistence-unit name="plannerdatasource_pu">
<description>Hibernate 3 Persistence Unit.</description>
<jta-data-source>java:jboss/datasources/PlannerDS</jta-data-source>
<properties>
<property name="hibernate.show_sql" value="false" />
<property name="jboss.as.jpa.providerModule" value="hibernate3-bundled" />
</properties>
</persistence-unit>
</persistence>
The AS7 testsuite contains a test that packages jars from the Hibernate 3.6.5.Final jars (hibernate3-core.jar, hibernate3-commons-annotations.jar, hibernate3-entitymanager.jar, dom4j.jar, slf4j.jar, slf4j-api.jar, commons-collections.jar, antlr.jar) in the ear lib.
Applications can share the same Hibernate3 (for Hibernate 3.5 or greater) persistence provider by manually creating an org.hibernate:3 module (in the AS/modules folder). Steps to create the Hibernate3 module:
In a command shell, go to the AS installation and change into the modules/org folder.
cd AS/modules/org or cd AS\modules\org\hibernate
Create folder for slot 3 to hold Hibernate 3
mkdir 3
cd 3
Copy the Hibernate3 jars into this new AS/modules/org/hibernate/3 folder
(hibernate3-core.jar, hibernate3-commons-annotations.jar, hibernate3-entitymanager.jar, dom4j.jar, slf4j.jar, slf4j-api.jar, commons-collections.jar, antlr.jar, slf4j-api.jar, commons-collections.jar, antlr.jar and any other jar needed for Hibernate 3).
Create the AS/modules/org/hibernate/3/module.xml file with contents:
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="org.hibernate" slot="3">
<resources>
<resource-root path="hibernate3-core.jar"/>
<resource-root path="hibernate3-commons-annotations.jar"/>
<resource-root path="hibernate3-entitymanager.jar"/>
<resource-root path="javassist-3.12.0.GA.jar"/>
<resource-root path="antlr-2.7.6.jar"/>
<resource-root path="commons-collections-3.1.jar"/>
<resource-root path="dom4j-1.6.1.jar"/>
<!-- Insert other Hibernate 3 jars to be used here -->
</resources>
<dependencies>
<module name="org.jboss.as.jpa.hibernate" slot="3"/>
<module name="asm.asm"/>
<module name="javax.api"/>
<module name="javax.persistence.api"/>
<module name="javax.transaction.api"/>
<module name="javax.validation.api"/>
<module name="org.apache.ant"/>
<module name="org.infinispan"/>
<module name="org.javassist"/>
<module name="org.slf4j"/>
</dependencies>
</module>
In your persistence.xml, you will refer to the Hibernate 3 persistence provider as follows:
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
<persistence-unit name="crm_pu">
<description>CRM Persistence Unit.</description>
<jta-data-source>java:jboss/datasources/CRMDS</jta-data-source>
<properties>
<property name="jboss.as.jpa.providerModule" value="org.hibernate:3" />
</properties>
</persistence-unit>
</persistence>
The static Hibernate 4.x (modules/org/hibernate/main) jars take precedence over the Hibernate 4.x jars that are packaged with your application. You can package Hibernate 3 jars because there is no conflict with the Hibernate 4.x jars in the modules/org.hibernate/main folder. Instead of packaging Hibernate 4.x jars with the application, update the shared Hibernate 4.x jars in the modules/org.hibernate/main folder as mentioned below.
To update from Hibernate 4.0.1.Final which is bundled with AS to Hibernate 4.1.0.Final, download the 4.1.0.Final package from sourceforge, which contains all the jars required for update. Extract the archive and copy hibernate-core-4.1.0.Final.jar and hibernate-entitymanager-4.1.0.Final.jar to modules/org/hibernate/main directory and update the following entries
<resources> ... <resource-root path="hibernate-core-4.0.1.Final.jar"/> <resource-root path="hibernate-entitymanager-4.0.1.Final.jar"/> ... </resources>
in the module.xml
<resources> ... <resource-root path="hibernate-core-4.1.0.Final.jar"/> <resource-root path="hibernate-entitymanager-4.1.0.Final.jar"/> ... </resources>
it is also required to update the hibernate-infinispan module by copying the hibernate-infinispan-4.1.0.Final.jar to modules/org/hibernate/infinispan/main and the hibernate-envers-4.1.0.Final.jar to modules/org/hibernate/envers/main and updating the module.xml for both modules accordingly.
This is a work in progress. A project to build integration for persistence providers like EclipseLink, is here. It looks like help from the EclipseLink community, would be helpful (in adding AS7 support to EclipseLink or suggesting how existing builds of EclipseLink could be used). EclipseLink contains integration classes for each of the different runtime environments (like earlier versions of JBoss AS). We also need to fix the AS7 persistence unit temp class path.
Integration code for other persistence providers can also be added to the jpa-modules project. Note that the project is in its very early stages and you need to build AS7 locally on the same machine (so that the snapshot versions of the AS7 JPA SPI jars will be available). Also note that the AS7 JPA SPI is likely to evolve a bit as we add additional integration modules. It will stabilize more when we have integrated persistence providers from three different sources (We already have Hibernate integrated, so that is one of three needed).
If your interested in helping integrate AS7 with other persistence providers, please find Scott Marlow on IRC (irc://irc.freenode.org/jboss-as7) or send email to [].
Applications that use the Hibernate API directly, are referred to here as native Hibernate applications. Native Hibernate applications, can choose to use the Hibernate jars included with JBoss AS or they can package their own copy of the Hibernate jars. Applications that utilize JPA will automatically have the JBoss AS Hibernate injected onto the application deployment classpath. Meaning that JPA applications, should expect to use the Hibernate jars included in JBoss AS.
Example MANIFEST.MF entry to add Hibernate dependency:
Manifest-Version: 1.0 ... Dependencies: org.hibernate
You can inject a org.hibernate.Session and org.hibernate.SessionFactory directly, just as you can do with EntityManagers and EntityManagerFactorys.
import org.hibernate.Session;
import org.hibernate.SessionFactory;
@Stateful public class MyStatefulBean ... {
@PersistenceContext(unitName="crm") Session session1;
@PersistenceContext(unitName="crm2", type=EXTENDED) Session extendedpc;
@PersistenceUnit(unitName="crm") SessionFactory factory;
}
The following properties are supported in the persistence unit definition (in the persistence.xml file):
|
Property |
Purpose |
|
jboss.as.jpa.providerModule |
is the name of the persistence provider module (default is org.hibernate). Should be hibernate3-bundled if Hibernate 3 jars are in the application archive (adapterModule and adapterClass will automatically be set for hibernate3-bundled). |
|
jboss.as.jpa.adapterModule |
is the name of the integration classes that help the AS to work with the persistence provider. Current valid values are org.jboss.as.jpa.hibernate:4 (Hibernate 4 integration classes) and org.jboss.as.jpa.hibernate:3 (Hibernate 3 integration classes). Other integration adapter modules are expected to be added. |
|
jboss.as.jpa.adapterClass |
is the class name of the integration adapter. Current valid values are org.jboss.as.jpa.hibernate3.HibernatePersistenceProviderAdaptor and org.jboss.as.jpa.hibernate4.HibernatePersistenceProviderAdaptor. |
Many thanks to the community, for reporting issues, solutions and code changes. A number of people have been answering AS7 forum questions related to JPA usage. I would like to thank them for this, as well as those reporting issues. For those of you that haven't downloaded the AS source code and started hacking patches together. I would like to encourage you to start by reading Hacking on AS7. You will find that it easy very easy to find your way around the AS7/JPA/* source tree and make changes. The following list of contributors should grow over time, I hope to see more of you listed here.
Steve Ebersole (lead of the Hibernate project)
Stuart Douglas (lead of the Seam Persistence project, AS7 project team member/committer)
Jaikiran Pai (Active member of JBoss forums and JBoss EJB3 project team member)
Strong Liu (leads the productization effort of Hibernate in the EAP product)
Scott Marlow (lead of the AS7 JPA sub-project)
The OSGi Developer Guide can be found here: OSGi User and Developer Guide.
This document details the main points that need to be considered by Spring developers that wish to develop new applications or to migrate existing applications to be run into JBoss Application Server 7 (AS7).
AS7 has a modular class loading strategy, different from previous versions of JBoss AS, which enforces a better class loading isolation between deployments and the application server itself. A detailed description can be found in the documentation dedicated to class loading in AS7.
This reduces significantly the risk of running into a class loading conflict and allows applications to package their own dependencies if they choose to do so. This makes it easier for Spring applications that package their own dependencies - such as logging frameworks or persistence providers to run on JBoss AS.
At the same time, this does not mean that duplications and conflicts cannot exist on the classpath. Some module dependencies are implicit, depending on the type of deployment as shown here.
Depending on the strategy being used, Spring applications can be:
native Hibernate applications;
JPA-based applications;
native JDBC applications;
Applications that use the Hibernate API directly with Spring (i.e. through either one of LocalSessionFactoryBean or AnnotationSessionFactoryBean) may use a version of Hibernate 3 packaged inside the application. Hibernate 4 (which is provided through the 'org.hibernate' module of AS7) is not supported by Spring 3.0 and Spring 3.1 (and may be supported by Spring 3.2 as described in SPR-8096), so adding this module as a dependency is not a solution.
Spring applications using JPA may choose between:
using a server-deployed persistence unit;
using a Spring-managed persistence unit.
Applications that use a server-deployed persistence unit must observe the typical Java EE rules in what concerns dependency management, i.e. the javax.persistence classes and persistence provider (Hibernate) are contained in modules which are added automatically by the application when the persistence unit is deployed.
In order to use the server-deployed persistence units from within Spring, either the persistence context or the persistence unit need to be registered in JNDI via web.xml as follows:
<persistence-context-ref>
<persistence-context-ref-name>persistence/petclinic-em</persistence-context-ref-name>
<persistence-unit-name>petclinic</persistence-unit-name>
</persistence-context-ref>
or, respectively:
<persistence-unit-ref> <persistence-unit-ref-name>persistence/petclinic-emf</persistence-unit-ref-name> <persistence-unit-name>petclinic</persistence-unit-name><persistence-unit-ref> <persistence-unit-ref-name>persistence/petclinic-emf</persistence-unit-ref-name> <persistence-unit-name>petclinic</persistence-unit-name> </persistence-unit-ref> </persistence-unit-ref>
When doing so, the persistence context or persistence unit are available to be looked up in JNDI, as follows:
<jee:jndi-lookup id="entityManager" jndi-name="java:comp/env/persistence/petclinic-em"
expected-type="javax.persistence.EntityManager"/>
or
<jee:jndi-lookup id="entityManagerFactory" jndi-name="java:comp/env/persistence/petclinic-emf"
expected-type="javax.persistence.EntityManagerFactory"/>
JNDI binding via persistence.xml properties is not supported in JBoss AS 7.0
Spring applications running in JBoss AS7 may also create persistence units on their own, using the LocalContainerEntityManagerFactoryBean. This is what these applications need to consider:
When the application server encounters a deployment that has a file named META-INF/persistence.xml (or, for that matter, WEB-INF/classes/META-INF/persistence.xml), it will attempt to create a persistence unit based on what is provided in the file. In most cases, such definition files are not compliant with the Java EE requirements, mostly because required elements such as the datasource of the persistence unit are supposed to be provided by the Spring context definitions, which will fail the deployment of the persistence unit, and consequently of the entire deployment.
Spring applications can easily avoid this type of conflict, by using a feature of the LocalContainerEntityManagerFactoryBean which is designed for this purpose. Persistence unit definition files can exist in other locations than META-INF/persistence.xml and the location can be indicated through the persistenceXmlLocation property of the factory bean class.
Assuming that the persistence unit is in the META-INF/jpa-persistence.xml, the corresponding definition can be:
<bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"> <property name="persistenceXmlLocation" value="classpath*:META-INF/jpa-persistence.xml"/> <!-- other definitions --> </bean>
Since the LocalContainerEntityManagerFactoryBean and the corresponding HibernateJpaVendorAdapter are based on Hibernate 3, it is required to use that version with the application. Therefore, the Hibernate 3 jars must be included in the deployment. At the same time, due the presence of @PersistenceUnit or @PersistenceContext annotations on the application classes, the application server will automatically add the 'org.hibernate' module as a dependency.
This can be avoided by instructing the server to exclude the module from the deployment's list of dependencies. In order to do so, include a META-INF/jboss-deployment-structure.xml or, for web applications, WEB-INF/jboss-deployment-structure.xml with the following content:
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0">
<deployment>
<exclusions>
<module name="org.hibernate"/>
</exclusions>
</deployment>
</jboss-deployment-structure>
There are several guides in the JBoss Application Server 7 documentation series. This list gives an overview of each of the guides:
*Getting Started Guide - Explains how to download and start JBoss Application Server 7.
*Getting Started Developing Applications Guide - Talks you through developing your first applications on JBoss Application Server 7, and introduces you to JBoss Tools and how to deploy your applications.
*JavaEE 6 Tutorial - A Java EE 6 Tutorial.
*Admin Guide - Tells you how to configure and manage your JBoss Application Server 7 instances.
*Developer Guide - Contains concepts that you need to be aware of when developing applications for JBoss Application Server 7. Classloading is explained in depth.
*High Availability Guide - Reference guide for how to set up clustered JBoss Application Server 7 instances.
*Extending JBoss AS 7 - A guide to adding new functionality to JBoss Application Server 7.