Capsule (capsule 0.10.0 API)

java.lang.Object
- Capsule

All Implemented Interfaces:

java.lang.Runnable
```
public class Capsule
extends java.lang.Object
implements java.lang.Runnable
```
An application capsule.
This API is to be used by caplets (custom capsules) to programmatically (rather than declaratively) configure the capsule and possibly provide custom behavior.
All non-final protected methods may be overridden by caplets. These methods will usually be called once, but they must be idempotent, i.e. if called numerous times they must always return the same value, and produce the same effect as if called once.
Overridden methods need not be thread-safe, and are guaranteed to be called by a single thread at a time.
Overridable (non-final) methods must never be called directly by caplet code, except by their overrides.
Final methods implement various utility or accessors, which may be freely used by caplets.
For command line option handling, see registerOption.

Field Summary

Fields
Modifier and Type	Field and Description
`protected static int`	`LOG_DEBUG`
`protected static int`	`LOG_NONE`
`protected static int`	`LOG_QUIET`
`protected static int`	`LOG_VERBOSE`
`protected static java.lang.String`	`VERSION`

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`Capsule(Capsule pred)` Caplets that will be listed on the manifest's `Caplets` attribute must use this constructor.
`protected`	`Capsule(java.nio.file.Path jarFile, java.nio.file.Path cacheDir)` Constructs a capsule.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected java.lang.String[]`	`buildAppId()` Computes and returns application's ID.
`protected java.util.List<java.lang.String>`	`buildArgs(java.util.List<java.lang.String> args)` Returns a list of command line arguments to pass to the application.
`protected java.util.List<java.nio.file.Path>`	`buildBootClassPath()` Compiles and returns the application's boot classpath as a list of paths.
`protected java.util.List<java.nio.file.Path>`	`buildBootClassPathA()` Compiles and returns the paths to be appended to the application's boot classpath.
`protected java.util.List<java.nio.file.Path>`	`buildBootClassPathP()` Compiles and returns the paths to be prepended to the application's boot classpath.
`protected java.util.List<java.nio.file.Path>`	`buildClassPath()` Compiles and returns the application's classpath as a list of paths.
`protected java.util.Map<java.lang.String,java.lang.String>`	`buildEnvironmentVariables(java.util.Map<java.lang.String,java.lang.String> env)` Returns a map of environment variables (property-value pairs).
`protected java.util.Map<java.nio.file.Path,java.lang.String>`	`buildJavaAgents()` Returns all Java agents that will be launched with the application.
`protected java.util.List<java.lang.String>`	`buildJVMArgs()` Returns a list of JVM arguments.
`protected java.util.List<java.nio.file.Path>`	`buildNativeLibraryPath()` Compiles and returns the application's native library as a list of paths.
`protected java.lang.ProcessBuilder`	`buildProcess()` Constructs a `ProcessBuilder` that is later used to launch the capsule.
`protected java.util.Map<java.lang.String,java.lang.String>`	`buildSystemProperties()` Returns a map of system properties (property-value pairs).
`protected java.nio.file.Path`	`chooseJavaHome()` Chooses which Java installation to use for running the app.
`protected int`	`chooseLogLevel()` Chooses and returns the capsules log level.
`protected java.lang.String`	`chooseMode()` Chooses this capsule's mode.
`protected void`	`cleanup()` Called when the capsule exits after a successful or failed attempt to launch the application.
`protected java.lang.Object`	`clone()` Throws a `CloneNotSupportedException`
`protected static int`	`compareVersions(java.lang.String a, java.lang.String b)` Compares two dotted software versions.
`protected static int`	`compareVersions(java.lang.String a, java.lang.String b, int n)` Compares two dotted software versions, regarding only the first several version components.
`protected static void`	`copy(java.nio.file.Path source, java.nio.file.Path target)` Copies the source file or directory (recursively) to the target location.
`protected static void`	`delete(java.nio.file.Path path)` Deletes the given file or directory (even if nonempty).
`boolean`	`equals(java.lang.Object obj)`
`protected static java.util.List<java.lang.String>`	`exec(int numLines, java.lang.ProcessBuilder pb)` Executes a command and returns its output as a list of lines.
`protected static java.util.List<java.lang.String>`	`exec(int numLines, java.lang.String... cmd)` Executes a command and returns its output as a list of lines.
`protected static java.util.List<java.lang.String>`	`exec(java.lang.ProcessBuilder pb)` Executes a command and returns its output as a list of lines.
`protected static java.util.List<java.lang.String>`	`exec(java.lang.String... cmd)` Executes a command and returns its output as a list of lines.
`protected java.lang.String`	`expand(java.lang.String str)` Expands occurrences of `$VARNAME` in attribute values.
`protected void`	`extractCapsule()` Extracts the capsule's contents into the app cache directory.
`protected java.nio.file.Path`	`getAppCache()` This capsule's cache directory, or `null` if capsule has been configured not to extract.
`protected java.lang.String`	`getAppId()` Returns the app's ID.
`protected java.lang.String`	`getAppName()` The app's name
`protected java.lang.String`	`getAppVersion()` The app's version or `null` if unversioned.
`protected java.lang.String`	`getAttribute(java.lang.String attr)` Returns the value of the given manifest attribute with consideration to the capsule's mode.
`protected java.lang.String`	`getAttribute0(java.lang.String attr)`
`protected java.util.List<java.lang.String>`	`getDependencies()` Returns a list of dependencies, each in the format `groupId:artifactId:version[:classifier]` (classifier is optional)
`protected java.nio.file.Path`	`getJarFile()` This capsule's JAR file.
`protected java.nio.file.Path`	`getJavaExecutable()` Returns the path to the executable that will be used to launch Java.
`protected static java.nio.file.Path`	`getJavaExecutable(java.nio.file.Path javaHome)` Finds the path to the executable that will be used to launch Java within the given `javaHome`.
`protected java.nio.file.Path`	`getJavaHome()` The path to the Java installation this capsule's app will use.
`protected static java.util.Map<java.lang.String,java.nio.file.Path>`	`getJavaHomes()` Returns all found Java installations.
`protected java.util.List<java.lang.String>`	`getListAttribute(java.lang.String attr)` Returns the value of the given attribute (with consideration to the capsule's mode) as a list.
`protected java.nio.file.Path`	`getLocalRepo()` Returns the path to the local dependency repository.
`protected int`	`getLogLevel()` Capsule's log level
`protected java.util.Map<java.lang.String,java.lang.String>`	`getMapAttribute(java.lang.String attr, java.lang.String defaultValue)` Returns the value of the given attribute (with consideration to the capsule's mode) as a map.
`protected java.lang.String`	`getMode()` This capsule's current mode.
`protected java.lang.String`	`getModeDescription(java.lang.String mode)` Returns the description of the given mode.
`protected java.util.Set<java.lang.String>`	`getModes()` Returns the names of all modes defined in this capsule's manifest.
`protected java.util.List<java.lang.String>`	`getNativeDependencies()` Constructs this capsule's native dependency list.
`protected java.util.List<java.nio.file.Path>`	`getPlatformNativeLibraryPath()` Returns the default native library path for the Java platform the application uses.
`protected boolean`	`hasAttribute(java.lang.String attr)` Tests whether the given attribute is found in the manifest.
`int`	`hashCode()`
`protected boolean`	`isAppCacheUpToDate()` Whether the app cache is up to date.
`protected boolean`	`isLogging(int level)` Tests if the given log level is currently being logged
`protected static boolean`	`isMac()` Tests whether the current OS is MacOS.
`protected static boolean`	`isUnix()` Tests whether the current OS is UNIX/Linux.
`protected static boolean`	`isWindows()` Tests whether the current OS is Windows.
`protected boolean`	`isWrapperCapsule()` Whether or not this is an empty capsule
`protected static java.util.List<java.nio.file.Path>`	`listDir(java.nio.file.Path dir, java.lang.String glob, boolean regular)` Returns the contents of a directory.
`protected void`	`log(int level, java.lang.String str)` Prints a message to stderr if the given log-level is being logged.
`static void`	`main(java.lang.String[] args)`
`protected void`	`markCache()` Called after a successful completion of launch preparation if an app cache is used to write persistent information to the cache denoting the successful preparation.
`protected boolean`	`needsAppCache()`
`protected static java.util.List<java.lang.String>`	`parse(java.lang.String value)` Parses an attribute's value string into a list.
`protected static java.util.Map<java.lang.String,java.lang.String>`	`parse(java.lang.String value, java.lang.String defaultValue)` Parses an attribute's value string into an ordered map.
`protected java.lang.ProcessBuilder`	`prelaunch(java.util.List<java.lang.String> args)` Returns a configured `ProcessBuilder` that is later used to launch the capsule.
`protected java.lang.String`	`processOutgoingPath(java.nio.file.Path p)` Every path emitted by the capsule to the app's command line, system properties or environment variables is first passed through this method.
`protected static void`	`registerOption(java.lang.String optionName, java.lang.String methodName, java.lang.String defaultValue, java.lang.String description)` Registers a capsule command-line option.
`protected static java.lang.String`	`systemProperty(java.lang.String propName)` Same as `System.getProperty(propName)` but sets context for error reporting.
`protected boolean`	`testAppCacheUpToDate()` Tests if the app cache is up to date.
`java.lang.String`	`toString()`
`protected static java.lang.String`	`toStringValue(java.util.Collection<?> list)` Combines collection elements into a string that can be used as the value of an attribute.
`protected static java.lang.String`	`toStringValue(java.util.Map<?,?> map)` Combines map elements into a string that can be used as the value of an attribute.

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Runnable
run

- Field Detail
  - LOG_DEBUG
```
protected static final int LOG_DEBUG
```
    See Also:
    
    Constant Field Values
  - LOG_NONE
```
protected static final int LOG_NONE
```
    See Also:
    
    Constant Field Values
  - LOG_QUIET
```
protected static final int LOG_QUIET
```
    See Also:
    
    Constant Field Values
  - LOG_VERBOSE
```
protected static final int LOG_VERBOSE
```
    See Also:
    
    Constant Field Values
  - VERSION
```
protected static final java.lang.String VERSION
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Capsule
```
protected Capsule(Capsule pred)
```
    Caplets that will be listed on the manifest's Caplets attribute must use this constructor. Caplets are required to have a constructor with the same signature as this constructor, and pass their arguments to up to this constructor.
    
    Parameters:
    
    pred - The capsule preceding this one in the chain (caplets must not access the passed capsule in their constructor).
  - Capsule
