<?xml version="1.0" encoding="UTF-8"?>
<book version="5.0" xml:id="j2eeclient" xml:lang="en"
      xmlns="http://docbook.org/ns/docbook"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      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:ns="http://java.sun.com/xml/ns/javaee"
      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 Client Programmer's Guide</title>

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

      <author>
        <personname><surname>COQ</surname><firstname>Philippe</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>Feb 2008</date>
  </info>

  <preface xml:id="client.preface">
    <para>The target audience for this guide is the Client component provider,
    i.e. the person in charge of developing the Client components on the
    client side. It describes how the Client component provider should build
    the deployment descriptors of its Client components and how the client
    components should be packaged.</para>
  </preface>

  <chapter xml:id="client.launch">
    <info>
      <title>Launching Java EE Client Applications</title>
    </info>

    <section xml:id="j2eeclient.Launch">
      <info>
        <title>Launching clients</title>
      </info>

      <para>The Java EE client application can be</para>

      <itemizedlist>
        <listitem>
           a standalone client in a .jar file, 
        </listitem>

        <listitem>
           a client bundled in an .ear file. An ear can contain many java clients. 
        </listitem>

        <listitem>
           a class name which must be found in the CLASSPATH. 
        </listitem>
      </itemizedlist>

      <para>All the files required to launch the client container are in the
      <code> JONAS_ROOT/lib/client.jar </code> file. This jar includes a
      manifest file with the name of the class to launch. To launch the client
      container on a computer where a JONAS_TROOT is present , simply
      type:</para>

      <para><code> jclient -? </code> . This will launch the client container
      and display usage information about this client container.</para>

      <para>To launch the client container on a remote computer, copy the
      client.jar and invoke the client container by typing <code> java -jar
      path_to_your/client.jar </code></para>

      <para>The client that must be launched by the client container is given
      as an argument of the client container. example : <code> java -jar
      client.jar myApplication.ear </code> or <code> java -jar client.jar
      myClient.jar </code> .</para>
    </section>

    <section xml:id="j2eeclient.Config">
      <info>
        <title>Configuring client container</title>
      </info>

      <section>
        <info>
          <title>JNDI access</title>
        </info>

        <para>Defining the JNDI access and the protocol to use is an important
        part of configuration. The JOnAS server, as well as the
        ClientContainer, uses the values specified in the <code>
        carol.properties </code> file. This file can be used at different
        levels. The <code> carol.properties </code> is searched with the
        following priority (high to low):</para>

        <itemizedlist>
          <listitem>
             the 

            <code>carol.properties</code>

             specified by the 

            <code>-carolFile</code>

             argument to the client container 
          </listitem>

          <listitem>
             the 

            <code>carol.properties</code>

             packaged into the client application (the jar client) 
          </listitem>

          <listitem>
             if not located previously, it will use the 

            <code>carol.properties</code>

             contained in the 

            <code>JONAS_ROOT/lib/client.jar</code>

             . 
          </listitem>
        </itemizedlist>

        <para>A convenient way is to update the <code> carol.properties
        </code> of a <code> client.jar </code> with a customized <code>
        carol.properties </code> file. That is, use the <code> jar -uf
        client.jar carol.properties </code> command.</para>
      </section>

      <section>
        <info>
          <title>Trace configuration</title>
        </info>

        <para>The client container <code> client.jar </code> includes a <code>
        traceclient.properties </code> file. This is the same file as the one
        in <code> JONAS_ROOT/conf </code> directory. A different configuration
        file can be used for the traces by specifying the parameter <code>
        -traceFile </code> when invoking the client container. The file in the
        <code> client.jar </code> can be replaced with the <code> jar -uf
        client.jar traceclient.properties </code> command.</para>
      </section>

      <section>
        <info>
          <title>Classpath configuration</title>
        </info>

        <para>Some jars/classes can be added to the client container. For
        example if a class requires some extra libraries/classes, the option
        <code> -cp path/to/classes </code> can be used.</para>

        <para>The classloader of the client container will use the
        libraries/classes provided by the <code> -cp </code> flag.</para>
      </section>

      <section>
        <info>
          <title>Specifying the client to use (EAR case)</title>
        </info>

        <para>An ear can contain many java clients, which are described in the
        <code> application.xml </code> file inside the <code>
        &lt;module&gt;&lt;java&gt; </code> elements. To invoke the client
        container with an ear, such as <code> java -jar client.jar my.ear
        </code> , specify the java client to use if there are many clients.
        Otherwise, it will take the first client. To specify the jar client to
        use from an ear, use the argument <code> -jarClient </code> and supply
        the name of the client to use. The <code> earsample </code> example in
        the JOnAS examples has two java clients in its ear.</para>
      </section>

      <section>
        <info>
          <title>Specifying the directory for unpacking the ear (EAR
          case)</title>
        </info>

        <para>By default, the client container will use the system property
        <code> java.io.tmpdir </code> To use another temporary directory,
        specify the path by giving the argument <code> -tmpDir </code> to the
        client container.</para>
      </section>

      <section>
        <info>
          <title>Disable Automated WsGen</title>
        </info>

        <para>By default, the client container will apply WsGen (generation of
        web services artifacts) on all given archives. To disable that feature
        (because WsGen has already been applied on the application, or because
        the client contains no web services), add the <code> -nowsgen </code>
        option to the client container.</para>
      </section>
    </section>

    <section xml:id="j2eeclient.Examples">
      <info>
        <title>Examples</title>
      </info>

      <para>The Java EE 5 EAR Sample located under
      $JONAS_ROOT/examples/javaee5-earsample provides three application
      clients showing how to interact with the application in different ways,
      and under different security levels. </para>

      <para>These application clients are described in details in <link
      xlink:href="getting_started_guide.html#getting_application_clients">Getting
      started with JOnAS 5 </link></para>
    </section>
  </chapter>

  <chapter xml:id="client.deploy">
    <info>
      <title>Defining the Client Deployment Descriptor</title>
    </info>

    <section xml:id="j2eeclient.Princip-2">
      <info>
        <title>Principles</title>
      </info>

      <para>The Client component programmer is responsible for providing the
      java class of the Client annotated accordingly to the Java EE 5
      Specification.</para>

      <para>If the Client component programmer wants to provide a XML
      deployment descriptor, this one mus be compliant to the XML Schema for
      the application client 5 deployment descriptor <link
      xlink:href="http://java.sun.com/xml/ns/javaee/application-client_5.xsd">http://java.sun.com/xml/ns/javaee/application-client_5.xsd</link></para>

      <para>To customize the Client components, information not defined in the
      standard XML deployment descriptor may be needed.</para>

      <para>The JOnAS-specific deployment descriptor's XML schema is located
      in <code><link
      xlink:href="http://jonas.ow2.org/ns/jonas-client_5_0.xsd">http://jonas.ow2.org/ns/jonas-client_5_0.xsd</link>
      </code></para>
    </section>

    <section xml:id="j2eeclient.Exampl1-2">
       

      <info>
        <title>Examples of Client Deployment Descriptors</title>
      </info>

       

      <link xlink:href="configuration_guide.html" />

      <itemizedlist>
        <listitem>Example of a standard Client Deployment Descriptor
        (application-client.xml): <screen>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;

