- Java Web Start
Java Web Start¶
The following instructions are largely based on:
Deploying eclipse based application with Java Web Start - from the current Eclipse documentation.
RCP and Java Web Start - for Eclipse 3.1 and no longer entirely accurate, but includes some helpful details not included in the official Eclipse help.
1. Create a feature project
The feature project is a wrapper for all JAR files necessary for the Editor to function. Create it with Ctrl-N -> Plug-in Development -> Feature Project. Name it "eu.etaxonomy.taxeditor.feature", and enter "EDIT" as the provider. Hit "Next", then
Under the "Plug-ins" tab, add "eu.etaxonomy.taxeditor", "org.eclipse.equinox.launcher", and any plug-ins necessary for the Editor to run; "2. Create a product" describes how to ensure these are all present. Under the "Included Features" tab, add "org.eclipse.rcp".
2. Create a product
Choose Ctrl-N -> Plug-in Development -> Product Configuration. Create the product in the eu.etaxonomy.taxeditor directory, and call the product eu.etaxonomy.taxeditor.product. Choose "Use a launch configuration: Eclipse Application", and hit "OK".
Under the "Overview" tab of the new product, go to "Product ID" and hit the "New" button. In the Product Definition wizard, choose "eu.etaxonomy.taxeditor" as the Defining Plug-in, choose a Product ID ("product1"), and under "Application:", choose "eu.etaxonomy.taxeditor.application". Back in the "Overview" tab, choose "features" under "The product configuration is based on". Under the "Configuration" tab, add "eu.etaxonomy.taxeditor.feature".
Now go back to "Overview" and attempt to launch the product. At this point, you can tell whether the feature has all the plug-ins it needs; error logs after unsuccessful launches should tell you exactly what's missing. Note that the feature needs to include not only the plug-ins listed in eu.etaxonomy.taxeditor/plugin.xml's "Required Plug-ins", but also the plug-ins that they in turn depend on.
3. Generate a keystore
All plug-ins must be signed since the application needs full permission from the client in order to run. Download, install, and run this keytool plugin to create a Java keystore (JKS), the keytool application that comes with the JDK. Be sure to note the keystore's location, alias, and password for the next step.
Note that when the user downloads the Editor for the first time, he will see a message that this signature could not be verified.
4. Export the feature
Choose File -> Export -> Deployable features, then hit "Next". Choose "eu.etaxonomy.taxeditor.feature" and an appropriate destination directory. Under the "Options" tab, choose "Package as individual JAR archives". Two new tabs appear. Under "JAR Signing", check "Sign the JAR archives using a keystore" and enter the appropriate data. Under "Java Web Start", check "Create JNLP manifests" and enter the URL and directory where the application files will be made available for download (currently "http://cybertaxonomy.eu/taxeditor"); JRE Version should be 1.6.
Note: If the project "eu.etaxonomy.taxeditor" has files with Java errors in them, a nasty-looking error will occur at this point: "Errors occurred during the operation. A zip file containing the build logs has been generated ...", even if the files are not referenced during Tax Editor sessions and will not cause problems during execution. Ignore!
Two directories - "features" and "plugins" - are then created. Copy these to the download directory. In features/org.eclipse.rcp_*.jnlp, comment out the following (don't ask me why - anything with "wpf" crashes the application, and apparently makes no difference when commented out):
<!--jar href="plugins/org.eclipse.equinox.launcher.wpf.win32.x86_1.0.0.v20070523.jar"/--> <!--jar href="plugins/org.eclipse.swt.wpf.win32.x86_3.3.0.v3346.jar"/-->
5. Create the JNLP file
Replace the test values in [this template](http://dev.e-taxonomy.eu/trac/attachment/wiki/JavaWebStart/test.jnlp with the production settings. For more information on the JNLP file, please consult the JNLP syntax guide) .
<jnlp spec="1.0+" codebase="http://c084.bgbm.fu-berlin.de/webstart" href="test.jnlp">
Replace "codebase" with the production server and download directory, and "href" with the name you give the JNLP file.
<icon kind="splash" href="http://c084.bgbm.fu-berlin.de/webstart/splash.PNG"/> <icon href="http://c084.bgbm.fu-berlin.de/webstart/edit.gif" kind="default" /> <shortcut online="false"> <desktop /> <menu /> </shortcut>
These are the hrefs to the splash page and the icon that will appear on the user's desktop, as well as instructions to put links on the desktop and in the start menu.
This tag says the user is allowed to use the cached application even when Web Start cannot contact the production server.
Make sure these reflect the current versions you're using.
<extension name="Wrapper feature" href="features/eu.etaxonomy.taxeditor.feature_1.0.0.jnlp"/>
<property name="eclipse.product" value="eu.etaxonomy.taxeditor.product"/>
These are the references to the Editor feature and product.
<security> <all-permissions/> </security>
The "all-permissions" tag gives the application full access to the client system if all its JAR files are signed.
<resources os="Mac"> <j2se version="1.5" java-vm-args="-XstartOnFirstThread"/> </resources> <resources os="Windows"> <j2se version="1.5"/> </resources> <resources os="Linux"> <j2se version="1.5"/> </resources>
Here is where you specify which JRE the user needs on his machine. If he has an earlier version, Web Start automatically upgrades.
6. Create a link to the JNLP file
The final step is to create a webpage with a link to the JNLP file. When the user clicks on this link, the fun starts.
This location in the JNLP:
<property name="osgi.instance.area" value="@user.home/Application Data/taxeditor"/> <property name="osgi.configuration.area" value="@user.home/Application Data/taxeditor"/>
is used by Web Start for various application information. (In Windows, @user.home = "C:\Documents and Settings_username_"). If the application dies without an error message, check here for an error log, for instance, to see which JAR files are missing.
To remove the cached version of the application, go to the Java Cache Viewer located in the temporary internet files part of the Java Control Panel. Delete everything relating to the application from "Applications" AND from "Resources". For descriptions on clearing the Web Start cache on different platforms, see https://www.vaultletsoft.com/support/clear-jws-cache.html.
Putting updates on the download site¶
The JNLP file and the two directories "features" and "plugins" should be placed on the EDIT server under:
The download site during testing is TaxonomicEditorDownload.
The version of Eclipse used for development must run on a Java SDK instead of a JRE. If this constraint is not satisfied, the JAR signing will fail. To run Eclipse under the Java SDK, go to Window ~~> Preferences -> Java -> Installed JREs. If no JDK is listed, click "Add ..." and enter the JDK home directory ~~ i.e. "C:\Programme\Java\jdk1.6.0_02" - under "JRE home directory". Then be sure the JDK entry has a check mark next to it before hitting "OK".
Important: Java 6 Update 7 causes a Web Start error¶
See https://bugs.eclipse.org/bugs/show_bug.cgi?id=240500. New security restrictions prevent Web Start from getting information about cached jars on the user's machine.
The result is the following entry in the log file in @user.home/Application Data/taxeditor/:
!SESSION Thu Jul 10 11:42:00 CEST 2008 ----------------------------------------- !ENTRY org.eclipse.equinox.launcher 4 0 2008-07-10 11:42:00.680 !MESSAGE Exception launching the Eclipse Platform: !STACK java.lang.NullPointerException at org.eclipse.equinox.launcher.Main.readFrameworkExtensions(Main.java:669) at org.eclipse.equinox.launcher.Main.addBaseJars(Main.java:720) at org.eclipse.equinox.launcher.Main.getDevPath(Main.java:642) at org.eclipse.equinox.launcher.Main.getBootPath(Main.java:827) at org.eclipse.equinox.launcher.Main.basicRun(Main.java:431) at org.eclipse.equinox.launcher.WebStartMain.basicRun(WebStartMain.java:78) at org.eclipse.equinox.launcher.Main.run(Main.java:1173) at org.eclipse.equinox.launcher.WebStartMain.main(WebStartMain.java:56) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source) at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source) at java.lang.reflect.Method.invoke(Unknown Source) at com.sun.javaws.Launcher.executeApplication(Unknown Source) at com.sun.javaws.Launcher.executeMainClass(Unknown Source) at com.sun.javaws.Launcher.doLaunchApp(Unknown Source) at com.sun.javaws.Launcher.run(Unknown Source) at java.lang.Thread.run(Unknown Source)
Web Start Alternatives¶
If another installation tool is chosen, here is a general description of how to write an Eclipse installer: http://help.eclipse.org/help33/topic/org.eclipse.platform.doc.isv/reference/misc/eclipse-install.html