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
clone, equals, finalize, 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 com.ibm.websphere.client.applicationclient.ClientContainerException,
                   java.lang.IllegalArgumentException,
                   com.ibm.etools.archive.exception.OpenFailureException,
                   com.ibm.etools.archive.exception.NoModuleElementException,
                   com.ibm.etools.archive.exception.SaveFailureException,
                   com.ibm.websphere.client.applicationclient.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. 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.
altDD=AlternateDeploymentDescriptor
The name of an Alternate Deployment Descriptor. This must be used with jar property and is used to specify which Deployment Descriptor to use. This property is only necessary when a client jar file is configured with more than one Deployment Descriptor.
BootstrapHost=your.server.ofchoice.com
The name of the host server you wish to connect to initially. This value is used to create a provider URL for Enterprise Java Bean and Resource Environment References and also to set the java.naming.provider.url system property. For compatibility, this value will also be mapped to the system property com.ibm.CORBA.BootstrapHost.
BootstrapPort=<nnnn>
The server port number to use. This value is used to create a provider URL for Enterprise Java Bean and Resource Environment References and also to set the java.naming.provider.url system property. For compatibility, this value will also be mapped to the system property com.ibm.CORBA.BootstrapPort.
providerURL=<Any valid provider url string>
This value is used to provide bootstrap server information that the initial context factory can use to obtain an initial context. WebSphere's initial context factory can use either a CORBA object URL or an IIOP URL. CORBA object URLs are more flexible than IIOP URLs and are the recommended URL format to use. This value can contain more than one bootstrap server address. This feature can be used when attempting to obtain an initial context from a server cluster. The bootstrap server addresses for all servers in the cluster can be specified in the URL. The operation will succeed if at least one of the servers is running, eliminating a single point of failure. There is no guarantee of any particular order in which the address list will be processed. For naming operations, this value overrides -CCBootstrapHost and -CCBootstrapPort parameters. An example of a CORBA object URL specifying multiple systems: providerURL=corbaloc:iiop:myserver.mycompany.com:9810,:mybackupserver.mycompany.com:2809 For more information, see the naming sections of the InfoCenter. This value is also mapped to the system property java.naming.provider.url.
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.
securityManager=<enable|disable>
Use this option to have WebSphere enable and run with a security manager. The default is disable.
securityMgrClass=securitymanagerclassname
The fully qualified name of a class that implements a security manager. This is only used if securityManager is set to "enable". The default is java.lang.SecurityManager.
securityMgrPolicy=securitymanagerpolicyfilename
The name of a security manager policy file. This value is mapped to system property java.security.policy and is only used if securityManager is set to "enable". If not specified, the default is <product_installation_directory>/properties/client.policy.
D<property key>=<property value>
Use this option to have WebSphere set the specified system property during initialization. Do not use the = character after the D. For example: Dcom.ibm.test.property=testvalue You may specify multiple D<property key>=<property value> properties.
exitVM=<true|false>
Use this option to have WebSphere call System.exit() after the client application has completed. The default is false.
soapConnectorPort=<nnnn>
The soap connector port to use. If no port is entered, a default port will be used.
dumpJavaNameSpace=<true|false|long>
Prints out the java: portion of the WebSphere JNDI name space. Specifying the value true uses the short format which prints out the binding name and the type of the object bound at that location. Specifying the value long uses the long format which prints out the binding name, bound object type, local object, type, and string representation of the local object (i.e. IORs, string values, etc.). The default is false.

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.
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.
com.ibm.websphere.client.applicationclient.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.
javax.naming.NamingException

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. 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.
altDD=AlternateDeploymentDescriptor
The name of an Alternate Deployment Descriptor. This must be used with jar property and is used to specify which Deployment Descriptor to use. This property is only necessary when a client jar file is configured with more than one Deployment Descriptor.
-CCBootstrapHost=your.server.ofchoice.com
The name of the host server you wish to connect to initially. This value is used to create a provider URL for Enterprise Java Bean and Resource Environment References and also to set the java.naming.provider.url system property. For compatibility, this value will also be mapped to the system property com.ibm.CORBA.BootstrapHost.
-CCBootstrapPort=<nnnn>
The server port number to use. This value is used to create a provider URL for Enterprise Java Bean and Resource Environment References and also to set the java.naming.provider.url system property. For compatibility, this value will also be mapped to the system property com.ibm.CORBA.BootstrapPort.
-CCproviderURL=<Any valid provider url string>
This value is used to provide bootstrap server information that the initial context factory can use to obtain an initial context. WebSphere's initial context factory can use either a CORBA object URL or an IIOP URL. CORBA object URLs are more flexible than IIOP URLs and are the recommended URL format to use. This value can contain more than one bootstrap server address. This feature can be used when attempting to obtain an initial context from a server cluster. The bootstrap server addresses for all servers in the cluster can be specified in the URL. The operation will succeed if at least one of the servers is running, eliminating a single point of failure. There is no guarantee of any particular order in which the address list will be processed. For naming operations, this value overrides -CCBootstrapHost and -CCBootstrapPort parameters.
An example of a CORBA object URL specifying multiple systems: -CCproviderURL=corbaloc:iiop:myserver.mycompany.com:9810,:mybackupserver.mycompany.com:2809 For more information, see the naming sections of the InfoCenter. This value is mapped to the system property java.naming.provider.url.
-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.
-CCsecurityManager=<enable|disable>
Use this option to have WebSphere enable and run with a security manager. The default is disable.
-CCsecurityMgrClass=securitymanagerclassname
The fully qualified name of a class that implements a security manager. This is only used if securityManager is set to "enable". The default is java.lang.SecurityManager.
-CCsecurityMgrPolicy=securitymanagerpolicyfilename
The name of a security manager policy file. This value is mapped to system property java.security.policy and is only used if -CCsecurityManager is set to "enable". If not specified, the default is <product_installation_directory>/properties/client.policy.
-CCexitVM=<true|false>
Use this option to have WebSphere call the System.exit() method when your invoked client application has completed.
-CCD<property key>=<property value>
Use this option to have WebSphere set the specified system property during initialization. Do not use the = character after the D. For example: -CCDcom.ibm.test.property=testvalue You may specify multiple -CCD<property key>=<property value> parameters.
-CCexitVM=true|false
Use this option to have WebSphere call System.exit() after the client application has completed. The default is false.
-CCsoapConnectorPort=<nnnn>
The soap connector port to use. If no port is entered, a default port will be used.
-CCdumpJavaNameSpace=<true|false|long>
Prints out the java: portion of the WebSphere JNDI name space. Specifying the value true uses the short format which prints out the binding name and the type of the object bound at that location. Specifying the value long uses the long format which prints out the binding name, bound object type, local object, type, and string representation of the local object (i.e. IORs, string values, etc.). The default is false.

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=myserver.mycompany.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. The Application Client runtime would create the following provider URL using the BootstrapHost and BootstrapPort parameters: corbaloc:iiop:myserver.mycompany.com:904". 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.

Note: WebSphere provides a launchClient.bat command shell on Windows systems and a launchClient.sh command shell on Unix systems that you can use to run the launchClient class. It is recommended you use these command shells as they setup the java invocation with all the necessary java parameters and classpath information. The command shells are located in the <product_installation_directory>/bin directory.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.