Triquetrum/Ptolemy/Porting

This page covers how to port Ptolemy actors to Triquetrum.

This page is not yet completed.

See Also

• Triquetrum/Extending_Triquetrum - A good place to start if you are not familiar with RCP and features.
• Triquetrum/Kepler - Porting Kepler actors to Triquetrum.
• Bug #90 Document the process for porting Ptolemy actors to Triquetrum

IP Issues

All jar files that are to be shipped with an official release must be vetted for IP issues, see Contribution Questionnaire->Third Party Libraries].

Actors that are checked in to the Ptolemy II ptII svn repository are considered to be third party libraries.

A large subset of the Ptolemy II actors have been reviewed as part of Eclipse IP process. The reviews themselves are not public, see Issue #70: Open Ipzilla issues for Triquetrum third party code.

OSGi split-package constraints

One limitation with OSGi is that a Java package is ideally only exported by one OSGi bundle. Or more correctly : it's tricky to have good control on what happens when a bundle imports a package when that package is exported by 2 provider bundles, with a same version. Especially when the contents of the package are different in those providers.

This means that actors in the ptolemy.actor.lib package that are not in source bundle that has passed the Eclipse Contribution Questionnaire (CQ) IP process must be put into another package, or added to the existing ptolemy.actor.lib bundle in ptII svn osgi-2-0 repository and a new CQ created.

In general we do not want to request IP review very often, so if the package is already in a bundle that has been reviewed, then we would like to be able to for instance provide extra bundles that can be installed from an update site. To avoid the package name conflict, this would involve renaming the concerned package. See also Bug 113: Need a way for OSGi bundles to add to the MoML Filters.

At the end of this page, an approach is described to combine this approach while still maintaining compatibility with existing models that use such extra actors, i.e. using the original fully-qualified actor class names.

Overview

Porting Ptolemy actors requires the following steps

1. Create an actor bundle
2. Add Required Projects
3. Implementing an actor
4. Providing the actor class to the runtime
5. Packaging the plugin(s) for your RCP editor

One key element is that because of IP issues, the Ptolemy actor OSGI jar files are not checked in to the Eclipse Triquetrum repository. Instead they are checked in elsewhere (FIXME: where?)

On this page, we import the Ptolemy II Higher Order Components (hoc) actors and directors like the Case actor.

Create an actor bundle

See Extending Triquetrum - Creating an Actor Bundle

TBD - Describe how to set up the bundle for the ptolemy.actor.lib.hoc classes

Add Required Projects

See Extending Triquetrum - Added Required Projects

Implementing an actor

See Extending Triquetrum - Implementing an actor

The code for the actors is already present in the ptII tree, what needs to happen is that we need to create an OSGi jar file that contains those classes.

Check out the ptII osgi-2-0 branch

See Extending Triquetrum - Providing the actor class to the runtime

Because of IP issues, the Ptolemy actor OSGI jar files are not checked in to the Eclipse Triquetrum repository. Instead they are checked in elsewhere (FIXME: where?)

Read-only access

1. Check out the branch with

 svn co https://repo.eecs.berkeley.edu/svn-anon/projects/eal/ptII/branches/osgi-2-0 

Read/write access

1. Get read/write access to the ptII svn repository by emailing Christopher Brooks
2. Check out the branch with

 svn co https://repo.eecs.berkeley.edu/svn/projects/eal/ptII/branches/osgi-2-0

Note, the above checks out the head of the osgi-2-0 branch, To check out the latest version that contains the approved sources that have gone through the Contribution Questionnaire (CQ), use

 svn co https://repo.eecs.berkeley.edu/svn/projects/eal/ptII/branches/osgi-2-0-cq-1 

See Bug #70: Open Ipzilla issues for Triquetrum third party code

Set up a jar file for the actors

TBD - describe the edits necessary to the osgi branch

To do: Create a script that does this automatically

Publish the OSGi bundle for the actors

TBD - where? We probably should create a p2 site and project somewhere outside of the Eclipse repos that is writable by the Triquetrum contributors. One possibility is to use the https://chess.eecs.berkeley.edu/triq. There is a website there and we can add users that need to update the location.

