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

[Matthew Jones]

Yes, nice work Dan.  Very exciting.  This has been a long time coming, 
and I am excited about the possibilities that this opens up.  It should 
be now far easier for us to split the repository into a kepler-core 
component and an actors component.

I assume that, if an actor kar file includes a jar for which another 
actor already has loaded an earlier version of a jar, then the original 
will be used and the actor that depends on the later version may not 
work.  So it is incumbent upon an actor developer to be sure that their 
kar file does not conflict with an earlier version, although this may be 
essentially impossible given that users will have the ability to import 
arbitrary kar files that may be incompatible.

Thanks Dan.  Nice move forward.

Matt

Chad Berkley wrote:
> Nice job, Dan!  This sounds great.  I'll give it a try here shortly. 
> Have you seen any changes in performance while using this?  Have you 
> changed any other actors besides ImageJ?
> 
> chad
> 
> Dan Higgins wrote:
>> 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
>>
>>
> 


-- 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Matthew B. Jones
Director of Informatics Research and Development
National Center for Ecological Analysis and Synthesis (NCEAS)
UC Santa Barbara
jones at nceas.ucsb.edu                       Ph: 1-907-523-1960
http://www.nceas.ucsb.edu/ecoinfo
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~