InfoCenter Home >
6: Administer applications >
6.6: Tools and resources quick reference >
6.6.0: About user assistance >
6.6.0.7: Launching Java application clients in the J2EE application client container

6.6.0.7: Launching Java application clients in the J2EE application client container

The J2EE specification requires support for a client container that runs standalone Java applications (known as J2EE application clients) and provides J2EE services to the applications. J2EE services include naming, security, and resource connections.

The WebSphere Application Server Java 2 Platform, Enterprise Edition (J2EE) Application client run time (launchClient) does not support the use of the embedded DataDirect database driver as a local client Java Database Connectivity (JDBC) resource. Attempting to do so results in a "License verification failed" error.

The DataDirect driver performs a license check to make sure you have a valid license to use the DataDirect drivers. A license key is provided by DataDirect and this key needs to be set as the on database connection objects using the oemID field. DataDirect has provided IBM a license key to be used by WebSphere Application Server run time when a database connection is created on the server. However, on the client, the J2EE specification requires a javax.sql.DataSource object to be returned to the client application instead of a database connection, as on the server. Therefore, WebSphere Application Server J2EE application client run time does not create or maintain database connection objects and cannot set the oemID license field. The client application code needs to create the connection object from the data source object returned by the application client run time and set the oemID field. IBM's agreement with DataDirect prohibits IBM from distributing the license key in a form that is usable by the client application in this situation. If the client application must access the database directly, then a client license needs to be acquired from DataDirect.

In general, WebSphere Application Server does not provide client database drivers. If your client application uses a database directly, you must provide the database drivers on the client machine. This could involve contacting your database vendor to acquire client database driver code and licenses.

Instead of accessing the database directly, it is recommended that your client application use an enterprise bean. Accessing a database through an enterprise bean eliminates the need to have database drivers on the client machine, since the database access is handled by the enterprise bean running on WebSphere Application Server.

Before using the tool

You are ready to run your client application using this tool after you have:

  1. Written the client application program
  2. Assembled and installed an application module (.ear file) in the application server runtime

Invoking the launchClient tool

J2EE application clients are launched using the launchClient shell, located in:

product_installation_root/bin/launchClient.bat

This command instantiates an instance of the launchClient class.

Application client runtime behavior

The launchClient batch command starts the application client runtime, which:

  • Initializes the client runtime
  • Loads the class that you designated as the main class with the application assembly tool
  • Runs the main method of the client application program

When your program terminates, the application client runtime cleans up the environment and the Java virtual machine ends.

Passing parameters

You have to pass parameters to the launchClient command. You can pass parameters to your client application program as well. The launchClient command allows you to do both.

The launchClient command requires that the first parameter is either:

  • an Ear file specifying the client application to launch
  • a request for launchClient usage information

All other parameters intended for the launchClient command must begin with the -CC prefix.

Parameters that are not Ear files, or usage requests, or that begin with the -CC prefix, are ignored by the application client runtime, and are passed directly to the client application program.

For more information on the launchClient parameters, refer to the main method in the launchClient javadoc.

launchClient retrieves parameters from three places:

  1. The command line
  2. A properties file
  3. System properties

The parameters are resolved in the order listed above, with command line values having the highest priority and system properties the lowest. This prioritization allows you to set and override default values.

Specifying the server name

By default, the launchClient command uses the environment variable COMPUTERNAME for the BootstrapHost property value. This setting is effective for testing your client application when it is installed on the same computer as the server. However, in other cases you need to override this value with the name of your server.

You can override the BootstrapHost value by invoking launchClient with the following parameters:

launchClient myapp.ear -CCBootstrapHost=abc.midwest.mycompany.com

You can also override the default by specifying the value in a properties file and passing the file name to launchClient.

Running a client application with security enabled

Security is controlled by the server. You do not need to configure security on the client because the client assumes that security is enabled. If security is not enabled, the server ignores the security request, and the client application works as expected.

Format of the launchClient properties file

You can store launchClient values in a properties file, a good method for distributing default values. A knowledgeable user can then override one or more values on the command line.

The format of the file is one launchClient -CC parameter per line without the -CC prefix. For example:

verbose=true
classpath=c:\mydir\util.jar;c:\mydir\harness.jar;c:\production\G19\global.jar
BootstrapHost=abc.westcoast.mycompany.com
tracefile=c:\WebSphere\mylog.txt

Command syntax reference

You can obtain additional help on this command by invoking it without arguments. Following is the result of one such invocation. The arguments are subject to change. For the definitive arguments and syntax, query the program.

IBM WebSphere Application Server, Release 4.0
J2EE Application Client Tool, Version 1.0
Copyright IBM Corp., 1997-2001
WSCL0012I: Processing command line arguments.

Usage: launchClient [<userapp.ear> | -help | -?] [-CC<name>=<value>] [app args]

where:

<userapp.ear>     = The path and name of the Ear file containing the client application.

-help, -?               = Print this help message.

where the -CC properties are for use by the Application Client Runtime:

-CCverbose              = <true|false> Use this option to display additional
informational messages. The default is false.

-CCclasspath            = A classpath value. When an application is launched,
the system classpath is not used. If you need to
access classes that are not in the ear file or part
of the resource classpaths, specify the appropriate
classpath here. Multiple paths may be concatenated.

-CCjar                  = The name of the client jar file within the EAR file
that contains the application you wish to launch.
This argument is only necessary when you have
multiple client jar files in the ear file.

-CCBootstrapHost        = The name of the host server you wish to connect to
initially. Format: your.server.ofchoice.com

-CCBootstrapPort        = The server port number. If not specified, the
WebSphere default value is used.

-CCinitonly             = <true|false> This option is intended for ActiveX
applications to initialize the Application Client
runtime without launching the client application.
The default is false.

-CCtrace                = <true|false> Use this option to have WebSphere write
debug trace information to a file. You may need this
information when reporting a problem to IBM Service.
The default is false.

-CCtracefile            = The name of the file to write trace information.
The default is to output to the console.

-CCpropfile             = Name of a Properties file containing launchClient
properties. In the file, specify the properties
without the -CC prefix. For example: verbose=true.

where "app args" are used by the client application and are ignored by
WebSphere.
Go to previous article: Starting and stopping Application Assembly Tool Go to next article: Expanding .ear files

 

 
Go to previous article: Starting and stopping Application Assembly Tool Go to next article: Expanding .ear files