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

[Christopher Brooks]

Ok, thanks to Aaron's hints below, I was able to set up the LSIDs
appropriately.  I updated

https://kepler-project.org/developers/reference/updating-the-kepler-directors-and-actors
and
https://kepler-project.org/developers/teams/framework/kepler-life-science-identifiers-keplerlsid

I created a separate "continuous" module that contains the kar .xml
descriptions for the Continuous domain actors.  I added the
ContinuousDirector itself to the list of other directors.

I'm thinking we should delete CTDirector from the list of directors
that are made available by default in Kepler.  ContinuousDirector
is under active development, CTDirector is not.  Users could still
instantiate CTDirector by hand if they so desired.  Comments?

Another question:  I put the Continuous actors in a separate module.
Was this the right thing to do, or should I just put them in with
the Actors?  One issues is that these actors probably will
only work under the ContinuousDirector.  I don't think they will
work well under SDF.  I created a separate module because the
actors module is rather large and I think we talked about breaking
it up.

If we want to have the continuous actor kar xml files in a separate
module, then should the default kepler build require the continuous
module?

The continuous module contains only the kar .xml files, so it is only
a few 10s of kbytes in size.

If we want Kepler to always have the continuous actors directly available,
then how is this done?  Should I just add continuous to
kepler/module-info/modules.txt?


One side issue about my current continuous module is that when I do
   ant change-to -Dsuite=continuous
   ant run
Then the left hand tree view looks like:
+ Components
+ Projects
+ Statistics
+ Actors
+ Continuous
+ Directors
+ R

I'd like Continuous to not be at the top level.  Any ideas?

This is all for bug 4194: Kepler should have the Continous and Modal domains
http://bugzilla.ecoinformatics.org/show_bug.cgi?id=4194

I'd like to finish this up by Friday.

I updated docs about how to add a Director to the list of directors.
I also created ptII/doc/adm/docml2karxml which reads in Ptolemy DocML
files from ptII/doc/codeDoc and tries to generate a KAR .xml file

Sample use might be:

    cd kepler/ptolemy
    export PTII=`pwd`
    ./configure
    make >& make.out
    cd $PTII/doc; make docs
    cd ~/src/kepler/actors/resources/kar
    $PTII/adm/bin/docml2karxml $PTII/doc/codeDoc/ptolemy/domains/continuous/lib/*.xml

_Christopher

On 1/21/10 12:25 PM, Aaron Schultz wrote:
>
> Hi Christopher,
>
> All the LSIDs that are in svn checked in xml files were hand generated.
> Feel free to generate your own LSIDs and put them in by hand.
>
> You can make up your own authority and namespace and do something like
> urn:lsid:ptolemy.berkeley.edu:brooks:1:1
> You will need to keep track of your own object ids and revisions when
> modifying things by hand.
>
> if you want to use the same web service that Kepler uses to automate
> namespace generation
> you can ping the following URL in your web browser
> http://gamma.msi.ucsb.edu/OpenAuth/?username=kepler&password=kepler&
> and this will return an incremented integer as the next available and
> unique namespace
> The lsid here would be (if the namespace returned was 10001)
> urn:lsid:gamma.msi.ucsb.edu/OpenAuth/:10001:1:1
> Where the authority in this case is the actual URL of the web service
> that generated the namespace
>
> Or you can implement your own web service:
> http://code.kepler-project.org/code/kepler-docs/trunk/teams-and-wg/2-infr-teams/framework/AuthNamespace_WebService_Spec/example.jsp
>
> and modify the configuration to reflect it in
> configuration-manager/resources/configuration/configuration.xml
> (authNamespaceServices)
>
> As for saving KARs from instantiated NamedObjs,
> I just tried saving an Instantiated Component (ContinuousIntegrator) as
> a KAR and it worked well.
> Instantiated Attributes however won't work at the moment. We would need
> to implement the ability
> to add Attributes to the Save Initiator list in the SaveKAR mechanism.
> Currently it only supports ComponentEntities
> at the top of the dependency hierarchy (meaning only ComponentEntities
> can be added to a KAR without having a
> dependency on another file in the KAR).
>
> Aaron
>
>
> Christopher Brooks wrote:
>> Hey Chad,
>> Thanks, that was a big help.
>> I have a start on docs at:
>> https://kepler-project.org/developers/reference/updating-the-kepler-directors-and-actors
>>
>>
>> Aaron, I have some FIXME's in that document.
>>
>> In particular, how do I handle lsids? I found
>> https://kepler-project.org/developers/teams/framework/kepler-life-science-identifiers-keplerlsid
>>
>>
>> but I'm not sure how to update this line in the .xml file:
>> <property name="entityId"
>> value="urn:lsid:kepler-project.org:director:4:1" class="or\
>> g.kepler.moml.NamedObjId"/>
>>
>> How do I update the two lsid fields in the MANIFEST.MF:
>> --start--
>> lsid: urn:lsid:kepler-project.org:kar:329:1
>>
>> Name: ContinousDirector.xml
>> lsid: urn:lsid:kepler-project.org:director:4:1
>> ---end---
>>
>> I found
>> https://kepler-project.org/developers/teams/framework/kepler-life-science-identifiers-keplerlsid
>>
>> and I can update the namespace, but how do I update the object tag?
>>
>> _Christopher
>>
>>
>> On 1/15/10 2:10 PM, Chad Berkley wrote:
>>> 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
>>>
>>
>

-- 
Christopher Brooks, PMP                       University of California
CHESS Executive Director                      US Mail: 337 Cory Hall
Programmer/Analyst CHESS/Ptolemy/Trust        Berkeley, CA 94720-1774
ph: 510.643.9841 fax:510.642.2718	      (Office: 545Q Cory)
home: (F-Tu) 707.665.0131 cell: 707.332.0670