Defining the Ear Deployment Descriptor

Target Audience and Content

The target audience for this guide is the Application Provider, 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 application provider should build the deployment descriptors of its components.

The content of this guide is the following:

  1. Target Audience and Content
  2. Principles
  3. Simple example of Application deployment Descriptors
  4. Advanced example of Application deployment Descriptors
  5. Tips

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 standard deployment descriptor should contain structural information that includes the following:

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:

&lt; < less than
&gt; > greater than
&amp; & ampersand
&apos; ' apostrophe
&quot; " quotation mark