org.apache.commons.launcher
Class Launcher
java.lang.Object
org.apache.commons.launcher.Launcher
- Runnable
public class Launcher
extends java.lang.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:
- You want to avoid having to determining where certain application paths
are e.g. your application's home directory, etc. Determining this
dynamically in a Windows batch scripts is very tricky on some versions of
Windows or when softlinks are used on Unix platforms.
- You need to enforce certain properties e.g. java.endorsed.dirs when
running with JDK 1.4.
- You want to allow users to pass in custom JVM arguments or system
properties without having to parse and reorder arguments in your script.
This can be tricky and/or messy in batch and shell scripts.
- You want to bootstrap Java properties from a configuration file instead
hard-coding them in your batch and shell scripts.
- You want to provide localized error messages which is very tricky to do
in batch and shell scripts.
static void | error(String message, boolean usage) - Print a detailed error message and exit.
|
static void | error(Throwable t) - Print a detailed error message and exit.
|
static File | getBootstrapDir() - Get the canonical directory of the class or jar file that this class was
loaded.
|
static File | getBootstrapFile() - Get the canonical directory or jar file that this class was loaded
from.
|
static String | getJDBCommand() - Get the full path of the JDB command to execute.
|
static String | getJavaCommand() - Get the full path of the Java command to execute.
|
static String | getLocalizedString(String key) - Get a localized property.
|
static String | getLocalizedString(String key, String className) - Get a localized property.
|
static PrintStream | getLog() - Get the PrintStream that all output should printed to.
|
static String | getToolsClasspath() - Set the classpath to the current JVM's tools classes.
|
static boolean | isStarted() - Get the started flag.
|
static boolean | isStopped() - Get the stopped flag.
|
static void | killChildProcesses() - Iterate through the list of synchronous child process launched by
all of the
LaunchTask instances.
|
void | run() - Wrapper to allow the
killChildProcesses() method to be
invoked in a shutdown hook.
|
static void | setLog(PrintStream log) - Set the PrintStream that all output should printed to.
|
static void | setVerbose(boolean verbose) - Set the verbose flag.
|
static int | start(String[] args) - Start the launching process.
|
static boolean | stop() - Interrupt the
start(String[]) method.
|
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.
error
public static void error(String message,
boolean usage)
Print a detailed error message and exit.
message
- the message to be printedusage
- if true, print a usage statement after the message
error
public static void error(Throwable t)
Print a detailed error message and exit.
getBootstrapDir
public static File getBootstrapDir()
throws IOException
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.
- the canonical directory of the class or jar file that this class
file was loaded from
getBootstrapFile
public static File getBootstrapFile()
throws IOException
Get the canonical directory or jar file that this class was loaded
from.
- the canonical directory or jar file that this class
file was loaded from
getJDBCommand
public static String getJDBCommand()
Get the full path of the JDB command to execute.
- a string suitable for executing a child JDB debugger
getJavaCommand
public static String getJavaCommand()
Get the full path of the Java command to execute.
- a string suitable for executing a child JVM
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.
key
- the localized property to retrieve
- 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.
key
- the localized property to retrieveclassName
- the name of the class to retrieve the property for
- 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.
- the PrintStream instance to print output to
getToolsClasspath
public static String getToolsClasspath()
throws IOException
Set the classpath to the current JVM's tools classes.
- a string suitable for use as a JVM's -classpath argument
isStarted
public static boolean isStarted()
Get the started flag.
- the value of the started flag
isStopped
public static boolean isStopped()
Get the stopped flag.
- the value of the stopped flag
killChildProcesses
public static void killChildProcesses()
Iterate through the list of synchronous child process launched by
all of the
LaunchTask
instances.
setLog
public static void setLog(PrintStream log)
Set the PrintStream that all output should printed to.
setVerbose
public static void setVerbose(boolean verbose)
Set the verbose flag.
verbose
- the value of the verbose flag
start
public static int start(String[] args)
throws IllegalArgumentException
Start the launching process. This method is essential the
main(String[])
method for this class except that this method
never invokes System.exit(int)
. This method is designed for
applications that wish to invoke this class directly from within their
application's code.
args
- command line arguments
- the exit value of the last synchronous child JVM that was
launched or 1 if any other error occurs
stop
public static boolean stop()
Interrupt the
start(String[])
method. This is done
by forcing the current or next scheduled invocation of the
LaunchTask.execute()
method to throw an exception. In addition,
this method will terminate any synchronous child processes that any
instances of the
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
start(String[])
method.
- 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