OME Power User Document

OME Power User Tutorial

Who is a "Power User"?

One who uses OME to build or experiment with modelling frameworks
One who develops plugins to extend OME’s functionality

What is a Framework?

A framework specifies the types of objects that can exist in a model employing the framework.
A framework also specifies the relationships that can exists between these objects in the model.
In OME3, these object types and relationships are specified in a textual Telos file (.tel).
In order to be usable, the types must branch off the OME Meta Framework founded in ome.tel.
OME Meta Framework contains the building blocks for all frameworks supported by OME, which includes following base types that all types must inherit from:

(Non-expandable) Elements

Basic objects
Nodes in a model graphic representation

Expandable Elements

Basic objects
Objects being able to include other (non-expandable) objects inside their boundary
Objects with internal states

Links

Basic objects
A connection between two other objects (can either be an elements or a link) in the model
Arcs (possibly directed) in a model graphic representation

Creating a Framework File

Framework file must use valid Telos syntax
Framework must be described in proper Telos semantic, for example, pay attention to the concept of metaclass, simple class, omega-class, token, etc.
Specification of types occurs in simple class level, which means instances of these types in models are at Token level.
The specification of types must meet the expectations of OME. We will discuss these rules in the context of an example framework.
The following example framework declaration is adapted from example1.tel

An element type declaration

SimpleClass MyFirstElement # (1)

IN OMEElementClass, OMEInstantiableClass # (2,3)

ISA OMEElement # (4)

WITH name
: "Element" # (5)

defaultname # (6)
: "An Element"

imagename # (7)
: "Graphic1.gif"

imagesize # (8)
width : 80;
height : 50

autogui : 1 # (9)

END

Rule (1): Every class should be given a name. This name is used to refer to this class elsewhere in the framework specification.

In this example, we defined a class of an element type, whose name is MyFirstElement. Traditionally, a type class in a framework is defined as a SimpleClass.

Rule (2): All element types must be IN (an instance of) OMEElementClass.

In the example, MyFirstElement is an instance of OMEElementClass.

Rule (3): All object types that can occur in the model (i.e. can be instantiated) must be an instance of OMEInstantiableClass.

In the example, MyFirstElement is an instance of OMEInstantiableClass.

Rule (4): All element types be a specialization (a.k.a. subclass) of OMEElement.

In the example, MyFirstElement is a specialization (a.k.a. subclass) of OMEElement. OMEElementClass, OMEInstantiableClass and OMEElement are defined in OME Meta Framework (see ome.tel).

Rule (5): In Attribute Category: "name", OME expects one unlabeled attribute, which should be the name of the type, as experienced by the user. Any user interface dialogues that refer the type will use this value.

In the example, the name of the element type Myfirstement refers to is "Element".

Rule (6): Attribute Category: "defaultname" is optional. If an attribute category "defaultname" exists, the tool expects one unlabeled attribute, which is the default name for instances of this type (the user can always change the name of any instance). If omitted, the default name will be the name of the type, followed by the internal unique integer id assigned to the object.

In the example, the default name for the objects of type MyFirstElement is "An Element".

Rule (7): In Attribute Category: "imagename", the tool expects one unlabeled, which should be the name of a .gif file to be used to represent objects of this type. The image that is used should reside in ome/program/images/, otherwise an exception will be thrown.

In the example, the name of the image file which is used to represent an element is "Graphic1.gif".

Rule (8): Attribute Category: "imagesize" is optional. If present, OME expects two attributes labeled "width" and "height". The integer values specify the default dimensions (in pixels) of the graphical representation of objects of this type. If omitted, the default dimensions will be those of the image specified under imagename.

In the example, the width of the image used to represent an element is 80 pixels, while the height is 50 pixels.

Rule (9): Attribute Category: "autogui" is optional. If an attribute category "autogui" is presented, one unlabeled integer attribute is expected. If the value of the attribute is non-zero, the tool will automatically produce items in the graphical user interface to allow users to instantiate objects of this type. If omitted, or given a value of zero, no user interface items for this object will produced (automatically).

In the example, there will be a toolbar button created automatically in the GUI to allow users to create a new object of type MyFirstElement.

link type declaration

SimpleClass MyLink

IN OMELinkClass, OMEInstantiableClass # (10)

ISA OMELink

WITH

attribute # (11)
to : OMEObject;
from : MyFirstElement

name
: "Link"

imagename # (12)
: "Arrow.gif"

imagesize
width : 20;
height : 20

stroke
: "dashed" # (13)

autogui
: 1

END

Rule (10): Similar to elements, links must be instances of OMELinkClass and specialization of OMELink. OMELinkClass and OMELink are also defined in OME Meta Framework (see ome.tel).

Here, we defined a type of link named MyLink.

Rule (11): Links must have attributes labelled "to" and "from" under the attribute category "attribute". These attributes specify what kinds of objects will be valid sources and destinations for this link. This feature can be used to place constraints in your framework!

