Capsule (capsule 0.8.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. The only exception to this rule is the launch method.
Overridden methods need not be thread-safe, and are guaranteed to be called by a single thread at a time.
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

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`

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 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`
`boolean`	`equals(Object obj)`
`protected String`	`expand(String str)` Expands occurrences of `$VARNAME` in attribute values.
`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`	`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`	`isEmptyCapsule()` Tests if this is an empty capsule.
`protected boolean`	`isLogging(int level)` Tests id 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 Process`	`launch(List<String> args)` Creates the `Process` this capsule will launch.
`protected static List<Path>`	`listDir(Path dir)` Returns the contents of a directory
`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()`
`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
- 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.
  - 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
  - equals
```
public final boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - expand
```
protected String expand(String str)
```
    Expands occurrences of $VARNAME in attribute values.
    
    Parameters:
    str - the original string
    
    Returns:
    the expanded string
  - 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.
  - 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
  - isEmptyCapsule
```
protected final boolean isEmptyCapsule()
```
    Tests if this is an empty capsule.
  - isLogging
```
protected final boolean isLogging(int level)
```
    Tests id the given log level is currently being logged
    
    Parameters:
    level -
  - 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.
  - launch
```
protected Process launch(List<String> args)
                  throws IOException,
                         InterruptedException
```
    Creates the Process this capsule will launch. Custom capsules may override this method to display a message prior to launch, or to configure the process's IO streams.
    
    Parameters:
    args - the application's command-line arguments (does not include JVM args)
    
    Returns:
    the process this capsule will launch
    
    Throws:
    
    IOException
    
    InterruptedException
  - listDir
```
protected static final List<Path> listDir(Path dir)
```
    Returns the contents of a directory
    
    Parameters:
    dir - the directory
  - main
```
public static final void main(String[] args0)
```
    Launches the capsule
  - 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()
```
  - 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

Constructor Detail

Capsule

Method Detail

buildAppId

buildArgs

buildBootClassPath

buildBootClassPathA

buildBootClassPathP

buildClassPath

buildEnvironmentVariables

buildJVMArgs

buildSystemProperties

chooseJavaHome

chooseLogLevel

chooseMode

clone

equals

expand

getAppCache

getAppId

getAttribute

getDependencies

getJarFile

getJavaHome

getJavaHomes

getListAttribute

getMapAttribute

getMode

getModeDescription

getModes

getNativeDependencies

hasAttribute

hashCode

isEmptyCapsule

isLogging

isMac

isUnix

isWindows

join

launch

listDir

main

mapSplit

myCapsule

split

toString