NetBeans JNLP launcher

$Revision: 1.3 $
Changes: available in CVS
For info on WebStarting NetBeans 4.x please visit jnlpInstaller.html.

This document describes deployment of the NetBeans platform using JNLP protocol. There were several requests for this functionality: overall discussion about possible implementations can be found here: issue 28376. More specifically status of the described solution can be found as issue 35036.

This document describes the implementation and can also serve as a User's Guide (better term could be Administrator's Guide). The solution is being developed in netbeans.org cvs repository in folder installer/jnlp

Description of the solution

Currently implemented solution is based on following assumptions:

• JNLP launcher starts NetBeans with all permissions.
• Modifications to the module system are needed and are desribed in this document.
• JNLP protocol is used for further updates.

Build script

The build script installer/jnlp/build.xml expects to be called from the main build script nbbuild/build.xml by a target like this:

  <target name="all-installer/jnlp" depends="all-core,all-openide, all-openide/io, all-core/term, all-core/output,
all-core/ui,  all-core/naming, all-core/windows, all-core/settings, all-core/javahelp, all-openidex/enode, all-contrib/bookmarks, all-contrib/zeroadmin,
all-yourmodules">
    <echo message="Building jnlp distribution ..."/>
    <ant dir="../installer/jnlp" target="netbeans"/>
  </target>

It is important to maintain the dependency on all modules that are part of the build in the depends clause of the installer/jnlp target. The list of modules is specified in build.properties file like for the regular build.

The installer includes following files in the JNLP distribution:

• converted .jar files from the "normal" NetBeans distribution from folders (modules, modules/autoload, modules/eager, modules/ext, modules/autoload/ext and modules/eager/ext)
• All the .jar files from directories lib/ext of all modules (left untouched)
• Couple of files added from the module installer/jnlp (bootstrap code in nbjnlpintaller.jar and nb-launch.jnlp

Both the content of lib/ext from all modules and all converted jars are put on classpath by the JNLP client - this is specified in the file nb-launch.jnlp. And all of those jar files have to be signed to be usable - signing is part of the build script of the installer.

The result of the build script can be found either as a content of folder installer/jnlp/release (in case of static build - see bellow) or in file installer/jnlp/netbeans.war (in case of war file build - see bellow).

Jar files conversion

Jar files from folders (modules, modules/autoload, modules/eager, modules/ext, modules/autoload/ext and modules/eager/ext) are repackaged by the build process like this:

1. If the original file is in folder modules called xyz.jar the new file will be called the same (xyz.jar).
2. All the contents of the original file (including manifest) will be moved to folder xyz and packed again. So in the new file the directory structure will by one level more deep.
3. The new jar file will have its own manifest containing following entries:

   NetBeans-Location: modules
   NetBeans-Prefix: xyz
   

   The NetBeans-Location attribute can have following values: modules, modules/autoload, modules/eager, modules/ext, modules/autoload/ext and modules/eager/ext. The NetBeans-Prefix attribute contains the name of the original jar file (without extension) - the prefix directory in the new jar file.

Module system changes

In order for the prefixed jar files to work the module system was changed (on branch platform_32247) to support the prefixed jar on the classpath. The main changes include:

• The string "memory" is used as value for netbeans.home and netbeans.user system properties.
• Instead of JarClassLoader new DelegatingClassLoader was created
• ModuleList functionality is crippled when using "memory" as netbeans.home
• If NetBeans-Location and NetBeans-Prefix attributes are found in manifest of a jar file on the classpath the new type ("prefix") of module or resource jar is registered by the module system.

Static build

The build script produces a static build when a property called jnlp.static is set to true. This can be achieved e.g. by putting following line into your nbbuild/user.build.properties

jnlp.static=true

Static build means that the result of the build can be used on static web sites (sites not supporting Java (not having a servlet container)).

All the files needed should be generated into installer/jnlp/release directory. After successfull build this directory should contain nb-launch.jnlp, *.jar. The .jar files should be referenced from nb-launch.jnlp.

War file build

This is a default option (when jnlp.static is not specified) and the result is a war file containing all the needed files (installer/jnlp/netbeans.war). The difference between this and the static build is in the fact that with static some information in the nb-launch.jnlp is hardcoded (like distribution URL).

Configuration variables

Following variables are used by the installer/jnlp/build.xml to create the installer. The variablese can be specified e.g. in nbbuild/user.build.properties.

 
jnlp.codebase=http://www.foo.com/nb/

Codebase used only in the static build. This code base is put into the .jnlp files in the static build. The .war file build does not use it since the servlet serving the .jnlp files provides the value of the code base.

jnlp.signjar.alias=mykey

The files put on classpath by the jnlp client have to be signed. The build script uses a standard ant task for signing the files which in turn uses the jarsigner tool from JDK. The key can be created by keytool (part of the J2SDK).

jnlp.signjar.password=<something>

Companion to the previous one. Password used by the jarsigner.

jnlp.signjar.keystore=../../keystore

Location of the keystore file used for signing the .jar files. Please check jarsigner (comes with J2SDK) documentation for more details on the content and location of this file.

jnlp.extra.properties=<property name="property_name" value="value"/>

Since ide.cfg is not used by the JNLP installer this is the place to put the properties from ide.cfg. The format is one long line in with XML-like syntax. The line will be merged into nb-launch.jnlp. You can specify almost all of the properties normally present on the command line or in ide.cfg file.