J2EE Application Assembler's Guide

Target Audience and Content

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.

The content of this guide is the following:

1. Target Audience and Content
2. Defining the Ear Deployment Descriptor
   • Principles
   • Simple example of Application deployment Descriptors
   • Advanced example of Application deployment Descriptors with alternate DD and security
   • Tips
3. EAR Packaging

Defining the Ear Deployment Descriptor

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 DTD as defined in the J2EE specification version 1.3. (Refer to $JONAS_ROOT/xml/application_1_3.dtd).

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.

JOnAS interprets the <!DOCTYPE> tag at the parsing of the deployment descriptor XML files.
The parser first tries to get the specified DTD via the classpath, then it uses the specified URL (or path).

In the following two examples, the parser gets the application_1_3.dtd DTD file via the URL or in the /usr/local/jonas/xml/ directory.

     <!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN' 
                                  'http://java.sun.com/dtd/application_1_3.dtd'>
     <!DOCTYPE application SYSTEM "/usr/local/jonas/xml/application_1_3.dtd">
    

Two J2EE application examples are provided in the JOnAS distribution:

• The EarSample example
• The Alarm demo

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.

Simple example of Application Deployment Descriptor

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN' 
                             'http://java.sun.com/dtd/application_1_3.dtd'>

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

Advanced example of Application Deployment Descriptors with alternate DD and security

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN' 
                             'http://java.sun.com/dtd/application_1_3.dtd'>

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

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:

EAR Packaging

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 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.3 specification. See $JONAS_ROOT/xml/application_1_3.dtd. This deployment descriptor must be stored with the name META-INF/application.xml in the ear file.

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 *