Packaging the plugin(s) for your RCP editor

See Extending Triquetrum - Packaging the plugin(s) for your RCP Editor

Solving the ptolemy.actor.lib package naming issue

Ptolemy II provides a huge list of actors in a single package, ptolemy.actor.lib. And the policy seems to be to keep on extending the list of actors in there. As explained above already, this does not fit well with the standard approach for OSGi bundles and contained packages, if one does not want to keep on modifying the ptolemy.actor.lib bundle contained in the Triquetrum distribution.

Here we describe a possible approach to work with this situation.

The requirements are :

• do not reuse a package name across 2 or more actor bundles : rename the packages
• support parsing and running existing models that point to the original actor class & package names : provide a mechanism for handling aliases

Creating a ptolemy.actor.lib2

As an example we're going to create an extra bundle to add a couple of actors that are not yet in the default ptolemy.actor.lib bundle :

1. ptolemy.actor.lib.Bernoulli
2. ptolemy.actor.lib.BooleanMultiplexor
3. ptolemy.actor.lib.BooleanSelect
4. ptolemy.actor.lib.BooleanSwitch

We start by creating a new bundle ptolemy.actor.lib2, copying the actor code in there and renaming their package to ptolemy.actor.lib2. Follow the steps described above to setup the bundle manifest etc.

Implementing aliases

As in all actor bundles, we must define a ModelElementClassProvider ( see Extending Triquetrum - Providing the actor class to the runtime ). This provides a spot to implement aliases, as it determines which actor class is provided for a requested class name.

An example provider implementation can be :

public class AliasModelElementClassProvider implements ModelElementClassProvider {

 /**
  * Creates a provider that does not care about class versions,
  * i.e. it will only check on class names to check if it can provide a requested class.
  *
  * @param knownClasses
  */
 public AliasModelElementClassProvider(Map<String,Class<? extends NamedObj>> knownClasses) {
   this(null, knownClasses);
 }

 /**
  * Creates a provider that cares about class versions,
  * i.e. it will check on class names and on the requested version to check if it can provide a requested class.
  *
  * @param version if null, the provider will not care about versions
  * @param knownClasses
  */
 public AliasModelElementClassProvider(VersionSpecification version, Map<String,Class<? extends NamedObj>> knownClasses) {
   this._knownClasses = knownClasses;
   this._versionSpec = version;
 }

 public Class<? extends NamedObj> getClass(String className, VersionSpecification versionSpec) throws ClassNotFoundException {
   if (_versionSpec != null && _versionSpec.compareTo(versionSpec)<0) {
     throw new ClassNotFoundException(className + " " + versionSpec);
   } else {
     for (Map.Entry<String, Class<? extends NamedObj>> actorEntry : _knownClasses.entrySet()) {
       if (actorEntry.getKey().equals(className)) {
         return actorEntry.getValue();
       }
     }
     throw new ClassNotFoundException(className);
   }
 }

 // private stuff

 private VersionSpecification _versionSpec;
 private Map<String,Class<? extends NamedObj>> _knownClasses;
}

and this can be registered by the activator as follows, defining the aliases :

public void start(BundleContext context) throws Exception {
 Version bundleVersion = context.getBundle().getVersion();
 VersionSpecification providerVersion = new ThreeDigitVersionSpecification(
     bundleVersion.getMajor(),
     bundleVersion.getMinor(),
     bundleVersion.getMicro(),
     bundleVersion.getQualifier());

 Map<String, Class<? extends NamedObj>> actorAliases = new HashMap<>();
   actorAliases.put("ptolemy.actor.lib.Bernoulli", Bernoulli.class);
   actorAliases.put("ptolemy.actor.lib.BooleanMultiplexor", BooleanMultiplexor.class);
   actorAliases.put("ptolemy.actor.lib.BooleanSelect", BooleanSelect.class);
   actorAliases.put("ptolemy.actor.lib.BooleanSwitch", BooleanSwitch.class);

 _apSvcReg = context.registerService(ModelElementClassProvider.class.getName(),
       new AliasModelElementClassProvider(providerVersion, actorAliases),
       null);
}