13 Using Java EE Client Application Modules

This chapter describes how Java EE specifies a standard for including client application code (a client module) in an EAR file. This allows the client side of an application to be packaged along with the other modules that make up the application.

The client module is declared in the META-INF/application.xml file of the EAR using a <java> tag. See "Enterprise Application Deployment Descriptor Elements" in Developing Applications for Oracle WebLogic Server.

Note:

The <java> tag is often confused to be a declaration of Java code that can be used by the server-side modules. This is not its purpose, it is used to declare client-side code that runs outside of the server-side container.

A client module is basically a JAR file containing a special deployment descriptor named META-INF/application-client.xml. This client JAR file also contains a Main-Class entry in its META-INF/MANIFEST.MF file to specify the entry point for the program. For more information on the application-client.xml file, see Appendix A, "Client Application Deployment Descriptor Elements."

The following sections provide information on using client application modules:

Extracting a Client Application

WebLogic Server includes two utilities that facilitate the use of client modules. They are:

  • weblogic.ClientDeployer—Extracts the client module from the EAR and prepares it for execution.

  • weblogic.j2eeclient.Main—Executes the client code.

You use the weblogic.ClientDeployer utility to extract the client-side JAR file from a Java EE EAR file, creating a deployable JAR file. Execute the weblogic.ClientDeployer class on the Java command line using the following syntax:

java weblogic.ClientDeployer ear-file client1 [client2 client3 ...]

The ear-file argument is a Java archive file with an .ear extension or an expanded directory that contains one or more client application JAR files.

The client arguments specify the clients you want to extract. For each client you name, the weblogic.ClientDeployer utility searches for a JAR file within the EAR file that has the specified name containing the .jar extension.

For example, consider the following command:

java weblogic.ClientDeployer app.ear myclient

This command extracts myclient.jar from app.ear. As it extracts, the weblogic.ClientDeployer utility performs two other operations.

  • It ensures that the JAR file includes a META-INF/application-client.xml file. If it does not, an exception is thrown.

  • It reads from a file named myclient.runtime.xml and creates a weblogic-application-client.xml file in the extracted JAR file. This is used by the weblogic.j2eeclient.Main utility to initialize the client application's component environment (java:comp/env). For information on the format of the runtime.xml file, see Client Application Deployment Descriptor Elements.

Note:

You create the <client>.runtime.xml descriptor for the client program to define bindings for entries in the module's META-INF/application-client.xml deployment descriptor.

Executing a Client Application

Once the client-side JAR file is extracted from the EAR file, use the weblogic.j2eeclient.Main utility to bootstrap the client-side application and point it to a WebLogic Server instance using the following command:

java weblogic.j2eeclient.Main clientjar URL [application args]

For example:

java weblogic.j2eeclient.Main myclient.jar t3://localhost:7001

The weblogic.j2eeclient.Main utility creates a component environment that is accessible from java:comp/env in the client code.

If a resource mentioned by the application-client.xml descriptor is one of the following types, the weblogic.j2eeclient.Main class attempts to bind it from the global JNDI tree on the server to java:comp/env using the information specified earlier in the myclient.runtime.xml file.

  • ejb-ref

  • javax.jms.QueueConnectionFactory

  • javax.jms.TopicConnectionFactory

  • javax.mail.Session

  • javax.sql.DataSource

The user transaction is bound into java:comp/UserTransaction.

The <res-auth> tag in the application.xml deployment descriptor is currently ignored and should be entered as application. Oracle does not currently support form-based authentication.

The rest of the client environment is bound from the weblogic-application-client.xml file created by the weblogic.ClientDeployer utility.

The weblogic.j2eeclient.Main class emits error messages for missing or incomplete bindings.

Once the environment is initialized, the weblogic.j2eeclient.Main utility searches the JAR manifest of the client JAR for a Main-Class entry. The main method on this class is invoked to start the client program. Any arguments passed to the weblogic.j2eeclient.Main utility after the URL argument is passed on to the client application.

The client JVM must be able to locate the Java classes you create for your application and any Java classes your application depends upon, including WebLogic Server classes. You stage a client application by copying all of the required files on the client into a directory and bundling the directory in a JAR file. The top level of the client application directory can have a batch file or script to start the application. Create a classes/ subdirectory to hold Java classes and JAR files, and add them to the client Class-Path in the startup script.

You may also want to package a Java Runtime Environment (JRE) with a Java client application.

Note:

The use of the Class-Path manifest entries in client module JARs is not portable, as it has not yet been addressed by the Java EE standard.