Java EE 6 Web Profile Requirements

• Java Platform, Enterprise Edition 6

• Java Web Technologies

  • Servlet 3.0 (JSR 315)

  • JSP 2.2 and Expression Language (EL) 1.2

  • JavaServer Faces (JSF) 2.0 (JSR 314)

  • Java Standard Tag Library (JSTL) for JSP 1.2

  • Debugging Support for Other Languages 1.0 (JSR 45)

• Enterprise Application Technologies

  • Contexts and Dependency Injection (CDI) (JSR 299)

  • Dependency Injection for Java (JSR 330)

  • Enterprise JavaBeans 3.1 Lite (JSR 318)

  • Java Persistence API 2.0 (JSR 317)

  • Common Annotations for the Java Platform 1.1 (JSR 250)

  • Java Transaction API (JTA) 1.1 (JSR 907)

  • Bean Validation (JSR 303)

Items Included in the EE 6 Full Profile

• EJB 3.1 (not Lite) (JSR 318)

• Java EE Connector Architecture 1.6 (JSR 322)

• Java Message Service (JMS) API 1.1 (JSR 914)

• JavaMail 1.4 (JSR 919)

• Web Service Technologies

  • Jax-RS RESTful Web Services 1.1 (JSR 311)

  • Implementing Enterprise Web Services 1.3 (JSR 109)

  • JAX-WS Java API for XML-Based Web Services 2.2 (JSR 224)

  • Java Architecture for XML Binding (JAXB) 2.2 (JSR 222)

  • Web Services Metadata for the Java Platform (JSR 181)

  • Java APIs for XML-based RPC 1.1 (JSR 101)

  • Java APIs for XML Messaging 1.3 (JSR 67)

  • Java API for XML Registries (JAXR) 1.0 (JSR 93)

• Management and Security Technologies

  • Java Authentication Service Provider Interface for Containers 1.0 (JSR 196)

  • Java Authentication Contract for Containers 1.3 (JSR 115)

  • Java EE Application Deployment 1.2 (JSR 88)

  • J2EE Management 1.1 (JSR 77)

Module based class loading

In previous releases of JBoss AS, the class loading architecture was hierarchical. In JBoss EAP 6, class loading is based on JBoss Modules. This offers true application isolation, hides server implementation classes, and only loads the classes your application needs. Class loading is concurrent for better performance. Applications written for JBoss Enterprise Application Platform 5 must be modified to specify module dependencies and in some cases, repackage archives. For more information, see Class Loading and Modules in the Development Guide for JBoss Enterprise Application Platform 6 located on the Customer Portal.

Domain Management

In JBoss EAP 6, the server can be run as a standalone server or in a managed domain. In a managed domain, you can configure entire groups of servers at once, keeping configurations synchronized across your entire network of servers. While this should not impact applications built for previous releases, this can simplify management of deployments to multiple servers. For more information, see About Managed Domains in the Administration and Configuration Guide for JBoss Enterprise Application Platform located on the Customer Portal.

Deployment Configuration

Directory Structure and Scripts

As previously mentioned, JBoss EAP 6 no longer uses profile based deployment configuration, so there is no JBOSS_HOME/server/ directory. Configuration files for standalone servers are now located in the JBOSS_HOME/standalone/configuration/ directory and deployments are located in the JBOSS_HOME/standalone/deployments/ directory. For servers running in a managed domain, configuration files can be found in the JBOSS_HOME/domain/configuration/ directory and deployments can be found in the JBOSS_HOME/domain/deployments/ directory.
In JBoss Enterprise Application Platform 5, the Linux script JBOSS_HOME/bin/run.sh or Windows script JBOSS_HOME/bin/run.bat was used to start the server. In JBoss Enterprise Application Platform 6, the server start script is dependent on how you run your server. The Linux script JBOSS_HOME/bin/standalone.sh or Windows script JBOSS_HOME/bin/standalone.bat is used to start a standalone server. The Linux script JBOSS_HOME/bin/domain.sh or Windows script JBOSS_HOME/bin/domain.bat is used to start a managed domain.