```
protected Capsule(java.nio.file.Path jarFile,
                  java.nio.file.Path cacheDir)
```
    Constructs a capsule.
    This constructor is used by a caplet that will be listed in the manifest's Main-Class attribute. Caplets are encouraged to "override" the other constructor so that they may be listed in the Caplets attribute.
    This constructor or that of a subclass must not make use of any registered capsule options, as they may not have been properly pre-processed yet.
    
    Parameters:
    
    jarFile - the path to the JAR file
    
    cacheDir - the path to the (shared) Capsule cache directory
- Method Detail
  - buildAppId
```
protected java.lang.String[] buildAppId()
```
    Computes and returns application's ID.
    
    Returns:
    
    An array of exactly two strings, the first being the application's name, and the second, its version (or null if no version).
  - buildArgs
```
protected java.util.List<java.lang.String> buildArgs(java.util.List<java.lang.String> args)
```
    Returns a list of command line arguments to pass to the application.
    
    Parameters:
    
    args - The command line arguments passed to the capsule at launch
  - buildBootClassPath
```
protected java.util.List<java.nio.file.Path> buildBootClassPath()
```
    Compiles and returns the application's boot classpath as a list of paths.
  - buildBootClassPathA
```
protected java.util.List<java.nio.file.Path> buildBootClassPathA()
```
    Compiles and returns the paths to be appended to the application's boot classpath.
  - buildBootClassPathP
