Capsule (capsule 0.9.0 API)

java.lang.Object
- Capsule

All Implemented Interfaces:

Runnable
```
public class Capsule
extends Object
implements Runnable
```
An application capsule.
This API is to be used by custom capsules to programmatically (rather than declaratively) configure the capsule and possibly provide custom behavior.
All non-final protected methods may be overridden by custom capsules. 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 custom capsule code, except by their overrides.
Final methods implement various utility or accessors, which may be freely used by custom capsules.

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 String`	`VERSION`

Constructor Summary

Constructors
Modifier Constructor and Description

protected Capsule(Path jarFile, Path cacheDir)
Constructs a capsule from the given JAR file.

Constructors
Modifier	Constructor and Description
`protected`	`Capsule(Path jarFile, Path cacheDir)` Constructs a capsule from the given JAR file.

Method Summary

Methods
Modifier and Type	Method and Description
`protected String`	`buildAppId()` Computes and returns application's ID
`protected List<String>`	`buildArgs(List<String> args)` Returns a list of command line arguments to pass to the application.
`protected List<Path>`	`buildBootClassPath()` Compiles and returns the application's boot classpath as a list of paths.
`protected List<Path>`	`buildBootClassPathA()` Compiles and returns the paths to be appended to the application's boot classpath.
`protected List<Path>`	`buildBootClassPathP()` Compiles and returns the paths to be prepended to the application's boot classpath.
`protected List<Path>`	`buildClassPath()` Compiles and returns the application's classpath as a list of paths.
`protected void`	`buildEnvironmentVariables(Map<String,String> env)` Returns a map of environment variables (property-value pairs).
`protected List<String>`	`buildJVMArgs()` Returns a list of JVM arguments.
`protected ProcessBuilder`	`buildProcess()` Constructs a `ProcessBuilder` that is later used to launch the capsule.
`protected Map<String,String>`	`buildSystemProperties()` Returns a map of system properties (property-value pairs).
`protected Path`	`chooseJavaHome()` Chooses which Java installation to use for running the app.
`protected int`	`chooseLogLevel()` Chooses and returns the capsules log level.
`protected String`	`chooseMode()` Chooses this capsule's mode.
`protected Object`	`clone()` Throws a `CloneNotSupportedException`
`protected static int`	`compareVersions(String a, String b)` Compares two dotted software versions.
`protected static int`	`compareVersions(String a, String b, int n)` Compares two dotted software versions, regarding only the first several version components.
`boolean`	`equals(Object obj)`
`protected static List<String>`	`exec(int numLines, ProcessBuilder pb)` Executes a command and returns its output as a list of lines.
`protected static List<String>`	`exec(int numLines, String... cmd)` Executes a command and returns its output as a list of lines.
`protected static List<String>`	`exec(ProcessBuilder pb)` Executes a command and returns its output as a list of lines.
`protected static List<String>`	`exec(String... cmd)` Executes a command and returns its output as a list of lines.
`protected String`	`expand(String str)` Expands occurrences of `$VARNAME` in attribute values.
`protected void`	`extractCapsule()` Extracts the capsule's contents into the app cache directory.
`protected Path`	`getAppCache()` This capsule's cache directory, or `null` if capsule has been configured not to extract.
`protected String`	`getAppId(List<String> args)` Returns the app's ID.
`protected String`	`getAttribute(String attr)` Returns the value of the given manifest attribute with consideration to the capsule's mode.
`protected List<String>`	`getDependencies()` Returns a list of dependencies, each in the format `groupId:artifactId:version[:classifier]` (classifier is optional)
`protected Path`	`getJarFile()` This capsule's JAR file.
`protected Path`	`getJavaExecutable()` Returns the path to the executable that will be used to launch Java.
`protected static Path`	`getJavaExecutable(Path javaHome)` Finds the path to the executable that will be used to launch Java within the given `javaHome`.
`protected Path`	`getJavaHome()` The path to the Java installation this capsule's app will use.
`protected static Map<String,Path>`	`getJavaHomes()` Returns all found Java installations.
`protected List<String>`	`getListAttribute(String attr)` Returns the value of the given attribute (with consideration to the capsule's mode) as a list.
`protected Map<String,String>`	`getMapAttribute(String attr, String defaultValue)` Returns the value of the given attribute (with consideration to the capsule's mode) as a map.
`protected String`	`getMode()` This capsule's current mode.
`protected String`	`getModeDescription(String mode)` Returns the description of the given mode.
`protected Set<String>`	`getModes()` Returns the names of all modes defined in this capsule's manifest.
`protected List<String>`	`getNativeDependencies()` Constructs this capsule's native dependency list.
`protected boolean`	`hasAttribute(String attr)` Tests whether the given attribute is found in the manifest.
`int`	`hashCode()`
`protected boolean`	`isAppCacheUpToDate()` Tests if the app cache is up to date.
`protected boolean`	`isEmptyCapsule()` Tests if this is an empty capsule.
`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 static String`	`join(Collection<?> coll, String separator)` Joins a collections into a string, separating elements with the given separator string.
`protected static List<Path>`	`listDir(Path dir)` Returns the contents of a directory
`protected void`	`log(int level, String str)` Prints a message to stderr if the given log-level is being logged.
`static void`	`main(String[] args0)` Launches the capsule.
`protected static Map<String,String>`	`mapSplit(String map, char kvSeparator, String separator, String defaultValue)` Splits a string into a map
`protected static Capsule`	`myCapsule()` Returns the singleton Capsule instance.
`protected ProcessBuilder`	`prelaunch(List<String> args)` Returns a configured `ProcessBuilder` that is later used to launch the capsule.
`protected static List<String>`	`split(String str, String separator)` Splits a string into a list using a regex separator
`String`	`toString()`

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 String VERSION
```
    See Also:
    Constant Field Values
