Jump to: navigation, search

Define Tigerstripe Annotations

< To: Tigerstripe_Tips-n-Tricks

This article will take you step-by-step through the definition of a new Annotation Scheme for Tigerstripe Models, and will show how to consume the annotations from a M1 Generator Plugin.

Note: The information doesn't have much specifics to Annotating Tigerstripe models. The same steps can be applied when defining annotation types not target to Tigerstripe model artifacts.

Scenario & Context

For this article, we will assume that the goal is to create a new Annotation Scheme for Tigerstripe models, that should allow users to annotate any Tigerstripe model artifact component with 2 types of Annotations:

  • Design Notes: that will contain a large Text Box to capture some human readable note.
  • TODOs: that will denote the fact that some more work is required on a model component, by providing a "summary message" in a smaller-one-line text box, and a boolean attribute allowing to specify whether a "hack is in place".

We will then create a plugin that will use these annotations to generate a "design report" about all artifacts, highlighting any design note on each artifact and some potential TODO list.

Defining the new Annotation Scheme

First things first, let's define the annotation types that will be presented to the end-user.

Annotation types are defined through an EMF .ecore file that needs to be packaged into an Eclipse Plugin so it can be installed. This plugin will need to be present on the end-user Eclipse install for him/her to see the corresponding Annotation Types.

The easiest starting point is to create a new EMF Plugin. Select File->New Project->Eclipse Modeling Framework->Empty EMF Project. In this example, we'll use org.eclipse.tigerstripe.annotation.example.designNotes for a name.

In order to define Annotations, we'll need to add a few dependencies to that plugin:

These are required to access the necessary Extension Points defined by the Tigerstripe Annotation Framework (TAF).

Next, let's define the .ecore, or EMF model, for the Annotations to be presented to the user. In our case, we will define:

  • DesignNotes
  • TODOs

A screenshot of the .ecore is shown below:

A couple of points to note here:

  • additional EMF EAnnotations can be used to drive the rendering of the field in the UI. In this case make sure the Text for the Design Notes allow for multiline text. More details can be found at [1].
  • The nsURI defined here for the package will be used to determine the filename of the annotation store, where all user annotations will be stored. In fact for each nsURI, a .ann file (in this case org.eclipse.tigerstripe.annotation.example.designNotes.ann) is created in the target Model Project to store the annotation values. Storing of annotation values goes to the Eclipse install for all non-tigerstripe related annotations. Tigerstripe defines a specific Router to ensure annotations are persisted in the context of the Model Project, so the values can be versioned through the same SCM. Here again more details about "annotation routers" can be found at [2].
  • In a single .ecore we have define 2 annotation types: DesignNote and TODO. Each of them need to be registered with the TAF through an extension point (see below)

Using the Annotation Scheme against a simple model

Consuming Annotations from a Plugin Template