• View
• Edit
• History
• Print

HTMLExport

Notes about how to Export Ptolemy Models to HTML

Overview

The Ptolemy II development tree contains facilities to export models to the web. There are two separate facilities:

1. HTML export of static models that allows the user to browse parameters and plotter output, but not actually execute the model. This facility uses image files, image maps and Javascript, so it should work on most browsers. Java is not required.
2. WebStart export that allows the user to change parameters and run the model. This facility requires that the user have Java installed locally on their machine.

By using these two facilities together, it is possible to export models that will be viewable for many years in the future.

Requirements

To build the complete set of signed jars and install them on the Ptolemy website, you will need:

• An ssh account on moog and be a member of the ptolemy Unix group.
• Access to our key, which is in /users/ptII/adm/certs/ptkeystore on moog.
• Access to the password, which is in /users/ptII/adm/certs/.pw on moog.

Building Ptolemy II

1. Download and configure Ptolemy II. See http://chess.eecs.berkeley.edu/ptexternal. For Mac/Linux, if you have read/write Subversion access:
   svn co https://repo.eecs.berkeley.edu/svn/projects/eal/ptII/trunk ptII
   

   [$[Get Code]]
   If you don't' have read/write access:
   svn co https://repo.eecs.berkeley.edu/svn-anon/projects/eal/ptII/trunk ptII
   

   [$[Get Code]]
   Then:
   cd ptII
   export PTII=`pwd`
   ./configure
   

   [$[Get Code]]
   For Windows:
   1. Download the tree using SVN
   2. Install Ant
   3. copy ptII/build.default.xml to ptII/build.xml
2. Build and then build jar files
   ant
   ant javadoc
   ant -f jars.xml jars
   

   [$[Get Code]]
   Also, create the lbnl jars:
   (cd $PTII/lbnl; make install)
   

   [$[Get Code]]
   If you don't have access to the Ptolemy web server, after downloading and building Ptolemy II, you can create your own key by running
   cd $PTII
   make ptKeystore
   

   [$[Get Code]]

Placing and cleaning the models

1. It is easiest if all of the models to be exported are in one directory. If necessary, create a directory in ptII/doc/books/ or ptII/doc/papers. Papers usually get put into a subdirectory with the year, for example ptII/doc/papers/y14/. The y is necessary because the path to the model needs to be a legitimate Java package name so that JUnit will work for the tests. Legitimate package names must start with an letter (or maybe an underscore). For example
   mkdir $PTII/doc/papers/y14/constructive
   

   [$[Get Code]]
2. Copy the models into the directory that was created.
3. Examples should follow the Ptolemy II style guide at http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/doc/coding/style.htm. In particular:
   1. .xml file names should be well formed Java identifiers
   2. Reset the zoom and center each model
4. Add a makefile. Try copying from an adjacent directory. See the style guide for more about makefiles. http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/doc/coding/style.htm
5. If you have read/write Subversion access, add the directory, models and makefile to subversion.
   svn add modularSemantics
   svn commit -m "Added models for ealpapers/y14/constructiveSemantics
   

   [$[Get Code]]
6. The makefile in the director that contains the models should have a echo_models rule. For books, this rule is in chapter.mk.
   # $PTII/mk/jnlp.mk calls "make echo_models"
   echo_models:
   @echo "$(EXAMPLE_MODELS) $(EXAMPLE_SUBMODELS)" | awk '{for(i=1;i<=NF;i++) {print $$i}}' | sort
   

   [$[Get Code]]

Create index.html and toc.htm

Create index.html and toc.htm files. It is easiest to work from prexisting sources, below is a sample index.html

Below is a sample toc.htm

Don't forget to make index.html and toc.htm executable

Signing the jar files

1. Create the directory on moog. You must have an ssh account on moog and be in the cvs unix group
   ssh moog "mkdir /home/www/ptweb/ptolemyII/ptII10.0/jnlp-constructive"
   

   [$[Get Code]]
2. On moog, check that you are in the cvs and the ealgroup Unix groups.
   moog.EECS.Berkeley.EDU:root: %C2> groups cxh
   cxh : cxh webmastr www cvs ptolemy ealgroup
   moog.EECS.Berkeley.EDU:root: %C2>
   

   [$[Get Code]]
   This is necessary because the /users/ptII/adm/certs/ptkeystore file in the next step is only readable by the root user and by people in the ealgroup unix group
3. Copy the keystore to your local machine as /users/ptII/adm/certs/ptkeystore. If you cannot create that directory, then use a different directory and substitute accordingly in the make commands below
   sudo mkdir /users/ptII/adm/certs
   sudo chown yourlocalusername /user/ptII/adm/certs
   scp yourAccountOnMoog@moog:/users/ptII/adm/certs/ptkeystore /user/ptII/adm/certs
   

   [$[Get Code]]
