Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.launcher
Class Launcher

    java.lang.Object
      |
      +--org.apache.commons.launcher.Launcher

All Implemented Interfaces:
  java.lang.Runnable

public class Launcher
extends java.lang.Object
implements java.lang.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.

Author:
  Patrick Luby

Field Summary
`static java.lang.Object[]` | `SUPPORTED_ANT_TASKS` List of supported Ant tasks.
`static java.lang.Object[]` | `SUPPORTED_ANT_TYPES` List of supported Ant types.

Constructor Summary
`Launcher()`

Method Summary
`static void` | `error(java.lang.String message, boolean usage)` Print a detailed error message and exit.
`static void` | `error(java.lang.Throwable t)` Print a detailed error message and exit.
`static java.io.File` | `getBootstrapDir()` Get the canonical directory of the class or jar file that this class was loaded.
`static java.io.File` | `getBootstrapFile()` Get the canonical directory or jar file that this class was loaded from.
`static java.lang.String` | `getJavaCommand()` Get the full path of the Java command to execute.
`static java.lang.String` | `getJDBCommand()` Get the full path of the JDB command to execute.
`static java.lang.String` | `getLocalizedString(java.lang.String key)` Get a localized property.
`static java.lang.String` | `getLocalizedString(java.lang.String key, java.lang.String className)` Get a localized property.
`static java.io.PrintStream` | `getLog()` Get the PrintStream that all output should printed to.
`static java.lang.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(java.io.PrintStream log)` Set the PrintStream that all output should printed to.
`static void` | `setVerbose(boolean verbose)` Set the verbose flag.
`static int` | `start(java.lang.String[] args)` Start the launching process.
`static boolean` | `stop()` Interrupt the `start(String[])` method.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### SUPPORTED_ANT_TASKS

    public static final java.lang.Object[] SUPPORTED_ANT_TASKS

  List of supported Ant tasks.

### SUPPORTED_ANT_TYPES

    public static final java.lang.Object[] SUPPORTED_ANT_TYPES

  List of supported Ant types.

Constructor Detail

### Launcher

    public Launcher()

Method Detail

### 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

### start

    public static int start(java.lang.String[] args)
                     throws java.lang.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.

  ``
  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:
    `java.lang.IllegalArgumentException` - if any error parsing the args parameter 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.

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

### error

    public static void error(java.lang.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(java.lang.Throwable t)

  Print a detailed error message and exit.

### getBootstrapDir

    public static java.io.File getBootstrapDir()
                                        throws java.io.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.

  Returns:
    the canonical directory of the class or jar file that this class file was loaded from
  Throws:
    `java.io.IOException` - if the canonical directory or jar file cannot be found

### getBootstrapFile

    public static java.io.File getBootstrapFile()
                                         throws java.io.IOException

  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:
    `java.io.IOException` - if the canonical directory or jar file cannot be found

### getJavaCommand

    public static java.lang.String getJavaCommand()

  Get the full path of the Java command to execute.

  Returns:
    a string suitable for executing a child JVM

### getJDBCommand

    public static java.lang.String getJDBCommand()

  Get the full path of the JDB command to execute.

  Returns:
    a string suitable for executing a child JDB debugger

### getLog

    public static java.io.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 java.lang.String getToolsClasspath()
                                              throws java.io.IOException

  Set the classpath to the current JVM's tools classes.

  Returns:
    a string suitable for use as a JVM's -classpath argument
  Throws:
    `java.io.IOException` - if the tools classes cannot be found

### getLocalizedString

    public static java.lang.String getLocalizedString(java.lang.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 java.lang.String getLocalizedString(java.lang.String key,
                                                      java.lang.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

### setLog

    public static void setLog(java.io.PrintStream log)

  Set the PrintStream that all output should printed to.

### setVerbose

    public static void setVerbose(boolean verbose)

  Set the verbose flag.

  Parameters:
    `verbose` - the value of the verbose flag

### killChildProcesses

    public static void killChildProcesses()

  Iterate through the list of synchronous child process launched by all of the `LaunchTask` instances.

### run

    public void run()

  Wrapper to allow the `killChildProcesses()` method to be invoked in a shutdown hook.

  Specified by:
    `run` in interface `java.lang.Runnable`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2001-2002 - Apache Software Foundation