```
protected java.util.List<java.nio.file.Path> buildBootClassPathP()
```
    Compiles and returns the paths to be prepended to the application's boot classpath.
  - buildClassPath
```
protected java.util.List<java.nio.file.Path> buildClassPath()
```
    Compiles and returns the application's classpath as a list of paths.
  - buildEnvironmentVariables
```
protected java.util.Map<java.lang.String,java.lang.String> buildEnvironmentVariables(java.util.Map<java.lang.String,java.lang.String> env)
```
    Returns a map of environment variables (property-value pairs).
    
    Parameters:
    
    env - the current environment
  - buildJavaAgents
```
protected java.util.Map<java.nio.file.Path,java.lang.String> buildJavaAgents()
```
    Returns all Java agents that will be launched with the application.
    
    Returns:
    
    A map from the path to each agent to a string containing the agent arguments (or an empty string if none).
  - buildJVMArgs
```
protected java.util.List<java.lang.String> buildJVMArgs()
```
    Returns a list of JVM arguments.
  - buildNativeLibraryPath
```
protected java.util.List<java.nio.file.Path> buildNativeLibraryPath()
```
    Compiles and returns the application's native library as a list of paths.
  - buildProcess
```
protected java.lang.ProcessBuilder buildProcess()
```
    Constructs a ProcessBuilder that is later used to launch the capsule. The returned process builder should contain the command minus the application arguments (which are later constructed by buildArgs and appended to the command).
    While environment variables may be set at this stage, the environment is later configured by buildEnvironmentVariables.
    This implementation tries to create a process running a startup script, and, if one has not been set, constructs a Java process.
    This method should be overridden to add new types of processes the capsule can launch (like, say, Python scripts). If all you want is to configure the returned ProcessBuilder, for example to set IO stream redirection, you should override prelaunch.
    
    Returns:
    
    a ProcessBuilder (must never be null).
  - buildSystemProperties