4. Get the key to the certificate. Local users, email Christopher for the password. If you have root on moog, see /users/ptII/adm/certs/.certpw. Other users, for details, see http://chess.eecs.berkeley.edu/ptolemy/sysadmin/certificates.htm
5. Place the password in a file called ~/.certpw that is readable only by you.
6. Verify that you can read the password: The make command should all be on one line
   cd $PTII
   make key_list STOREPASSWORD="-storepass `cat ~/.certpw`" KEYSTORE=/users/ptII/adm/certs/ptkeystore
   

   [$[Get Code]]
   You should see something like:
   Keystore type: JKS
   Keystore provider: SUN
   
   Your keystore contains 1 entry
   
   Alias name: ptolemy
   Creation date: Jan 13, 2012
   Entry type: PrivateKeyEntry
   Certificate chain length: 4
   Certificate[1]:
   Owner: CN=University of California at Berkeley, OU=IST-CalNetIdM, O=University of California at Berkeley, STREET="200 California Hall #1500", L=Berkeley, ST=Calif\
   ornia, OID.2.5.4.17=947201500, C=US
   Issuer: CN=InCommon Code Signing CA, OU=InCommon, O=Internet2, C=US
   

   [$[Get Code]]
   followed by a bunch of other information.
7. Run these commands:
   cd $PTII
   rm -rf signed
   make KEYSTORE=/users/ptII/adm/certs/ptkeystore KEYALIAS=ptolemy STOREPASSWORD="-storepass `cat $HOME/.certpw`" KEYPASSWORD="-storepass `cat $HOME/.certpw`" DIST_BASE=ptolemyII/ptII10.0/jnlp-constructive jnlp_dist
   

   [$[Get Code]]
   This will populate /export/home/pt0/ptweb/ptolemyII/ptII10.0/jnlp-constructive.
8. On the local machine, do
   cp $PTII/ptKeystore.properties $HOME/ptKeystore.properties
   

   [$[Get Code]]
   and edit $HOME/ptKeystore.properties to contain the path to the keystore, the passwords and the alias. This file is used by copernicus to create signed jars. We don't use $PTII/ptKeystore.properties because we don't want the password to appear in the installer as part of the nightly build. For example:
   # $Id: ptKeystore.properties 57286 2010-02-22 17:36:17Z bldmastr $
   # Java properties file used by ptolemy/copernicus/applet/AppletWriter.java
   
   keystoreFileName = /users/ptII/adm/certs/ptkeystore
   storePassword = xxxxxx
   keyPassword = xxxxxx
   alias = ptolemy
   

   [$[Get Code]]
9. If you are using Server Side Includes (SSI) on the server, copy the *-ssi.htm.in files:
   cd $PTII/ptolemy/copernicus/applet
   cp modelJnlp-ssi.htm.in modelJnlp.htm.in
   cp modelVergil-ssi.htm.in modelVergil.htm.in
   cd $PTII
   

   [$[Get Code]]

Exporting one model

1. If you are logged in remotely, start up an X Server. On Sisyphus, try running Xvfb
   Xvfb :2 &
   export DISPLAY=localhost:2.0
   

   [$[Get Code]]
2. It is easiest to work on one model and get that working and then try all the models. So, clean up any previous work for a model:
   make book_real_clean JNLP_MODEL_DIRECTORY=doc/papers/y14/constructive/models JNLP_MODEL=Friction
   

   [$[Get Code]]
3. To create a JNLP file for one model and upload it: The make command should all be on one line
   make JNLP_MODEL_DIRECTORY=doc/papers/y14/constructive/models JNLP_MODEL=Friction KEYSTORE=/users/ptII/adm/certs/ptkeystore KEYALIAS=ptolemy STOREPASSWORD="-storepass `cat $HOME/.certpw`" KEYPASSWORD="-storepass `cat $HOME/.certpw`" DIST_BASE=ptolemyII/ptII10.0/jnlp-constructive book_dist_update
   

   [$[Get Code]]
   1. If you get Caused by: java.security.UnrecoverableKeyException: Password verification failed, then the problem is that $PTII/ptKeystore.properties is incorrect, see above.
   2. If you get sed: doc/papers/y14/constructive/models/Friction.jnlp: No such file or directory, then check that the name of the file and the name of the model in the file are the same.
      1. To update a jar file on the website, use
         (cd ptolemy/vergil; make install)
         cp ptolemy/vergil/vergil.jar signed/ptolemy/vergil/vergil.jar
         make sign_jar JARFILE=signed/ptolemy/vergil/vergil.jar STOREPASSWORD="-storepass `cat $(HOME)/.certpw`" KEYPASSWORD="-storepass `cat $(HOME)/.certpw`"
         scp signed/ptolemy/vergil/vergil.jar moog:/export/home/pt0/ptweb/ptolemyII/ptII10.0/jnlp-constructive/signed/ptolemy/vergil/
         

         [$[Get Code]]
