JyMOL Applet Deployment
Overview
We provide an example of how to deploy JyMOL in an Applet that can be run inside browsers
on all platforms that PyMOL runs on (MacOS, Linux, and Windows). This Applet deployment uses Java's WebStart.
Proper knowledge of Java Applet deployment is highly recommended. These links will help the developer:
* Java Deployment Advice
* Apple Developer Site (Apple ships their own Java VM.)
* Understanding Signing and Verification
* JNLP File Format
* JaNeLa JNLP Validator
Online Demonstration
Link to Online Demonstration
Browser/Operating System Support:
JyMOL 1.1 is compiled with Java 1.6.0_24, so ideally you want to use this version or a more recent version. However, it is known to work with slightly older versions, but you could run into problems.
| | Browsers tested successfully | Not supported |
| Windows | Internet Explorer, Firefox, Chrome, Opera | |
| Linux | Firefox | Konqueror |
| MacOS1 | Safari, Firefox2 | Chrome |
-
On MacOS, JoGL Applets work on Firefox 3.6, but the 3D window is shown on every tab (bug). JoGL Applets do not work in Firefox 4.0 on MacOS.
Note: If you are having trouble getting your Applet (or the Online Demonstration) to work inside a particular browser on a particular Operating system, first make sure JoGL is working by going to JoGL JNLP Applet Test
MacOS Deployment
There is a known problem when running applets that use OpenGL on Mac. In order to get this to work, you need to run Applets “Within the browser process” : (go to Applications→Utilities→Java Preferences→General, click on the “Within the browser process” checkbox, which is the default). This checkbox not supported by Chrome and Firefox 4.0.
For Applets that run “In their own process”, it might not load the dependent dynamic libraries properly, but if it does, it will show a blank white display inside the browser. In order to get this to work, you need to detach the applet from the browser by mousing over the applet and pressing the Apple key. Once you do this, a frame around the applet is shown, click on it and drag it away from its place. The Applet will now be showing the graphics. We are working on eliminating this problem, and hopefully will have it resolved soon. (4/29/11) You can also see “Radar #7308408” for more information on the
Apple Web Site (ResolvedIssues).
Source Files Distribution
The src/com/schrodinger/jymol/applet directory contains the java code that implements JyMOL as
an applet.
| JyMOLApplet.java | Provides an example of how to use JyMol inside an Applet. It provides a way to download and run commands using a simple command language that calls the JyMol cmd methods. |
| JyMOLNetworkingUtil.java | Provides some utilities for applets to fetch data. |
| JyMOLUtil.java | Some JyMOL Utilities that make it easy to retrieve data from within an applet. |
The applet_deployment directory contains html and jnlp code for using JyMOL as an Applet:
| README.txt | This documentation to help guide you through Applet Deployment |
| index.html | Example HTML that shows how to embed an Applet into a webpage |
| stereo.html | Example HTML that shows how to embed a stereoscopic Applet into a webpage |
| JNLP Files | Example JAVA Network Launching Protocol files to support the JyMOL deployment in JAVA WebStart |
| —jymol_applet.jnlp | top level JNLP file that has dependencies on jymol, jogl, gluegen, and nativewindow |
| —jymol.jnlp | defines where the jymol jar and native jar files exist (has dependencies on jogl) |
| —jogl.jnlp | defines where the jogl jar and native jar files exist (has dependencies on gluegen and nativewindow) |
| —gluegen-rt.jnlp | defines where the gluegen jar and native jar files exist |
| —nativewindow.jnlp | defines where the nativewindow jar and native jar files exist (has dependencies on nativewindow) |
| m-jymol-package.zip | demonstration zip file. this has input files and scripts that are used in the example. |
| applet-launcher.jar | jar file that is used for the class org.jdesktop.applet.util.JNLPAppletLauncher1, which is used in the example |
The JNLPAppletLauncher packaged in JyMOL 1.1 has been modified so that all
href links can be relative, including inside the “extension”. The current version downloaded from the git repository (from
https://github.com/sgothel/applet-launcher) assumes that the href in the “extension” links to an absolute http address. This is a simple one line fix, but we have included this changed version of applet-launcher.jar inside JyMOL 1.1.
Note: This is not a complete solution: a complete solution requires a webserver, signing authority,
key store, signed jar files, and more.
Outline to General JyMOL Applet Development/Deployment
Setup a webserver. Testing on you localhost will often be different than testing from a real webserver due to sandboxing issues. Ensure that the server knows how to serve JNLP files. The 'appletviewer' program while helpful, doesn't handle loading native libraries without tampering with system internals.
Compile your code against JyMOL. The solution to not having access to -Djava.library.path in an applet is to either place your jymol dynamic libraries in your main jar file or to specify them in the JNLP.
Properly create and format your JNLP file
Link your
HTML code to your JNLP file (see index.html)
Package your solution + the jymol class files into ONE jar file, which contains the main class file for your solution. This is the class that the JNLP file calls
Use Java's “jarsigner” to sign EVERY jar file you publish. You can temporarily sign files for testing or acquire official credentials from a certifying authority like VeriSign or Thawte
Upload the requisite jymol-, jogl-, nativewindow-, and gluegen-rt- dependencies to your server, ensuring that each has its appropriate entry in the JNLP file (see jymol_applet.jnlp)
Visit your webpage
Other Notes
The jymol_applet package and JyMOLApplet class are now included in the jymol-1.1.jar file. It is also included in the JyMol
API documentation. There are some good examples in this class and the index.html file that shows how to use LiveConnect to call JyMol from JavaScript.
For a large-scale deployment, we have used a small subset of the jar files available from the JoGL web site to minimize the download size. If you want to simplify these jar files, or add more parts of the JoGL libraries for any reason, you can exchange some of these jar files in the JyMOL release with jar files from the JoGL web site. For JyMol 1.1, we are using JoGL 2.0rc2. To do this, jars from this release could be exchanged for ones in the JyMOL release.