Adding New Classes (JARs) to Kepler

NOTE: OBSOLETE material; this page applies to Kepler 1.0, but not to Kepler 2.0, which has introduced "modules" for handling jar files -- see the Kepler 2.0 documentation instead.  In particular, see our Hello World tutorial.

One of the Kepler Framework  team's top priorities is to separate the actor tree from the main kernel of Kepler, allowing Kepler Archive files (KARs) to load JARs and other resources dynamically in their own namespace using an independent classloader. For more information about the status and design of this functionality, please see the Framework team's work area. In the meantime, JAR files can be added to KAR files and to the classpath with the following limitations: Kepler does not currently support multiple class versions or class unloading.

Background

Kepler uses the KAR (Kepler ARchive) format to store and transport Kepler actors and workflows. A KAR file is a zipped file that contains a manifest file and a MoML file, as well as (in some cases) one or more JAR files. The MoML file is an XML file that contains standard Ptolemy information (such as the Java class names) plus some additional information about semantic types for characterizing the actor and actor ports, and actor documentation. The manifest file (manifest.mf) is a text document that contains versioning information as well as the location of the actor's MoML file and its LSIDs (Life Science Identifier)—one for the KAR file, another for the actor. If additional JAR files are used, the manifest file also contains information about them.

Each actor that is shipped with Kepler has a manifest and MoML file that is stored in the $kepler/src/actors directory in a folder named after the actor. For example, the manifest and MoML files for the Constant actor are stored under $kepler/src/actors/constant. The ant task 'ant buildkarlib' zips the information in these directories into KAR files, one for each actor. The KAR files are examined at Kepler startup and information from the KAR file is saved in the Kepler cache and also used to build the Kepler actor tree displayed in the Components and Data Access area of the application. Kepler will not pass the MoML file to the MomlParser until the actor is dragged to the work area and dropped, thus deferring the loading of Java actor classes.

For new Java-based actors, the Java classes are not known to Kepler and must be dynamically added to the classpath. Kepler currently uses the ClassPathHackerclass (see $KEPLER/src/util/ClassPathHacker) to automatically add all files under $KEPLER/lib/jar/ to the classpath when Kepler starts up. The KAR loader extracts and copies any JARs included in a KAR file into this directory, and the classes are simultaneously added to the classpath as well.

Example

Take a look at the $KEPLER/src/actors/ImageJ/ directory. In addition to the manifest and MoML file, the directory contains two JARs: ImageJ.jar, which contains the Kepler actor Java classes; and  ij.jar, which is a library used by the actor. The manifest file has been modified to list these two JARs:

Manifest-Version: 1.4.2 KAR-Version: 1.0 lsid: urn:lsid:kepler-project.org:kar:154:1
Name: ImageJ.xml lsid: urn:lsid:kepler-project.org:actor:251:1 type: actorMetadata
Name: ImageJ.jar lsid: urn:lsid:kepler-project.org:jar:251:1 type: jar
Name: ij.jar lsid: urn:lsid:kepler-project.org:jar:252:1 type: jar

At startup, when the KAR files are scanned (in the KARCacheObject class), the entries of type JAR are pulled out of the KAR and copied to the $KEPLER/lib/jar/ directory. Any JARs in this directory are automatically added the classpath the next time Kepler is started. The JARs are also dynamically added to the classpath when they are copied. This means that if all the Java classes needed by an actor are included in the KAR file (in JARs), then the KAR file is "self-contained." One simply needs to import a KAR file to add a new Java-based actor to Kepler.

NOTE: Currently, the ij.jar and ImageJ.jar classes are already in SVN. If you are using Ant, remove build/classes/util/ImageJActor.class and lib/jar/ij.jar to test this dynamic loading. You will also need to delete the .kepler directory to force rebuilding the cache.