JNDI Lookups

JBoss EAP 6 now uses standardized portable JNDI namespaces. Applications that use other types of JNDI lookups must be changed to follow the new standardized JNDI namespace convention. For more information about JNDI naming syntax, see the section below on “Portable JNDI Naming Syntax”.

Modules

A Module is a logical grouping of classes used for class loading and dependency management. JBoss EAP 6 identifies two different types of modules, sometimes called static and dynamic modules. However the only difference between the two is how they are packaged. All modules provide the same features.

<?xml version="1.0" encoding="UTF-8"?>
<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"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

Modules and Class Loading in Enterprise Archives

Enterprise Archives (EAR) are not loaded as a single module like JAR or WAR deployments. They are loaded as multiple unique modules.

The following rules determine what modules exist in an EAR.

• Each WAR and EJB JAR subdeployment is a module.

• The contents of the lib/ directory in the root of the EAR archive is a module. This is called the parent module.

These modules have the same behavior as any other module with the following additional implicit dependencies:

• WAR subdeployments have implicit dependencies on the parent module and any EJB JAR subdeployments.

• EJB JAR subdeployments have implicit dependencies on the parent module and any other EJB JAR subdeployments.

  No subdeployment ever gains an implicit dependency on a WAR subdeployment. Any subdeployment can be configured with explicit dependencies on another subdeployment as would be done for any other module.

The implicit dependencies described above occur because JBoss EAP 6 has subdeployment class loader isolation disabled by default.

Subdeployment class loader isolation can be enabled if strict compatibility is required. This can be enabled for a single EAR deployment or for all EAR deployments. The Java EE 6 specification recommends that portable applications should not rely on subdeployments being able to access each other unless dependencies are explicitly declared as Class-Path entries in the MANIFEST.MF file of each subdeployment.

level Directories

Directories within the domain/ directory

servers/ Contains the equivalent data/, log/, and tmp/ directories for each server instance in a domain, which contain similar data to the same directories within the top-level domain/ directory. |

Directories within the standalone/ directory

Management Console

The Management Console is a web-based administration tool used to to start and stop servers, deploy and undeploy applications, tune system settings, and make persistent modifications to the server configuration. The Management Console also has the ability to perform administrative tasks, with live notifications when any changes require the server instance to be restarted or reloaded. In a Managed Domain, server instances and server groups in the same domain can be centrally managed from the Management Console of the domain controller.

JBoss CLI

The Management Command Line Interface (CLI) is a command line administration tool that can perform operations in batch modes, allowing multiple tasks to be run as a group.

JON

TODO: section is not complete.

Resolve ClassCastExceptions Caused by Duplicate JARs

Because JBoss EAP 6 ships with a number of classes, or modules, that are commonly used by applications, packaging these common JARs with your application can result in a ClassCastException. For example, if you bundle the jstl.jar and standard.jar with the application archive, you may see a ClassCastException similar to the following:

08:38:01,867 ERROR [org.apache.catalina.core.ContainerBase.[jboss.web].[default-host].[/].[MVCUserInterface]] (http-localhost/127.0.0.1:8080-2)
Servlet.service() for servlet MVCUserInterface threw exception: java.lang.ClassCastException: javax.servlet.jsp.jstl.fmt.LocalizationContext cannot be cast to java.lang.String at org.apache.taglibs.standard.tag.common.fmt.BundleSupport.getLocalizationContext(BundleSupport.java:178)
[jboss-jstl-api_1.2_spec-1.0.3.Final-redhat-2.jar:1.0.3.Final-redhat-2]
The following is an example of the procedure used to resolve this type issue.

To resolve this issue:

1. Find the JBoss module that contains the class named by the ClassCastException. In this case, the jboss-jstl-api_1.2_spec-1.0.3.Final-redhat-2.jar can be found in the EAP_HOME/modules/system/layers/base/javax/servlet/jstl/api/main directory.

