org.apache.commons.launcher

Class Launcher

public class Launcher extends Object implements Runnable

A class that is used to launch a Java process. The primary purpose of this class is to eliminate the need for a batch or shell script to launch a Java process. Some situations where elimination of a batch or shell script may be desirable are:

Author: Patrick Luby

Field Summary
static Object[]SUPPORTED_ANT_TASKS
List of supported Ant tasks.
static Object[]SUPPORTED_ANT_TYPES
List of supported Ant types.
Method Summary
static voiderror(String message, boolean usage)
Print a detailed error message and exit.
static voiderror(Throwable t)
Print a detailed error message and exit.
static FilegetBootstrapDir()
Get the canonical directory of the class or jar file that this class was loaded.
static FilegetBootstrapFile()
Get the canonical directory or jar file that this class was loaded from.
static StringgetJavaCommand()
Get the full path of the Java command to execute.
static StringgetJDBCommand()
Get the full path of the JDB command to execute.
static StringgetLocalizedString(String key)
Get a localized property.
static StringgetLocalizedString(String key, String className)
Get a localized property.
static PrintStreamgetLog()
Get the PrintStream that all output should printed to.
static StringgetToolsClasspath()
Set the classpath to the current JVM's tools classes.
static booleanisStarted()
Get the started flag.
static booleanisStopped()
Get the stopped flag.
static voidkillChildProcesses()
Iterate through the list of synchronous child process launched by all of the {@link LaunchTask} instances.
voidrun()
Wrapper to allow the {@link #killChildProcesses()} method to be invoked in a shutdown hook.
static voidsetLog(PrintStream log)
Set the PrintStream that all output should printed to.
static voidsetVerbose(boolean verbose)
Set the verbose flag.
static intstart(String[] args)
Start the launching process.
static booleanstop()
Interrupt the {@link #start(String[])} method.

Field Detail

SUPPORTED_ANT_TASKS

public static final Object[] SUPPORTED_ANT_TASKS
List of supported Ant tasks.

SUPPORTED_ANT_TYPES

public static final Object[] SUPPORTED_ANT_TYPES
List of supported Ant types.

Method Detail

error

public static void error(String message, boolean usage)
Print a detailed error message and exit.

Parameters: message the message to be printed usage if true, print a usage statement after the message

error

public static void error(Throwable t)
Print a detailed error message and exit.

Parameters: message the exception whose stack trace is to be printed.

getBootstrapDir

public static File getBootstrapDir()
Get the canonical directory of the class or jar file that this class was loaded. This method can be used to calculate the root directory of an installation.

Returns: the canonical directory of the class or jar file that this class file was loaded from

Throws: IOException if the canonical directory or jar file cannot be found

getBootstrapFile

public static File getBootstrapFile()
Get the canonical directory or jar file that this class was loaded from.

Returns: the canonical directory or jar file that this class file was loaded from

Throws: IOException if the canonical directory or jar file cannot be found

getJavaCommand

public static String getJavaCommand()
Get the full path of the Java command to execute.

Returns: a string suitable for executing a child JVM

getJDBCommand

public static String getJDBCommand()
Get the full path of the JDB command to execute.

Returns: a string suitable for executing a child JDB debugger

getLocalizedString

public static String getLocalizedString(String key)
Get a localized property. This method will search for localized properties and will resolve ${...} style macros in the localized string.

Parameters: key the localized property to retrieve

Returns: the localized and resolved property value

getLocalizedString

public static String getLocalizedString(String key, String className)
Get a localized property. This method will search for localized properties and will resolve ${...} style macros in the localized string.

Parameters: key the localized property to retrieve className the name of the class to retrieve the property for

Returns: the localized and resolved property value

getLog

public static PrintStream getLog()
Get the PrintStream that all output should printed to. The default PrintStream returned in System.err.

Returns: the PrintStream instance to print output to

getToolsClasspath

public static String getToolsClasspath()
Set the classpath to the current JVM's tools classes.

Returns: a string suitable for use as a JVM's -classpath argument

Throws: IOException if the tools classes cannot be found

isStarted

public static boolean isStarted()
Get the started flag.

Returns: the value of the started flag

isStopped

public static boolean isStopped()
Get the stopped flag.

Returns: the value of the stopped flag

killChildProcesses

public static void killChildProcesses()
Iterate through the list of synchronous child process launched by all of the {@link LaunchTask} instances.

run

public void run()
Wrapper to allow the {@link #killChildProcesses()} method to be invoked in a shutdown hook.

setLog

public static void setLog(PrintStream log)
Set the PrintStream that all output should printed to.

Parameters: a PrintStream instance to print output to

setVerbose

public static void setVerbose(boolean verbose)
Set the verbose flag.

Parameters: verbose the value of the verbose flag

start

public static int start(String[] args)
Start the launching process. This method is essential the main(String[]) method for this class except that this method never invokes {@link System#exit(int)}. This method is designed for applications that wish to invoke this class directly from within their application's code.

Parameters: args command line arguments

Returns: the exit value of the last synchronous child JVM that was launched or 1 if any other error occurs

Throws: IllegalArgumentException if any error parsing the args parameter occurs

stop

public static boolean stop()
Interrupt the {@link #start(String[])} method. This is done by forcing the current or next scheduled invocation of the {@link LaunchTask#execute()} method to throw an exception. In addition, this method will terminate any synchronous child processes that any instances of the {@link LaunchTask} class have launched. Note, however, that this method will not terminate any asynchronous child processes that have been launched. Accordingly, applications that use this method are encouraged to always set the LaunchTask.TASK_NAME task's "waitForChild" attribute to "true" to ensure that the application that you want to control can be terminated via this method. After this method has been executed, it will not return until is safe to execute the {@link #start(String[])} method.

Returns: true if this method completed without error and false if an error occurred or the launch process is already stopped

Copyright (c) 2001-2002 - Apache Software Foundation