JAR Packaging

The package goal packages any self-executable SeedStack application in a Capsule. A Capsule is a way of packaging and running any application with all its dependencies from a unique plain executable JAR.

Parameters

Parameters can be given as system properties (-DparameterName=parameterValue) or specified in the pom.xml plugin declaration:

Name Type Mandatory Description
capsuleVersion String No The capsule version to be used. If not given, the latest version discoverable is automatically used.
classpathEntries List of strings No The classpath entries to add to the application classpath.
Relative paths are resolved to the location of the capsule JAR.
The current user home path (~) can be used.
systemProperties List of strings No The system properties to set when launching the application.
environmentVariables List of strings No The environment variables to set when launching the application.
jvmArgs List of strings No The JVM arguments to apply when launching the application.
allowSnapshots - No If specified, the Capsule will allow SNAPSHOT dependencies to be used.

Custom Classpath

The classpath of the capsule can be augmented:

  • Statically with the classpathEntries plugin configuration attribute. In this case the entries are put in the JAR manifest and cannot be changed after the capsule has been built.
  • Dynamically with the capsule.classpath system property on the command-line used to run the capsule.

Syntax of Classpath entries

The following features are available when specifying a Classpath entry:

  • A tilde ~ character is resolved to the current user home directory,
  • A dot . character is resolved to the directory where the capsule is located,
  • When a plain directory is specified, it is added to the Classpath of the application as is,
  • When a directory suffixed with /* is specified, all the JAR files inside this directory are added to the Classpath of the application.

Static classpath

Classpath entries can be specified in the Maven configuration of the package goal:

<plugin>
    <groupId>org.seedstack</groupId>
    <artifactId>seedstack-maven-plugin</artifactId>
    <version>2.8.2</version>
    <executions>
        <execution>
            <id>build-capsule</id>
            <goals>
                <goal>package</goal>
            </goals>
            <configuration>
                <classpathEntries>
                    <classpathEntry>~/.app/etc</classpathEntry>
                    <classpathEntry>~/.app/lib/*</classpathEntry>
                    <classpathEntry>/opt/app/etc</classpathEntry>
                    <classpathEntry>/opt/app/lib/*</classpathEntry>
                </classpathEntries>
            </configuration>
        </execution>
    </executions>
</plugin>

In the example above:

  • etc directories will be added as-is to the classpath
  • JAR files contained in the lib directories will be directly added to the classpath.

The order of static entries is preserved in the classpath. All static entries are placed before the application entries so they can override them.

Dynamic Classpath

Classpath entries can be specified on the command-line using the capsule.classpath system property:

java -Dcapsule.classpath="/usr/local/app/etc:/user/local/app/lib/*" -jar my-capsule.jar

The order of dynamic entries is preserved in the classpath. All dynamic entries are placed before static entries in the classpath so they can override them.

Example

Standalone Capsule

A standalone Capsule packs all its dependencies and is completely self-contained. It is the default mode of operation. To build such a Capsule, use the following command:

mvn seedstack:package

Running a capsule

To run a capsule, you simply execute it as a plain executable JAR:

java [jvm-args] -jar my-capsule.jar [args...]

In addition to any argument already specified in the capsule manifest (with the plugin parameters described above), you can specify any argument to the JVM or to the program as usual.

A lot of options can be specified to alter the default behavior of the Capsule itself. Please refer to the Capsule user-guide for more information.

   

On this page


Edit