Overview of Java EE 6 Profiles

Java Enterprise Edition 6 (EE 6) includes support for multiple profiles, or subsets of APIs. The only two profiles that the EE 6 specification defines are the Full Profile and the Web Profile.
EE 6 Full Profile includes all APIs and specifications included in the EE 6 specification. EE 6 Web Profile includes a subset of APIs which are useful to web developers.

JBoss AS 7 is a certified implementation of the Java Enterprise Edition 6 Full Profile and Web Profile specifications.

Java Enterprise Edition 6 Web Profile

The Web Profile is one of two profiles defined by the Java Enterprise Edition 6 specification. It is designed for web application development.

Java Enterprise Edition 6 Full Profile

The Java Enterprise Edition 6 (EE 6) specification defines a concept of profiles, and defines two of them as part of the specification. Besides the items supported in the Java Enterprise Edition 6 Web Profile, the Full Profile supports the following APIs. JBoss AS 7 supports the Full Profile.

Review What's New and Different in JBoss AS 7

The following is a list of notable differences in JBoss AS 7 from the previous release.

Modules and Modular Class Loading

Class loading in AS 7 is based on the JBoss Modules project.

<?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>

Directory Structure of JBoss AS 7

JBoss AS 7 includes a simplified directory structure, compared to previous versions. The following table contains a listing of the directories and a description of what each directory contains. It also includes directory structures of the standalone/ and domain/ folders.

Deployment

TODO: section is not complete.

Administration Tools

WebLogic Server Configuration and Deployment Descriptor Files

Configuration of the WebLogic Server is centralized in the WEBLOGIC_HOME/domains/DOMAIN_NAME/config/config.xml file. It contains the configuration parameter settings for each server instance, cluster, resource, and service in the domain. In most cases you use the Administration Console or one of the other WebLogic tools to modify the domain's configuration and the changes are then reflected in the configuration files.

JBoss AS 7 Configuration File

In JBoss AS 7, the server can be run as a standalone server or in a managed domain. A standalone server is configured using the JBOSS_HOME/standalone/configuration/standalone.xml file. For servers running in a managed domain, the server is configured using the JBOSS_HOME/domain/configuration/domain.xml and JBOSS_HOME/domain/configuration/host.xml files. In most cases you will not edit these files directly. You can use the Management Console or Management Command Line Interface (CLI) to configure the server and the changes will be reflected in the server configuration file. You can find more information about the Management CLI here: CLI Recipes.

Migrate the Server Configuration

Unfortunately, server configuration is a complex process and there is not an easy mapping from one application server to another. The best approach is to open the WebLogic configuration file and examine each section. Use the Admin Guide to find information about how to perform the same configuration in JBoss.

Map weblogic-ejb-jar.xml Elements to the jboss-ejb3.xml Descriptor

The following table maps the WebLogic XPath elements to the corresponding JBoss XPath elements for various types of beans.

Map Additional weblogic-ejb-jar.xml Elements to the JBoss Enterprise Application Platform Equivalent

The following list describes how to map addtional elements to the JBoss Enterprise Application Platform Equivalent.

• delay-updates-until-end-of-tx
  This element in the webLogic-ejb-jar.xml file, which defaults to True, is used for performance reasons to delay updates to the persistent store of all beans until the end of the transaction. When set to False, updates are sent to the database after each method invocation, but are not committed until the end of the transaction. This allows other processes to access the persisted data while the transaction is waiting to be completed. In JBoss Enterprise Application Platform 6, you can achieve the same behavior by specifying the <sync-on-commit-only> in the jbosscmp-jdbc.xml file. For example:

  <jbosscmp-jdbc>
  ...
      <entity>
          <ejb-name>Student</ejb-name>
          <create-table>true</create-table>
          <remove-table>true</remove-table>
          <table-name>STUDENT</table-name>
          ...
          <sync-on-commit-only>true</sync-on-commit-only>
          <insert-after-ejb-post-create>true</insert-after-ejb-post-create>
          <call-ejb-store-on-clean>true</call-ejb-store-on-clean>
      </entity>
  </jbosscmp-jdbc>

  This feature is available in JBoss Enterprise Application Platform 6.1. For JBoss Enterprise Application Platform 6.0.x, it is available as a patch.

Use Property Substitution to Specify the Target Deployment Environment

1. Enable Property Substitution in the Server Configuration File