4. Check the jnlp file, which will appear as http://ptolemy.org/ptolemyII/ptII10.0/jnlp-constructive/doc/papers/y14/constructive/models/Friction. Ignore any messages in the table of contents navigation panel on the left, we are checking that the JNLP, HTML and applet work. To test the JNLP from the command line, use
   javaws http://ptolemy.eecs.berkeley.edu/ptolemyII/ptII8.1/jnlp-modularSemantics/doc/papers/y15/modularSemantics/CTLorenz.jnlp
   

   [$[Get Code]]
5. Repeat the above two make commands until you are satisfied.

Debugging

It may be easier to work with files on our local machine to debug problems.

Certificate Problems

For certificate problems, be sure that the certificate password works.

JNLP loads, but exits

The JNLP files typically invoked ptolemy.copernicus.applet.JNLPApplication. If the JNLP file downloads and then exits, the problem could be with JNLPApplication. A good test command to try is to run

Building jnlp files

These instructions are weak, but might help

In general, for file problems, the signed jar files in $PTII/signed are portable, but the .jnlp file has to be regenerated and signed to include the location of the signed jar files and the .jnlp file itself.

1. The make ... jnlp_dist file will create the $PTII/signed directory and populate it, or do
   cd $PTII
   rm -rf *.jnlp signed
   make jnlp_all STOREPASSWORD="-storepass `cat ~/.certpw`" KEYSTORE=/users/ptII/adm/certs/ptkeystore KEYPASSWORD="-keypass `cat ~/.certpw`"
   

   [$[Get Code]]
2. One good test is to try running the ptiny version of vergil via a JNLP file. The $PTII directory contains .jnlp files, to run one, try
   make jnlp_run PTJNLP=vergilPtiny.jnlp
   

   [$[Get Code]]
3. To create a local .jnlp file:
   FIXME
   

   [$[Get Code]]
4. To update a .jar:
   cd $PTII/ptolemy
   rm ptsupport.jar; make ptsupport.jar
   cd $PTII
   cp ptolemy/ptsupport.jar signed/ptolemy
   make sign_jar JARFILE=signed/ptolemy/ptsupport.jar STOREPASSWORD="-storepass `cat ~/.certpw`" KEYSTORE=/users/ptII/adm/certs/ptkeystore KEYPASSWORD="-keypass `cat ~/.certpw`"
   

   [$[Get Code]]

I was working on instructions on building a local .jnlp, but it got complex. Basically ptolemy/copernicus/applet/model.jnlp.in needs to be changed from

to

and then run

Cleaning all the models

To clean all the models: (:source) cd doc/papers/y14/constructive/models make jnlps_real_clean (:end:)

Exporting all the models

1. Once you are satisfied with the first model, create JNLP files for all the models listed in the $(EXAMPLE_MODELS) makefile variable:
   cd $PTII/doc/papers/y14/constructive/models
   
   make KEYSTORE=/users/ptII/adm/certs/ptkeystore KEYALIAS=ptolemy STOREPASSWORD="-storepass `cat $HOME/.certpw`" KEYPASSWORD="-storepass `cat $HOME/.certpw`" DIST_BASE=ptolemyII/ptII10.0/jnlp-constructive jnlps
   

   [$[Get Code]]

Using a shortened URL

Optional: To use a shortened URL like http://ptolemy.org/modularSemantics

1. Become root on moog
2. Edit /usr/local/apache/conf/extra/httpd-vhosts.conf and find the ptolemy section that starts with
   <VirtualHost 128.32.48.150:80>
   ServerName ptolemy.eecs.berkeley.edu
   DocumentRoot "/home/www/ptweb"
   (:source:)
   Search for @@jnlp@@ and add a Redirect '''to the ptolemy section''': (:source:)
   Redirect /constructive http://ptolemy.eecs.berkeley.edu/ptolemyII/ptII10.0/jnlp-constructive/doc/papers/y14/constructive
   Redirect /constructive/ http://ptolemy.eecs.berkeley.edu/ptolemyII/ptII10.0/jnlp-constructive/doc/papers/y14/constructive/
   

   [$[Get Code]]
3. As root on moog, run
   /etc/init.d/apachectl graceful
   

   [$[Get Code]]

Removing unused jar files

To reduce space, it might be worth removing unused jar files.

To find out what jar files are used:

Updating the index.htm file

If you want to change http://ptolemy.eecs.berkeley.edu/ptolemyII/ptII10.0/jnlp-constructive/doc/papers/y14/constructive/models/index.html, then the source code at $PTII/doc/papers/y14/constructive/models/index.html.in. That file gets copied to /home/www/ptweb/ptolemyII/ptII10.0/jnlp-constructive/doc/papers/y14/constructive/models on moog.

To update, you could

1. Edit $PTII/doc/papers/y14/constructive/models/index.html.in
2. scp index.html.in moog:/tmp
3. Log on to moog as eal
4. Become root: sudo -i
5. cd /home/www/ptweb/ptolemyII/ptII10.0/jnlp-constructive/doc/papers/y14/constructive/models
6. cp index.html.in .