The JBoss Application Server (JBoss AS) 4.0 is a production-ready Java 2 Enterprise Edition (J2EE) application server. It is the first officially certified J2EE 1.4-compliant application server in the industry, providing full support for J2EE Web Services and the Service Oriented Architecture (SOA). Beyond the standard J2EE, JBoss AS also supports next generation middleware technologies, including Aspect-Oriented Programming (AOP) with JBoss AOP, Object-Relational data persistence with Hibernate, and clustering support with JGroups and JBoss Cache. To see a comprehensive list of new features in JBoss AS 4.0, please refer to the "What's new in JBoss AS 4.0" document.
Upgrading your servers to JBoss 4.0 allows you to take advantage of new features in J2EE 1.4 as well as Open Source innovations, such as JBoss AOP, Hibernate and JBoss Cache, from the JBoss community. For most users who are already deploying JBoss AS 3.2.x, the upgrading process should be smooth with little or no tweaking of your applications. In this document, we discuss common problems and pitfalls our users have encountered in their upgrading efforts.
JBoss AS 4.0 requires JDK 1.4 or higher to run. A known issues exists in Sun's JDK 1.4.2_05, which results in a "Real-time signal 28" error at server shutdown. The incomplete shutdown could cause problems at next start-up. You should use JDK 1.4.2_06 and later if possible. If you run JBoss AS on Solaris or Suse Linux operating systems, there are also two known issues with specific versions of those operating systems.
The most common JBoss AS 4.0 upgrading problems arise from the user's mis-understanding of how class loaders work in JBoss AS 4.0's default server configurations. This problem is especially confusing in JBoss AS 4.0.0. The symptom of this problem is that a JBoss AS 3.2.x application throws the NoClassFoundException or other exceptions indicating missing or conflicting resources, when it deployed in JBoss AS 4.0.0. If you are interested in learning more on how the JBoss ClassLoader works, please check out this wiki item: http://www.jboss.org/wiki/Wiki.jsp?page=JBossClassLoadingUseCases.
The reason is that the default configuration in JBoss AS 4.0.0 uses a scoped class loader, which compartmentalizes each deployed application, in order to conform to the J2EE 1.4 certification requirements. However, in JBoss AS 3.2.x, the class loader in the default configuration allows different deployment packages to share classes and resources. The shared class loader has better performance and is used by most existing JBoss AS 3.2.x applications. In JBoss AS 4.0.0, the shared class loader configuration is the standard configuration. So, the first step to diagnose class loader problems is to deploy your application in the deploy/standard directory and start JBoss AS 4.0.0 in the standard configuration using the following command.
run -c standard
In addition to the class loader problems, there are also other side-effects associated with the name change of the default configuration in JBoss 4.0.0. For instance, the service binding manager is available in the standard configuration but not in the default configuration in JBoss AS 4.0.0.
In JBoss AS 4.0.1, we tried to reduce the confusion by eliminating the standard configuration and use the shared class loader again for the default configuration. To configure a J2EE certified configuration in JBoss 4.0.1, please refer to the "What's New in JBoss AS 4.0" document. So, your JBoss 3.2.x application should run fine in the default configuration of JBoss AS 4.0.1 but your JBoss AS 4.0.0 applications may not be.
If you customize the JBoss AS's default configurations and libraries, there are also things to look out for.
If your JBoss applications must be started in a particular order to function correctly, there is a slight chance that they might be affected by the upgrade to JBoss AS 4.0.
If you put a deployment in the META-INF directory (e.g. a META-INF/some-service.xml in an EJB jar file), it is not deployed in JBoss AS 4.0. This did work in JBoss AS 3.2.x, but it was not the intended behavior. The META-INF directory is reserved for information about the current deployment. If you want to make a subdeployment (for those archives that support simple Russian Doll packaging), place it in the root of the parent deployment. To add a -service.xml or other non j2ee deployment to an EAR, you need to reference it from the META-INF/jboss-app.xml in a service element. To learn more on this subject, please refer to the wiki item: http://www.jboss.org/wiki/Wiki.jsp?page=JBoss4FAQ.
From JBoss AS 3.2.x to JBoss AS 4.0, a rather significant change has been made to the resource adaptor descriptor in order to accommodate the needs of JCA 1.5, which is part of J2EE 1.4. While you can still deploy JBoss AS 3.2.x rar files in JBoss AS 4.0, you will need to revise your JBoss AS 3.2.x resource adaptor descriptors to migrate to JBoss AS 4.0.
To deploy a resource adaptor in JBoss is a two step process: First, take your standard rar deployment file (either as a standalone deployment or part of another deployment like an ear) and place it in the deploy directory. Then, you need a JBoss AS specific -ds.xml file in the deploy directory, which actually deploys the ConnectionFactory from the rar deployment, configuring the pool, JNDI name and other parameters. In essence, the rar archive acts as a template for the connection factory deployment in the ds.xml.
In JBoss AS 3.2.x, the adapter-display-name value in the ds.xml file must match the display-name value from the ra.xml file inside the rar archive. However, in JBoss AS 4.0, the adapter-display-name is no longer used. Instead, the rar-name and connection-definition elements are used to support multiple connection factories (i.e., connection-definitions). The following example shows how to define a connection factory from a rar file inside a ear file.
<tx-connection-factory>
...
<rar-name>myapplication.ear#jms-ra.rar</rar-name>
<connection-definition>
org.jboss.resource.adapter.jms.JmsConnectionFactory
</connection-definition>
...
</tx-connection-factory>To learn more about resource adapters in JBoss AS, please check out this wiki item: http://www.jboss.org/wiki/Wiki.jsp?page=HowDoIDeployMyResourceAdapter.
Significant changes have been made in the Web Services module from JBoss AS 3.2.x to 4.0. In JBoss 4.0, the JBoss.Net module is no longer supported and a new module called JBossWS is developed to conform to the J2EE Web Services specification. An overview of JBossWS is available from this wiki item: http://www.jboss.org/wiki/Wiki.jsp?page=JBossWS.
If you have JBoss.Net server applications that need to run in JBoss AS 4.0, it possible to replace the JBossWS module with the JBoss.Net module in located in the docs/examples directory. But you cannot have both JBossWS and JBoss.Net running at the same time.
For Web Services clients, the Axis generated stubs for JBoss.Net applications should work fine for the new JBossWS applications.
JBoss AS 4.0 bundles the Hibernate library. If your JBoss AS 3.2.x application uses Hibernate, it probably already bundles Hibernate library in its own deployment archive. You should avoid any library conflicts -- make sure that your Hibernate client and server uses the same version of Hibernate library. Otherwise, the java.io.InvalidClassException would be thrown.
JBoss AS 4.0 provides Hibernate integration support such as obtaining session factories via JNDI names. If you manage Hibernate sessions inside your own application, the JBoss AS EJB container does not understand how Hibernate opens and closes connections. In your server log, you might see frequent messages like "[CachedConnectionManager] Closing a connection for you". That does NOT indicate a connection leak. However, it is recommended that you use the JBoss Hibernate integration module to manage your Hibernate sessions and avoid those warnings.
A caveat for the above statement is that the JBoss Hibernate integration module is not well tested yet. There is a known conflict between the Hibernate integration code and the JBoss TreeCache code, which could result in MappingExceptions in some cases. If you are not using the Hibernate integration stuff, you should be able to complete remove the jars from the lib directory (hibernate2, cglib, and odmg), remove the jboss-hibernate-service.xml file from the deploy directory, and then bundle the jars inside your ear as before.
Similar to the case with Hibernate, JBoss AS 4.0 provides built-in support for JBoss Cache. So, if your application still bundles its own JBoss Cache library in the EAR deployment file, it is time to remove them and use the library JARs in JBOSS_HOME/server/config/lib directory instead. Failing to do could result in LinkageErrors occasionally.
In clustered web applications, some TCP-multicasting users have noticed replication failures from JBossCacheManager when the load is heavy. To fix this problem, try switch to UDP-multicasting. Or, if you have to use TCP, you can work it around by setting the cache mode to REPL_ASYNC.
In this section, we lists some common known issues of JBoss AS 4.0, which have not been covered in previous sections. This is by no means a complete bug list. Most of those issues have already been fixed in JBoss 4.0.1. But if you use JBoss 4.0.0, you might encounter them. In this case, we recommend you upgrade.