Launcher

java.lang.Object
- org.graalvm.launcher.Launcher

Direct Known Subclasses:: LanguageLauncherBase

public abstract class Launcher
extends Object

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`Launcher.AbortException` Exception which shall abort the launcher execution.
`protected static class`	`Launcher.OS`
`protected static class`	`Launcher.VersionAction`
`static class`	`Launcher.VMType`

Field Summary

Fields
Modifier and Type Field and Description

static int LAUNCHER_OPTIONS_INDENT
Default option description indentation.

Fields
Modifier and Type	Field and Description
`static int`	`LAUNCHER_OPTIONS_INDENT` Default option description indentation.

Constructor Summary

Constructors
Modifier Constructor and Description

protected Launcher()

Constructors
Modifier	Constructor and Description
`protected`	`Launcher()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected Launcher.AbortException`	`abort(IOException e)` Exits the launcher, indicating failure because of the provided `IOException`.
`protected Launcher.AbortException`	`abort(IOException e, int exitCode)` Exits the launcher with the provided exit code because of the provided `IOException`.
`protected Launcher.AbortException`	`abort(String message)` Exits the launcher, indicating failure.
`protected Launcher.AbortException`	`abort(String message, int exitCode)` Exits the launcher, with the provided exit code.
`protected Launcher.AbortException`	`abort(Throwable t)` Exits the launcher, indicating failure because of the provided `Throwable`.
`protected Launcher.AbortException`	`abort(Throwable t, int exitCode)` Exits the launcher with the provided exit code because of the provided `Throwable`.
`protected Launcher.AbortException`	`abortInvalidArgument(String argument, String message)` Exits the launcher, indicating failure because of an invalid argument.
`protected Launcher.AbortException`	`abortInvalidArgument(String argument, String message, int exitCode)` Exits the launcher with the provided exit code because of an invalid argument.
`protected Launcher.AbortException`	`abortUnrecognizedArgument(String argument)` This is called to abort execution when an argument can neither be recognized by the launcher or as an option for the polyglot engine.
`protected boolean`	`canPolyglot()` Determines if the tool supports polyglot.
`protected abstract void`	`collectArguments(Set<String> options)` Add all known arguments to the `options` list.
`protected void`	`executeJVM(String classpath, List<String> jvmArgs, List<String> remainingArgs)` Called if a JVM has to be started instead of AOT binary.
`protected void`	`executePolyglot(List<String> mainArgs, boolean forceNative)` Called to execute the bin/polyglot launcher with the supplied options.
`protected Launcher.AbortException`	`exit()` Exits the launcher, indicating success.
`protected Launcher.AbortException`	`exit(int exitCode)` Exits the launcher with the provided exit code.
`protected abstract org.graalvm.options.OptionDescriptor`	`findOptionDescriptor(String group, String key)` Finds the a descriptor for the option.
`protected Launcher.VMType`	`getDefaultVMType()` The return value specifies the default VM when none of --jvm, --native options is used.
`protected PrintStream`	`getError()`
`protected Path`	`getGraalVMBinaryPath(String binaryName)` Returns filename of the binary, depending on OS.
`protected Path`	`getGraalVMHome()`
`protected Path`	`getLogFile()` Provides the name of the log file, if specified on the command line.
`protected String`	`getMainClass()` Returns the name of the main class for this launcher.
`protected PrintStream`	`getOutput()`
`protected static String`	`getProgramName()` Returns what is an equivalent of `argv[0]`}, i.e., the command that executed the launcher.
`static boolean`	`isAOT()` Returns true if the current launcher was compiled ahead-of-time to native code.
`protected boolean`	`isGraalVMAvailable()`
`protected boolean`	`isStandalone()`
`protected void`	`launcherOption(String option, String description)` Prints a line for a launcher option.
`protected void`	`maybeNativeExec(List<String> originalArgs, List<String> unrecognizedArgs, boolean isPolyglotLauncher)` Possibly re-executes the launcher when JVM or polyglot mode is requested; call only if `Launcher.isAOT()` is true.
`protected void`	`maybePrintAdditionalHelp(org.graalvm.options.OptionCategory helpCategory)` Should print tool-specific help.
`protected static OutputStream`	`newLogStream(Path path)` Creates a new log file.
`protected boolean`	`parseCommonOption(String defaultOptionPrefix, Map<String,String> polyglotOptions, boolean experimentalOptions, String arg)` Parses an option, returning success.
`protected void`	`parseUnrecognizedOptions(String defaultOptionPrefix, Map<String,String> polyglotOptions, List<String> unrecognizedArgs)` Parses otherwise unrecognized options.
`protected void`	`printDefaultHelp(org.graalvm.options.OptionCategory printCategory)` Prints default help text.
`protected abstract void`	`printHelp(org.graalvm.options.OptionCategory maxCategory)` Prints a help message to stdout.
`protected void`	`println(String... lines)` Prints sequence of lines to the output stream.
`protected void`	`println(String l)` Prints a single line to the output stream, terminated with newline.
`protected void`	`printOtherHelpCategory(String kind, String option)` Instructs that information about other help categories should be printed.
`protected abstract void`	`printVersion()` Prints version information on stdout.
`protected boolean`	`runLauncherAction()` Runs launcher's action as version print or help.
`protected void`	`setError(PrintStream ps)` Uses the defined output to print error messages.
`protected void`	`setOptionIndent(int indent)` Sets the indentation for option descriptions.
`protected void`	`setOutput(PrintStream ps)` Uses the defined output to print messages.
`protected void`	`warn(String message)`
`protected void`	`warn(String message, Object... args)`

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

