com.ibm.websphere.client.applicationclient
Class launchClient

java.lang.Object
  |
  +--com.ibm.websphere.client.applicationclient.launchClient

public class launchClient
extends java.lang.Object

The launchClient class is used to launch a J2EE WebSphere Application Client.


Constructor Summary
launchClient()
           
 
Method Summary
 void launch(java.lang.String filename, java.util.Properties p, java.lang.String[] argv)
          Launches a J2EE WebSphere Application Client.
static void main(java.lang.String[] argv)
          Launches a J2EE WebSphere Application Client.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

launchClient

public launchClient()
Method Detail

launch

public void launch(java.lang.String filename,
                   java.util.Properties p,
                   java.lang.String[] argv)
            throws ClientContainerException,
                   java.lang.IllegalArgumentException,
                   com.ibm.etools.archive.exception.OpenFailureException,
                   com.ibm.etools.archive.exception.NoModuleElementException,
                   com.ibm.etools.archive.exception.SaveFailureException,
                   NoMainClassException,
                   javax.naming.NamingException,
                   java.io.IOException,
                   java.util.zip.ZipException,
                   java.lang.ClassNotFoundException,
                   java.lang.NoSuchMethodException,
                   java.lang.IllegalAccessException,
                   java.lang.reflect.InvocationTargetException
Launches a J2EE WebSphere Application Client. It first creates the Application Client runtime that initializes the JNDI name space with the client application's EJB's and resources, and then it launches the client application.

The Properties parameter is for setting Application Client runtime properties. The list of valid properties is:

verbose=<true|false>
Outputs the parsed arguments, classpath, and other informational messages, which are useful for debugging. A value of true turns verbose on, and false turns it off. The default is false.
classpath=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.
jar=jarfilename
The name of the client application jar file within the ear file that contains the client application you wish to launch. This argument is only necessary when there are multiple client application jar files in the ear file; otherwise, launchClient will locate the client application. Generally, it is only necessary to specify the jar file name, but if the jar file was added to the ear file with a path, you will have to specify the path (relative to the root of the ear) as well. It is recommended you store the jar file in the root, however.
BootstrapHost=your.server.ofchoice.com
The name of the host server you wish to connect to initially. This value will be mapped to the system property com.ibm.CORBA.BootstrapHost.
BootstrapPort=<nnnn>
The server port number to use. This value will be mapped to the system property com.ibm.CORBA.BootstrapPort.
trace=<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.
tracefile=tracefilename
The path/name of the file to write trace information to. The file will be created if it doesn't exist.
initonly=<true|false>
This option is intended for ActiveX applications to initialize the Application Client runtime without launching the client application.

Here's a programming example:

FileInputStream fis = new FileInputStream("c:\\production\\myapp.properties");
Properties p = new Properties();
p.load(fis);
p.setProperty("verbose", "true");
p.setProperty("classpath", "c:\abc\def.jar;c:\mystuff.jar");
String myargs[] = {"-store=12345", "-unit=#77211", "-verbose", "minneapolis"};
launchClient lc = new launchClient();
lc.launch("c:\\production\\myapp.ear", p, myargs);

Parameters:
filename -
The .ear file with the Application Client to launch.
p -
A list of properties intended for the Application Client runtime.
argv[] -
A list of arguments to pass directly to the client application being launched. These arguments are ignored by WebSphere.
Throws:
ClientContainerException -
This is a generic exception for the J2EE Application Client runtime. Refer to the help for the message embedded in the exception.
java.lang.IllegalArgumentException -
Thrown if a bad argument is passed to launch.
com.ibm.etools.archive.exception.OpenFailureException -
Thrown if an error occurs while opening the .ear file.
com.ibm.etools.archive.exception.NoModuleElementException -
Thrown if an error occurs while opening the Application Client file.
com.ibm.etools.archive.exception.SaveFailureException -
Thrown if an error occurs while saving the .ear file to the temporary directory.
NoMainClassException -
Thrown if the manifest in the client application .jar file does not indicate the name of the main class to launch.
javax.naming.NamingException
Thrown - if the J2EE name space cannot be initialized on the server.
java.io.IOException -
Thrown if an error occurs while opening the .ear file or the client application .jar file, or if an error occurs while saving the .ear file to the temporary directory.
java.util.zip.ZipException -
Thrown if a ZIP error occurs while processing the .ear file or the client application .jar file.
java.lang.ClassNotFoundException -
Thrown if the main class cound not be found.
java.lang.NoSuchMethodException -
Thrown if no main method exists in the main class.
java.lang.IllegalAccessException -
Thrown if launchClient doesn't have access to the main method in the main class.
java.lang.reflect.InvocationTargetException -
This is a checked exception that wraps an exception thrown by an invoked method or constructor.

main

public static void main(java.lang.String[] argv)
Launches a J2EE WebSphere Application Client. It first creates the Application Client runtime that initializes the JNDI name space with the client application's EJB's and resources, and then it launches the client application.

The arguments must be in the following format:

[<userapp.ear> | -help | -?] [-CC<Property>=<value>] [application arguments]

The first argument must be the .ear file with the client application to launch, or it can be -help or -?, which will output usage information and exit.

The list of valid -CC properties is:

-CCverbose=<true|false>
Outputs the parsed arguments, classpath, and other informational messages, which are useful for debugging. A value of true turns verbose on, and false turns it off. 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.
-CCpropfile=propfilename
A file where you can store -CC properties for launchClient. In the file, specify the properties without the -CC prefix. For example: verbose=true
-CCjar=jarfilename
The name of the client application jar file within the ear file that contains the client application you wish to launch. This argument is only necessary when there are multiple client application jar files in the ear file; otherwise, launchClient will locate the client application. Generally, it is only necessary to specify the jar file name, but if the jar file was added to the ear file with a path, you will have to specify the path (relative to the root of the ear) as well. It is recommended you store the jar file in the root, however.
-CCBootstrapHost=your.server.ofchoice.com
The name of the host server you wish to connect to initially. This value will be mapped to the system property com.ibm.CORBA.BootstrapHost.
-CCBootstrapPort=<nnnn>
The server port number to use. This value will be mapped to the system property com.ibm.CORBA.BootstrapPort.
-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.
-CCtracefile=tracefilename
The path/name of the file to write trace information to. The file will be created if it doesn't exist.
-CCinitonly=<true|false>
This option is intended for ActiveX applications to initialize the Application Client runtime without launching the client application.

Note: There is no space between the -CC and the property. Also, you may specify as many -CC properties as you wish.

The first parameter (the ear file, -help, or -?) and the -CC arguments are passed to the Application Client runtime. All others are passed directly to the client application being launched and are ignored by WebSphere.

Here's a sample command line invocation:

java -Dcom.ibm.CORBA.BootstrapHost=gungho.blue.ibm.com com.ibm.websphere.client.applicationclient.launchClient c:\production\myapp.ear -CCBootstrapPort=904 -CCclasspath=c:\abc\def.jar;c:\mystuff.jar -CCverbose=true -store=12345 -unit=#77211 minneapolis

This would launch the client application stored in c:\production\myapp.ear. Java would set the system properties com.ibm.CORBA.BootstrapHost and com.ibm.CORBA.BootstrapPort to gungho.blue.ibm.com and 904, respectively. The arguments -CCverbose=true and -CCclasspath=c:\abc\def.jar;c:\mystuff.jar would be used by the Application Client runtime, and the arguments -store=12345 -unit=#77211 -verbose minneapolis would be passed to the client application being launched.

Parameters:
argv[] - The list of command line arguments that were passed to the java command.