diff options
Diffstat (limited to 'www')
| -rw-r--r-- | www/index.html | 408 |
1 files changed, 404 insertions, 4 deletions
diff --git a/www/index.html b/www/index.html index 67ed10f..35e9726 100644 --- a/www/index.html +++ b/www/index.html @@ -11,12 +11,412 @@ <body style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);"> -<p>Welcome to the home page for the applet-launcher project. This -project contains the JNLPAppletLauncher utility, which...</p> +<h2>Overview</h2> -<h3>Downloads</h3> +<!-- NOTE: to regenerate the text for this web page, copy the class + javadoc for the JNLPAppletLauncher and run an emacs macro over it + to remove the leading " *"s. --> -<p>Coming soon...</p> + The JNLPAppletLauncher is a general purpose JNLP-based applet + launcher class for deploying applets that use extension libraries + containing native code. It allows applets to use extensions like + Java 3D, JOGL, and JOAL very easily, with just a few additional + parameters to the <code><applet></code> tag, on Java SE + versions as far back as 1.4.2. + + <p> + + Like Java Web Start, the JNLPAppletLauncher uses an extension's + .jnlp file to locate the native resources for a given extension. + The applet developer only needs to specify the platform-independent + .jar files containing the .class files for the extension. The + platform-specific "nativelib" .jar files are downloaded + automatically from the same server that hosts the extension's Java + Web Start binaries. + + <p> + + Extensions that support JNLPAppletLauncher include Java 3D, JOGL, + and JOAL. More can be added without needing to modify the + JNLPAppletLauncher. See the section below on <a + href="#MODIFYING">modifying extensions to work with the + JNLPAppletLauncher</a>. + + <h2> How to Deploy Applets Using the JNLPAppletLauncher </h2> + <p> + + The <code>applet-launcher.jar</code> file containing the + JNLPAppletLauncher class must be signed with the same certificate + as the extension's native resources, for example "sun microsystems, + inc.". The user will receive a security dialog and will be prompted + to accept the certificate for the JLNPAppletLauncher. The applet + being deployed may be either signed or unsigned; if it is unsigned, + it runs inside the security sandbox, and if it is signed, the user + receives a security dialog to accept the certificate for the applet + (in addition to the applet-launcher jar, if it is signed by a + different entity). + + <p> + + The steps for deploying such applets are straightforward. First, + the <code>archive</code> parameter to the applet tag must contain + <code>applet-laucher.jar</code>, the extension .jar files, and any + jar files associated with your applet. See the section on <a + href="#ORGANIZING">organizing jar files</a> for more details. + + <p> + + Second, the name of your applet's main class and a textual + description must be specified via the applet tag parameters + <code>subapplet.classname</code> and + <code>subapplet.displayname</code>. + + <p> + + Finally, the URLs for the extension .jnlp files being used must be + specified as parameters. The <code>jnlpNumExtensions</code> + parameter indicates the number of JNLP files that are referenced, + and for <code>n</code> such files, their URLs are passed in as + parameters <code>jnlpExtension1</code> ... + <code>jnlpExtension[n]</code>. + + <h2><a name="ORGANIZING">Organizing Jar Files</a></h2> + + <p> + + Traditionally, applets are specified with a codebase and an archive + parameter, the latter which is a list of jar files relative to that + codebase. The codebase is optional and defaults to the directory on + the web server containing the HTML document which contains the + applet tag. See the documentation for the <a + href="http://java.sun.com/j2se/1.4.2/docs/guide/misc/applet.html">applet + tag</a>. + + <p> + + It is not well documented, but at least in the Sun JRE at least as + far back as Java SE 1.4.2, it is possible to use absolute URLs in + the applet tag's archive parameter. This functionality works on all + major operating systems: Windows, Mac OS X, Linux, and Solaris. + This means that you can pull code resources from multiple web + servers, not just one, in similar fashion to Java Web Start and its + extension mechanism. (The security implications are that each + unsigned piece of code downloaded from a separate server receives + sandboxed permissions to connect back to that server; if there are + multiple pieces of unsigned code on the stack during execution of + the program then the permissions will be the intersection of all of + those on the stack, implying that no programmatic network + connections back to the web server(s) will be allowed. See the <a + href="http://java.sun.com/sfaq/">Applet Security FAQ</a> for more + details.) + + <p> + + This capability means that your applets can refer directly to + extensions like Java 3D and JOGL hosted on Sun's web servers + without having to duplicate their jar files on your web server. + + <p> + + To use this capability effectively with the JNLPAppletLauncher, you + need to pull in at least three primary pieces of code: the applet + launcher itself, your applet's code, and the Java code for the + extension, or extensions, your applet depends on. (Remember that + the JNLPAppletLauncher's primary function is to automatically + download the native code associated with these extensions, and not + the Java code for these extensions.) + + <p> + + You might choose to specify the codebase of your applet to point to + your web server's directory containing the jar files of your + applet, and specify absolute URLs to the + <code>applet-launcher.jar</code> and the extension jar files. Or + you might decide to point the codebase to the server which hosts + the applet launcher and specify all of the other resources, + including your applet, with absolute URLs. Or you might decide to + use all absolute URLs in your archive tag with no codebase. The + techniques are basically equivalent. We recommend either pointing + the codebase to the directory containing your applet's jars, using + relative URLs for your applet, and using absolute URLs for all + other resources; or using all absolute URLs. + + <p> + + Alternatively, you can re-host the jar files and/or JNLP files and + nativelib jars for the extensions you use on your own web + server. This has the advantage that your applet will connect to + fewer web servers upon startup, but has the disadvantages of + requiring additional maintenance on your part and not automatically + receiving updates to the extensions when they are published. + + <p> + + The <code>jnlpExtension</code> parameters passed to the + JNLPAppletLauncher must be specified with absolute URLs. + + <p> + + The <a href="#EXAMPLES">examples</a> show how to use the + JNLPAppletLauncher in a few different scenarios. + + <h2>Applets using the OpenGL(r) 3D API</h2> + + Applets using the OpenGL 3D graphics API, for example through JOGL + or Java 3D, may encounter robustness issues on the Windows platform + because Sun's Java 2D implementation on Windows uses Microsoft's + DirectDraw API. DirectDraw and OpenGL are incompatible at the + driver level. + + <p> + + As a workaround for this problem, the JNLPAppletLauncher supports + disabling the use of DirectDraw. Currently this can only be done on + a global basis, for all applets, but doing so is unlikely to slow + down other non-3D applets significantly. + + <p> + + Specifying the applet parameter + + <pre> + <param name="noddraw.check" value="true"> + </pre> + + will cause the applet launcher, when run on Windows, to check to + see whether DirectDraw is enabled and, if so, will prompt the user + with a dialog box asking to disable it. A browser restart is + required if the setting is changed. + + <p> + + If the dialog box is undesirable in a given situation, you can + force the noddraw check to always disable DirectDraw with the two + applet parameters: + + <pre> + <param name="noddraw.check" value="true"> + <param name="noddraw.check.silent" value="true"> + </pre> + + In this case it will not be obvious to the end user that a browser + restart might be required for best robustness, but you could + potentially document the need to try restarting the browser in case + of instability. + + <h2><a name="EXAMPLES">Examples</a></h2> + + <p> + + An applet using Java 3D as an extension: + + <pre> + <applet code="org.jdesktop.applet.util.JNLPAppletLauncher" + width=640 + height=480 + codebase="http://download.java.net/media/java3d/applets/applet-test/" + archive="applet-launcher.jar,j3d-examples.jar,j3dcore.jar,j3dutils.jar,vecmath.jar"> + <param name="subapplet.classname" value="org.jdesktop.j3d.examples.four_by_four.FourByFour"> + <param name="subapplet.displayname" value="Java 3D Four by Four Applet"> + <param name="jnlpNumExtensions" value="1"> + <param name="jnlpExtension1" + value="http://download.java.net/media/java3d/webstart/early-access/java3d-1.5.1-exp.jnlp"> + <param name="progressbar" value="true"> + </applet> + </pre> + + <p> + + An applet using JOGL as an extension. Note that this example does + not specify a codebase, instead specifying all of its archive tag + elements with absolute URLs. Note also the use of the + <code>noddraw.check</code> parameter to disable the use of + DirectDraw since using JOGL implies the use of OpenGL. + + <pre> + <applet code="org.jdesktop.applet.util.JNLPAppletLauncher" + width=600 + height=400 + archive="http://download.java.net/media/applet-launcher/applet-launcher.jar,http://download.java.net/media/jogl/builds/archive/jsr-231-webstart-current/jogl.jar,http://download.java.net/media/gluegen/webstart/gluegen-rt.jar,http://download.java.net/media/jogl/builds/archive/jsr-231-webstart-current/jogl-demos.jar"> + <param name="subapplet.classname" value="demos.applets.GearsApplet"> + <param name="subapplet.displayname" value="JOGL Gears Applet"> + <param name="noddraw.check" value="true"> + <param name="progressbar" value="true"> + <param name="jnlpNumExtensions" value="1"> + <param name="jnlpExtension1" + value="http://download.java.net/media/jogl/builds/archive/jsr-231-webstart-current/jogl.jnlp"> + </applet> + </pre> + + <p> + + An applet using both JOGL and JOAL as extensions. Note again that + all code resources are specified with absolute URLs. In this + example the unsigned applet pulls in code from both + <code>jogl-demos.jar</code> and <code>joal-demos.jar</code>. Note + again the use of the <code>noddraw.check</code> parameter. + + <pre> + <applet code="org.jdesktop.applet.util.JNLPAppletLauncher" + width=600 + height=400 + archive="http://download.java.net/media/applet-launcher/applet-launcher.jar,http://download.java.net/media/jogl/builds/archive/jsr-231-webstart-current/jogl.jar,http://download.java.net/media/gluegen/webstart/gluegen-rt.jar,http://download.java.net/media/jogl/builds/archive/jsr-231-webstart-current/jogl-demos.jar,http://download.java.net/media/joal/webstart/joal.jar,http://download.java.net/media/joal/webstart/joal-demos.jar"> + <param name="subapplet.classname" VALUE="demos.applets.GearsJOALApplet"> + <param name="subapplet.displayname" VALUE="JOGL / JOAL Gears Applet"> + <param name="noddraw.check" value="true"> + <param name="progressbar" value="true"> + <param name="jnlpNumExtensions" value="2"> + <param name="jnlpExtension1" + value="http://download.java.net/media/jogl/builds/archive/jsr-231-webstart-current/jogl.jnlp"> + <param name="jnlpExtension2" + value="http://download.java.net/media/joal/webstart/joal.jnlp"> + </applet> + </pre> + + <h2> Locations of Standard Extensions </h2> + + <p> + + This section describes how to set up the <code>archive</code> and + <code>jnlpExtension</code> parameters for a few standard + extensions. + + <h3>JNLPAppletLauncher</h3> + + The master jar file for the JNLPAppletLauncher is located at the following URL: + <pre> + http://download.java.net/media/applet-launcher/applet-launcher.jar + </pre> + + This jar needs to be added to your archive parameter. + + <h3>Java 3D</h3> + + The early access release of Java 3D 1.5.1 and later support the + JNLPAppletLauncher. You will need to add the following URLs to your + archive parameter: + + <pre> + http://download.java.net/media/java3d/webstart/early-access/j3d/1.5.1/j3dcore.jar + http://download.java.net/media/java3d/webstart/early-access/j3d/1.5.1/j3dutils.jar + http://download.java.net/media/java3d/webstart/early-access/vecmath/1.5.1/vecmath.jar + </pre> + + and refer to the following in one of your <code>jnlpExtension</code> parameters: + + <pre> + http://download.java.net/media/java3d/webstart/early-access/java3d-1.5.1-exp.jnlp + </pre> + + <h3>JOGL</h3> + + JOGL 1.1.1-rc3 and later support the JNLPAppletLauncher. You will + need to add the following URL to your archive parameter: + + <pre> + http://download.java.net/media/jogl/builds/archive/jsr-231-webstart-current/jogl.jar + </pre> + + Because JOGL depends on the GlueGen runtime, you will also need to + add the following URL to your archive parameter: + + <pre> + http://download.java.net/media/gluegen/webstart/gluegen-rt.jar + </pre> + + Finally, add the following to one of your + <code>jnlpExtension</code> parameters: + + <pre> + http://download.java.net/media/jogl/builds/archive/jsr-231-webstart-current/jogl.jnlp + </pre> + + Note that the jogl.jnlp extension will automatically pull in the + native code associated with the GlueGen runtime, so you don't have + to separately refer to the gluegen-rt.jnlp file. + + <h3>JOAL</h3> + + JOAL 1.1.1 and later support the JNLPAppletLauncher. You will need + to add the following URL to your archive parameter: + + <pre> + http://download.java.net/media/joal/webstart/joal.jar + </pre> + + Because JOAL, like JOGL, depends on the GlueGen runtime, you will + also need to add the following URL to your archive parameter: + + <pre> + http://download.java.net/media/gluegen/webstart/gluegen-rt.jar + </pre> + + (If you are using both JOGL and JOAL, you only need to refer to + gluegen-rt.jar once in your archive parameter.) + + <p> + + Finally, add the following to one of your + <code>jnlpExtension</code> parameters: + + <pre> + http://download.java.net/media/joal/webstart/joal.jnlp + </pre> + + Note that the joal.jnlp extension will automatically pull in the + native code associated with the GlueGen runtime, so you don't have + to separately refer to the gluegen-rt.jnlp file. + + <h2><a name="MODIFYING">Modifying Your Extension To Work With The JNLPAppletLauncher</a></h2> + + <p> + + If you are the author of an extension like JOGL which requires some + native code, with only a simple code change you can make your + extension work with the JNLPAppletLauncher. Simply add the + following method somewhere in your code: + + <pre> + private static void loadLibraryInternal(String libraryName) { + String sunAppletLauncher = System.getProperty("sun.jnlp.applet.launcher"); + boolean usingJNLPAppletLauncher = + Boolean.valueOf(sunAppletLauncher).booleanValue(); + if (usingJNLPAppletLauncher) { + try { + Class jnlpAppletLauncherClass = + Class.forName("org.jdesktop.applet.util.JNLPAppletLauncher"); + Method jnlpLoadLibraryMethod = + jnlpAppletLauncherClass.getDeclaredMethod("loadLibrary", + new Class[] { String.class }); + jnlpLoadLibraryMethod.invoke(null, new Object[] { libraryName }); + } catch (Exception e) { + throw new RuntimeException(e); + } + } else { + System.loadLibrary(libraryName); + } + } + </pre> + + and wherever you would call <code>System.loadLibrary()</code> (from + within an <code>AccessController.doPrivileged()</code> block) to + load your extension's native code, call the above + <code>loadLibraryInternal</code> method instead. + + <p> + + Note again that because the <code>applet-launcher.jar</code> and + the nativelib jars for all extensions must currently be signed with + the same certificate, this implies that you must resign both the + applet launcher as well as any other extensions your applet relies + on (unless yours is a Sun-standard extension and can be signed with + Sun's code signing certificate). + + <h2>Acknowledgments</h2> + + The JNLPAppletLauncher was developed by Kevin Rushforth, Kenneth + Russell, and Chien Yang. It is based on the former + JOGLAppletLauncher developed by Lilian Chamontin. </body> </html> |