+

Search Tips   |   Advanced Search

EJB content in WAR modules

Use this topic to understand the packaging requirements of EJB content in web application archive (WAR) modules.


Supported EJB content

Except for explicitly stated restrictions, the EJB function supported for beans packaged inside EJB Java archive (JAR) modules is also supported for beans packaged inside WAR modules. A bean that is packaged inside a WAR module can have the same behavior as a bean that is packaged inside an EJB JAR module.

All types of EJB 3.x beans are supported in WAR modules, and 2.x and 1.x session beans. See the EJB 3.1 specification for complete details.


Packaging mechanics

The rules for packaging EJB content in a WAR module are different from the rules for packaging EJB content in a JAR module.

The bean class files must be placed in one of two locations within the WAR module:

For example, we might loosely place the bean class com.foo.MyBean in the WAR module at this location: WEB-INF/classes/com/foo/MyBean.class.

We might also place this bean class in the myJar.jar file, which is then placed in this location: WEB-INF/lib/myJar.jar.

A WAR module can have some bean code loosely placed in the WEB-INF/classes directory structure, and have other bean code inside JAR files in the WEB-INF/lib directory. It is also valid for a WAR module to have all the bean code in the WEB-INF/classes directory structure and nothing in the WEB-INF/lib directory, or all the bean code in JAR files in the WEB-INF/lib directory and nothing in WEB-INF/classes.

It is valid to have multiple JAR files in the WEB-INF/lib directory, all of which might contain bean code.

If the same bean class is loosely placed in the WEB-INF/classes directory structure and also placed in a JAR file in the WEB-INF/lib directory, then the instance of the class placed loosely in the WEB-INF/classes directory structure is loaded, and the instance placed in a JAR file in the WEB-INF/lib directory is ignored.

If the same bean class is placed in two different JAR files in the WEB-INF/lib directory, it is not known which instance of the class is loaded, and which instance is ignored. At run time, the server arbitrarily picks one class instance and loads it, and ignores the other class instance.

The EJB deployment descriptor files must be placed in the WEB-INF directory. This directory contains the ejb-jar.xml deployment descriptor, and any ibm-ejb-jar-ext and ibm-ejb-jar-bnd XML or XMI bindings and extensions files. EJB descriptor files that are located inside JAR files in the WEB-INF/lib directory are ignored. As with an EJB JAR module, there might be 0 or 1 instance of each EJB descriptor file. There cannot be multiple instances of any EJB descriptor file. This does not include the persistence.xml file, if one exists. Per the Java Persistence API specification, if a persistence.xml file is present, it must remain in a META-INF directory located in either the WEB-INF/classes directory of the WAR module or in a JAR file in the WEB-INF/lib directory of the WAR module. For example:

The MyEntity.jar contains META-INF/persistence.xml.

If an ejb-jar.xml file is located in a JAR file in the WEB-INF/lib directory, a warning message displays. For example:

IWAE0068W The EJB deployment descriptor META-INF/ejb-jar.xml in the library archive
 foo.jar file is ignored. The product does not process the META-INF/ejb-jar.xml deployment
 descriptor in library archives. Move the META-INF/ejb-jar.xml deployment descriptor from the  library archive to the WEB-INF directory in the WAR module.

A WAR module must be version 2.5 or later to contain EJB content. EJB content placed in a WAR module that is version 2.4 or earlier is ignored.

If a WAR module is version 2.5 or later, the web metadata files containing bindings and extensions information must use the XML version of the files, not the XMI version.


Technical differences for enterprise beans that are packaged in a WAR file

The following list contains key technical differences that exist between beans that are packaged in a WAR module and beans that are packaged in an EJB JAR module:


Stub generation

Remote access of EJB methods requires the use of client-side stub classes. For most client environments, the product runtime automatically generates the required stub classes. One exception is the thin client environment. For thin clients, the stub classes must be manually generated and packaged with the client.

Use the createEJBStubs tool to generate stubs when the EJB content is packaged in a WAR module, regardless of the EJB version.

See the topic, Create stubs command, for more information.

When packaging EJB 2.1 classes in a WAR module, do not include any stub classes generated by the EJBDeploy tool. These stub classes are different than the stub classes automatically generated by the product run time and can cause failures. In most situations the automatically generated stub classes are sufficient. The exception is if a component in the web module must make a remote method invocation on an EJB 2.1 class packaged in another JAR module. In this case, the EJBDeploy generated stub class for the EJB in the other JAR module must be packaged in the WAR module.


EJB 2.x and 1.x content in a WAR module

Except for entity beans, EJB 2.x and 1.x content is supported in a WAR module.

A 2.x or 1.x module packaged inside a WAR file requires an ejb-jar.xml deployment descriptor at version 2.x or 1.x in the WEB-INF directory of the WAR module. If XMI bindings and extension files are present, we must also package these bindings and files in the WEB-INF directory of a WAR module.

Session beans and message driven beans that you implement according to the 2.x or 1.x coding style can be packaged inside a WAR module.

Both bean managed persistence (BMP) and container managed persistence (CMP) entity beans are not supported in a WAR module.

The application profiling and access intent services are not supported in a WAR module. Session beans found in a WAR module cannot access application profiling tasks.

EJB content that you implement according to both the 3.x coding style and the 2.x and 1.x coding styles, can be packaged together in a single WAR module. However, in this case, we must declare any bindings and extensions information with the XML version of the files, not the XMI version.


Move existing EJB content from EJB JAR modules into WAR modules

One approach is to put the existing EJB JAR file in the WEB-INF/lib directory of the WAR file. Then, remove the descriptor files from the META-INF directory of the JAR file and place them in the WEB-INF directory of the WAR file.

A second approach is to put the class files from the EJB JAR file in the correct location under the WEB-INF/classes directory in the WAR module. Then, remove the descriptor files from the META-INF directory of the JAR file and place them into the WEB-INF directory of the WAR file.

If multiple EJB JAR modules are moved into a single WAR module, we must merge the contents of each of the descriptor files previously found in the META-INF directories of the EJB JAR modules into the single version of the descriptor files that are now placed in the WEB-INF directory of the WAR file. Examples of descriptor files that may be merged include, but are not limited to, ejb-jar.xml, ibm-ejb-jar-bnd.xml, ibm-ejb-jar-ext.xml, and ibm-ejb-jar-ext-pme.xml.

We must inspect the references declared by the various components in the WAR module, both EJB and non-EJB, to ensure that they do not conflict with each other, since everything in the WAR module shares a single component name space.

We must modify the bindings and extension XMI files that are moved from an EJB JAR module to a WAR module in several places to remove references to META-INF/ejb-jar.xml and replace them with WEB-INF/ejb-jar.xml.


EJB function supported in EJB JAR modules, but not in WAR modules

The following EJB function is not supported in WAR modules:

If an entity bean is placed in a WAR module, error messages display, and the application fails to start. For example, the foo entity bean is placed in the foo.war module in the FooApp application. This results in the following messages:

CWMDF0025E: Entity beans in EJB web application archive (WAR) modules are not allowed,
 per the EJB 3.1 specification.
WSVR0039E: Unable to start EJB JAR, foo.war: Entity beans in EJB web application archive
 (WAR) modules are not allowed, per the EJB 3.1 specification. The foo bean in the foo.war module
 must be moved to a stand-alone EJB module. Examine the log to see a full list of invalid entity
 beans in a WAR module.

  • EJB 3.x module packaging overview
  • Create stubs command