Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Triquetrum/Extending Triquetrum

< Triquetrum
Revision as of 10:17, 12 February 2016 by Erwindl0.gmail.com (Talk | contribs) (Adding actors)

Introduction

A Triquetrum runtime can be extended in several ways and to suit different purposes. But all extensions are based on normal OSGi and/or eclipse extension mechanisms. I.e. the base concept for an extension is always an OSGi bundle.

Depending on the particular situation, an extension may offer alternative implementations of Triquetrum service APIs, it may add extra actor implementations, add features to the RCP editor etc.

In this text we will describe some common extension approaches, starting with how to add actor implementations.

Adding actors

Triquetrum fully exploits OSGi and eclipse plugin features to develop and use actors. Also the initial set of actors, directors and other model elements are contributed using the same mechanisms that can be used to add extra elements :

  • actors must be developed/packaged in OSGi bundles. The same goes for new directors implementations or any other possible type of model element.
  • to add new entries to the RCP editor palette, they must be registered using the provided extension points.
  • to allow the model parser to instantiate new actor instances, an actor class provider must be registered as an OSGi service implementation.

Below we describe some important steps in this process in more detail. The source code for the example actor can be found on the Triquetrum repository.

Creating an actor plugin project

As an example, we will implement a XYPlotActor that uses the Nebula XYGraph widget. To achieve this, we start by creating a bundle project org.eclipse.triquetrum.workflow.actor.plot .

TBD

Implementing an actor

TBD

Providing the actor class to the runtime

In a Triquetrum runtime, actor implementation classes are made available by registering OSGi services that implement org.ptolemy.classloading.ModelElementClassProvider . This indirect approach to access actor classes serves the following purposes :

  • Promote modular design, where groups of related actors can be developed and packaged and deployed as separate bundles
  • Benefit from the dynamic features and lifecycle offered by using OSGi services :
    • You can add actor bundles to a running Triquetrum system and the actors become available dynamically.
    • Similarly actor maintenance can be done using standard OSGi bundle and service maintenance without system downtime.
  • Version management for actor implementations can be supported by the combination of OSGi bundle version management and the API of the ModelElementClassProvider .
  • Additional actor lookup-logic can be plugged in as needed (e.g. class-name aliasing, filtering logic, ...)

A default implementation org.ptolemy.classloading.osgi.DefaultModelElementClassProvider offers a simple way of passing the actor classes into its constructor.

It can be used in a bundle activator for example, as follows :

public class Activator implements BundleActivator {
  public void start(BundleContext context) throws Exception {
   // FIXME figure out a more compact way to create a version-aware provider,
   // that uses the bundle version but is not too dependent on OSGi APIs itself.
   Version bundleVersion = context.getBundle().getVersion();
   VersionSpecification providerVersion = new ThreeDigitVersionSpecification(
       bundleVersion.getMajor(),
       bundleVersion.getMinor(),
       bundleVersion.getMicro(),
       bundleVersion.getQualifier());
   _apSvcReg = context.registerService(ModelElementClassProvider.class.getName(),
       new DefaultModelElementClassProvider(providerVersion, XYPlotActor.class),
       null);
 }
 public void stop(BundleContext context) throws Exception {
   _apSvcReg.unregister();
 }
 /** The svc registration for the actor provider */
 private ServiceRegistration<?> _apSvcReg;
}

Remark that the above is also valid for when you want to add other types of model elements like new Director implementations.

Packaging the plugin(s) for your RCP editor

To be able to add a new actor bundle to your RCP workbench, two extra things are required :

  1. Define the palette-related meta-data for your new actor(s), mainly :
    • Group name(s) and actor names that should be used in the editor palette
    • Images/icons that must be used
  2. Provide an eclipse feature project to package a deployable unit

Defining the palette entry

The palette definition is done using extension points. As this is purely GUI-related, and as it requires a "real" eclipse plugin, it is good practice to split this from the actual actor implementation bundle.

So we create a new simple plugin project (no need for any Java in here) org.eclipse.triquetrum.workflow.actor.plot.palette . In our example it contains following elements :

icons/plot.png
META-INF/MANIFEST.MF
build.properties
plugin.xml

The most important content is in the plugin.xml :

<extension 
     name="Triquetrum palette XYPlot extension"
     point="org.eclipse.triquetrum.workflow.editor.paletteContribution">
  <group displayName="Examples">
     <entry 
            class="org.eclipse.triquetrum.workflow.actor.plot.XYPlotActor"
            displayName="XY Plot"
            icon="icons/plot.png"
            type="Actor">
    </entry>
  </group>
</extension>

The MANIFEST is simply :

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Palette entry for XYPlotActor
Bundle-SymbolicName: org.eclipse.triquetrum.workflow.actor.plot.palette;singleton:=true
Bundle-Version: 1.0.0.qualifier
Require-Bundle: org.eclipse.triquetrum.workflow.editor;bundle-version="1.0.0"

Implementing an actor feature

Finally we need to provide a packaging feature. This is best achieved with a third project. Eclipse provides a dedicated feature project wizard that we can use to create this, in our case org.eclipse.triquetrum.workflow.actor.plot.feature .

Besides some meta-info, the main contents of the feature.xml are the plugins that should be packaged. In our plot example these are :

  • org.eclipse.nebula.visualization.xygraph
  • org.eclipse.triquetrum.workflow.actor.plot
  • org.eclipse.triquetrum.workflow.actor.plot.palette

An important extra point of attention : to ensure that the actor bundle is auto-started upon its installation, we need to add a short p2.inf instruction file in the actor bundle, alongside its MANIFEST file, containing a single, rather cryptic, line :

instructions.configure = setStartLevel(startLevel:4); markStarted(started: true);

Installing the feature in your workbench

When the above is implemented, i.e. an actor bundle, the palette configuration and the feature definition, it is straightforward to provide an installable unit that can be uploaded e.g. in a Triquetrum RCP editor. The following steps are needed :

  1. Open the feature.xml editor on the Overview tab
  2. Select the Export Wizard link in the Exporting section
  3. Make sure your feature project is selected from the Available Features
  4. Choose 'Archive File' as Destination and specify its path and name
  5. In the Options tab, check the 'Package as individual JAR archives' and the 'Generate p2 repository' options.
  6. Do it!

TODO : add a screenshot

Then, in your Triquetrum RCP editor, go to the Help > Install New Software... menu and add your exported archive as repository. You may need to uncheck the 'Group items by category' box, and then you should see your new actor feature! From there on, follow the standard eclipse plugin installation steps in this wizard.

After the requested restart, you should see your new actor in the editor palette, and you should be able to use it in your workflows!

TODO : add a screenshot

Back to the top