[kepler-dev] Adding a new director and actors to kepler/director and kepler/actors

[Chad Berkley]

Hey Christopher,

See my answers below.

Christopher Brooks wrote:
> I want to add the ContinuousDirector to Kepler.
> What do I do?

The short answer is copy one of the existing directors' 
resources/kar/xxx directories and then fill in the values.  There is no 
automated functionality for this that I am aware of.  If you wanted to 
make a new module just for the ContinuousDirectory, that would work too.

> 
> 
> I did not find documentation about this, the closest is
> https://kepler-project.org/developers/reference/adding-new-classes-jars-to-kepler 
> 
> which is marked as private.
> 

I believe it is private because it is no longer current or relevant.

> I see there is a directors repository:
> bash-3.2$ ls kepler/directors
> build.xml    kar        lib        resources
> 
> That directory has a kar directory that contains the kar files:
> 
> bash-3.2$ ls kepler/directors/kar
> CTDirector.kar    DDFDirector.kar    DEDirector.kar    PNDirector.kar    
> SDFDirector.kar
> 
> How do I create a kar file such as these?
> Instantiating the director using "Instantiate Attribute"
> and then using "Save Archive (KAR)" creates a workflow that contains the
> ContinuousDirector, but I want just the ContinuousDirector.

This directory is created automatically by kepler at startup.

> 
> Do I need to create ContinuousDirector.kar by hand? (I suspect
> that ContinuousDirector.kar will be created for me from the
> files in the resources directory.)
> 
> I see that there is also a resources directory:
> bash-3.2$ ls kepler/directors/resources
> kar
> bash-3.2$ ls kepler/directors/resources/kar
> CTDirector    DDFDirector    DEDirector    PNDirector    SDFDirector
> bash-3.2$ ls kepler/directors/resources/kar/CTDirector
> CTDirector.xml    MANIFEST.MF
> 
> It looks like the contents of the kar file and the contents of the
> resources directory are the same.
> Why?
> 
> bash-3.2$ jar -tvf kepler/directors/kar/CTDirector.kar
>      0 Thu Jan 14 13:38:38 PST 2010 META-INF/
>    333 Thu Jan 14 13:38:36 PST 2010 META-INF/MANIFEST.MF
>  12461 Thu Jul 23 13:48:38 PDT 2009 CTDirector.xml
>    254 Tue Oct 20 17:17:36 PDT 2009 MANIFEST.MF
> bash-3.2$ ls -l kepler/directors/resources/kar/CTDirector/
> total 40
> -rw-r--r--  1 cxh  staff  12461 Jul 23 13:48 CTDirector.xml
> -rw-r--r--  1 cxh  staff    254 Oct 20 17:17 MANIFEST.MF
> 
> I guess the kar directory is created from the resources directory because
> director/kar is not in svn:

right, when you startup kepler, you'll notice a line on the console that 
says "building kars" or something like that.  Any module can have a 
resources/kar directory and the contents of that directory will be 
automatically turned into kars at startup.

> 
> bash-3.2$ svn info kar/CTDirector.kar
> svn: 'kar' is not a working copy
> 
> In fact, the kar directory is listed in svn:ignore.
> 
> Looking at the kepler/directors/resources/kar/CTDirector.xml file, I
> see that I could just try copying the file.
> 
> However, I have some questions:
> 1. CTDirector has an entityId:
> 
> <property name="entityId"  
> value="urn:lsid:kepler-project.org:director:4:1" 
> class="org.kepler.moml.NamedObjId"/>
> How do I update this?

Right now, it's by hand.  Aaron will have the latest info on lsid 
generation.  Aaron?

> 
> 2. I see that the class comment is included in the .xml file.
> What happens when the class comment is updated in the java file?
> Does the .xml file get automatically updated?

The xml file is not updated automatically from the source.  There used 
to be an 'ant generate-actor-docs' task that did this, but I don't think 
it exists anymore.

> 
> 3. I see the .xml file has ports and parameters.  Do these get
> automatically updated as the .java file changes?

No, the xml file is metadata about the java file.  It must be updated 
manually at this point.  We did this because we wanted to allow semantic 
annotations on any port and ptolemy allows ports and params to be 
created either in the moml or in the java code.  We wanted all 
declarations in the xml file so that we had a complete description of 
the component without having to instantiate it in java.  That having 
been said, we've had many problems over the years with our branched 
version of moml.  I saw edward comment the other day on a possible moml 
2.0 spec.  If that were to happen, I'd be happy to be on the design 
committee :)

I don't think everything is on the web site, but aaron does have a good 
Q&A about the kar system here:
https://kepler-project.org/developers/teams/framework/kepler-archive-kar/questions-and-answers
and there's a spec for the manifest here:
https://kepler-project.org/developers/teams/framework/kepler-archive-kar/kar-manifest-specification
All of the kar docs are here:
https://kepler-project.org/developers/teams/framework/kepler-archive-kar

Feel free to point out any ommissions or errors if you find them.  Also 
if you want to write up a how-to based on what you're doing, that would 
be awesome!

chad