- Field Detail
  - LAUNCHER_OPTIONS_INDENT
```
public static final int LAUNCHER_OPTIONS_INDENT
```
    Default option description indentation.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Launcher
```
protected Launcher()
```
- Method Detail
  - getLogFile
```
protected final Path getLogFile()
```
    Provides the name of the log file, if specified on the command line.
    
    Returns:
    
    log file Path. null if unspecified.
    
    Since:
    
    20.0
  - setOutput
```
protected final void setOutput(PrintStream ps)
```
    Uses the defined output to print messages.
    
    Parameters:
    
    ps - printStream to use as out
    
    Since:
    
    20.0
  - setError
```
protected final void setError(PrintStream ps)
```
    Uses the defined output to print error messages.
    
    Parameters:
    
    ps - printStream to use as err
    
    Since:
    
    20.0
  - getOutput
```
protected final PrintStream getOutput()
```
    Returns:
    
    the stream for regular output. Defaults to System.out
    
    Since:
    
    20.0
  - getError
```
protected final PrintStream getError()
```
    Returns:
    
    the stream for errors. Defaults to System.err
    
    Since:
    
    20.0
  - exit
```
protected final Launcher.AbortException exit()
```
    Exits the launcher, indicating success. This exits by throwing an Launcher.AbortException.
  - exit
```
protected final Launcher.AbortException exit(int exitCode)
```
    Exits the launcher with the provided exit code. This exits by throwing an Launcher.AbortException.
    
    Parameters:
    
    exitCode - the exit code of the launcher process.
  - abort
```
protected final Launcher.AbortException abort(String message)
```
    Exits the launcher, indicating failure. This aborts by throwing an Launcher.AbortException.
    
    Parameters:
    
    message - an error message that will be printed to stderr. If null, nothing will be printed.
  - abort
```
protected final Launcher.AbortException abort(String message,
                                              int exitCode)
```
    Exits the launcher, with the provided exit code. This aborts by throwing an Launcher.AbortException.
    
    Parameters:
    
    message - an error message that will be printed to stderr. If null, nothing will be printed.
    
    exitCode - the exit code of the launcher process.
  - abort