&lt;application-client
  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-client_5.xsd"
  version="5"&gt;

  &lt;display-name&gt;OW2 JOnAS :: EAR Sample :: JMS Application Client&lt;/display-name&gt;

  &lt;!-- The JMS ConnectionFactory to use --&gt;
  &lt;resource-ref&gt;
    &lt;res-ref-name&gt;jms/QueueConnectionFactory&lt;/res-ref-name&gt;
    &lt;res-type&gt;javax.jms.QueueConnectionFactory&lt;/res-type&gt;
    &lt;res-auth&gt;Container&lt;/res-auth&gt;
  &lt;/resource-ref&gt;

  &lt;!-- The JMS Queue where Messages will be send --&gt;
  &lt;resource-env-ref&gt;
    &lt;resource-env-ref-name&gt;jms/SampleQueue&lt;/resource-env-ref-name&gt;
    &lt;resource-env-ref-type&gt;javax.jms.Queue&lt;/resource-env-ref-type&gt;
  &lt;/resource-env-ref&gt;

&lt;/application-client&gt;




</screen></listitem>

        <listitem>Example of a specific Client Deployment Descriptor
        (jonas-client.xml): <screen>&lt;jonas-client xmlns="http://www.objectweb.org/jonas/ns"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.objectweb.org/jonas/ns
        http://jonas.ow2.org/ns/jonas-client_5_0.xsd" &gt;
  &lt;jonas-resource&gt;
    &lt;res-ref-name&gt;jms/QueueConnectionFactory&lt;/res-ref-name&gt;
    &lt;jndi-name&gt;JQCF&lt;/jndi-name&gt;
  &lt;/jonas-resource&gt;

  &lt;jonas-resource-env&gt;
    &lt;resource-env-ref-name&gt;jms/SampleQueue&lt;/resource-env-ref-name&gt;
    &lt;jndi-name&gt;SampleQueue&lt;/jndi-name&gt;
  &lt;/jonas-resource-env&gt;
&lt;/jonas-client&gt;
</screen></listitem>
      </itemizedlist>

       For advices about xml file writing, refer to 

      <xref linkend="xmltips" />

       . 
    </section>
  </chapter>

  <chapter xml:id="client.packaging">
    <info>
      <title>Client Packaging</title>
    </info>

    <section xml:id="j2eeclient.Princip-3">
      <info>
        <title>Principles</title>
      </info>

      <para>Client components are packaged for deployment in a standard Java
      programming language Archive file called a jar file (Java ARchive). The
      document root contains a subdirectory called META-INF , which contains
      the following files and directories:</para>

      <itemizedlist>
        <listitem>
           application-client.xml : The standard xml deployment descriptor in the format defined in the Java EE 5 Specification. Refer to 

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

           . 
        </listitem>

        <listitem>
           jonas-client.xml : The optional JOnAS specific xml deployment descriptor in the format defined in 

          <link
          xlink:href="http://jonas.ow2.org/ns/jonas-client_5_0.xsd">http://jonas.ow2.org/ns/jonas-client_5_0.xsd</link>

           . 
        </listitem>
      </itemizedlist>

      <para>The manifest of this client jar must contain the name of the class
      to launch (containing the main method). This is defined by the value of
      the Main-Class attribute of the manifest file. For a standalone client
      (not bundled in an Ear), all the Ejb classes (except the skeleton) on
      which lookups will be performed must be included.</para>
    </section>

    <section>
      <info>
        <title>Example</title>
      </info>

      <para>Two examples of building a java client are provided.</para>

      <itemizedlist>
        <listitem>
           The first is the 

          <code>build.xml</code>

           of the 

          <code>earsample</code>

           example with a java client inside the ear. Refer to the client1jar and client2jar targets. 
        </listitem>

        <listitem>
           The second is the 

          <code>build.xml</code>

           of the 

          <code>jaasclient</code>

           example with a java standalone client which performs a lookup on an EJB. Refer to the clientjars target. 
        </listitem>
      </itemizedlist>
    </section>
  </chapter>

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

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