- Constructor Detail
  - Capsule
```
protected Capsule(Path jarFile,
       Path cacheDir)
```
    Constructs a capsule from the given JAR file.
    
    Parameters:
    jarFile - the path to the JAR file
    cacheDir - the path to the (shared) Capsule cache directory
- Method Detail
  - buildAppId
```
protected String buildAppId()
```
    Computes and returns application's ID
  - buildArgs
```
protected List<String> buildArgs(List<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 List<Path> buildBootClassPath()
```
    Compiles and returns the application's boot classpath as a list of paths.
  - buildBootClassPathA
```
protected List<Path> buildBootClassPathA()
```
    Compiles and returns the paths to be appended to the application's boot classpath.
  - buildBootClassPathP
```
protected List<Path> buildBootClassPathP()
```
    Compiles and returns the paths to be prepended to the application's boot classpath.
  - buildClassPath
```
protected List<Path> buildClassPath()
```
    Compiles and returns the application's classpath as a list of paths.
  - buildEnvironmentVariables
```
protected void buildEnvironmentVariables(Map<String,String> env)
```
    Returns a map of environment variables (property-value pairs).
    
    Parameters:
    env - the current environment
  - buildJVMArgs
```
protected List<String> buildJVMArgs()
```
    Returns a list of JVM arguments.
  - buildProcess
```
protected 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
  - buildSystemProperties
```
protected Map<String,String> buildSystemProperties()
```
    Returns a map of system properties (property-value pairs).
  - chooseJavaHome
```
protected 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 String chooseMode()
```
    Chooses this capsule's mode. The mode is chosen during the preparations for launch (not at construction time).
  - clone
```
protected final Object clone()
                      throws CloneNotSupportedException
