J2EE Application Assembler's Guide

JOnAS Team

Guillaume SAUTHIER

1. Defining the Ear Deployment Descriptor

1.1. Principles
1.2. Simple example of Application Deployment Descriptor
1.3. Advanced example of Application Deployment Descriptors with alternate DD and security

2.1. Ear Components
2.2. Example

A.1. xml Tips

The target audience for this guide is the Application Provider and Assembler, i.e. the person in charge of combining one or more components (ejb-jars and/or wars) to create a J2EE application. It describes how the J2EE components should be packaged to create a J2EE application.

Defining the Ear Deployment Descriptor

1.1. Principles
1.2. Simple example of Application Deployment Descriptor
1.3. Advanced example of Application Deployment Descriptors with alternate DD and security

1.1. Principles

The application programmer is responsible for providing the deployment descriptor associated with the developed application (Enterprise ARchive). The Application Assembler's responsibilities is to provide a XML deployment descriptor that conforms to the deployment descriptor's XML schema as defined in the J2EE specification version 1.4. (Refer to $JONAS_ROOT/xml/application_1_4.xsd or http://java.sun.com/xml/ns/j2ee/application_1_4.xsd ).

To deploy J2EE applications on the application server, all information is contained in one XML deployment descriptor. The file name for the application XML deployment descriptor is application.xml and it must be located in the top level META-INF directory.

The parser gets the specified schema via the classpath (schemas are packaged in the $JONAS_ROOT/lib/common/ow_jonas.jar file).

Some J2EE application examples are provided in the JOnAS distribution:

$JONAS_ROOT/examples/alarm for The Alarm demo
$JONAS_ROOT/examples/cmp2 for The Cmp2 example
$JONAS_ROOT/examples/earsample for The EarSample example
$JONAS_ROOT/examples/petstore1.3 for The Blueprints Petstore application

The standard deployment descriptor should contain structural information that includes the following:

EJB components,
Web components,
Client components,
Alternate Deployment Descriptor for theses components,
Security role.

There is no JOnAS-specific deployment descriptor for the Enterprise ARchive.

1.2. Simple example of Application Deployment Descriptor

<?xml version="1.0" encoding="UTF-8"?>

<application xmlns="http://java.sun.com/xml/ns/j2ee"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
             http://java.sun.com/xml/ns/j2ee/application_1_4.xsd"
             version="1.4">

  <display-name>Simple example of application</display-name>
  <description>Simple example</description>

  <module>
    <ejb>ejb1.jar</ejb>
  </module>
  <module>
    <ejb>ejb2.jar</ejb>
  </module>

  <module>
    <web>
      <web-uri>web.war</web-uri>
      <context-root>web</context-root>
    </web>
  </module>
</application>

1.3. Advanced example of Application Deployment Descriptors with alternate DD and security

<?xml version="1.0" encoding="UTF-8"?>

<application xmlns="http://java.sun.com/xml/ns/j2ee"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
             http://java.sun.com/xml/ns/j2ee/application_1_4.xsd"
             version="1.4">

  <display-name>Ear Security</display-name>
  <description>Application with alt-dd and security</description>
  <module>
    <web>
      <web-uri>admin.war</web-uri>
      <context-root>admin</context-root>
    </web>
  </module>
  <module>
    <ejb>ejb.jar</ejb>
    <alt-dd>altdd.xml</alt-dd>
  </module>
  <security-role>
    <role-name>admin</role-name>
  </security-role>
</application>

For advices about xml file writing, refer to Section A.1, “xml Tips”.

EAR Packaging

2.1. Ear Components
2.2. Example

2.1. Ear Components

J2EE applications are packaged for deployment in a standard Java programming language Archive file called an ear file (Enterprise ARchive). This file can contain the following:

The web components (war): One or more wars which contain the web components of the J2EE application. Due to the class loader hierarchy, when the wars are packaged in a J2EE application, it is not necessary to package classes of EJBs accessed by the web components in the WEB-INF/lib directory. Details about this class loader hierarchy are described in JOnAS class loader hierarchy .
The EJB components (ejb-jar): One or more ejb-jars, which contain the beans of the J2EE application.
The RAR components (resource adapters): One or more rars, which contain the resource adapters of the J2EE application.
The libraries (jar): One or more jars which contain the libraries (tag libraries and any utility libraries) used for the J2EE application.
The J2EE deployment descriptor: The standard xml deployment descriptor in the format defined in the J2EE 1.4 specification. See $JONAS_ROOT/xml/application_1_4.xsd . This deployment descriptor must be stored with the name META-INF/application.xml in the ear file.

2.2. Example

Before building an ear file for a J2EE application, the ejb-jars and the wars that will be packaged in the J2EE application must be built and the XML deployment descriptor (application.xml) must be written.

Then, the ear file ( <j2ee-application>.ear ) can be built using the jar command:

    cd <your_j2ee_application_directory>
    jar cvf <j2ee-application>.ear *

Appendix

A.1. xml Tips

Although some characters, such as ">", are legal, it is good practice to replace them with XML entity references.

The following is a list of the predefined entity references for XML:

<	<	less than
>	>	greater than
&	&	ampersand
'	'	apostrophe
"	"	quotation mark