```
protected java.util.Map<java.lang.String,java.lang.String> buildSystemProperties()
```
    Returns a map of system properties (property-value pairs).
  - chooseJavaHome
```
protected java.nio.file.Path chooseJavaHome()
```
    Chooses which Java installation to use for running the app.
    
    Returns:
    
    the path of the Java installation to use for launching the app, or null if the current JVM is to be used.
  - chooseLogLevel
```
protected int chooseLogLevel()
```
    Chooses and returns the capsules log level.
  - chooseMode
```
protected java.lang.String chooseMode()
```
    Chooses this capsule's mode. The mode is chosen during the preparations for launch (not at construction time).
  - cleanup
```
protected void cleanup()
```
    Called when the capsule exits after a successful or failed attempt to launch the application. If you override this method, you must make sure to call super.cleanup() even in the event of an abnormal termination (i.e. when an exception is thrown). This method must not throw any exceptions. All exceptions origination by cleanup must be wither ignored completely or printed to STDERR.
  - clone
```
protected final java.lang.Object clone()
                                throws java.lang.CloneNotSupportedException
```
    Throws a CloneNotSupportedException
    
    Overrides:
    
    clone in class java.lang.Object
    
    Throws:
    
    java.lang.CloneNotSupportedException
  - compareVersions
```
protected static final int compareVersions(java.lang.String a,
                                           java.lang.String b)
```
    Compares two dotted software versions.
    
    Parameters:
    
    a - first version
    
    b - second version
    
    Returns:
    
    0 if a == b; > 0 if a > b; < 0 if a < b;
  - compareVersions
```
protected static final int compareVersions(java.lang.String a,
                                           java.lang.String b,
                                           int n)
```
    Compares two dotted software versions, regarding only the first several version components.
    
    Parameters:
    
    a - first version
    
    b - second version
    
    n - the number of (most significant) components to consider
    
    Returns:
    
    0 if a == b; > 0 if a > b; < 0 if a < b;
  - copy
```
protected static void copy(java.nio.file.Path source,
                           java.nio.file.Path target)
                    throws java.io.IOException
```
    Copies the source file or directory (recursively) to the target location.
    
    Throws:
    
    java.io.IOException
  - delete
```
protected static void delete(java.nio.file.Path path)
                      throws java.io.IOException
```
    Deletes the given file or directory (even if nonempty).
    
    Throws:
    
    java.io.IOException
  - equals
```
public final boolean equals(java.lang.Object obj)
```
    Overrides:
    
    equals in class java.lang.Object
  - exec
```
protected static java.util.List<java.lang.String> exec(int numLines,
                                                       java.lang.ProcessBuilder pb)
                                                throws java.io.IOException
```
    Executes a command and returns its output as a list of lines. If the number of lines read is less than numLines, or if numLines < 0, then the method will wait for the child process to terminate, and throw an exception if the command returns an exit value != 0.
    
    Parameters:
    
    numLines - the maximum number of lines to read, or -1 for an unbounded number
    
    pb - the ProcessBuilder that will be used to launch the command
    
    Returns:
    
    the lines output by the command
    
    Throws:
    
    java.io.IOException
  - exec
