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:
The J2EE 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,
java -jar $JONAS_ROOT/lib/client.jar -?. This will launch the
client container and display usage information about this client
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.
java -jar client.jar myApplication.ear
java -jar client.jar myClient.jar.
Defining the JNDI access and the protocol to use is an important part of
The JOnAS server, as well as the ClientContainer, uses the values specified in the
This file can be used at different levels.
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
carol.properties of a
client.jar with a customized
file. That is, use the
jar -uf client.jar carol.properties
The client container
client.jar includes a
traceclient.properties file. This is the same file as the one in
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
-uf 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,
-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
To invoke the client container with an ear, such as
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.
earsample example in the JOnAS examples has two java clients
in its ear.
By default, the client container will use the system property
To use another temporary directory, specify the path by giving the argument
-tmpDirto the client
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.
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.
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
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 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:
The JOnAS-specific deployment descriptor (jonas-client.xml) may contain information that includes the following::
<?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>
<?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>
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:
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.
jaasclientexample with a java standalone client which performs a lookup on an EJB.