```
protected final Launcher.AbortException abort(Throwable t)
```
    Exits the launcher, indicating failure because of the provided Throwable. This aborts by throwing an Launcher.AbortException.
    
    Parameters:
    
    t - the exception that causes the launcher to abort.
  - abort
```
protected final Launcher.AbortException abort(Throwable t,
                                              int exitCode)
```
    Exits the launcher with the provided exit code because of the provided Throwable. This aborts by throwing an Launcher.AbortException.
    
    Parameters:
    
    t - the exception that causes the launcher to abort.
    
    exitCode - the exit code of the launcher process.
  - abort
```
protected final Launcher.AbortException abort(IOException e)
```
    Exits the launcher, indicating failure because of the provided IOException. This tries to build a helpful error message based on exception. This aborts by throwing an Launcher.AbortException.
    
    Parameters:
    
    e - the exception that causes the launcher to abort.
  - abort
```
protected final Launcher.AbortException abort(IOException e,
                                              int exitCode)
```
    Exits the launcher with the provided exit code because of the provided IOException. This tries to build a helpful error message based on exception. This aborts by throwing an Launcher.AbortException.
    
    Parameters:
    
    e - the exception that causes the launcher to abort.
    
    exitCode - the exit code of the launcher process
  - abortUnrecognizedArgument
```
protected Launcher.AbortException abortUnrecognizedArgument(String argument)
```
    This is called to abort execution when an argument can neither be recognized by the launcher or as an option for the polyglot engine.
    
    Parameters:
    
    argument - the argument that was not recognized.
  - abortInvalidArgument
```
protected final Launcher.AbortException abortInvalidArgument(String argument,
                                                             String message)
```
    Exits the launcher, indicating failure because of an invalid argument. This aborts by throwing an Launcher.AbortException.
    
    Parameters:
    
    argument - the problematic argument.
    
    message - an error message that is printed to stderr.
  - abortInvalidArgument
```
protected final Launcher.AbortException abortInvalidArgument(String argument,
                                                             String message,
                                                             int exitCode)
```
    Exits the launcher with the provided exit code because of an invalid argument. This aborts by throwing an Launcher.AbortException.
    
    Parameters:
    
    argument - the problematic argument.
    
    message - an error message that is printed to stderr.
    
    exitCode - the exit code of the launcher process.
  - warn
```
protected void warn(String message)
```
  - warn
```
protected void warn(String message,
                    Object... args)
```
  - setOptionIndent
```
protected final void setOptionIndent(int indent)
```
    Sets the indentation for option descriptions. Sets number of spaces in the first column reserved for option names. Defaults to Launcher.LAUNCHER_OPTIONS_INDENT.
    
    Parameters:
    
    indent - the new indent.
    
    Since:
    
    20.0
  - printHelp
```
protected abstract void printHelp(org.graalvm.options.OptionCategory maxCategory)
```
    Prints a help message to stdout. This only prints options that belong to categories maxCategory or less.
    
    Parameters:
    
    maxCategory - the maximum category of options that should be printed.
  - printVersion
```
protected abstract void printVersion()
```
    Prints version information on stdout.
  - collectArguments
```
protected abstract void collectArguments(Set<String> options)
```
    Add all known arguments to the options list.
    
    Parameters:
    
    options - list to which valid arguments must be added.
  - findOptionDescriptor
```
protected abstract org.graalvm.options.OptionDescriptor findOptionDescriptor(String group,
                                                                             String key)
```
    Finds the a descriptor for the option.
    
    Parameters:
    
    group - option group
    
    key - the option name (including the group)
    
    Returns:
    
    descriptor or null.
    
    Since:
    
    20.0
  - canPolyglot
```
protected boolean canPolyglot()
```
    Determines if the tool supports polyglot. Returns true, if --polyglot option is valid for this tool and polyglot launcher works for it. The default implementation returns false only when Launcher.isStandalone() is true.
    
    Returns:
    
    true, if polyglot is relevant in this launcher.
    
    Since:
    
    20.0
  - maybePrintAdditionalHelp