```
protected static java.util.List<java.lang.String> exec(int numLines,
                                                       java.lang.String... cmd)
                                                throws java.io.IOException
```
    Executes a command and returns its output as a list of lines. If the number of lines read is less than numLines, or if numLines < 0, then the method will wait for the child process to terminate, and throw an exception if the command returns an exit value != 0.
    
    Parameters:
    
    numLines - the maximum number of lines to read, or -1 for an unbounded number
    
    cmd - the command
    
    Returns:
    
    the lines output by the command
    
    Throws:
    
    java.io.IOException
  - exec
```
protected static java.util.List<java.lang.String> exec(java.lang.ProcessBuilder pb)
                                                throws java.io.IOException
```
    Executes a command and returns its output as a list of lines. The method will wait for the child process to terminate, and throw an exception if the command returns an exit value != 0.
    Same as calling exec(-1, pb}.
    
    Parameters:
    
    pb - the ProcessBuilder that will be used to launch the command
    
    Returns:
    
    the lines output by the command
    
    Throws:
    
    java.io.IOException
  - exec
```
protected static java.util.List<java.lang.String> exec(java.lang.String... cmd)
                                                throws java.io.IOException
```
    Executes a command and returns its output as a list of lines. The method will wait for the child process to terminate, and throw an exception if the command returns an exit value != 0.
    Same as calling exec(-1, cmd}.
    
    Parameters:
    
    cmd - the command
    
    Returns:
    
    the lines output by the command
    
    Throws:
    
    java.io.IOException
  - expand
```
protected java.lang.String expand(java.lang.String str)
```
    Expands occurrences of $VARNAME in attribute values.
    
    Parameters:
    
    str - the original string
    
    Returns:
    
    the expanded string
  - extractCapsule
```
protected void extractCapsule()
                       throws java.io.IOException
```
    Extracts the capsule's contents into the app cache directory. This method may be overridden to write additional files to the app cache.
    
    Throws:
    
    java.io.IOException
  - getAppCache
```
protected final java.nio.file.Path getAppCache()
```
    This capsule's cache directory, or null if capsule has been configured not to extract.
  - getAppId
```
protected final java.lang.String getAppId()
```
    Returns the app's ID.
  - getAppName
```
protected final java.lang.String getAppName()
```
    The app's name
  - getAppVersion
```
protected final java.lang.String getAppVersion()
```
    The app's version or null if unversioned.
  - getAttribute
```
protected final java.lang.String getAttribute(java.lang.String attr)
```
    Returns the value of the given manifest attribute with consideration to the capsule's mode.
    
    Parameters:
    
    attr - the attribute
  - getAttribute0
```
protected final java.lang.String getAttribute0(java.lang.String attr)
```
  - getDependencies
```
protected java.util.List<java.lang.String> getDependencies()
```
    Returns a list of dependencies, each in the format groupId:artifactId:version[:classifier] (classifier is optional)
  - getJarFile
```
protected final java.nio.file.Path getJarFile()
```
    This capsule's JAR file.
  - getJavaExecutable
```
protected java.nio.file.Path getJavaExecutable()
```
    Returns the path to the executable that will be used to launch Java. The default implementation uses the capsule.java.cmd property or the JAVACMD environment variable, and if not set, returns the value of getJavaExecutable(getJavaHome()).
  - getJavaExecutable
```
protected static final java.nio.file.Path getJavaExecutable(java.nio.file.Path javaHome)
```
    Finds the path to the executable that will be used to launch Java within the given javaHome.
  - getJavaHome
```
protected final java.nio.file.Path getJavaHome()
```
    The path to the Java installation this capsule's app will use.
  - getJavaHomes
```
protected static java.util.Map<java.lang.String,java.nio.file.Path> getJavaHomes()
```
    Returns all found Java installations.
    
    Returns:
    
    a map from installations' versions to their respective paths
  - getListAttribute
