# 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 to the developed application (Enterprise ARchive). As one goes along the different steps of the application development and deployment life cycle of an application (development, assembly, deployment), the deployment descriptor has to be completed.

The Application Assembler's responsibilities is to provide a XML deployment descriptor respecting the deployment descriptor's XML DTD defined in the J2EE specification version 1.3. (See `$JONAS_ROOT/xml/application_1_3.dtd`).

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

The JOnAS interpretation of the <!DOCTYPE> tag is particular, at the parsing of the deployment descriptor XML files.
The parser try, first, to get the specified DTD via the classpath, and then via the specified URL (or path).

Examples: in these two following examples, the parser get 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">

You can find two J2EE application exemples in the JOnAS distribution:

- The EarSample example
- The Alarm demo

The standard deployment descriptor should contain structural information including:

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

Some characters, such "<" and "&" are strictly illegal in the XML data.
Others, such ">", are legal, but it is a good habit to replace them by XML entity references.

Here is the list of the predefined entity references in XML:

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