2. Explicitly define the dependency in either the MANIFEST.MF file or in the jboss-deployment-structure.xml file. The following is an example of a jboss-deployment-structure file that defines the module dependency:

   <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
     <deployment>
         <dependencies>
           <module name="javax.servlet.jstl.api" slot="main" />
         </dependencies>
     </deployment>
   </jboss-deployment-structure>

3. Search the application archive to find all JAR(s) that are packaged with the application that contain the class named by the ClassCastException. In this case, the jstl.jar and standard.jar JARs were packaged in the lib/ folder of the application archive. Remove the duplicate JAR(s) from the application's packaged WAR or EAR file.

Resolve ClassCastExceptions and ClassNotFoundExceptions Caused by API Version Differences

If your application uses a version of an API other than the default API included in the main/ module of the modules/system/layers/base/ directory, you may see a ClassCastException or a ClassNotFoundException when you run the application.

For example, if your application uses JSF 1.2 instead of the default JSF 2.0, you may see you may see a ClassCastException or ClassNotFoundException like the following:

Caused by: java.lang.ClassNotFoundException: javax.faces.FacesException from \[Module "deployment.weblogic-example.ear:main" from Service Module Loader\]
    at org.jboss.modules.ModuleClassLoader.findClass(ModuleClassLoader.java:191)

In this case, it cannot find the class javax.faces.FacesException due to a mismatch in API versions. The default JSF module for JBoss EAP 6 is version JSF 2.0 and the application is using JSF 1.2. To resolve the mismatch, you must explicitly include the JSF 1.2 dependency and exclude the JSF 2.0 dependency.

To resolve this issue:

1. Find the JBoss module that contains the class named by the ClassNotFoundException. In this case, there are 2 modules for the javax.faces.api classes. The default module for JSF 2.0 is located in the EAP_HOME/modules/system/layers/base/javax/faces/api/main directory and a module for JSF 1.2 is located in the EAP_HOME/modules/system/layers/base/javax/faces/api/1.2 directory.

2. Explicitly define the dependency on the older JSF 1.2 version in the jboss-deployment-structure.xml file and exclude the default JSF 2.0 module as follows:

   <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0">
       <deployment>
           <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" export="true"/>
               <module name="com.sun.jsf-impl" slot="1.2" export="true"/>
           </dependencies>
       </deployment>
   </jboss-deployment-structure>

3. Search the application archives and remove any jsf-api JARs from the packaged application.

Migrate Your Hibernate 3.3.x Application to Hibernate 4.x

1. Map Hibernate text types to JDBC LONGVARCHAR
   In versions of Hibernate prior to 3.5, text type was mapped to JDBC "CLOB". A new Hibernate type, "materialized_clob", was added in Hibernate 4 to map Java String properties to JDBC "CLOB". If your application has properties configured as type="text" that are intended to be mapped to JDBC "CLOB", you must do one of the following:

   1. If your application uses hbm mapping files, change the property to type="materialized_clob".

   2. If your application uses annotations, you should replace @Type(type = "text") with @Lob.

2. Review code to find changes in returned value types
   Numeric aggregate criteria projections now return the same value type as their HQL counterparts. As a result, the return types from the following projections in org.hibernate.criterion have changed.

   1. Due to changes in CountProjection, Projections.rowCount(), Projections.count(propertyName), and Projections.countDistinct(propertyName), the count and count distinct projections now return a Long value.

   2. Due to changes in Projections.sum(propertyName), the sum projections now return a value type that depends on the property type.

      1. For properties mapped as Long, Short, Integer, or primitive integer types, a Long value is returned;

      2. For properties mapped as Float, Double, or primitive floating point types, a Double value is returned.

         Failure to modify your application code could result in a java.lang.ClassCastException.

Migrate Your Hibernate 3.5.x Application to Hibernate 4.x

