JarCastingKEYSTONE : Bootstrap your java application
Keystone project is a bootstrap that loads your application and its dependencies from a single archive.
With his maven plugin and few line of configuration, your application will be available with all his dependencies in a single archive.
The four main ideas which make the difference with other solution are:
- all dependencies are not exploded in final archive, 'jar' file stay without anny modification, so manifest also...
- user our maven plugin to package all that you need (and we'll loading dependencies automatically for you)
- you could load native library
- you could restart your application
So, you will be able to run it as this:
java -jar myapp.jar
This project was born after some code on another project named 'winstone'. Class loading and dependencies packaging can be a nightmare when you did more than just a war file to deploy (war can be very difficult also, .. I known ...)
This project is now used for many application, like:
- distribution of tool (database managment, batch processing)
- installation tool with gui
- web server (winstone)
- little games
So it's time to start
Configure your project
<build>
<plugins>
<plugin>
<groupId>org.intelligents-ia</groupId>
<artifactId>keystone-plugin</artifactId>
<version>3.4</version>
<executions>
<execution>
<id>make-assembly</id>
<phase>package</phase>
<configuration>
<mainClass>your.class.Main</mainClass>
</configuration>
<goals>
<goal>custom</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
The single archive will be builded with your maven dependencies and main class is 'your.class.Main'.
Keystone Maven Plugin Parameters
- mainClass: your class ‘Main’ which implements:
public static void main(String[] args) - cleanUpLib: true | false (default true),
clean up folder named “lib” at startup before extraction of initial archive - cleanUpBeforeShutdown: true | false (default is false),
clean up folder named “lib” at shutdown - info: true | false (default is false),
level ‘INFO’ logs generated by the Keystone bootsrap - verbose: true | false (default is false),
level ‘VERBOSE’ logs generated by the Keystone bootsrap - logFile: Log file path.
Per default, all logs go on standard output. - minimalJvmVersion: minimal JVM specification version required.
- explodeDirectory: Root extracting archives embark with the bootstrap.
By default, this directory is the current directory if write operations are allowed on it, otherwise it is a temporary folder that is used. - finalName: Final artifact name.
By default, this is the name of the original artefact suffix “-boot”. Example for “sample.jar”, it will be “sample-boot.jar” - includedScope: regular expression, specify which dependencies scope will be included. By default, only 'test' scope are excluded.
- natives: add a list of native libraries.
- libraries: add a list of extra java libraries. Each path can be a file or a directory (Not recursive).
Each path can be a file or a directory (Not recursive).
<natives>
<paths>
<path>${basedir}/extra/timer.dll</path>
<path>${basedir}/extra/timer.so</path>
<path>${basedir}/extra-natives</path>
</paths>
</natives>
<libraries>
<paths>
<path>${basedir}/h2-driver.jar</path>
<path>${basedir}/drivers</path>
</paths>
</libraries>
Native libraries are supported in both way
- with plugin parameters
- within embedded jar
Use extra features: Restart your application when needed!
- add a new dependency on your project
- When you want to restart, simply throw this exception
In your pom:
<dependency>
<groupId>org.intelligents-ia</groupId>
<artifactId>keystone-boot</artifactId>
<version>3.4</version>
</dependency>
In your code:
throw new KeystoneException(KeystoneException.Operation.RESTART);
Releases Notes
3.5 Snapshot
TODO:
- remove deprecated maven plugin api
3.4
- support JDK 8
- update maven plugin (using 3.x api and keep 2.x compatibility)
- remove useless parameter "includeJavaHomeLib": always add to classpath application, archives from the JAVA_HOME / lib if it exists
- remove useless parameter "replaceProjectArtifact": archive packaged artifact should never replaces the current project
- remove useless parameter "includeSystemClassLoader": system classloader is parent of application classloader.
- fix exception handling of embedded application
3.3
- add properties "BootStrap.restarted" when system is restarted
- fix exception handling
- update pom for release keystone in central maven repository
- change group id from org.intelligents-ia.keystone to org.intelligents-ia
3.2
- configure dependencies scope with maven plugin, parameter 'includedScope'. By default, only 'test' scope is excluded (since 3.1).
- add optional parameter 'minimalJvmVersion' to check minimal jvm version on start
- update deprecated logback configuration
- update deprecated maven properties declaration
- update parent pom (1.4.7, to use new distribution management configuration)
3.1
- exclude only “test” scope artifacts
- add native support
- be able to load embedded native library file
- be able to load native library in classpath at runtime
- add plugin configuration utilities:
- add a path set of native libraries
- add a path set of extra java libraries
3.0
- Integrate super pom 1.4.4 and add git.properties
- Integrate keystone sample in this project
- use org.intelligents-ia:intelligents-ia as super pom
- extract all keystone-kernel and extras in another project:
- keystone project focus on bootstrap application, maven integration, restart features and pattern to update embedded java application at runtime
- keystone-kernel focus on micro kernel container (yes, i like playing…)
2.6.0
- Bootstrap: add stack trace when exception occurs
- Use Jackson libraries from github: com.fasterxml.jackson
- Fix header of license
- Add copy constructor on Version (keystone api)