* Notice how we can use non-instantiable objects (OMEObject) in our constraints. This is a very powerful mechanism. Framework developers can create Object classes that are never meant to be instantiated but can be used to set up a hierarchy that may be utilized in establishing the proper constraints.

In this example, a MyLink can only have a MyFirstElement as its source, but any type of object (including another link) as a destination, since all instantiated objects are specialization of OMEObject (via OMEElement or OMELink).

Rule (12): Similar to an element, a link must provide an image. This image however, is used only for the "head" of the link (typically an arrow head).

Rule (13): The tool expects one unlabelled attribute under the category of "stroke". The value of the attribute must be one of the supported stroke types. If omitted, the default value for this attribute is "solid". Currently, the two supported stroke types are: "solid" - a solid line; "dashed" - a dashed line.
In the future, more stroke types can be still defined if necessary.

Some more elements to showcase using constraints.

SimpleClass ValidChild # (14)
ISA OMEElement
END

SimpleClass ChildA
IN OMEElementClass, OMEInstantiableClass
ISA OMEElement, ValidChild # (15)
WITH
name
: "Child A"

imagename
: "Resource.gif"

imagesize
width : 80;
height : 50

autogui
: 1

END

SimpleClass ChildB
IN OMEElementClass, OMEInstantiableClass
ISA OMEElement, ValidChild # (15)
WITH
name
: "Child B"

imagename
: "Task.gif"

imagesize
width : 80;
height : 50

autogui
: 1

END

SimpleClass MyExpandableElement
IN OMEElementClass, OMEInstantiableClass
ISA OMEElement, OMEGrowableElement # (16)
WITH
attribute
children : ValidChild # (17)

name
: "Expandable"

imagename
: "Actor.gif"

imagesize
width : 80;
height : 80

autogui
: 1

END

Rule (14): A user will never be able to create a direct instance of a non-instantiable class, which is not an instance of OMEInstantiableClass, but such classes can be used to express a constrain involves a certain group of classes.

In the example, a non-instantiable class named ValidChild is defined. We will make use of the this class in the following.

Rule (15): A user can bring together previously unrelated classes by declaring them as the subclasses of a same non-instantiable class.

The declarations of types ChildA and ChildB are standard element type declarations (instances of OMEElement, OMEInstantiableClass, subclass of OMEElement), but are also subclasses of ValidChild. Thus, these two class must have some common features described by ValidChild.

Rule (16): To declare an element to be expandable, we can simply make it a subclass of OMEGrowableElement.

Here we defined an expandable element named as MyExpandableElement.

Rule (17): All expandable element types should have an attribute labeled "children" under the attribute category "attribute". The value of this attribute should be some element type.

In a very loosely constrained example, we could use OMEElement. Here, we have used ValidChild to demonstrate using non-instantiable classes for constraining relationships. In this framework, ChildA and ChildB can be children (or "within the bounds") of a MyExpandableElement, but a MyFirstElement cannot.

What is a Plugin?

A Plugin is a Java class that implements OMEPlugin interface.
A Plugin is composed of a collection of methods. Each method is also a Java class, which implements PluginMethod interface.
In OME, there are two kinds of plugins.

Generic plugins: this kind of plugins include a collection of methods suitable to all frameworks, an example is OMEDefaultPlugin;
Framework-specific plugins: this kind of plugins wrap a collection of methods available to a special framework. For example, NFRPlugin encapsulate all the functionalities used to operate and analysis NFR models, while IstarPlugin is specifically used to i* models.

The flexibility and openness of OME tool is extremely due to the adoption of plugin mechanisms.

Building a Plugin

Specify when (under what condition) the plugin should be loaded (via the definition of isCompatiableWith());
Build the methods current plugin should include(classes inherited PluginMethods);
Specify where the methods will appear in the GUI, possible alternatives are: Menubar, toolbar, and popup menu.

In OME, model manager is responsible to establish and manage mappings between models and plugins. The operations include: initializePlugins(), getAllPlugins(), and getPlugins().
The View asks the ModelManager for the plugins corresponding to the model of current view.

What is a Plugin Method?

A plugin method can be seen as an agent providing certain kinds of services to the View.
A plugin method is made available in GUI at model loading/creating time;
A plugin method is reactive agent, who simply waiting for requests (or signals) from the View.

The Lifecycle of a Plugin Method

First, the View will ask the plugin method for framework information necessary to setup GUI, e.g., ask object name via getName(), ask for image file name to represent the object graphically via getImage().
If a plugin method is dealing with part of a context sensitive portion of the GUI, the view may ask the method if it should be enabled via isEnabled(), while the View will present the method with a ViewContext to support the decision.
When the user activates a plugin method (via the GUI), the view will ask the plugin method whether it needs any "parameters";
If yes, the plugin method will respond with a Parameter object that describes the type of parameter needed.
The view will then capture the corresponding parameter and transmit it to the plugin method, and then ask if more are needed.
This will continue until no more parameters are required.
After that, invoke() will be called, where the method "really does its job".
At any point prior to invoke(), the process may be cancelled.
In this event, the method needs to return to a "stable" state (i.e., forget about parameters it has received).