J2EE Client Application Programmer's Guide

Target Audience and Content

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.

The content of this guide is the following:

Launching J2EE Client Applications

Launching clients

The J2EE client application can be

a standalone client in a .jar file,
a client bundle in an .ear file. An ear can contain many java clients.
a class name which must be found in the CLASSPATH.

All the files required to launch the client container are in the JONAS_ROOT/lib/client.jar file. This jar includes a manifest file with the name of the class to launch. To launch the client container, simply type:

java -jar $JONAS_ROOT/lib/client.jar -?. This will launch the client container and display usage information about this client container.

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

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

Configuring client container

JNDI access

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 carol.properties file.
This file can be used at different levels.
The carol.properties is searched with the following priority (high to low):

the carol.properties specified by the -carolFile argument to the client container
the carol.properties packaged into the client application (the jar client)
if not located previously, it will use the carol.properties contained in the JONAS_ROOT/lib/client.jar.

A convenient way is to update the carol.properties of a client.jar with a customized carol.properties file. That is, use the jar -uf client.jar carol.properties command.

Trace configuration

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

Classpath configuration

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

The classloader of the client container will use the libraries/classes provided by the -cp flag.

Specifying the client to use (EAR case)

An ear can contain many java clients, which are described in the application.xml file inside the <module><java> elements.
To invoke the client container with an ear, such as java -jar client.jar my.ear, 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 -jarClient and supply the name of the client to use.
The earsample example in the JOnAS examples has two java clients in its ear.

Specifying the directory for unpacking the ear (EAR case)

By default, the client container will use the system property java.io.tmpdir.
To use another temporary directory, specify the path by giving the argument -tmpDirto the client container.

Disable Automated WsGen

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 -nowsgen option to the client container.

Examples

The earsample and jaasclient examples of the JOnAS examples are packaged for use by the client container.
The first example demonstrates the client inside an ear. The second example demonstrates the use of a standalone client.

Defining the Client Deployment Descriptor

Principles

The Client component programmer is responsible for providing the deployment descriptor associated with the developed client components.

The client component provider's responsibilities and the Application Assembler's responsibilities are to provide an XML deployment descriptor that conforms to the deployment descriptor's XML DTD as defined in the Java ^TM Application Client Specification Version 1.4.(Refer to $JONAS_ROOT/xml/application-client_1_4.xsd or http://java.sun.com/xml/ns/j2ee/application-client_1_4.xsd).

To customize the Client components, information not defined in the standard XML deployment descriptor may be needed. Such information might include, for example, the mapping of the name of referenced resources to its JNDI name. This information can be specified during the deployment phase within another XML deployment descriptor that is specific to JOnAS. The JOnAS-specific deployment descriptor's XML schema is located in $JONAS_ROOT/xml/jonas-client_X_Y.xsd. The file name of the JOnAS-specific XML deployment descriptor must be 'jonas-client.xml'.

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).

The parser gets the specified schema via the classpath (schemas are packaged in the $JONAS_ROOT/lib/common/ow_jonas.jar file).

The standard deployment descriptor (application-client.xml) should contain structural information that includes the following:

A Client description
Environment entries
EJB references
Resource references
Resource env references
The callback handler to use

The JOnAS-specific deployment descriptor (jonas-client.xml) may contain information that includes the following::

The JNDI name of the external resources referenced by a Client component
The JNDI name of the external resources environment referenced by a Client component
The JNDI name of the beans referenced by a Client component
The security aspects including the jaas file, the jaas entry, and a login/password to use for a specific callback handler

Examples of Client Deployment Descriptors

Example of a standard Client Deployment Descriptor (application-client.xml):

<?xml version="1.0" encoding="UTF-8"?>

<application-client xmlns="http://java.sun.com/xml/ns/j2ee"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                    http://java.sun.com/xml/ns/j2ee/application-client_1_4.xsd"
                    version="1.4">

  <display-name>Client of the earsample</display-name>
  <description>client of the earsample</description>

  <env-entry>
    <env-entry-name>envEntryString</env-entry-name>
    <env-entry-type>java.lang.String</env-entry-type>
    <env-entry-value>Test of envEntry of application-client.xml file</env-entry-value>
  </env-entry>


  <ejb-ref>
    <ejb-ref-name>ejb/Op</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <home>org.objectweb.earsample.beans.secusb.OpHome</home>
    <remote>org.objectweb.earsample.beans.secusb.Op</remote>
    <ejb-link>secusb.jar#EarOp</ejb-link>
  </ejb-ref>

  <resource-ref>
    <res-ref-name>url/jonas</res-ref-name>
    <res-type>java.net.URL</res-type>
    <res-auth>Container</res-auth>
  </resource-ref>

  <callback-handler>org.objectweb.jonas.security.auth.callback.LoginCallbackHandler
  </callback-handler>

</application-client>

Example of a specific Client Deployment Descriptor (jonas-client.xml):

<?xml version="1.0" encoding="UTF-8"?>
<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://www.objectweb.org/jonas/ns/jonas-client_4_0.xsd">

  <jonas-resource>
    <res-ref-name>url/jonas</res-ref-name>
    <jndi-name>http://jonas.objectweb.org</jndi-name>
  </jonas-resource>

  <jonas-security>
    <jaasfile>jaas.config</jaasfile>
    <jaasentry>earsample</jaasentry>
    <username>jonas</username>
    <password>jonas</password>
  </jonas-security>

</jonas-client>

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:

<	<	less than
>	>	greater than
&	&	ampersand
'	'	apostrophe
"	"	quotation mark

Client Packaging

Principles

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:

application-client.xml: The standard xml deployment descriptor in the format defined in the J2EE 1.4 Specification. Refer to $JONAS_ROOT/xml/application-client_1_4.xsd.
jonas-client.xml: The optional JOnAS specific xml deployment descriptor in the format defined in $JONAS_ROOT/xml/jonas-client_X_Y.xsd.

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.

Example

Two examples of building a java client are provided.

The first is the build.xml of the earsample example with a java client inside the ear.
Refer to the client1jar and client2jar targets.
The second is the build.xml of the jaasclient example with a java standalone client which performs a lookup on an EJB.
Refer to the clientjars target.