The <spec-descriptor-property-replacement> element in the ee subsystem of the server configuration file is used to enable or disable property substitution in the ejb-jar.xml and persistence.xml descriptor files. The <jboss-descriptor-property-replacement> element in the ee subsystem of the server configuration file is used to enable or disable property substitution in the jboss-ejb3.xml, jboss-app.xml, jboss-web.xml, *-jms.xml, and *-ds.xml descriptor files. To enable property substitution it must be set to true. This is the default value. The following is an example of the ee subsystem element configured to enable property substitution.

    <subsystem xmlns="urn:jboss:domain:ee:1.1">
        <spec-descriptor-property-replacement>true</spec-descriptor-property-replacement>
        <jboss-descriptor-property-replacement>true</jboss-descriptor-property-replacement>
    </subsystem>

2. Bind Strings for JNDI Runtime Mapping

For values outside deployment descriptors that change depending on the target environment, you can bind string values into JNDI and them map them into the application.
Assume the application's web.xml file contains the following resource reference:

<resource-env-ref>
    <description>IP address of the destination</description>
    <resource-env-ref-name>destination/ip-address</resource-env-ref-name>
    <resource-env-ref-type>java.lang.String</resource-env-ref-type>
</resource-env-ref>

To bind simple strings into JNDI, create a <simple> element in the naming subsystem of the server configuration file. The following is an example of the naming subsystem element configured for JNDI substitution.

<subsystem xmlns="urn:jboss:domain:naming:1.1">
    <bindings>
        <simple name="java:/my/jndi/key" value="MyJndiValue"/>
    </bindings>
</subsystem>

Add an entry to the application's jboss-web.xml to map the global JNDI entry to the application's java:comp/env/ Environment Naming Context (ENC). The <resource-env-ref-name> element value must match the value specified in the web.xml and the <jndi-name> element must match the <simple> element name in the server configuration file.

<jboss-web>
    <resource-env-ref>
        <resource-env-ref-name>destination/ip-address</resource-env-ref-name>
        <jndi-name>java:/my/jndi/key</jndi-name>
    </resource-env-ref>
</jboss-web>

Follow the same procedure to implement property substitution for other descriptor files.
For more information about how to manage the server configuration files, refer to the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 located on the Customer Portal at https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

Replace WebLogic JNDI Lookup Code

In WebLogic, you create a Hashtable containing environment information such as provider URL, context factory, security principal and credentials. You pass this table as a parameter when you create the InitialContext. Then you lookup the Service using a prefix with the Service class name

This is an example of how code may look in WebLogic:

Hashtable<String, String> env = new Hashtable<String, String>();
env.put( Context.PROVIDER_URL, "t3://localhost:7001" );
env.put( Context.INITIAL_CONTEXT_FACTORY, "weblogic.jndi.WLInitialContextFactory" );
env.put( Context.SECURITY_PRINCIPAL, "weblogic" );
env.put( Context.SECURITY_CREDENTIALS, "weblogic" );
Context context = new InitialContext( env );
Service service = (Service)context.lookup( "sample.Service#" + Service.class.getName() );

In JBoss, you instantiate the InitialContext with no argument and then look up the service using the portable JNDI lookup rules: java:global, java:app, java:module.

This is an example of what the code would look like in JBoss:

Context context = new InitialContext();
Service service = (Service) context.lookup( "java:app/service/" + ServiceImpl.class.getSimpleName() );

Portable JNDI Naming Syntax

There are four logical namespaces, each with its own scope. Three of the namespaces are used for portable JNDI lookups. The following table details when and how to use each namespace.

You can find more information about JNDI naming contexts in section EE.5.2.2, "Application Component Environment Namespaces" in the "JSR 316: JavaTM Platform, Enterprise Edition (Java EE) Specification, v6". You can download the specification from here: http://jcp.org/en/jsr/detail?id=316

Portable JNDI Naming Syntax Rules

JBoss Enterprise Application Platform 6 has improved upon JNDI namespace names, not only to provide predictable and consistent rules for every name bound in the application server, but also 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:

1. 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.

2. Unqualified absolute names like /jdbc/DefaultDS should be qualified relative to a java:jboss/root name.

3. Qualified absolute names like java:/jdbc/DefaultDS should be qualified the same way as Unqualified absolute names above.

4. The special java:jboss namespace is shared across the entire AS server instance.

5. Any relative name with a java: prefix must be in one of the five namespaces: comp, module, app, global, or the proprietary jboss. Any name starting with java:xxx where xxx does not match any of the above five would result in an invalid name error.

Archive Packaging and Assembly Rules