1. Merge the AnnotationConfiguration into the Configuration
   Although AnnotationConfiguration is now deprecated, it should not affect your migration. If you are still using an hbm.xml file, you should be aware that JBoss EAP 6 now uses the "org.hibernate.cfg.EJB3NamingStrategy" in AnnotationConfiguration instead of the "org.hibernate.cfg.DefaultNamingStrategy" that was used in previous releases. This can result in naming mismatches. If you rely on the naming strategy to default the name of an association (many-to-many and collections of elements) table, you may see this issue. To resolve it, you can tell Hibernate to use the legacy org.hibernate.cfg.DefaultNamingStrategy by calling Configuration#setNamingStrategy and passing it org.hibernate.cfg.DefaultNamingStrategy#INSTANCE.

2. Modify the namespaces to conform to the new Hibernate DTD file names.

   Previous DTD Namespace	New DTD Namespace
   http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd	http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd
   http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd	http://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd

3. Modify environment variables

   1. If you are using Oracle and using the "materialized_clob" or "materialized_blob" properties, the global environment variable "hibernate.jdbc.use_streams_for_binary" must be set to true.

   2. If you are using PostgreSQL and using the "CLOB" or "BLOB" properties, the global environment variable "hibernate.jdbc.use_streams_for_binary" must be set to false.

Package the Hibernate 3.x JARs with the Application

1. Copy the specific Hibernate 3.x JARs into the application's lib/ directory.

2. Create a jboss-deployment-structure.xml file with the following content to tell the server to exclude the Hibernate 4 classes:

   <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0">
       <deployment>
           <exclusions>
               <module name="org.hibernate"/>
           </exclusions>
       <deployment>
   </jboss-deployment-structure>

3. Place the jboss-deployment-structure.xml file in either the META-INF/ directory or the WEB-INF/ directory if you are deploying a WAR, or in the META-INF/ directory if you are deploying an EAR.

Create a Custom Module for the Hibernate 3.x Libraries

1. Create a custom module for the Hibernate 3 libraries.

   1. Create a directory structure under the JBOSS_HOME/module directory to contain the Hibernate 3 files and JARs. For example:

      $ cd JBOSS_HOME/modules/
      $ mkdir -p org/hibernate/3

   2. Copy the JARs from the Hibernate distribution to the {{JBOSS_HOME/modules/org/hibernate/3/} folder.

   3. Create a module.xml file in the JBOSS_HOME/modules/org/hibernate/3/ directory that describes the JARs and dependencies for the Hibernate 3 libraries. The following is an example of a module.xml file for Hibernate 3.6.6:

      <?xml version="1.0" encoding="UTF-8"?>
      <module xmlns="urn:jboss:module:1.0" name="org.hibernate" slot="3">
          <resources>
              <resource-root path="hibernate3.jar"/>
              <resource-root path="javassist-3.12.0.GA.jar"/>
              <resource-root path="antlr-2.7.6.jar"/>
              <resource-root path="commons-collections.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>

2. Modify the persistence.xml to use the custom Hibernate module. Set the "jboss.as.jpa.providerModule" to "org.hibernate:3" as follows:

   <!-- persistence.xml using Hibernate 3.6.6.Final -->
   <?xml version="1.0" encoding="UTF-8"?>
   <persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
   <persistence-unit name="GameOfThrones_pu">
       <description>my Hibernate 3 persistence unit.</description>
       <jta-data-source>java:jboss/datasources/gameDS</jta-data-source>
       <properties>
           <property name="jboss.as.jpa.providerModule" value="org.hibernate:3"/>
       </properties>
   </persistence-unit>

   The Java Persistence API (JPA) deployer will detect the presence of a persistence provider in the application and use the Hibernate 3 libraries.

3. Create a jboss-deployment-structure.xml file with the following content to tell the server to use the Hibernate 3 module and exclude the Hibernate 4 libraries:

   <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0">
       <deployment>
           <dependencies>
               <module name="org.hibernate" slot="3"/>
           </dependencies>
           <exclusions>
               <module name="org.hibernate" slot="main"/>
          </exclusions>
       <deployment>
   </jboss-deployment-structure>

4. Place the jboss-deployment-structure.xml file in either the META-INF/ directory or the WEB-INF/ directory if you are deploying a WAR, or in the META-INF/ directory if you are deploying an EAR.

Structure of the Archives