[kepler-dev] Adding jar files (and java classes) to kar files

[Dan Higgins]

Hi All,

    Currently, Kepler uses a concept called a 'kar' file for 
encapsulating actor information. In the $KEPLER/src/actors/ directory 
there are subdirectories for each actor. These subdirectories contain a 
MANIFEST file and a MoML (XML) file. This MoML file contains standard 
Ptolemy information (such as the java class names) plus some additional 
info about semantic types for characterizing the actor and actor ports 
(and Kepler actor help info is also stored in this MoML file). The ant 
task 'ant buildkarlib' zips the information in these directories into 
'kar' files, one for each actor.
    Now, the kar files are examined at Kepler startup and information 
from the kar file is saved in the Kepler cache and also used build the 
Kepler actor tree on the left of the main window. Up to now only the 
information in the contained MoML file was cached. [Recently the startup 
code was changed to 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.]
    The information in the MoML file is all that is needed for 
composites, pure MoML actors, and extension actors like those built by 
customizing the RExpression actor. Importing a kar file for these types 
of actors works fine because the underlying Java classes are already in 
the Kepler classpath. For new Java based actors, however, there is a big 
problem - the java classes are not known to Kepler!
    Well, the original idea for the kar file was to include other 
information. Stubs for a number of types of information was included in 
the KARCacheObject class when it was originally written. We originally 
discussed a custom ClassLoader that would allow classes to be loaded, 
unloaded, and versioned. Implementing this turned out to a major task 
and was postponed. But recently a means for dynamically adding a class 
to the standard classpath was discovered and this allows one to at least 
add new classes by including the compiled java classes in the kar file!
    Take a look at the $KEPLER/src/actors/ImageJ/ directory for an 
example. Two jar files are included in addition to the usual MANIFEST 
and MoML xml file. ImageJ.jar contains the Kepler actor java classes. 
ij.jar is a library used by the actor. The MANIFEST has been modified to 
list these two jars; i.e.

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' will be 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 will also be dynamically added to the classpath when thay 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 CVS. 
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.

As always, comments are appreciated.

Dan


-- 
*******************************************************************
Dan Higgins                                  higgins at nceas.ucsb.edu
http://www.nceas.ucsb.edu/    Ph: 805-893-5127
National Center for Ecological Analysis and Synthesis (NCEAS) Marine Science Building - Room 3405
Santa Barbara, CA 93195
*******************************************************************