JBoss Enterprise Application Platform 6 uses a modular classloading system for controlling the class paths of deployed applications. This system provides more flexibility and control than the traditional system of hierarchical class loaders. This can simplify packaging of archives and eliminate the need to bundle Java EE 6 and other common classes. The following are general rules for assembly of archives or directories that are deployed to JBoss Enterprise Application Platform 6:

• Archives may be nested within other archived deployments.

• Extracted directories may be nested in extracted deployments.

• Archives may be nested in extracted deployments.

• Extracted directories may NOT be nested in archived deployments. You must recreate archives for the nested artifacts.

• In WebLogic, an extracted WAR, EAR, or other archive can be deployed without the archive extension in the directory name. In JBoss, the extension must appear on the extracted directory name, for example myEnterpriseApp.ear or myWebApp.war.

• The JBoss AS 7 installation includes Java EE 6, JBoss Logging, Hibernate, and other commonly used classes in the server install modules/ directory. You can also create custom dynamic modules to make third-party JARs and other resources available to all applications running on the server. Modules are only loaded when a deployment requests them and these JARs or classes should not be bundled within the application archives.

• For web applications, it is generally better to avoid the use of a web.xml file if possible. If this file is required, it should be located under the root of the application WEB-INF/ directory.

• If your enterprise application requires an application.xml file, it should be located under the META-INF/ directory in the root of the EAR.

Debug and Resolve ClassCastExceptions and ClassNotFoundExceptions

A ClassCastException can occur because a 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. A ClassNotFoundException can be a result of missing JARs or a mismatch of API versions. Due to the modular class loading system used by JBoss AS 7, you may need to modify deployment descriptors, remove JARs, or change the packaging structure of your EAR or WAR.

JBoss AS ships with a number of classes, or modules, that are commonly used by applications. These classes are located in the JBOSS_HOME/modules/system/layers/base/ directory and include all the application server provided APIs, the Java EE APIs, as well as other APIs such as JBoss Logging. If your WebLogic application packages a JAR that is also included in the server modules/system/layers/base/ directory, you may see a ClassCastException when you deploy or run your application. If your application needs a version of the classes that is different than the classes located in the JBOSS_HOME/modules/system/layers/base/ directory, you may see a ClassCastException or a ClassNotFoundException.

For more information about class loading and modules, refer to the chapter entitled Class Loading and Modules in the Development Guide for JBoss Enterprise Application Platform 6 on the Customer Portal .

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.

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)

Tell JBoss to Use Primitive Return Types

1. Modify the application code.
   Assume the application has defined the following interface for the CMP entity bean:

   public interface primitiveInterface {
   
       public int getNumber();
       public void setNumber(int number);
   
   }

   WebLogic returns a 0 in the case of a NULL value in the database, so you must modify the interface as follows to get the similar result in JBoss EAP 6.x.

   public interface primitiveInterface {
   
       public Integer getNumberAsObject();
   
       public int getNumber() {
           if (getNumberAsObject() != null) {
               return getNumberAsObject().intValue();
           } else {
               return 0;
           }
       }
   
       public void setNumberAsObject(Integer number);
   
       public void setNumber(int number) {
           // The following code assumes primitive autoboxing is available.
           // Use the appropriate code if it is not.
           setNumberAsObject(number);
       }
   }

2. Modify the ejb-jar.xml descriptor file.
   The following is an example of the entity bean description in the ejb-jar.xml file before migration.

   <entity>
       <ejb-name>PrimitiveInterface</ejb-name>
       <home>com.redhat.demo.PrimitiveInterfaceHome</home>
       <remote>com.redhat.demo.PrimitiveInterface</remote>
       <ejb-class>com.redhat.demo.PrimitiveInterface</ejb-class>
       <persistence-type>Container</persistence-type>
       <reentrant>false</reentrant>
       <cmp-version>2.x</cmp-version>
       <abstract-schema-name>PrimitiveInterface</abstract-schema-name>
       <cmp-field>
           <field-name>number</field-name>
       </cmp-field>
   </entity>

   You must change the <field-name> element from number to numberAsObject. This tells JBoss EAP to associate the getNumberAsObject() method with the database instead of the getNumber() method.

   <entity>
       <ejb-name>PrimitiveInterface</ejb-name>
       <home>com.redhat.demo.PrimitiveInterfaceHome</home>
       <remote>com.redhat.demo.PrimitiveInterface</remote>
       <ejb-class>com.redhat.demo.PrimitiveInterface</ejb-class>
       <persistence-type>Container</persistence-type>
       <reentrant>false</reentrant>
       <cmp-version>2.x</cmp-version>
       <abstract-schema-name>PrimitiveInterface</abstract-schema-name>
       <cmp-field>
           <field-name>numberAsObject</field-name>
       </cmp-field>
   </entity>