```
protected void maybePrintAdditionalHelp(org.graalvm.options.OptionCategory helpCategory)
```
    Should print tool-specific help. Regular languages print info on the installed tools and languages. The default implementation prints nothing.
    
    Parameters:
    
    helpCategory - category of options to print
    
    Since:
    
    20.0
  - getMainClass
```
protected String getMainClass()
```
    Returns the name of the main class for this launcher. Typically:
```
 return MyLauncher.class.getName();
 
```
  - getDefaultVMType
```
protected Launcher.VMType getDefaultVMType()
```
    The return value specifies the default VM when none of --jvm, --native options is used.
    
    Returns:
    
    the default VMType
  - isAOT
```
public static boolean isAOT()
```
    Returns true if the current launcher was compiled ahead-of-time to native code.
  - isGraalVMAvailable
```
protected boolean isGraalVMAvailable()
```
  - isStandalone
```
protected boolean isStandalone()
```
  - getGraalVMHome
```
protected Path getGraalVMHome()
```
  - getGraalVMBinaryPath
```
protected final Path getGraalVMBinaryPath(String binaryName)
```
    Returns filename of the binary, depending on OS. Binary will be searched in bin directory.
    
    Parameters:
    
    binaryName - binary name, without path.
    
    Returns:
    
    OS-dependent binary filename.
  - runLauncherAction
```
protected boolean runLauncherAction()
```
    Runs launcher's action as version print or help. Returns true, if the execution should terminate, e.g. after printing help. Launcher.parseCommonOption(java.lang.String, java.util.Map<java.lang.String, java.lang.String>, boolean, java.lang.String) should be called for commandline argument(s) prior to this method to set up flags to display help etc.
    
    Returns:
    
    true when execution should be terminated.
    
    Since:
    
    20.0
  - printDefaultHelp
```
protected void printDefaultHelp(org.graalvm.options.OptionCategory printCategory)
```
    Prints default help text. Prints options, starting with tool specific options. Launcher implementations can override to provide launcher-specific intro / summary.
    
    Parameters:
    
    printCategory - options category to print.
    
    Since:
    
    20.0
  - printOtherHelpCategory
```
protected void printOtherHelpCategory(String kind,
                                      String option)
```
    Instructs that information about other help categories should be printed.
    
    Parameters:
    
    kind - category kind name
    
    option - the option to print the category
    
    Since:
    
    20.0
  - parseUnrecognizedOptions
```
protected final void parseUnrecognizedOptions(String defaultOptionPrefix,
                                              Map<String,String> polyglotOptions,
                                              List<String> unrecognizedArgs)
```
    Parses otherwise unrecognized options. Terminates the application if an option is not among the generic launcher / VM ones.
    
    Parameters:
    
    defaultOptionPrefix - (language) prefix for the options
    
    polyglotOptions - options being built for the polyglot launcher
    
    unrecognizedArgs - arguments (options) to evaluate
    
    Since:
    
    20.0
  - parseCommonOption
```
protected boolean parseCommonOption(String defaultOptionPrefix,
                                    Map<String,String> polyglotOptions,
                                    boolean experimentalOptions,
                                    String arg)
```
    Parses an option, returning success. The method is called to parse `arg` option from the commandline, not recognized by the application. The method may contribute to the `polyglotOptions` (in/out parameter, modifiable) to alter polyglot behaviour. If the option is recognized, the method must return true.
    
    Parameters:
    
    defaultOptionPrefix - default prefix for the option names, derived from the launching application.
    
    polyglotOptions - options for polyglot engine
    
    experimentalOptions - true, if experimental options are explicitly allowed
    
    arg - argument to parse
    
    Returns:
    
    true, if the option was recognized.
    
    Since:
    
    20.0
  - launcherOption
```
protected void launcherOption(String option,
                              String description)
```
    Prints a line for a launcher option. Uses indentation set by Launcher.setOptionIndent(int) to align option's description. If option name is too long, description is printed on the next line, indented.
    
    Parameters:
    
    option - option name, including dash(es)
    
    description - description
    
    Since:
    
    20.0
  - println
