Development jcp

JChempaint applet and application: development pointers.

Set up

To start developing on JChempaint (also "JCP"), you need java code checkouts of the CDK as well as JCP. CDK provides the core cheminformatics functionality, JCP deals with the drawing and rendering aspects. In Eclipse, you define two Java projects. One for the CDK code, the other for JCP code. The JCP Eclipse project needs a dependency on the CDK (Project properties -> Java build path -> Projects, add the CDK as a required project for JCP).

• read Building the application below
• apply the changes to config files as described
• make sure you have eclipse >= 3.6
• install the JavaCC plugin from http://eclipse-javacc.sourceforge.net/
• create two projects in eclipse, CDK and, say, JCP
• make JCP dependent on CDK
• select CDK/src/main/org/openscience/cdk/iupac/parser/NomParser.jj and right-click compile with JavaCC
• select CDK/src/main/org/openscience/cdk/smiles/smarts/parser/SMARTSParser.jjt and right-click compile with JavaCC (anyone to automate this?)

Running from Eclipse

You can run and debug JChempaint through Eclipse. The class org.openscience.jchempaint.applet.JChemPaintEditorApplet implements Applet and is runnable as such. It's recommended to use Eclipse Run Configurations to make the applet look and work better, for example by setting impliciths to true. Alternatively class org.openscience.jchempaint.application.JChemPaint can be run as as a standard Java application.

Fork info

The CDK itself in principle has the Java code for rendering images, found in packages org/openscience/cdk/controller/ and org/openscience/cdk/controller/renderer. These CDK packages were used by the JCP applet and application. The CDK code was removed to be re-engineered and to be released again in the future. When you look in the renderer and controller folders of for example CDK 1.4 you will see that most code is missing.

Due to circumstances it was decided for the JChempaint application and applet to fork away from CDK and instead hard copy the renderer and controller into JCP's own source folders. So, you can find directories org/openscience/jchempaint/controller/ and org/openscience/jchempaint/renderer, a fork of the CDK's version with some specific patches applied.

CDK git clone (EBI details)

As virtual EBI user 'cheminf' we publish our own CDK patched code through http://www.ebi.ac.uk/steinbeck-srv/git/cdk/. This points to EBI directory /nfs/panda/steinbeck/www/git, which publishes EBI's /nfs/panda/steinbeck/git/cdk. On that master checkout we apply patches that are necessary to run the current development version of JCP. Eventually these patches should be submitted to CDK master and removed as patch from our repo. To apply patches, work in branch "ebiPatches" and keep it rebased on recent pulls of the "master" branch. To publish the repo after a new patch, go to direcory /nfs/panda/steinbeck/www/git and run (bash) command "source repo.source". This makes the latest changes public. Pulling from http://www.ebi.ac.uk/steinbeck-srv/git/cdk/ should then reflect that newest patch.

Building the application

Following are the instructions to compile the newest JChemPaint from the repositories

• github/cdk/cdk
• github/rwst/jchempaint

Use 'ant' to build the Jchempaint application. You must first edit the file 'ant.properties' located in the top folder, to make it point to a valid CDK checkout (property cdk.dir=...) Then run: ant clean dist

Here is a list of all commands you will have to give:

 git clone [email protected]:rwst/jchempaint.git
 cd jchempaint
 cp ant.properties.template ant.properties
 edit ant.properties (set cdk.dir=/home/vedrin/jcp/20120405/cdk)
 edit build.xml (set <include name="org/openscience/jchempaint/**" /> for target dist
 ant

(from http://sourceforge.net/mailarchive/forum.php?forum_name=cdk-devel&max_rows=25&style=nested&viewmonth=201205&viewday=21 )

The log of this target shows the location of the application, for example:

  dist:
     [jar] Building jar: /home/markr/src/jchempaint/trunk/dist/jchempaint-3.1.3.jar
  BUILD SUCCESSFUL

This is a runnable jar file, to continue the example you can run the application with

   java -jar /home/markr/src/jchempaint/trunk/dist/jchempaint-3.1.3.jar

Building the applet

The applet can also be built with ant, a few varieties exist:

• ant clean dist-applet
• ant clean dist-applet-signed (see "Applet signing" further down)
• ant clean dist-applet-shrunk-signed (see "Applet shrinking" further down)

Applet class lists

In order to make loading of the applet faster, we use the class index system. This means the classes are split in several jars and only one (jchempaint-applet-core.jar) is referenced in the applet tag. This contains a list where other classes are found. In practice, when the applet list is set up properly you should see loading of only a handful of jar files during start up of the applet (see the JRE log window) If you see more exotic CDK jar files being loaded, you need to see why that happens (which particular class(es) are needed) and move these into the core jar file by manually editing. See also:

• Applet class lists

Applet signing

The applet performs certain I/O operations and to allow this it needs to be signed (resulting in a message to allow users to trust the certificate or not). More information on signing jar files is here. To create a local certificate for use in development you use the commands

  keytool -genkey

and

  keytool -selfcert

The ant target "dist-applet-signed" takes care of signing the jar files. For the ant target to work, you need to give your alias and passphrase in the ant.properties file.

Example output:

    [signjar] Warning:
    [signjar] The signer certificate will expire within six months.
    [signjar] Signing JAR: /home/markr/src/jchempaint/trunk/dist/jar/jchempaint-applet-viewer-opts.jar to /home/markr/src/jchempaint/trunk/dist/jar/jchempaint-applet-viewer-opts.jar as mykey
    .... etc

Use a browser for testing. Note that the appletviewer tool ignores signing, it will still throw security exceptions. On release of an applet version, we let the EBI sign the jar files. You can let Systems do this, Andy Cafferkey is the man with the plan.

Applet shrinking

The combined applet jar files add up to quite a few megatrons so we use Yguard to try and bring down the total size. Yguard is not distributed through the JCP SVN repository because that's not allowed. You need to download it separately and then save it in the root folder of JCP. You can then run the ant target "dist-applet-shrunk-signed" which will shrink the applet jar files, stripping out classes that are not needed. This is risky: sometimes too many classes/methods are stripped, which results in runtime errors. If this happens you get 'class not found' like exceptions, check the JRE log window of your browser. Find the problematic classes or methods and register them to be kept by Yguard, then build the jar files again. These 'keep' instructions are done in the build.xml file, for example as in the lines below:

 <keep>
   <class classes="public">
   <patternset>
      <include name="org.openscience.jchempaint.undoredo.**.*"/>
    </patternset>
   </class>
   <class name="org.openscience.cdk.tools.LoggingTool" methods="public" fields="none" />
   <class name="org.openscience.cdk.tools.ILoggingTool" methods="public" fields="none" />
   .....

Testing

Junit tests are in place that test the drawing of structures with JChempaint. These test classes are located in src/test, an example is org.openscience.jchempaint.JCPEditorAppletDrawingTest. While running these test classes you should not touch your mouse or keyboard because this will make things fail. Junit tests should be added for each bug fixed.

• Testing JCP

Cron building nightly

Virtual user "cheminf" runs a daily cron job that puts the latest development build into /nfs/panda/steinbeck/www/jchempaint-nightly.

Some more topics

• Past JCP Events
• New Renderer Architecture
• JCP3/Internationalization
• Undo/Redo
• Templates
• JCP GUI configuration
• To report bugs in JCP or to propose enhancements: go to the issue tracker