JBoss 5.0.0.GA Release Notes

This is the final release of the JBoss 5.0 series for the Java EE™5 codebase that fully complies with the Java EE 5
conformance testing certification requirements. It brings us to the end of a 3+ year marathon of redesigning the most
popular open-source application server over a completely new kernel architecture, the JBoss Microcontainer. It also
marks the beginning of a new era of innovation for JBoss as we will be exploring the capabilities and limitations of
the new architecture in the releases to come. In our view, JBossAS 5 provides a healthy foundation and the most
advanced and fully extensible, cross component model, aspect integration, server runtime environment.
For information on the APIs that make up Java EE 5, see Java EE APIs & Docs. A tutorial on Java EE 5 can be found
here. Please visit also the JBoss AS docs pages as we'll be updating the documents with the latest information, and
post your questions to the JBossAS 5 User Forum.

A sample Java EE 5 application that can be run on top of JBoss 5 and demonstrates many interesting technologies is
the Seam Booking Application available here. Check out the JBoss Seam framework pages that link to many interesting
topics for combining Seam with JBossAS 5.
Overview

   * Highlights
   * Compatibility Issues
   * Configuration Issues
   * Other Issues
   * JBoss/Thirdparty Library Updates
   * Detailed Release Notes
   * Additional Docs and Help
   * Licenses
   * About JBoss

Highlights
JBoss 5 is the next generation of the JBoss Application Server build on top of the new JBoss Microcontainer. The
JBoss Microcontainer is a lightweight container for managing POJOs, their deployment, configuration and
lifecycle. It is a standalone project that replaces the famous JBoss JMX Microkernel of the 3.x and 4.x JBoss
series. The Microcontainer integrates nicely with the JBoss framework for Aspect Oriented Programming, JBoss AOP.
Support for JMX in JBoss 5 remains strong and MBean services written against the old Microkernel are expected to work.

JBoss5 is designed around the advanced concept of a Virtual Deployment Framework (VDF), that takes the aspect oriented
design of many of the earlier JBoss containers and applies it to the deployment layer. Aspectized Deployers operate in
a chain over a Virtual File System (VFS), analyze deployments and produce metadata to be used by the JBoss
Microcontainer, which in turn instantiates and wires together the various pieces of a deployment, controlling
their lifecycle and dependencies.

Many key features of JBoss 5 are provided by integrating other standalone JBoss projects:

   * JBoss EJB3 included with JBoss 5 provides the implementation of the latest revision of the Enterprise
Java Beans (EJB) specification. EJB 3.0 is a deep overhaul and simplification of the EJB specification. EJB 3.0's
goals are to simplify development, facilitate a test driven approach, and focus more on writing plain old java objects
(POJOs) rather than coding against complex EJB APIs.
   * JBoss Messaging is a high performance JMS provider in the JBoss Enterprise Middleware Stack (JEMS), included with
JBoss 5 as the default messaging provider. It is also the backbone of the JBoss ESB infrastructure. JBoss Messaging
is a complete rewrite of JBossMQ, which is the default JMS provider for the JBoss AS 4.x series.
   * JBossCache that comes in two flavors. A traditional tree-structured node-based cache and a PojoCache, an
in-memory, transactional, and replicated cache system that allows users to operate on simple POJOs transparently
without active user management of either replication or persistency aspects.
   * JBossWS is the web services stack for JBoss 5 providing Java EE compatible web services, JAX-WS-2.0.
   * JBoss Transactions is the default transaction manager for JBoss 5. JBoss Transactions is founded on industry
proven technology and 18 year history as a leader in distributed transactions, and is one of the most
interoperable implementations available.
   * JBoss Web is the Web container in JBoss 5, an implementation based on Apache Tomcat that includes the
Apache Portable Runtime (APR) and Tomcat native technologies to achieve scalability and performance
characteristics that match and exceed the Apache Http server.

JBoss 5 includes features and bug fixes, many of them carried over upstream from the 4.x codebase. See the
Detailed Release Notes section for the full details.

A common theme for JBossAS 5 is the breaking out of internal subsystems into stand-alone projects and the
introduction of SPIs throughout the server codebase. Those changes should not affect directly the end user but they
are an important part of the JBoss strategy for making available the various EE services as independent projects,
so that they can be wired-together and be consumed à la carte inside different runtime environments and not only 
inside the JBoss Application Server.

