Using the gradle-jnlp-plugin – part 1

2017-03-11

Page content

This collection of articles describe the gradle-jnlp-plugin from Tobias Schulte, hosted at Github.

The plugin produces a webstart distribution for a JavaSE application as required by the webstart specification. It creates the jnlp file and compresses/signs the jar files. The directory created by the plugin may then be uploaded to your static web server or embedded into your war file.

Applying the plug-in

The gradle-jnlp-plugin is hosted in JCenter and is registered in the Gradle Plug-in Portal. It is also recommended to apply the application plugin.

buildscript {
   repositories {
      jcenter()
   }
   dependencies {
      classpath 'de.gliderpilot.gradle.jnlp:gradle-jnlp-plugin:+'
   }
}
apply plugin: 'application'
apply plugin: 'de.gliderpilot.jnlp'

Relevant tasks

The gradle-jnlp-plugin provides three relevant tasks.


`createWebstartDir`	Bundles the project as a webstart distribution. Creates the `jnlp` file and compresses/signs the `jar` files. The directory created by this tasks may be uploaded to your static web server or embedded into your `war` file.
`webstartDistTar`	Bundles the webstart distribution within a .tar file.
`webstartDistZip`	Bundles the webstart distribution within a .zip file.

Customization

A jnlp extension is available for the project in order to describe the webstart distribution. The default values are reasonable most webstart requirement.

The gradle-jnlp-plugin assumes the main class declared for the application plugin. For a production ready application, you need to declare certificate to sign the jar files.

mainClassName = 'package.name.to.MainClass'
jnlp {
   signJarParams.keystore = 'keystore.ks'
   signJarParams.alias = 'myalias'
   signJarParams.storepass = 'mystorepass'
}

Describe the distribution

Following options are available within the jnlp extension with the purpose to describe the webstart distribution.


`href`	File name and file extension of the `jnlp` file created. Optional. Defaults to “launch.jnlp”
`codebase`	Base URL where the application is hosted. All relative URLs specified in href attributes in the `jnlp` file are using this URL as a base. Optional. When the application is distributed within a `war` file using some kind of jnlp servlet, the codebase should be “$$codebase”.
`spec`	The webstart specification required by the distribution. Optional. Defaults to “7.0”.
`mainClassName`	Fully qualified name of the class containing the main method. Optional. Defaults to `project.mainClassName`, as defined by the `application` plugin.

The available options are exactly the attribute names for the jnlp element within the jnlp file, as described by the jnlp syntax specification.

I recommend changing only, if needed, the href option. The users may prefer reading something like application_name.jnlp instead of launch.jnlp. All other options work well with their default value and there is no relevant reason to change them.

Example:

jnlp {
   href 'myapplication.jnlp'
   codebase 'http://gliderpilot.de'
   spec '7.0'
}

Describe the JVM

Following options are available within the jnlp extension with the purpose to describe minimal JVM requirements.


`j2seParams`	A map of key/value pairs that describe the JVM required to execute the application. Optional. Defaults to `[version: current-JVM-version]` Possible key names are:
	`version`	Ordered list of version ranges to use. For example, “1.7+” means that your application requise Java 7 or higher. Optional.
	href	The URL denoting the supplier of this version of java, and where it may be downloaded from. Optional.
	`java-vm-args`	Indicates an additional set of standard and non-standard virtual machine arguments that the application would prefer the JNLP Client to use when launching Java. Optional.
	`initial-heap-size`	Indicates the initial size of the Java heap. Optional.
	`max-heap-size`	Indicates the maximum size of the Java heap. Optional.

The available keys are exactly the attribute names for the java (or j2se) element within the jnlp file, as described by the jnlp syntax specification.

You may provide the JVM options within one line:

jnlp {
   j2seParams = [version: '7.0+', 'max-heap-size': '256m']
}

Or as individual attributes, which I prefer for better readability:

jnlp {
   j2seParams.version = '7.0+'
   j2seParams.'max-heap-size' = '256m'
}

I recommend changing only, if your application crashes without OutOfMemoryExceptions, the j2seParams.initial-heap-size/j2seParams.'max-heap-size' options. As far as I understand this plugin, if you set any j2seParams option, you also need to set the j2seParams.version manually.

Further customization options will be explained on my next article about the gradle-jnlp-plugin.