<?xml version="1.0" encoding="UTF-8"?>
<book version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:svg="http://www.w3.org/2000/svg"
      xmlns:mml="http://www.w3.org/1998/Math/MathML"
      xmlns:html="http://www.w3.org/1999/xhtml"
      xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>Java EE Application Assembler's Guide</title>

    <authorgroup>
      <author>
        <orgname>JOnAS Team</orgname>
      </author>

      <author>
        <personname><surname>SAUTHIER</surname><firstname>Guillaume</firstname></personname>
      </author>
    </authorgroup>

    <legalnotice>
      <para>This work is licensed under the Creative Commons
      Attribution-ShareAlike License. To view a copy of this license,visit
      <link
      xlink:href="http://creativecommons.org/licenses/by-sa/2.0/deed.en">http://creativecommons.org/licenses/by-sa/2.0/deed.en</link>
      or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford,
      California 94305, USA.</para>
    </legalnotice>

    <copyright>
      <year>2008-2009</year>

      <holder>OW2 Consortium</holder>
    </copyright>

    <date>Fev 2008</date>
  </info>

  <preface xml:id="eardeploy.preface">
    <para>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 Java EE application. It describes how
    the Java EE components should be packaged to create a Java EE
    application.</para>
  </preface>

  <chapter xml:id="ear.define">
    <info>
      <title>Defining the Ear Deployment Descriptor</title>
    </info>

    <section xml:id="ear.define.principles">
      <info>
        <title>Principles</title>
      </info>

      <para>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 Java EE specification version
      5. (Refer to <link
      xlink:href="http://java.sun.com/xml/ns/javaee/application_5.xsd">http://java.sun.com/xml/ns/javaee/application_5.xsd</link>
      ).</para>

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

      <para>Some Java EE application examples are provided in the JOnAS
      distribution:</para>

      <itemizedlist>
        <listitem>
           $JONAS_ROOT/examples/cluster-javaee5 for the Java EE 5 cluster demo 
        </listitem>

        <listitem>
           $JONAS_ROOT/examples/javaee5-earsample for the Java EE 5 library example 
        </listitem>
      </itemizedlist>

      <para>The standard deployment descriptor should contain structural
      information that includes the following:</para>

      <itemizedlist>
        <listitem>
           EJB components, 
        </listitem>

        <listitem>
           Web components, 
        </listitem>

        <listitem>
           Client components, 
        </listitem>

        <listitem>
           Alternate Deployment Descriptor for theses components, 
        </listitem>

        <listitem>
           Security role. 
        </listitem>
      </itemizedlist>

      <para>There is no JOnAS-specific deployment descriptor for the
      Enterprise ARchive.</para>
    </section>

    <section xml:id="eardeploy.Exampl1">
      <info>
        <title>Sample Application Deployment Descriptor</title>
      </info>

      <screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt;

&lt;application
  xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                      http://java.sun.com/xml/ns/javaee/application_5.xsd"
  version="5"&gt;


  &lt;description&gt;Java EE 5.0 EAR Sample&lt;/description&gt;
  &lt;display-name&gt;Java EE 5.0 EAR Sample&lt;/display-name&gt;

  &lt;!-- EJB Modules --&gt;
  &lt;module&gt;
    &lt;ejb&gt;ejb3.jar&lt;/ejb&gt;
  &lt;/module&gt;

  &lt;!-- Web Modules --&gt;
  &lt;module&gt;
    &lt;web&gt;
      &lt;web-uri&gt;javaee5-earsample.war&lt;/web-uri&gt;
      &lt;context-root&gt;javaee5-earsample&lt;/context-root&gt;
    &lt;/web&gt;
  &lt;/module&gt;

  &lt;!-- Application Client Modules --&gt;
  &lt;module&gt;
    &lt;!-- Application Client using JMS to interact with the application --&gt;
    &lt;java&gt;jms-application-client.jar&lt;/java&gt;
  &lt;/module&gt;
  &lt;module&gt;
    &lt;!-- Not secured Application Client (only access read-only beans) --&gt;
    &lt;java&gt;not-secured-application-client.jar&lt;/java&gt;
  &lt;/module&gt;
  &lt;module&gt;
    &lt;!-- Secured Application Client (can access all bean under a SecurityContext) --&gt;
    &lt;java&gt;jaas-secured-application-client.jar&lt;/java&gt;
  &lt;/module&gt;