If you are building JBossAS from source you'll notice we are migrating to a maven2 build. At this point the build is
a hybrid one because it declares all JBoss dependencies as maven2 artifacts, however after the dependencies are
resolved/imported the legacy ant based build is used to compile and build the distribution. This will change to a
full maven build at some point in time. The jboss maven repo can be found here. Starting from AS5 CR2, please note
how the -sources.jar are also downloaded.
Compatibility Issues
JBossAS 5.0.0.GA can be compiled with both Java5 & Java6. The Java5 compiled binary is our primary/recommended binary
distribution. It has undergone rigorous testing and can run under both a Java 5 and a Java 6 runtime. When running
under Java 6 you need to manually copy the following libraries from the JBOSS_HOME/client directory to the
JBOSS_HOME/lib/endorsed directory, so that the JAX-WS 2.0 apis supported by JBossWS are used:

   * jbossws-native-saaj.jar
   * jbossws-native-jaxrpc.jar
   * jbossws-native-jaxws.jar
   * jbossws-native-jaxws-ext.jar

The other option is to download the jdk6 distribution (jboss-5.0.0.GA-jdk6.zip) in which case no configuration
changes are required. If you still have problems using JBoss with a Sun Java 6 runtime, you may want to set 
-Dsun.lang.ClassLoader.allowArraySyntax=true, as described in JBAS-4491. Other potential problems under a Java 6
runtime include:

   * ORB getting prematurely destroyed when using Sun JDK 6 (see Sun Bug ID: 6520484)
   * Unimplemented methods in Hibernate for JDK6 interfaces.
   * When JBossAS 5 is compiled with Java 6, support for the extended JDBC 4 API is included in the binary, however
this can only be used under a Java 6 runtime. In this case no manual configuration steps are necessary. It should be
noted however that the Java 6 compiled distribution of JBoss AS 5 is still in experimental stage.

Other compatibility issues:

   * JBossMQ has been removed from the distribution and is no longer supported in AS5. JBoss Messaging Service is now
the default JMS provider.
   * All the *-beans.xml configuration files have been renamed to *-jboss-beans.xml to avoid conflicts with spring
configuration files.
   * For mod_cluster integration you will have to use the workaround described in JBAS-5966 until the tomcat service
mbean descriptor is converted to an MC bean descriptor.
   * JBoss VFS provides a set of different switches to control it's internal behavior. JBoss AS sets
jboss.vfs.forceCopy=true by default. To see all the provided VFS flags check out the code of the VFSUtils.java class.
   * VFS uses an internal caching mechanism to speed up access to deployment artifacts. This means that files in
deploy/ remain open as long as they are accessed and then closed by a reaper thread after a 5 seconds inactivity. On
window platforms this may cause locking issues if files are re-deployed too quickly. In this case you may want to
turn-off the reaper by specifying the  -Djboss.vfs.forceNoReaper=true property in the command line.
   * Hibernate-core is now using slf4j-api as a logging facade. To properly integrate that in JBossAS we have
created an slf4j-to-jboss-logging adapter (slf4j-jboss-logging.jar) that creates a static binding between sl4j and
jboss-logging-spi . The jboss-logging default implementation is configured to use log4j. See JBAS-5519.
   * The client/jbossall-client.jar library that used to bundle the majority of jboss client libraries, is now