3. Modify the jbosscmp-jdbc.xml descriptor file.
   The following is an example of the entity bean description in the jbosscmp-jdbc.xml file before migration.

   <jbosscmp-jdbc>
     <enterprise-beans>
       <entity>
         <ejb-name>PrimitiveInterface</ejb-name>
         <table-name>primitive</table-name>
   
         <cmp-field>
           <field-name>number</field-name>
           <column-name>number</column-name>
         </cmp-field>
       <entity>
     <enterprise-beans>
   <jbosscmp-jdbc>

   Change the <field-name> element from number to numberAsObject.

   <jbosscmp-jdbc>
     <enterprise-beans>
       <entity>
         <ejb-name>PrimitiveInterface</ejb-name>
         <table-name>primitive</table-name>
   
         <cmp-field>
           <field-name>numberAsObject</field-name>
           <column-name>number</column-name>
         </cmp-field>
       <entity>
     <enterprise-beans>
   <jbosscmp-jdbc>

Migrate Your Application From Hibernate 3 to Hibernate 4

Configure Your Application to Use the Hibernate 3 Libraries

If you do not want to migrate your appliation to use Hibernate 4, you can try to resolve any issues using one of the following approaches.

Replace Application Start and Stop Events

In JBoss Enterprise Application Platform 6, there is no equivalent to intercept the preStart or preStop processing, but you can use one of the following methods to achieve results similar to the postStart and postStop methods.

1. Create a ServletContextListener

The ServletContextListener class provides two methods that are analoguous to postStart() and postStop() methods in the WebLogic ApplicationLifecycleListener class. Since the code must access the context root of the application using the ServletContext, the servlet must be deployed to a WAR file. The following is an example of code that uses the ServletContextListener to perform tasks after application server start and stop:

import javax.servlet.ServletContext;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
import javax.servlet.annotation.WebListener;

@WebListener
public class ContextListener implements ServletContextListener {

    @Override
    public void contextInitialized(ServletContextEvent evt)  {
        ServletContext ctx = evt.getServletContext();
        System.out.println("contextInitialized(): ServerInfo: " +
            ctx.getServerInfo() + " " + System.currentTimeMillis());
        System.out.println("contextInitialized(): ContextPath: " +
            ctx.getContextPath() + " " + System.currentTimeMillis());
    }

    @Override
    public void contextDestroyed(ServletContextEvent evt)  {
        ServletContext ctx = evt.getServletContext();
        System.out.println("contextDestroyed(): ServerInfo: " +
            ctx.getServerInfo() + " " + System.currentTimeMillis());
        System.out.println("contextDestroyed(): ContextPath: " +
            ctx.getContextPath() + " " + System.currentTimeMillis());
    }
}

2. Create a Singleton Stateless Session Bean

Create a singleton bean using the @Singleton annotation. Use the @Startup annotation to tell the container to initialize the singleton session bean at application start. Use the @PostConstruct annotation to specify the method to invoke at the start of the application lifecyle and the @PostDestroy annotation to specify the method to invoke at the end of the application life cycle. The following is an example of a stateless session bean:

import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import javax.ejb.Singleton;
import javax.ejb.Startup;

@Startup
@Singleton
public class StartupBean
{
    @PostConstruct
    void startup() {
        System.out.println("startup()", "@PostContruct called");
    }

    @PreDestroy
    void shutdown() {
        System.out.println("shutdown()", "@PreDestroy called");
    }
}

Replace the Proprietary WebLogic @WLServlet Annotation

You must replace the proprietary WebLogic @WLServlet annotation with the standard Java EE 6 @WebServlet equivalent. Before you replace the code, you must understand how to map the attribute values. The following table shows the mapping of the WebLogic @WLServlet annotation attributes to the Java EE 6 @WebServlet equivalents.

The following is a list of options for replacement of the runAs attribute:

1. Use the javax.annotation.security.RunAs annotation in the class file.

2. Define the run-as element for the Servlet in the application's web.xml file.

3. Define the run-as element in a application's {{web-fragments.xml} file. See sections 8.2.1 through 8.2.3 of the Servlet 3.0 specification for further information about web-fragments.

Here is an example of WebLogic code that uses the @WLServlet annotation:

import weblogic.servlet.annotation.WLServlet;

@WLServlet (
    name = "catalog",
    runAs = "SuperEditor"
    initParams = {
        @WLInitParam (name="catalog", value="spring"),
        @WLInitParam (name="language", value="English")
     },
     mapping = {"/catalog/*"}
)
public class MyCatalogServlet extends HttpServlet { . . . }