```
protected final void println(String l)
```
    Prints a single line to the output stream, terminated with newline.
    
    Parameters:
    
    l - line text.
    
    Since:
    
    20.0
  - println
```
protected final void println(String... lines)
```
    Prints sequence of lines to the output stream. Each argument will be printed as a whole line, terminated by a newline.
    
    Parameters:
    
    lines - lines
    
    Since:
    
    20.0
  - getProgramName
```
protected static String getProgramName()
```
    Returns what is an equivalent of argv[0]}, i.e., the command that executed the launcher. If the launcher was executed via a symlink, this returns the symlink. If the launcher was executed via a command resolved via the user's PATH environment variable, this returns that command.
    
    Returns:
    
    The program name or null if not available.
  - maybeNativeExec
```
protected final void maybeNativeExec(List<String> originalArgs,
                                     List<String> unrecognizedArgs,
                                     boolean isPolyglotLauncher)
```
    Possibly re-executes the launcher when JVM or polyglot mode is requested; call only if Launcher.isAOT() is true. If the result is to run native, then it applies VM options on the current process. The method parses the unrecognizedArgs for --jvm/--native/--polyglot flags and --vm.* options. If JVM mode is requested, it execs a Java process configured with supported JVM parameters and system properties over this process - in this case, the method does not return (except errors).
    
    Parameters:
    
    originalArgs - the original arguments from main(), unmodified.
    
    unrecognizedArgs - a subset of originalArgs that was not recognized by AbstractLanguageLauncher.preprocessArguments(List, Map). All arguments recognized by maybeExec are removed from the list.
    
    isPolyglotLauncher - whether this is the PolyglotLauncher (bin/polyglot)
    
    Since:
    
    20.0
  - executeJVM
```
protected void executeJVM(String classpath,
                          List<String> jvmArgs,
                          List<String> remainingArgs)
```
    Called if a JVM has to be started instead of AOT binary. The method is only called in AOT mode. Subclasses may override to apply different options or launch mechanism
    
    Parameters:
    
    classpath - class path to be used with the JVM
    
    jvmArgs - arguments for the VM
    
    remainingArgs - main arguments
  - executePolyglot
```
protected void executePolyglot(List<String> mainArgs,
                               boolean forceNative)
```
    Called to execute the bin/polyglot launcher with the supplied options. Subclasses may eventually override and implement in a different way.
    
    Parameters:
    
    mainArgs - program arguments
  - newLogStream
```
protected static OutputStream newLogStream(Path path)
                                    throws IOException
```
    Creates a new log file. The method uses a supplemental lock file to determine the file is still opened for output; in that case, it creates a different file, named `path'1, `path`2, ... until it finds a free name. Files not locked (actively written to) are overwritten.
    
    Parameters:
    
    path - the desired output for log
    
    Returns:
    
    the OutputStream for logging
    
    Throws:
    
    IOException - in case of I/O error opening the file
    
    Since:
    
    20.0

Class Launcher

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LAUNCHER_OPTIONS_INDENT

Constructor Detail

Launcher

Method Detail

getLogFile

setOutput

setError

getOutput

getError

exit

exit

abort

abort

abort

abort

abort

abort

abortUnrecognizedArgument

abortInvalidArgument

abortInvalidArgument

warn

warn

setOptionIndent

printHelp

printVersion

collectArguments

findOptionDescriptor

canPolyglot

maybePrintAdditionalHelp

getMainClass

getDefaultVMType

isAOT

isGraalVMAvailable

isStandalone

getGraalVMHome

getGraalVMBinaryPath

runLauncherAction

printDefaultHelp

printOtherHelpCategory

parseUnrecognizedOptions

parseCommonOption

launcherOption

println

println

getProgramName

maybeNativeExec

executeJVM

executePolyglot

newLogStream