Updated javadoc for JOGLAppletLauncher to document JOAL support, new

library and native library jar structure, and to remove comment on bug
with multiple JOGL applets on the same web page, which has been fixed


git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/trunk@1040 232f8b59-042b-4e1e-8c03-345bb8c30851

1 files changed, 46 insertions, 21 deletions

diff --git a/src/classes/com/sun/opengl/util/JOGLAppletLauncher.java b/src/classes/com/sun/opengl/util/JOGLAppletLauncher.java
index 328895009..cc3b3f31e 100755
--- a/src/classes/com/sun/opengl/util/JOGLAppletLauncher.java
+++ b/src/classes/com/sun/opengl/util/JOGLAppletLauncher.java
@@ -63,20 +63,40 @@ import javax.swing.*;
 import javax.media.opengl.*;
 
 
-/** Basic JOGL installer for Applets. The key functionality this class
- *  supplies is the ability to deploy unsigned applets which use JOGL.
- *  It may also be used to deploy signed applets in which case
- *  multiple security dialogs will be displayed. <p>
+/** This class enables deployment of high-end applets which use OpenGL
+ *  for 3D graphics via JOGL and (optionally) OpenAL for spatialized
+ *  audio via JOAL. 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 as well as for JOGL and JOAL. <P>
  *
- *  On the server side the codebase must contain jogl.jar ,
- *  gluegen-rt.jar, and all of the jogl-natives-*.jar and
- *  gluegen-rt-natives-*.jar files from the standard JOGL distribution
- *  (provided in jogl-[version]-webstart.zip).  This is the location
- *  from which the JOGL library used by the applet is downloaded. The
- *  codebase additionally contains the jar file of the user's
- *  potentially untrusted applet. All of the JOGL and GlueGen-related
+ *  The steps for deploying such applets are straightforward. First,
+ *  the "archive" parameter to the applet tag must contain jogl.jar
+ *  and gluegen-rt.jar, as well as any jar files associated with your
+ *  applet (in this case, "your_applet.jar"). <P>
+ *
+ *  Second, the codebase directory on the server, which contains the
+ *  applet's jar files, must also contain jogl.jar, gluegen-rt.jar,
+ *  and all of the jogl-natives-*.jar and gluegen-rt-natives-*.jar
+ *  files from the standard JOGL and GlueGen runtime distributions
+ *  (provided in jogl-[version]-webstart.zip from the <a
+ *  href="http://jogl.dev.java.net/servlets/ProjectDocumentList">JOGL
+ *  release builds</a> and gluegen-rt-[version]-webstart.zip from the
+ *  <a
+ *  href="http://gluegen.dev.java.net/servlets/ProjectDocumentList">GlueGen
+ *  runtime release builds</a>). Note that the codebase of the applet
+ *  is currently the location from which the JOGL native library used
+ *  by the applet is downloaded. All of the JOGL and GlueGen-related
  *  jars must be signed by the same entity, which is typically Sun
- *  Microsystems, Inc.
+ *  Microsystems, Inc. <P>
+ *
+ *  To deploy an applet using both JOGL and JOAL, simply add joal.jar
+ *  to the list of jars in the archive tag of the applet, and put
+ *  joal.jar and the joal-natives-*.jar signed jars into the same
+ *  codebase directory on the web server. These signed jars are
+ *  supplied in the joal-[version]-webstart.zip archive from the <a
+ *  href="http://joal.dev.java.net/servlets/ProjectDocumentList">JOAL
+ *  release builds</a>. <P>
  *
  * Sample applet code:
  * <pre>
@@ -97,16 +117,21 @@ import javax.media.opengl.*;
  * There are some limitations with this approach. It is not possible
  * to specify e.g. -Dsun.java2d.noddraw=true or
  * -Dsun.java2d.opengl=true for better control over the Java2D
- * pipeline as it is with Java Web Start. There appear to be issues
- * with multiple JOGL-based applets on the same web page, though
- * multiple instances of the same applet appear to work. The latter
- * may simply be a bug which needs to be fixed. <p>
+ * pipeline as it is with Java Web Start. However, the
+ * JOGLAppletLauncher tries to force the use of
+ * -Dsun.java2d.noddraw=true on Windows platforms for best robustness
+ * by detecting if it has not been set and asking the user whether it
+ * can update the Java Plug-In configuration automatically. If the
+ * user agrees to this, a browser restart is required in order for the
+ * change to take effect, though it is permanent for subsequent
+ * browser restarts. <P>
  * 
- * The JOGL natives are cached in the user's home directory (the value
- * of the "user.home" system property in Java) under the directory
- * .jogl_ext. The Java Plug-In is responsible for performing all other
- * jar caching. If the JOGL installation is updated on the server, the
- * .jogl_ext cache will automatically be updated. <p>
+ * The JOGL (and optionally JOAL) natives are cached in the user's
+ * home directory (the value of the "user.home" system property in
+ * Java) under the directory .jogl_ext. The Java Plug-In is
+ * responsible for performing all other jar caching. If the JOGL
+ * installation is updated on the server, the .jogl_ext cache will
+ * automatically be updated. <p>
  * 
  * This technique requires that JOGL has not been installed in to the
  * JRE under e.g. jre/lib/ext. If problems are seen when deploying