```
    Throws a CloneNotSupportedException
    
    Overrides:
    
    clone in class Object
    
    Throws:
    
    CloneNotSupportedException
  - compareVersions
```
protected static final int compareVersions(String a,
                  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(String a,
                  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;
  - equals
```
public final boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - exec
```
protected static List<String> exec(int numLines,
                ProcessBuilder pb)
                            throws 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:
    
    IOException
  - exec
```
protected static List<String> exec(int numLines,
                String... cmd)
                            throws 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:
    
    IOException
  - exec
```
protected static List<String> exec(ProcessBuilder pb)
                            throws 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.
    This is the 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:
    
    IOException
  - exec
```
protected static List<String> exec(String... cmd)
                            throws 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.
    This is the same as calling exec(-1, cmd}.
    
    Parameters:
    cmd - the command
    
    Returns:
    the lines output by the command
    
    Throws:
    
    IOException
  - expand
```
protected String expand(String str)
```
    Expands occurrences of $VARNAME in attribute values.
    
    Parameters:
    str - the original string
    
    Returns:
    the expanded string
  - extractCapsule
```
protected void extractCapsule()
```
    Extracts the capsule's contents into the app cache directory. This method may be overridden to write additional files to the app cache.
  - getAppCache
```
protected final Path getAppCache()
```
    This capsule's cache directory, or null if capsule has been configured not to extract.
  - getAppId
```
protected final String getAppId(List<String> args)
```
    Returns the app's ID. The arguments are required in case this is an empty capsule, in which case the ID is determined by the artifact supplied at the command line.
    
    Parameters:
    args - the command line arguments; may be null.
    
    Returns:
    the app ID
  - getAttribute
```
protected final String getAttribute(String attr)
```
    Returns the value of the given manifest attribute with consideration to the capsule's mode.
    
    Parameters:
    attr - the attribute
  - getDependencies
```
protected List<String> getDependencies()
```
    Returns a list of dependencies, each in the format groupId:artifactId:version[:classifier] (classifier is optional)
  - getJarFile
```
protected final Path getJarFile()
```
    This capsule's JAR file.
  - getJavaExecutable
```
protected 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 Path getJavaExecutable(Path javaHome)
```
    Finds the path to the executable that will be used to launch Java within the given javaHome.
  - getJavaHome
```
protected final Path getJavaHome()
```
    The path to the Java installation this capsule's app will use.
  - getJavaHomes
```
protected static Map<String,Path> getJavaHomes()
```
    Returns all found Java installations.
    
    Returns:
    a map from installations' versions to their respective paths
  - getListAttribute
```
protected final List<String> getListAttribute(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.
    
    Parameters:
    attr - the attribute
  - getMapAttribute
```
protected final Map<String,String> getMapAttribute(String attr,
                                 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.
    
    Parameters:
    attr - the attribute
  - getMode
```
protected final String getMode()
```
    This capsule's current mode.
  - getModeDescription
```
protected final String getModeDescription(String mode)
```
    Returns the description of the given mode.
    
    Parameters:
    mode -
    
    Returns:
    the description of the given mode, or null if no description is found.
  - getModes
```
protected final Set<String> getModes()
```
    Returns the names of all modes defined in this capsule's manifest.
  - getNativeDependencies
```
protected List<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).
  - hasAttribute
```
protected final boolean hasAttribute(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 Object
  - isAppCacheUpToDate
```
protected boolean isAppCacheUpToDate()
```
    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.
  - isEmptyCapsule
```
protected final boolean isEmptyCapsule()
```
    Tests if this is an empty capsule.
  - 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.
  - join
```
protected static final String join(Collection<?> coll,
          String separator)
```
    Joins a collections into a string, separating elements with the given separator string.
  - listDir
```
protected static final List<Path> listDir(Path dir)
```
    Returns the contents of a directory
    
    Parameters:
    dir - the directory
  - log
```
protected final void log(int level,
       String str)
```
    Prints a message to stderr if the given log-level is being logged.
  - main
```
public static final void main(String[] args0)
```
    Launches the capsule. A custom capsule may provide its own main method to add capsule actions, and then call this method if no custom action is performed.
  - mapSplit
```
protected static final Map<String,String> mapSplit(String map,
                          char kvSeparator,
                          String separator,
                          String defaultValue)
```
    Splits a string into a map
    
    Parameters:
    map - the string
    kvSeparator - the character separating each key from its corresponding value
    separator - a regex separator between key-value pairs
    defaultValue - A default value to use for keys without a value, or null if such an event should throw an exception
    
    Returns:
    the map
  - myCapsule
```
protected static Capsule myCapsule()
```
    Returns the singleton Capsule instance.
  - prelaunch
```
protected ProcessBuilder prelaunch(List<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. Custom capsules may override this method to display a message prior to launch, or to configure the process's IO streams. Other, more elaborate customization of the command are best done by overriding buildProcess.
    
    Parameters:
    args - the application command-line arguments
    
    Returns:
    a configured ProcessBuilder
  - split
```
protected static final List<String> split(String str,
                 String separator)
```
    Splits a string into a list using a regex separator
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

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

Method Detail

buildAppId

buildArgs

buildBootClassPath

buildBootClassPathA

buildBootClassPathP

buildClassPath

buildEnvironmentVariables

buildJVMArgs

buildProcess

buildSystemProperties

chooseJavaHome

chooseLogLevel

chooseMode

clone

compareVersions

compareVersions

equals

exec

exec

exec

exec

expand

extractCapsule

getAppCache

getAppId

getAttribute

getDependencies

getJarFile

getJavaExecutable

getJavaExecutable

getJavaHome

getJavaHomes

getListAttribute

getMapAttribute

getMode

getModeDescription

getModes

getNativeDependencies

hasAttribute

hashCode

isAppCacheUpToDate

isEmptyCapsule

isLogging

isMac

isUnix

isWindows

join

listDir

log

main

mapSplit

myCapsule

prelaunch

split

toString