```
protected final java.util.List<java.lang.String> getListAttribute(java.lang.String attr)
```
    Returns the value of the given attribute (with consideration to the capsule's mode) as a list. The items comprising attribute's value must be whitespace-separated.
    Same as parse(getAttribute(attr)).
    
    Parameters:
    
    attr - the attribute
  - getLocalRepo
```
protected final java.nio.file.Path getLocalRepo()
```
    Returns the path to the local dependency repository.
  - getLogLevel
```
protected final int getLogLevel()
```
    Capsule's log level
  - getMapAttribute
```
protected final java.util.Map<java.lang.String,java.lang.String> getMapAttribute(java.lang.String attr,
                                                                                 java.lang.String defaultValue)
```
    Returns the value of the given attribute (with consideration to the capsule's mode) as a map. The key-value pairs comprising attribute's value must be whitespace-separated, with each pair written as key=value.
    Same as parse(getAttribute(attr), defaultValue).
    
    Parameters:
    
    attr - the attribute
    
    defaultValue - a default value to use for keys without a value, or null if such an event should throw an exception
  - getMode
```
protected final java.lang.String getMode()
```
    This capsule's current mode.
  - getModeDescription
```
protected final java.lang.String getModeDescription(java.lang.String mode)
```
    Returns the description of the given mode.
  - getModes
```
protected final java.util.Set<java.lang.String> getModes()
```
    Returns the names of all modes defined in this capsule's manifest.
  - getNativeDependencies
```
protected java.util.List<java.lang.String> getNativeDependencies()
```
    Constructs this capsule's native dependency list.
    
    Returns:
    
    a list of native dependencies, each in the format groupId:artifactId:version[:classifier][,renameTo] (classifier and renameTo are optional).
  - getPlatformNativeLibraryPath
```
protected java.util.List<java.nio.file.Path> getPlatformNativeLibraryPath()
```
    Returns the default native library path for the Java platform the application uses.
  - hasAttribute
```
protected final boolean hasAttribute(java.lang.String attr)
```
    Tests whether the given attribute is found in the manifest.
    
    Parameters:
    
    attr - the attribute
  - hashCode
```
public final int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - isAppCacheUpToDate
```
protected final boolean isAppCacheUpToDate()
```
    Whether the app cache is up to date. This is the result returned from testAppCacheUpToDate().
  - isLogging
```
protected final boolean isLogging(int level)
```
    Tests if the given log level is currently being logged
  - isMac
```
protected static final boolean isMac()
```
    Tests whether the current OS is MacOS.
  - isUnix
```
protected static final boolean isUnix()
```
    Tests whether the current OS is UNIX/Linux.
  - isWindows
```
protected static final boolean isWindows()
```
    Tests whether the current OS is Windows.
  - isWrapperCapsule
```
protected final boolean isWrapperCapsule()
```
    Whether or not this is an empty capsule
  - listDir
```
protected static final java.util.List<java.nio.file.Path> listDir(java.nio.file.Path dir,
                                                                  java.lang.String glob,
                                                                  boolean regular)
```
    Returns the contents of a directory.
    Passing null as the glob pattern is the same as passing "*"
    
    Parameters:
    
    dir - the directory
    
    glob - the glob pattern to use to filter the entries, or null if all entries are to be returned
    
    regular - whether only regular files should be returned
  - log
```
protected final void log(int level,
                         java.lang.String str)
```
    Prints a message to stderr if the given log-level is being logged.
  - main
```
public static final void main(java.lang.String[] args)
```
  - markCache
```
protected void markCache()
                  throws java.io.IOException
```
    Called after a successful completion of launch preparation if an app cache is used to write persistent information to the cache denoting the successful preparation.
    
    Throws:
    
    java.io.IOException
  - needsAppCache
```
protected boolean needsAppCache()
```
    Returns:
    
    true if this capsule requires an app cache; false otherwise.
  - parse
```
protected static final java.util.List<java.lang.String> parse(java.lang.String value)
```
    Parses an attribute's value string into a list. The items comprising attribute's value must be whitespace-separated.
    
    Parameters:
    
    value - the attribute's value
  - parse
```
protected static final java.util.Map<java.lang.String,java.lang.String> parse(java.lang.String value,
                                                                              java.lang.String defaultValue)
```
    Parses an attribute's value string into an ordered map. The key-value pairs comprising string must be whitespace-separated, with each pair written as key=value.
    
    Parameters:
    
    value - the attribute's value
    
    defaultValue - a default value to use for keys without a value, or null if such an event should throw an exception
  - prelaunch
```
protected java.lang.ProcessBuilder prelaunch(java.util.List<java.lang.String> args)
```
    Returns a configured ProcessBuilder that is later used to launch the capsule. The ProcessBuilder's IO redirection is left in its default settings. Caplets may override this method to display a message prior to launch, or to configure the process's IO streams. For more elaborate manipulation of the Capsule's launched process, consider overriding buildProcess.
    
    Parameters:
    
    args - the application command-line arguments
    
    Returns:
    
    a configured ProcessBuilder (if null, the launch will be aborted).
  - processOutgoingPath
```
protected java.lang.String processOutgoingPath(java.nio.file.Path p)
```
    Every path emitted by the capsule to the app's command line, system properties or environment variables is first passed through this method. Caplets that relocate files should override it.
    
    Parameters:
    
    p - the path
    
    Returns:
    
    the processed path
  - registerOption
```
protected static final void registerOption(java.lang.String optionName,
                                           java.lang.String methodName,
                                           java.lang.String defaultValue,
                                           java.lang.String description)
```
    Registers a capsule command-line option. Must be called in the caplet's static initializer.
    Capsule options are system properties beginning with the prefix ".capsule", normally passed to the capsule as -D flags on the command line.
    Options can be top-level *actions* (like print dependency tree or list JVMs), in which case the methodName argument must be the name of a method used to launch the action instead of launching the capsule.
    Options can have a default value, which will be automatically assigned to the system property if undefined. The default values "true" and "false" are treated specially. If one of them is the assigned default value, and the system property is defined with with a value of the empty string, then it will be re-assigned the value "true".
    Simple Command Line Options for Wrapper Capsules
    When the capsule serves as a wrapper (i.e. it's an empty capsule used to launch an executable artifact or another capsule) then the options can also be passed to the capsule as simple command line options (arguments starting with a hyphen), with the "capsule." prefix removed, and every '.' character replaced with a '-'.
    These command line arguments will automatically be converted to system properties, which will take their value from the argument following the option (i.e. -option value), unless the option is given one of the special default values "true" or "false", in which case it is treated as a flag with no arguments (note that an option with the default value "true" will therefore not be able to be turned off if simple options are used).
    
    Parameters:
    
    optionName - the name of the system property for the option; must begin with "capsule.".
    
    methodName - if non-null, then the option is a top-level action (like print dependency tree or list JVMs), and this is the method which will run the action. The method must accept a single args parameter of type List<String>.
    
    defaultValue - the option's default value ("true" and "false" are specially treated; see above).
  - systemProperty
```
protected static final java.lang.String systemProperty(java.lang.String propName)
```
    Same as System.getProperty(propName) but sets context for error reporting.
  - testAppCacheUpToDate
```
protected boolean testAppCacheUpToDate()
                                throws java.io.IOException
```
    Tests if the app cache is up to date. The app cache directory is obtained by calling getAppCache. This creates a file in the app cache, whose timestamp is compared with the capsule's JAR timestamp.
    
    Throws:
    
    java.io.IOException
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - toStringValue
```
protected static final java.lang.String toStringValue(java.util.Collection<?> list)
```
    Combines collection elements into a string that can be used as the value of an attribute.
  - toStringValue
```
protected static final java.lang.String toStringValue(java.util.Map<?,?> map)
```
    Combines map elements into a string that can be used as the value of an attribute.

Class Capsule

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Runnable

Field Detail

LOG_DEBUG

LOG_NONE

LOG_QUIET

LOG_VERBOSE

VERSION

Constructor Detail

Capsule

Capsule

Method Detail

buildAppId

buildArgs

buildBootClassPath

buildBootClassPathA

buildBootClassPathP

buildClassPath

buildEnvironmentVariables

buildJavaAgents

buildJVMArgs

buildNativeLibraryPath

buildProcess

buildSystemProperties

chooseJavaHome

chooseLogLevel

chooseMode

cleanup

clone

compareVersions

compareVersions

copy

delete

equals

exec

exec

exec

exec

expand

extractCapsule

getAppCache

getAppId

getAppName

getAppVersion

getAttribute

getAttribute0

getDependencies

getJarFile

getJavaExecutable

getJavaExecutable

getJavaHome

getJavaHomes

getListAttribute

getLocalRepo

getLogLevel

getMapAttribute

getMode

getModeDescription

getModes

getNativeDependencies

getPlatformNativeLibraryPath

hasAttribute

hashCode

isAppCacheUpToDate

isLogging

isMac

isUnix

isWindows

isWrapperCapsule

listDir

log

main

markCache

needsAppCache

parse

parse