referencing them instead through the Class-Path manifest entry. This allows swapping included libraries (e.g.
jboss-javaee.jar) without having to re-package jbossall-client.jar. On the other hand, it requires that you have
jbossall-client.jar together with the other client/*.jar libraries, so they can be found. See JBAS-4355.
   * If using proprietary JBoss/EJB3 annotations, those have moved (since Beta4) into the org.jboss.ejb3.annotation
package, EJBTHREE-1099. Those are now included in a new artifact, jboss-ejb3-ext-api.jar
   * Interoperating with previous JBoss EJB3 implementations may present problems due to
serialVersionUIDs issues, EJBTHREE-1118.
   * Use of JBoss Cache 3.x. has a significantly different API from the 1.x releases used in JBoss AS 4.x and 3.2.x.
   * @EJB injections should now work from servlets, JBAS-5646.
   * The ClassPathExtension MBean has been replaced with a VFS classloader definition, see JBAS-5446.
   * The old JMX-based ServiceBindingManager has been replaced by a POJO-based ServiceBindingManager, see JBAS-5192.
   * The Farm service from 4.x has been removed.
   * JBoss 5 is stricter when it comes to verifying/deploying JavaEE artifacts. EJB3 deployments that
run in AS 4.2 may fail in AS5. We have tried to keep the validation messages as accurate as possible in order to
help you modify your deployment descriptors/annotations to be in-line with the JavaEE 5 requirements.

Configuration Issues

JBossAS 5.0.0.GA introduces two new configuration, the standard and the web config.

   * The standard config is the configuration that has been tested for JavaEE compliance. The major differences
with the existing configurations is that call-by-value and deployment isolation are enabled by default, along with
support for rmiiiop and juddi (taken from the all config), as shown below:
         o deployers/ear-deployer-jboss-beans.xml
           true
           true
         o conf/jboss-service.xml call-by-value for "jboss:service=Naming"
           true
         o conf/jndi.properties
           java.naming.factory.initial=org.jboss.iiop.naming.ORBInitialContextFactory
         o conf/jacorb.properties
           deploy/iiop-service.xml
           lib/avalon-framework.jar
           lib/jacorb.jar
         o deploy/juddi-service.sar
   * The web config is a new experimental lightweight configuration created around JBoss Web that will follow the
developments of the JavaEE 6 web profile. Except for the servlet/jsp container it provides support for JTA/JCA and
JPA. It also limits itself to allowing access to the server only through the http port. Please note that this
configuration is not JavaEE certified and will most likely change in the following releases.

Another notable change is that the majority of the libraries common to the different configurations have moved
to a new shared location, JBOSS_HOME/common/lib/. This is so we avoid having multiple copies of the same libraries in
the distribution. The location of the common library directory can be controlled by the following properties:

   * jboss.common.base.url defaulting to ${jboss.home.url}/common
   * jboss.common.lib.url  defaulting to ${jboss.common.base.url}/lib

The common library directory is shared by all the configurations except for the minimal config. It is
referenced in the very beginning of every configuration's conf/jboss-service.xml.




You can see that the library directory of the individual configurations is still in place, although in some cases
it's empty (e.g. JBOSS_HOME/server/default/lib/)

The directory structure of JBoss 5 resembles that of the 4.x series with some notable differences:

   * bin - start scripts and run.jar
   * client - client jars - note how jbossall-client.jar is now referencing the other client jars.
   * common
         o lib
   * docs - docs, schemas/dtds, examples
   * lib - core bootstrap jars, somewhat different with the introduction of the microcontainer and breakup of jboss-common.
   * server - the same server configuration dirs.
         o xyz configuration
               + conf
                     # bootstrap.xml - new mc kernel bootstrap configuration referencing other
                     # configuration files that contain the beans that setup each individual subsystem.
                           * bootstrap
                                 o vfs.xml - vfs initialization
                                 o classloader.xml
                                 o aop.xml
                                 o jmx.xml - legacy JMX support
                                 o deployers.xml
                                 o bindings.xml (POJO-based ServiceBindingManager & port bindings)
                                 o profile-repository.xml (profile service enabled deployment repository)
                     # jax-ws-catalog.xml - oasis catalog driven schema/dtd namespace configuration
                     # jbossjta-properties.xml - new JBossTS properties
                     # jboss-service.xml - legacy static mbeans for compatibility, somewhat reduced
                     # jndi.properties - the same jndi props
                     # log4j.xml - the same log4j config
                     # login-config.xml - the same jaas login config
                     # props/ - the same default jaas login properties files
                     # standardjaws.xml - obsolete cmp config
                     # standardjbosscmp-jdbc.xml - the same cmp2 config
                     # standardjboss.xml - the same ejb2 config
                     # xmdesc/ - legacy xmbean descriptors
               + deploy/ - the same deploy directory.
                     # ...
                     # jca-jboss-beans.xml
                     # hdscanner-jboss-beans.xml - the hot deployment scanner
                     # legacy-invokers-service.xml
                     # profileservice-jboss-beans.xml
                     # remoting-jboss-beans.xml
                     # transaction-jboss-beans.xml
                     # vfs-jboss-beans.xml
               + deployers/ - new vdf deployers
                     # bsh-deployer - beanshell deployer
                     # ejb3.deployer - ejb3 deployers
                     # jboss-aop-jboss5.deployer - aspect deployer
                     # jboss-jca.deployer - JCA deployers
                     # jbossweb.deployer - war deployers
                     # jbossws.deployer - web services deployers
                     # seam.deployer - SEAM deployer
                     # alias-deployers-jboss-beans.xml
                     # clustering-deployers-jboss-beans.xml
                     # dependency-deployers-jboss-beans.xml
                     # directory-deployer-jboss-beans.xml
                     # ear-deployer-jboss-beans.xml - ear deployers
                     # ejb-deployer-jboss-beans.xml - ejb2.x deployers
                     # hibernate-deployer-jboss-beans.xml
                     # jsr77-deployers-jboss-beans.xml
                     # metadata-deployer-jboss-beans.xml - metadata handlers
                     # security-deployer-jboss-beans.xml - security deployers
               + lib/ - the same static library jars with a few jars, as most have moved to top level common/lib

Various configuration issues:

   * A new jboss.server.log.threshold system property can be used to control the log/server.log threshold. It defaults to DEBUG.
   * Use of the jboss.jgroups.udp.mcast_port property to control easy configuration of multicast port, JBAS-2395
   * Overriding of ra.xml properties in jboss-ra.xml, JBAS-3343
   * Support for defining dependencies in JCA adapters, JBAS-4508
   * Controlling command line arguments for the appClientLauncher, JBAS-5888.
   * Shutdown.sh now accepts a JNDI url, JBAS-5922.
   * DeleteWorkDirOnContextDestroy property for JSP pages, JBAS-5453.
   * The clustering configurations have been organized in the deploy dir in a new cluster subfolder (JBAS-4709).
   * A separate cache is now used for Clustered SSO (JBAS-4676).
   * Per webapp configuration of useJK, snapshot mode and snapshot interval (JBAS-3460). Default for useJK is whether
jvmRoute is set (JBAS-4961).
   * Total replication (rather than buddy replication) is the default setting for session replication (JBAS-5085).
   * The transaction manager configuration has moved from conf/jboss-service.xml to deploy/transaction-service.xml
(JBAS-5103).
   * The default conf/jboss-log4j.xml configuration now includes the thread name for entries in log/server.log (JBAS-5274).
   * All the security related configuration files are now grouped under the deploy/security directory (JBAS-5318).
   * Loopback is now set to true for all JGroups UDP stacks (JBAS-5323).

EJB3 configuration  is now controlled by deployers/ejb3.deployer/META-INF/ejb3-deployers-jboss-beans.xml.
For more details check out this wiki page.

For security related configuration changes, please consult this wiki page.
For clustering related changes, check out the Wiki for more info.
Other Issues

   * Bootstrap time has improved compared to AS5 CR1, but it still somewhat slower when compared to the 4.2.x series,
due to the extensive annotation scanning that goes on behind the scenes. There are ways to optimize the
annotation scanning, especially for large deployments. Check the JBoss Wiki for more information.

Library Updates
For a full list of the JBoss and thirdparty libraries used with JBoss AS 5.0.0.GA check the pom.xml found in the
component-matrix directory of the source code distribution. To see the maven dependency tree you can also do a 'mvn
dependency:tree' from the thirdparty directory of the source code distro.

Some rather important used jboss project versions are listed below. You are encouraged to browse the individual
project's documentation and view the release notes at www.jboss.org.

   * JBoss Transactions, v4.4.0.GA
   * JBoss WebServices, v3.0.4.GA
   * JBoss Messaging, v1.4.1.GA
   * JBoss Web, v2.1.1.GA
   * JBoss AOP, v2.0.0.SP1
   * JBoss EJB3, v1.0.0-Beta10
   * JBoss Microcontainer, v2.0.2.GA
   * JBoss Security, v2.0.2.SP3
   * Hibernate, v3.3.1.GA
   * Hibernate Entity Manager, v3.4.0.GA
   * Hibernate Annotations, v3.4.0.GA
   * JBoss Cache POJO, v3.0.0.GA
   * JBoss Cache Core, v3.0.1.GA
   * JGroups, v.2.6.7.GA