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 can be given as system properties (
-DparameterName=parameterValue) or specified in the
pom.xml plugin declaration:
|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.|
The classpath of the capsule can be augmented:
- Statically with the
classpathEntriesplugin 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.classpathsystem 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.
Classpath entries can be specified in the Maven configuration of the
<plugin> <groupId>org.seedstack</groupId> <artifactId>seedstack-maven-plugin</artifactId> <version>2.7.4</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:
etcdirectories will be added as-is to the classpath
- JAR files contained in the
libdirectories 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.
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.
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:
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.