Here is the equivalent code that uses the standard @WebServlet annotation:

import javax.annotation.security.RunAs;
import javax.servlet.annotation.WebServlet;

@WebServlet (
    name = "catalog",
    initParams = {
        @WebInitParam (name="catalog", value="spring"),
        @WLInitParam (name="language", value="English")
    },
    urlPatterns = "/catalog/*"
)
@RunAs("SuperEditor")
public class MyCatalogServlet extends HttpServlet { . . . }

Replace the Proprietary WebLogic @WLFilter Annotation

You must replace the proprietary WebLogic @WLFilter annotation with the standard Java EE 6 @WebFilter equivalent. Before you replace the code, you must understand how to map the attribute values. The following table shows the mapping of the WebLogic @WLFilter annotation attributes to the Java EE 6 @WebFilter equivalents.

Here is an example of WebLogic code that uses the @WLFilter annotation:

import weblogic.servlet.annotation.WLFilter;
import weblogic.servlet.annotation.WLInitParam;

@WLFilter (
    name = "catalogFilter",
    initParams = { @WLInitParam(name="catalog", value="winter") }
    mapping = {"/catalog/*"}
)
public class MyFilter implements Filter { . . . }

Here is the equivalent code that uses the standard @WebFilter annotation:

import javax.servlet.annotation.WebFilter;
import javax.servlet.annotation.WebInitParam;

@WebFilter (
    filterName = "catalogFilter",
    initParams = { @WebInitParam(name="catalog", value="winter") }
    urlPatterns = {"/catalog/*"}
)
public class MyFilter implements Filter { . . . }

Replace the Proprietary WebLogic @WLInitParam Annotation

You must replace the proprietary WebLogic @WLInitParam annotation with the standard Java EE 6 @WebInitParam equivalent. Before you replace the code, you must understand how to map the attribute values. The following table shows the mapping of the WebLogic @WLInitParam annotation attributes to the Java EE 6 @WebInitParam equivalents.

Here is an example of WebLogic code that uses the @WLInitParam annotation:

import weblogic.servlet.annotation.WLFilter;
import weblogic.servlet.annotation.WLInitParam;

@WLFilter (
    name = "catalogFilter",
    initParams = { @WLInitParam(name="catalog", value="winter") }
    mapping = {"/catalog/*"}
)
public class MyFilter implements Filter { . . . }

Here is the equivalent code that uses the standard @WebInitParam annotation:

import javax.servlet.annotation.WebFilter;
import avax.servlet.annotation.WebInitParam;

@WebFilter (
    filterName = "catalogFilter",
    initParams = { @WebInitParam(name="catalog", value="winter", description="winter catalog") }
    urlPatterns = {"/catalog/*"}
)
public class MyFilter implements Filter { . . . }

Deploy the new application to a secondary server group or cluster.

This approach requires the use of a hardware or software dispatcher, for example, Apache, on the front end to route the new session requests to the new version of the application deployed to the secondary server group.

Deploy the new application serially to the same clustered domain.

For this approach, you must create a rollout deployment plan using the Management CLI. The following is an example of a CLI command to create a rollout plan in a clustered domain:

deploy ClusterWebApp.war --name=ClusterWebApp.war --runtime-name=ClusterWeb.war --server-groups=ha-server-group --headers={rollout ha-server-group(rolling-to-servers=true)}

JVM Version

Frameworks

• Portal

• Rules Engine

• Workflow

• ESB

IDE (Eclipse Plugins)

Database

• JDBC compliant drivers

• Hibernate

• Persistence frameworks

LDAP

Requirements for High-Availablity, Clusting, Failover, Caching

Third-party Libraries

External Systems

WebLogic Proprietary Libraries and APIs

Examine the Current Build Process

• Consider conversion to Maven

Analyze and Understand the Application Code

Services and Components

Look for uses of the following components or services.

• Cache

• Clustering

• Data sources - JDBC or proprietary

• EJB

• JMS - Queues, Topics, Messages to Migrate

• JNDI

• JTA

• LDAP

• Logging - Map WebLogic Debug options to the equivalent Java EE or JBoss classes for logging

• MDB

• Resource adapters

• RMI

• Security - JAAS, Encryption

• Web Services

Proprietary WebLogic Features or Libraries

• jCOM - Bridge to ActiveX

• JSP tag extensions

• WebLogic Helper Classes

Packaging and Deployment

Deployment Descriptors and Plans

Eclipse and Plugins

NetBeans

ADF