&lt;/application&gt;</screen>
    </section>
  </chapter>

  <chapter xml:id="ear.packaging">
    <info>
      <title>EAR Packaging</title>
    </info>

    <section xml:id="ear.packaging.components">
      <info>
        <title>Ear Components</title>
      </info>

      <para>Java EE 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:</para>

      <variablelist>
        <varlistentry>
          <term>The web components (war)</term>

          <listitem>
             One or more wars which contain the web components of the Java EE application. Due to the class loader hierarchy, when the wars are packaged in a Java EE 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 

            <link xlink:href="j2eeprogrammerguide#j2ee.pg.classloader">JOnAS
            class loader hierarchy</link>

             . 
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>The EJB components (ejb-jar)</term>

          <listitem>
             One or more ejb-jars, which contain the beans of the Java EE application. 
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>The RAR components (resource adapters)</term>

          <listitem>
             One or more rars, which contain the resource adapters of the Java EE application. 
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>The libraries (jar)</term>

          <listitem>
             One or more jars which contain the libraries (tag libraries and any utility libraries) used for the Java EE application. 
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>The Java EE deployment descriptor</term>

          <listitem>
             The standard xml deployment descriptor in the format defined in the Java EE 5 specification: 

            <link
            xlink:href="http://java.sun.com/xml/ns/javaee/application_5.xsd">http://java.sun.com/xml/ns/javaee/application_5.xsd</link>

             . This deployment descriptor must be stored with the name 

            <code>META-INF/application.xml</code>

             in the ear file. 
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section xml:id="ear.packaging.manifest">
      <info>
        <title>Ear MANIFEST.MF</title>
      </info>

      <para>An EAR being a standard Java archive, it also has a MANIFEST
      file.</para>

      <para>An interesting attribute to add to this file is the EAR's
      implementation version: indeed, if this information is present and the
      <link xlink:href="services.versioning.config.about">versioning</link>
      service is active, you can do smooth application version
      migration:</para>

      <screen>
    Manifest-Version: 1.0
    Implementation-Version: 2.1.0
          </screen>
    </section>

    <section xml:id="ear.packaging.example">
      <info>
        <title>Example</title>
      </info>

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

      <para>Then, the ear file (<code>&lt;java-ee-application&gt;.ear</code>)
      can be built using the jar command:</para>

      <screen>
    cd &lt;java-ee_application_directory&gt;
    jar cvfm &lt;java-ee-application&gt;.ear META-INF/MANIFEST.MF *
          </screen>

      <para>Note that in order to include your custom MANIFEST file, you need
      to specify its path to the <code>jar</code> command:</para>

      <screen>
    cd &lt;java-ee_application_directory&gt;
    jar cvfm &lt;java-ee-application&gt;.ear META-INF/MANIFEST.MF *
          </screen>
    </section>
  </chapter>

  <chapter xml:id="ear.maven">
    <info>
      <title>EAR Packaging using Maven</title>
    </info>

    <para>If the Java EE application's components are available as <link
    xlink:href="http://maven.apache.org/">Apache Maven</link> dependencies,
    you can also use the <link
    xlink:href="http://maven.apache.org/plugins/maven-ear-plugin/">maven-ear-plugin</link>
    for the EAR generation. In this case, the generation and inclusion of all
    files is done automatically by Maven.</para>

    <para>Here's an example pom.xml file generating a EAR with the
    Implementation Version:</para>

    <screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt;

&lt;project
  xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/maven-v4_0_0.xsd"&gt;

  &lt;parent&gt;
    &lt;groupId&gt;org.ow2.jonas.samples&lt;/groupId&gt;
    &lt;artifactId&gt;ear-sample&lt;/artifactId&gt;
    &lt;version&gt;1.0.0&lt;/version&gt;
  &lt;/parent&gt;
  &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
  &lt;artifactId&gt;${parent.artifactId}-ear&lt;/artifactId&gt;
  &lt;packaging&gt;ear&lt;/packaging&gt;
  &lt;name&gt;JOnAS Java EE 5 sample&lt;/name&gt;
  &lt;description&gt;This is a sample Java EE 5 application.&lt;/description&gt;

  &lt;dependencies&gt;
    &lt;!-- WARs and EJB-JARs --&gt;
    &lt;dependency&gt;
      &lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
      &lt;artifactId&gt;${parent.artifactId}-ejb&lt;/artifactId&gt;
      &lt;version&gt;${project.version}&lt;/version&gt;
      &lt;type&gt;ejb&lt;/type&gt;
    &lt;/dependency&gt;
    &lt;dependency&gt;
      &lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
      &lt;artifactId&gt;${parent.artifactId}-war&lt;/artifactId&gt;
      &lt;version&gt;${project.version}&lt;/version&gt;
      &lt;type&gt;war&lt;/type&gt;
    &lt;/dependency&gt;
  &lt;/dependencies&gt;

  &lt;build&gt;
    &lt;plugins&gt;
      &lt;plugin&gt;
        &lt;artifactId&gt;maven-ear-plugin&lt;/artifactId&gt;
        &lt;configuration&gt;
          &lt;!-- Make sure it is a Java EE 5 EAR --&gt;
          &lt;version&gt;5&lt;/version&gt;

          &lt;!-- Here, we can rename the included files' names --&gt;
          &lt;modules&gt;
            &lt;webModule&gt;
              &lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
              &lt;artifactId&gt;
                ${parent.artifactId}-war
              &lt;/artifactId&gt;
              &lt;contextRoot&gt;
                /${parent.artifactId}
              &lt;/contextRoot&gt;
              &lt;bundleFileName&gt;
                ${parent.artifactId}.war
              &lt;/bundleFileName&gt;
            &lt;/webModule&gt;
            &lt;ejbModule&gt;
              &lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
              &lt;artifactId&gt;
                ${parent.artifactId}-ejb
              &lt;/artifactId&gt;
              &lt;bundleFileName&gt;
                ${parent.artifactId}.jar
              &lt;/bundleFileName&gt;
            &lt;/ejbModule&gt;
          &lt;/modules&gt;

          &lt;archive&gt;
            &lt;!-- Don't forget the Implementation Version --&gt;
            &lt;manifestEntries&gt;
              &lt;Implementation-Version&gt;${project.version}&lt;/Implementation-Version&gt;
            &lt;/manifestEntries&gt;
          &lt;/archive&gt;
        &lt;/configuration&gt;
      &lt;/plugin&gt;
    &lt;/plugins&gt;
  &lt;/build&gt;
&lt;/project&gt;</screen>
  </chapter>

  <appendix>
    <info>
      <title>Appendix</title>
    </info>

    <xi:include href="xmltips.xml" />
  </appendix>
</book>