Copyright © 2008-2009 OW2 Consortium
This work is licensed under the Creative Commons Attribution-ShareAlike License. To view a copy of this license,visit http://creativecommons.org/licenses/by-sa/2.0/deed.en or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
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 Java EE client application can be
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 on a computer where a JONAS_TROOT is present , simply
jclient -? . 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
The client that must be launched by the client container is given
as an argument of the client container. example :
client.jar myApplication.ear or
java -jar client.jar
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
carol.properties is searched with the
following priority (high to low):
carol.propertiesspecified by the
-carolFileargument to the client container
carol.propertiespackaged into the client application (the jar client)
carol.propertiescontained in the
A convenient way is to update the
client.jar with a customized
carol.properties file. That is, use the
client.jar carol.properties command.
The client container
client.jar includes a
traceclient.properties file. This is the same file as the one
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
client.jar traceclient.properties command.
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
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.
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
-tmpDir to the
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
option to the client container.
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.
These application clients are described in details in Getting started with JOnAS 5
The Client component programmer is responsible for providing the java class of the Client annotated accordingly to the Java EE 5 Specification.
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 http://java.sun.com/xml/ns/javaee/application-client_5.xsd
To customize the Client components, information not defined in the standard XML deployment descriptor may be needed.
The JOnAS-specific deployment descriptor's XML schema is located
<?xml version="1.0" encoding="UTF-8"?> <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"> <display-name>OW2 JOnAS :: EAR Sample :: JMS Application Client</display-name> <!-- The JMS ConnectionFactory to use --> <resource-ref> <res-ref-name>jms/QueueConnectionFactory</res-ref-name> <res-type>javax.jms.QueueConnectionFactory</res-type> <res-auth>Container</res-auth> </resource-ref> <!-- The JMS Queue where Messages will be send --> <resource-env-ref> <resource-env-ref-name>jms/SampleQueue</resource-env-ref-name> <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type> </resource-env-ref> </application-client>
<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" > <jonas-resource> <res-ref-name>jms/QueueConnectionFactory</res-ref-name> <jndi-name>JQCF</jndi-name> </jonas-resource> <jonas-resource-env> <resource-env-ref-name>jms/SampleQueue</resource-env-ref-name> <jndi-name>SampleQueue</jndi-name> </jonas-resource-env> </jonas-client>
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:
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.
Two examples of building a java client are provided.
earsampleexample with a java client inside the ear. Refer to the client1jar and client2jar targets.
jaasclientexample with a java standalone client which performs a lookup on an EJB. Refer to the clientjars target.