Installing GEMS

 

Prerequisites 

To install GEMS, you will need:

1.        A working Eclipse installation

1.        http://www.eclipse.org (version 3.0+)

2.        The Graphical Editor Framework (GEF)

1.        http://www.eclipse.org/gef

3.        The Eclipse Modeling Framework (EMF)

1.        http://www.eclipse.org/emf

Obtain and install Eclipse, GEF, and EMF (please see their respective installation guides for instructions). Throughout this guide, we will refer to root folder of your Eclipse installation location as <eclipse_install>.

Obtaining GEMS 

GEMS is available from: http://www.eclipse.org/gmt/gems and also from http://www.sf.net/projects/gems.

Download the latest zip file for GEMS and unzip it to <eclipse_install>/plugins. This should create several new directories in your <eclipse_install>/plugins directory:

1.        org.gems.designer.dsml_X.X.X

2.        org.gems.designer.css.parser_X.X.X

3.        etc.

Validating the Installation 

From the file menu in Eclipse, choose New->Other->GEMS2->Metamodel Model. If a new GEMS metamodel is created and appears in the modeling editor, you have successfully finished the installation.

Installation Troubleshooting: 

If GEMS2 does not show up as a folder in the new file wizard:

1.        Ensure that all of the prerequisite plugins are installed and working properly. Go to Window->Show View->Error Log and check for any errors related to org.gems.designer.* plugins. These errors should tell you if any of the prerequisites are missing.

If a new model shows up but exceptions are thrown in the error log and adding/deleting elements does not work properly:

1.        ...and the org.gems.designer.dsml.kb plugin (Prolog) is installed
on Windows -the Prolog plugin is the #1 source of errors in GEMS installs...if you don't need Prolog, delete org.gems.designer.dsml.kb and org.gems.designer.dsml.kb.jpl

1.        Make sure SWI Prolog is installed and that the jpl.jar from the org.gems.designer.dsml.kb plugin's lib directory matches the one in the SWI Prolog lib directory

 

Upgrading or Re-Installing

First, delete your existing GEMS installation by removing ALL plugin dirrectories starting with "org.gems.": 

1.        <eclipse_install>/plugins/org.gems.designer.dsml_X.X.X

2.        <eclipse_install>/plugins/org.gems.designer.dsml.X_X.X.X

3.        etc.

Next, follow the directions above for a new installation. Finally, ***VERY IMPORTANT*** start Eclipse from the command line using the "-clean" option.

 

Creating a GEMS Metamodel

 

Known Bugs

1.         Do NOT drag modeling elements from one parent to another...this can corrupt the model....

 

About the Example Used in this Tutorial

This tutorial shows the usage of GEMS in the context of a modeling tool for Spring framework bean files (GEMS is not related to Spring-specific or related to Spring). This is only one example of how GEMS can be used. You can create your own modeling tools for whatever you want.

The Spring framework uses dependency injection to configure a Java application. The Spring framework is designed to allow developers to create highly-modular and configurable enterprise Java applications.  The framework provides a container that can read an XML configuration file for an application and dynamically instantiate and wire components based on XML directives, which is a process called dependency injection. Complex configuration options, such as exposing a Java object as a web service, can be accomplished with only a few lines of XML code.  A key tenent behind the Spring framework is that the Java objects it manages should be oblivious to it. The objects specified in the XML configuration file need not implement any special interfaces or participate in specific inheritance hierarchies.

 Spring uses the factory pattern to instantiate and wire enterprise Java components. Spring makes extensive use of Java reflection and allows the application components to be oblivious to the configuration process. At launch, a factory is created and initialized using one or more XML configuration files. The factory then uses the XML configuration files to determine what objects it constructs and how they are wired together. In the process of constructing objects, the factory may associate crosscutting aspect advice with them, generate dynamic proxies to perform remote invocations, load objects into a naming service, or perform numerous other complex application configuration tasks.

The example modeling tool used in this tutorial allows modelers to specify the Spring beans in a Spring configuration file. It also allows modelers to specify how the properties of the beans are wired together. Finally, it allows developers to generate the necessary Spring XML code to implement the model.

Create a new Java project for your GEMS-based Modeling Tool

1.        File->New->Project->Java Project

2.        Next

3.        Give your project a name

4.        Make sure the "Create separate source and output folders" option is checked

5.        Finish



Create a new GEMS Metamodel

Image 

1.        File->New->Other->GEMS2->Metamodel Model

2.        Next

3.        Select the project that you created in the previous step to contain the metamodel

4.        Finish



VERY IMPORTANT -> Setting Metamodel Language Attributes

Image 

1.        If the properties pane is not open, Window->Show View->Other->General->Properties

2.        Click in the main canvas on the GEMS editor, this should cause the property pane to load the attributes for the root element of the metamodel.

3.        Change the "Category" attribute to the name of the folder that you would like your modeling language to appear under in the new file wizard. For example, GEMS uses the category "GEMS2" and thus you can find the "Metamodel Model" language under GEMS2 in the new file wizard. For our example, we will change it to "SpringframeworkModeling".

4.        ****Change the DSMLID to a UNIQUE URI**** - duplicate DSMLIDs cause very strange and hard to diagnose errors. It is essential that you change this a unique URI that you can guarantee another GEMS metamodeling language will not use.

5.        Change the "FileExtensions" attribute to the name that you would like to appear after the "." on a file name. For example, GEMS metamodels always end in the .gemsmeta2 file extension and this attribute is set to "gemsmeta2". DO NOT INCLUDE DOT in the file extension. In the plugin descriptor, GEMS will associate these file extensions with your GEMS modeling tool. For our example, we will change it to "gspringbeans".

6.        Change the "Name" attribute to a meaningful name for your plugin.

7.        DO NOT CHANGE "id" --- It is different than DSMLID

 

Creating a Root Element for the Modeling Language

The root element of a GEMS model is represented by the canvas of the modeling tool. The root element determines what elements can be added to the main canvas and what properties show up when the canvas is click on. 

 If the GEMS tool palette is closed, it will look like this:

Image

After opening the palette, it will look like this:

Image 

1.        See the images above to determine if the GEMS tool palette is open or closed

2.        If the palette is closed, open it by clicking on the toggle button shown in the first image

3.        Click on the "Entity" icon in the tool palette

4.        Click again on the main canvas to add an entity to the model

5.        Click on the Entity

6.        In the properties pane, name the Entity a "SpringBean". The name must be a name that is also a valid Java class name (i.e. no spaces, dashes, or other strange stuff)

7.        Change the "IsRoot" attribute to true. Only one Entity in a metamodel should ever be designated as the root. Every metamodel must have at least one Entity designated as root

Image

Adding Entities to the Modeling Language

Each Entity specified in a metamodel is realized as an element on the tool palette of the generated modeling tool. The entities determine what elements are available on the modeling palette that can be added to the model to create its structure. 

To add a new entity to the modeling language: 

1.        Click on the Entity icon in the tool palette

2.        Click again on canvas

3.        Click on the new Entity

4.        Change the name of the Entity in the properties pane

Continuing the Spring example:

1.         Add a new Entity

2.        Name the Entity "SpringBean"

 

Adding Attributes (things that show up in the properties pane) to an Entity

Attributes are Java bean style properties that can be get/set on a modeling element. Each Attribute shows up as a line in the properties pane.

To add an attribute to an Entity:

1.        Click on the Attribute icon in the tool palette

2.        Click again on the Entity you would like the attribute added to

3.        Set the Name, AttributeType, and DefaultValue (avoid characters that would not be valid inside an XML attribute value - this will be fixed to escape the value correctly at some point....) in the properties pane

To add an attribute to a Connection:

1.        Click on the Attribute icon in the tool palette

2.        Click again on the Connection you would like to add the attribute to

3.        Set the Name, AttributeType, and DefaultValue in the properties pane

Continuing the Spring example:

1.        Add an Attribute to SpringBean

2.        Name the Attribute "BeanClass"

Image

 

Creating Containment Relationships

A containment relationship between two Entities allows you to add instances of the child type of the containment relationship to the parent type. If the parent type is the root of the modeling language, instances of the child type can be added to the main canvas.

To add a containment relationship:

1.        Click on the connection tool on the tool palette

2.        Click on the child of the containment relationship

3.        Click on the parent of the containment relationship to complete the connection

4.        Click on the connection that is created

5.        In the properties pane, set the ChildRole and ParentRole properties. The values for these properties must be valid Java identifiers and MUST start with a capital letter. GEMS will generate methods like get<ParentRole>() and the names must create a valid Java method. Certain methods names are already taken by GEMS. For example, "Parent", "Children", etc. GEMS will notify you at code generation time if you have attempted to take a reserved name.

Continuing the example:

1.        Create a containment relationship from SpringBean to SpringBeansModel.

2.        Set the ParentRole to "Beans"

3.        Set the ChildRole to "ParentModel"

4.        Image

5.        Add a new Entity and name it "BeanProperty"

6.        Create a containment relationship from BeanProperty to SpringBean

7.        Set the ParentRole to "BeanProperties"

8.        Set the ChildRole to ParentBean

9.        Image

 

Creating Inheritance Relationships

Inheritance relationships allow one Entity to inherit all of the Attributes of another Entity and participate in any connection or containment relationships defined by the parent. 

ORDER IS EXTREMELY IMPORTANT IN THE STEPS BELOW!!!!! 

To create an inheritance relationship:

1.        Click on the Inheritance icon in the tool palette

2.        Click on the canvas to add the Inheritance element

3.        Click on the connection tool in the tool palette

4.        Click on the Entity that you would like to be DERIVED from another Entity (CLICKING ON THE INHERITANCE ELEMENT FIRST AND THEN THE ENTITY SIGNALS THAT THE ENTITY IS THE BASE CLASS...CLICKING ON THE ENTITY AND THEN THE INHERITANCE ELEMENT SIGNALS THAT THE ENTITY IS A DERIVED CLASS)

5.        Click on the Inheritance element to create a connection

6.        Click on the Inheritance element and then click on the Entity that you would like to be the BASE class

Continuing the example:

1.        Add two Entities, one called  "ValueProperty" and another called "RefProperty"

2.        Add an Inhertiance element to the canvas

3.        Set both ValueProperty and RefProperty as derived classes by first clicking on ValueProperty and then connecting it to the Inheritance element and then performing the same steps for RefProperty

4.        Click on the Inheritance element and then on BeanProperty to make it the BASE class of ValueProperty and RefProperty

Image

 

Making Entities Abstract

Abstract Entities do not show up on the palette of the generated modeling tool. Abstract entitites are useful for defining abstract base classes.

To make an Entity abstract:

1.        Click on the Entity

2.        In the properties pane, change IsAbstract to "true"

Continuing the example:

1.        Click on BeanProperty

2.        set IsAbstract to "true"

Defining Connections between Entities

Connection definitions allow the modeler to use the connection tool to draw a line between two types of modeling elements in the generated modeling tool. For example, GEMS containment connections in the metamodel were created by defining a connection type called "Containment" between two elements of type Entity.

To define a connection:

1.        Click on the Connection element in the palette

2.        Click on the canvas to add the Connection element to the metamodel

3.        Give the Connection element a new name (the name must be a valid Java class name)

4.        Click on the Connection tool in the palette

5.        Click on the Entity representing the type that should be the source of this connection

6.        Click on the Connection element

7.        Click on the new line between the Connection element and the source Entity to select it

8.        Change the  "SourceRole" property to a valid Java identifier (again..a method get<SourceRole>() is going to be created...so name accordingly)

9.        Click on the Connection tool in the palette

10.     Click on the Connection element in the model

11.     Click on the Entity representing the type that should be the target of the connection

12.     Select the new line between the Connection element and the target Entity

13.     Change the "TargetRole" property to a new value (see above naming requirements)

Continuing the example:

1.        Add a Connection element to the model and name it "Ref"

2.        Connect the RefProperty Entity to the Ref Connection to make it the source of the connection

3.        Set the SourceRole to "ReferencedBean"

4.        Set the Cardinality to "1"

5.        Connection the Ref Connection to SpringBean

6.        Set the TargetRole to "ReferencedBy"

Image

 

 

Generating Code from a GEMS Metamodel

 

Invoking the GEMS Plug-in Generator 

 

1.        If your target Java project does not have a source folder named "src", create a new source folder named "src" and add it to the project

1.        To create a source folder, right-click on the project's root folder

2.        New->Source Folder

3.        Name the folder "src"

4.        Finish

2.        Right-click on the metamodel

3.        Image

4.        Generate Plug-in->Generate DSML Plugin

5.        Choose the src folder of the target Java project

6.        Image

7.        Provide a package name (e.g. foo.bar.mymodelinglanguage) for the generated plugin, this will also be the plugin id of the generated plug-in

8.        Image

9.        Finish

 

Testing the Generated Modeling Tool

The generated modeling tool can be run from within Eclipse as an Eclipse application.

1.        Run->Run

2.        Right-click on Eclipse Application

3.        New

4.        Under the "Plug-ins" tab, make sure that either "Launch with all workspace and enabled external plug-ins" is selected or that the checkbox next to your plug-in's id is checked

5.        Run

6.        After the workbench has started, you can create a new instance of your modeling language, New->Other->Your_Category->Your_Modeling_Language's_Name

7.        Image

8.        Image

 

Adding a Stylesheet to a GEMS Modeling Tool

 

 

Changing Icons

The default icons used by GEMS are placed in the folder: your-plugins-package.icons. For example, if you generated the SpringBeans plugin into the package "org.gems.springbeans" the icons would be located in the package "org.gems.springbeans.icons" or the folder "src/org/gems/sprinbeans/icons". Each Entity from the metamodel has a corresponding icon in this folder. Replacing the icon will update the way the Entity is drawn in the canvas. You can replace the icons with the "_s" ending to update the palette icons. 

Specifying Styles

The default look and feel produced by GEMS isn't always what is needed. GEMS allows developers to create stylesheets to change the look and feel of a modeling tool. Stylesheets can adjust visual properties ranging from layouts to borders to icons. 

A stylesheet consists of number of "selectors" and a series of attribute/value pairs associated with each selector. For example:

SpringBean {

active-style:true;

ShowAttributes:false; 

}

The selector is "SpringBean". This means that all model elements of type "SpringBean" (or a derived class) will have this style applied. The attribute "ShowAttributes" is set to false in this style. This will make the bottom panel of the figure for SpringBeans disappear (this does not affect the properties pane). Also note that the property "active-style" is set to true. This enables the new GEMS stylesheet language. GENERALLY EVERY STYLE SHOULD SET active-style:true; AS THE FIRST LINE;

Selectors can also incorporate a special attribute of a model element called a Tag. In the next section on interpreters, we show examples of how Tags can be applied. Simply enough, a Tag is a way of marking a model element as having a special property. For example, all elements can use the built-in tag "selected" that is applied when an element is selected. More on Tags is availabe in the next section. An example of matching selectors based on Tags:

SpringBean {

active-style:true; 

ShowAttributes:false; 

}

SpringBean[selected] {

active-style:true;

ShowAttributes:true; 

}

In this example, SpringBeans that are not selected will have their attributes hidden. SpringBeans that are selected will show their attributes panel. Complex graphical behaviors can be created by swapping out styles when Tags change. Tags can be applied when elements reach a specific state of interest.

Comments in stylesheets can be created with /* comment */ syntax. For example:

/* My comment about the SpringBean style */

SpringBean {

.... 

or

/*

 * A longer comment....

 * My comment about the SpringBean style

 */

SpringBean {

.... 

}

 

There are a large number of attributes that can be set in a style sheet. At the end of this section, there is a complete list of accessible attributes. An attribute is set by specifying its name a ":" and then the desired value followed by a ";". For example:

TitleTemplate: Hello %Name%;

This would set the title or name label of a modeling element to "Hello "+the_element's_name. The %Attribute_Name% format can be used in the title template to specify values of attributes that should be filled in by the current element. When the element's name changes, the title will automatically be updated. From our SpringBean example, we could set the title template to:

TitleTemplate: %Name% [%BeanClass%];

This would display the SpringBean's title in the form "Foo [org.foo.Foo]".

GEMS knows how to set values for the following types of attributes:

String:

    Foo: My String; 

Point: (an X,Y coordinate), example:

     Foo: 10,10;

Dimension: (a Length X Width dimension) example:

    Foo: 10,10;

Rectangle: (X,Y,Length,Width) example:

   Foo: 3,3,5,7; 

Color: (an Red,Green,Blue color) example:

    Foo: 255,255,255;

Font: (a font name, size in pt, and style) example:

    Foo: Arial, 14, bold;

Boolean:

     Foo:true;

Numeric value:

     Foo:1.3;

Images (SWT Images):

    /*resolves icons/Foo.gif against the jar file containing the code for the plug-in. If this icon is resolved against a model element whose code is contained in the bar.jar in the class org.foo.Foo, the icon would be resolved to the  bar.jar/org/foo/icons/Foo.gif */

    Foo:resources/icons/Foo.gif; 

  /*resolves the icon relative to the file containing the current model. */

    Foo:model_file/icons/Foo.gif;

 /*resolves the icon relative to the plug-in directory containing the modeling language */

   Foo:icons/Foo.gif;

Image files can be in gif, jpg, or png formats (..and probably anything else supported by SWT). 

 LayoutManager: (a Draw2D layout manager to use for a figure):

     known valid values: FlowLayout, DirectedGraphLayout, FreeFormLayout

     examples: 

          ContentLayout: FlowLayout;

          ContentLayout: FlowLayout[V, StretchMinorAxis]; //a vertical flow that equalizes the widths of all children

          ContentLayout: FlowLayout[H]; //a horizontal layout

          ContentLayout: DirectedGraphLayout;

          ContentLayout: FreeFormLayout;

   You can also specify the fully qualified name of any LayoutManager that derives from one of these three types.

           ContentLayout: org.foo.MyDirectedGraphLayoutManager;

Connection Styles

Styles can be applied to connections. To apply a style to a connection, use the name of the Connection type as the selector. For example:

Ref {
 line-color:(0,0,0);
 line-style:dash;
 line-width:2;
 dst-decoration:arrow;
 @mylabel:Uses, dst-top, (100,100,255), (255,255,255), Verdana, 10, -15, false, false, false;
}

Ref is the Connection type defined in the example. The style sets the line's color, width, style, and destination decoration. It also adds a label with the text "Uses". Available connection attributes:

line-color: R,G,B;

line-style: solid|dash|dash-dot|dash-dash-dot;

line-width: integer for pixels;

dst-decoration: none, arrow, diamond;

src-decoration: none, arrow, diamond;

Custom labels can be added to connections with the format:

@your_identifier: Your_label_text, dst-top|dst-bottom|src-top|src-bottom, RGB foreground, RGB background, font, size, v-offset, bold, italic

The text of the label may use %attribute_name% notations to retrieve attribute values from the connection. 

Commonly Used Style Attributes

Sets the icon used by a modeling element in the main view: 

 ExpansionPanel.ClosedImage:resources/icons/MyImage.gif;

Sets the icon used in the tree view:

TreeImage:resources/icons/BeanProperty_s.gif;

Sets the label for an element in the tree view:

TreeTitleTemplate:%Name%;

Sets the label for an element in the main view: 

 TitleTemplate:%Name%;

Hides the small expandable attribute panel on the bottom of elements:

  ShowAttributes: false;

Change the foreground of the label: 

 NameLabel.ForegroundColor:0,0,0;

Make an element so that it does not have the small toggle button to expand/contract the child view:

  ExpansionPanel.Expandable: false;

Make an element expanded by default (usually used in conjunction with removing the toggle button and setting the default state):

ExpansionPanel.Expanded: true;

Determines if an element's icon is used in the main view.

ExpansionPanel.ShowClosedPanel: false;

Each figure has a left, top, right, bottom, and center panel. Any of the borders can be set with XXXPanel.Border: 

 TopPanel.Border.Color:0,0,0;

Sets the layout used to arrange the children of a figure. 

 ContentLayout: FlowLayout[V,StretchMinorAxis];

 

Advanced Styles

GEMS can use reflection to get/set any Java bean property on the Figure or EditPart drawing controlling a model element. This allows you to set other properties not listed below that you know about. You can inspect the classes org.gems.designer.dsml.visuals.edit.ModelEditPart and org.gems.designer.dsml.visuals.figures.NewModelFigure for other properties that can be accessed. 

If the property you would like to access does not have one of the above types, you can set it by specifying the fully qualified name of the class you would like to construct and set the value to.  For example:

BottomPanel.Border:org.gems.designer.dsml.visuals.figures.RoundedLineBorder[ Color=[0,0,0], Width=3];

This would create a new instance of the class org.gems.designer.dsml.visuals.figures.RoundedLineBorder, set its Color to RBG(0,0,0), and set is Width to 3.

Really Really Advanced Styles

If the above mechanisms just aren't enough, you can always implement your own classes to resolve the properties that are set and the values assigned to them. A PropertyResolver takes the strings of the format "BottomPanel.Border"  and returns a TargetProperty object that can be used to set the value of that property on an object. By implementing the PropertyResolver class. We plan to add OGNL support soon.

If you need to convert or create custom types to set as the values of properties, you can extend the extension point: org.gems.designer.dsml.styles.active.propertyvalueconverter. You must implement the interface org.gems.designer.dsml.styles.active.PropertyValueConverter

Example:

....

//This class converts string properties by prefixing them with "custom-string:" 

public class MyCustomPropertyValueConverter implements PropertyValueConverter {

  public Class[] getHandledTypes(){

      return new Class[]{String.class};

  }

  public Object valueToObject(Object figuremodel, Hashtable st, String prop, Class type, String value){

      return "custom-string:"+value;

  }
 

 

Creating a Global Stylesheet

The most common error is forgeting to add the dsml.css to the build section of the plugin descriptor. See steps 2-4 below.

To create a stylesheet for an entire modeling language:

1.        In the package that you chose to generate your modeling tool's code, create a file named "dsml.css". If you generated your code into "org.foo.bar", you need to create the file src/org/foo/bar/dsml.css

2.        Double-click on plugin.xml in  your modeling tool's project

3.        Select the build tab

4.        Ensure that your file dsml.css has a check in its checkbox under the "Binary Build" and "Source Build" columns

5.        Add some styles with selectors that match against the modeling element

Continuing the Spring beans example:

1.        Create a dsml.css stylesheet in the package of the model (

2.        Save the following image files into your SpringBeans modeling tool's icons folder

3.        SpringBean.gif Image

4.        SpringBean_s.gif Image

5.        BeanProperty.gif Image

6.        BeanProperty_s.gif Image

7.        Copy BeanProperty_s.gif to ValueProperty_s.gif and RefProperty_s.gif

8.        Add the following styles to it:

SpringBean{
 active-style:true;
 ExpansionPanel.ClosedImage:resources/icons/SpringBean.gif;
 TreeImage:resources/icons/SpringBean_s.gif;
 TreeTitleTemplate:%Name% [%BeanClass%];
 TitleTemplate:%Name% [%BeanClass%];
 ShowAttributes: false;
 ContentLayout: FlowLayout[V,StretchMinorAxis];
 NameLabel.ForegroundColor:0,0,0;
 ExpansionPanel.Expandable: true;
 LeftPanel.Border.Color:0,0,0;
 RightPanel.Border.Color:0,0,0;
 CenterPanel.Border.Color:0,0,0;
 TopPanel.Border.Color:0,0,0;
 BottomPanel.Border.Color:0,0,0;
}

BeanProperty{
 active-style:true;
 ExpansionPanel.ClosedImage:resources/icons/BeanProperty.gif;
 TreeImage:resources/icons/BeanProperty_s.gif;
 TreeTitleTemplate:%Name%;
 TitleTemplate:%Name%;
 ShowAttributes: false;
 NameLabel.ForegroundColor:0,0,0;
 ExpansionPanel.Expandable: false;
 ExpansionPanel.Expanded: false;
 ExpansionPanel.ShowClosedPanel: false;
 TopPanel.Border.Color:0,0,0;
 TopPanel.Border.DrawTop:false;
 TopPanel.Border.DrawLeft:false;
 TopPanel.Border.DrawRight:false;
 TopPanel.Border.DrawBottom:true;
 TopPanel.Border.Width:1;
 BottomPanel.Border:none;
 CenterPanel.Border:none;
}

Ref {
 line-color:(0,0,0);
 line-style:dash;
 line-width:2;
 dst-decoration:arrow;
 @mylabel:Dependency, dst-top, (100,100,255), (255,255,255), Verdana, 10, -15, false, false, false;
}

The modeling tool after applying the stylesheet:

Image 

Creating a Stylesheet for a Specific Model Instance 

1.         In the folder containing the model that you would like to create a custom stylesheet for, create a file called "mymodel.myext.css". For example, if you want to make a stylesheet for a model contained in the file "SpringBeans1.gspringbeans", you would create the file "SpringBeans1.gspringbeans.css"

2.        Add some styles with selectors matching the model elements

3.        Restart Eclipse and open the model again

Accessible Attributes 

This list was generated programmatically. Not all of these attributes may make sense. 

PortMode type:boolean
Autosize type:boolean
ExpandOnChildAdded type:boolean
ContentLayout type:LayoutManager
Focus type:boolean
Selected type:int
AlwaysOpen type:boolean
Expandable type:boolean
BottomPanel.Size type:Dimension
BottomPanel.Location type:Point
BottomPanel.Enabled type:boolean
BottomPanel.Visible type:boolean
BottomPanel.Bounds type:Rectangle
BottomPanel.Font type:Font
BottomPanel.MinimumSize type:Dimension
BottomPanel.Valid type:boolean
BottomPanel.PreferredSize type:Dimension
BottomPanel.ToolTip.Size type:Dimension
BottomPanel.ToolTip.Location type:Point
BottomPanel.ToolTip.Enabled type:boolean
BottomPanel.ToolTip.Visible type:boolean
BottomPanel.ToolTip.Bounds type:Rectangle
BottomPanel.ToolTip.Font type:Font
BottomPanel.ToolTip.MinimumSize type:Dimension
BottomPanel.ToolTip.PreferredSize type:Dimension
BottomPanel.ToolTip.BackgroundColor type:Color
BottomPanel.ToolTip.ForegroundColor type:Color
BottomPanel.ToolTip.FocusTraversable type:boolean
BottomPanel.ToolTip.LayoutManager type:LayoutManager
BottomPanel.ToolTip.MaximumSize type:Dimension
BottomPanel.ToolTip.Opaque type:boolean
BottomPanel.ToolTip.RequestFocusEnabled type:boolean
BottomPanel.BackgroundColor type:Color
BottomPanel.ForegroundColor type:Color
BottomPanel.FocusTraversable type:boolean
BottomPanel.LayoutManager type:LayoutManager
BottomPanel.MaximumSize type:Dimension
BottomPanel.Opaque type:boolean
BottomPanel.RequestFocusEnabled type:boolean
CenterPanel.Size type:Dimension
CenterPanel.Location type:Point
CenterPanel.Enabled type:boolean
CenterPanel.Visible type:boolean
CenterPanel.Bounds type:Rectangle
CenterPanel.Font type:Font
CenterPanel.MinimumSize type:Dimension
CenterPanel.Valid type:boolean
CenterPanel.PreferredSize type:Dimension
CenterPanel.ToolTip.Size type:Dimension
CenterPanel.ToolTip.Location type:Point
CenterPanel.ToolTip.Enabled type:boolean
CenterPanel.ToolTip.Visible type:boolean
CenterPanel.ToolTip.Bounds type:Rectangle
CenterPanel.ToolTip.Font type:Font
CenterPanel.ToolTip.MinimumSize type:Dimension
CenterPanel.ToolTip.PreferredSize type:Dimension
CenterPanel.ToolTip.BackgroundColor type:Color
CenterPanel.ToolTip.ForegroundColor type:Color
CenterPanel.ToolTip.FocusTraversable type:boolean
CenterPanel.ToolTip.LayoutManager type:LayoutManager
CenterPanel.ToolTip.MaximumSize type:Dimension
CenterPanel.ToolTip.Opaque type:boolean
CenterPanel.ToolTip.RequestFocusEnabled type:boolean
CenterPanel.BackgroundColor type:Color
CenterPanel.ForegroundColor type:Color
CenterPanel.FocusTraversable type:boolean
CenterPanel.LayoutManager type:LayoutManager
CenterPanel.MaximumSize type:Dimension
CenterPanel.Opaque type:boolean
CenterPanel.RequestFocusEnabled type:boolean
LeftPanel.Size type:Dimension
LeftPanel.Location type:Point
LeftPanel.Enabled type:boolean
LeftPanel.Visible type:boolean
LeftPanel.Bounds type:Rectangle
LeftPanel.Font type:Font
LeftPanel.MinimumSize type:Dimension
LeftPanel.Valid type:boolean
LeftPanel.PreferredSize type:Dimension
LeftPanel.ToolTip.Size type:Dimension
LeftPanel.ToolTip.Location type:Point
LeftPanel.ToolTip.Enabled type:boolean
LeftPanel.ToolTip.Visible type:boolean
LeftPanel.ToolTip.Bounds type:Rectangle
LeftPanel.ToolTip.Font type:Font
LeftPanel.ToolTip.MinimumSize type:Dimension
LeftPanel.ToolTip.PreferredSize type:Dimension
LeftPanel.ToolTip.BackgroundColor type:Color
LeftPanel.ToolTip.ForegroundColor type:Color
LeftPanel.ToolTip.FocusTraversable type:boolean
LeftPanel.ToolTip.LayoutManager type:LayoutManager
LeftPanel.ToolTip.MaximumSize type:Dimension
LeftPanel.ToolTip.Opaque type:boolean
LeftPanel.ToolTip.RequestFocusEnabled type:boolean
LeftPanel.BackgroundColor type:Color
LeftPanel.ForegroundColor type:Color
LeftPanel.FocusTraversable type:boolean
LeftPanel.LayoutManager type:LayoutManager
LeftPanel.MaximumSize type:Dimension
LeftPanel.Opaque type:boolean
LeftPanel.RequestFocusEnabled type:boolean
RightPanel.Size type:Dimension
RightPanel.Location type:Point
RightPanel.Enabled type:boolean
RightPanel.Visible type:boolean
RightPanel.Bounds type:Rectangle
RightPanel.Font type:Font
RightPanel.MinimumSize type:Dimension
RightPanel.Valid type:boolean
RightPanel.PreferredSize type:Dimension
RightPanel.ToolTip.Size type:Dimension
RightPanel.ToolTip.Location type:Point
RightPanel.ToolTip.Enabled type:boolean
RightPanel.ToolTip.Visible type:boolean
RightPanel.ToolTip.Bounds type:Rectangle
RightPanel.ToolTip.Font type:Font
RightPanel.ToolTip.MinimumSize type:Dimension
RightPanel.ToolTip.PreferredSize type:Dimension
RightPanel.ToolTip.BackgroundColor type:Color
RightPanel.ToolTip.ForegroundColor type:Color
RightPanel.ToolTip.FocusTraversable type:boolean
RightPanel.ToolTip.LayoutManager type:LayoutManager
RightPanel.ToolTip.MaximumSize type:Dimension
RightPanel.ToolTip.Opaque type:boolean
RightPanel.ToolTip.RequestFocusEnabled type:boolean
RightPanel.BackgroundColor type:Color
RightPanel.ForegroundColor type:Color
RightPanel.FocusTraversable type:boolean
RightPanel.LayoutManager type:LayoutManager
RightPanel.MaximumSize type:Dimension
RightPanel.Opaque type:boolean
RightPanel.RequestFocusEnabled type:boolean
TopPanel.Size type:Dimension
TopPanel.Location type:Point
TopPanel.Enabled type:boolean
TopPanel.Visible type:boolean
TopPanel.Bounds type:Rectangle
TopPanel.Font type:Font
TopPanel.MinimumSize type:Dimension
TopPanel.Valid type:boolean
TopPanel.PreferredSize type:Dimension
TopPanel.ToolTip.Size type:Dimension
TopPanel.ToolTip.Location type:Point
TopPanel.ToolTip.Enabled type:boolean
TopPanel.ToolTip.Visible type:boolean
TopPanel.ToolTip.Bounds type:Rectangle
TopPanel.ToolTip.Font type:Font
TopPanel.ToolTip.MinimumSize type:Dimension
TopPanel.ToolTip.PreferredSize type:Dimension
TopPanel.ToolTip.BackgroundColor type:Color
TopPanel.ToolTip.ForegroundColor type:Color
TopPanel.ToolTip.FocusTraversable type:boolean
TopPanel.ToolTip.LayoutManager type:LayoutManager
TopPanel.ToolTip.MaximumSize type:Dimension
TopPanel.ToolTip.Opaque type:boolean
TopPanel.ToolTip.RequestFocusEnabled type:boolean
TopPanel.BackgroundColor type:Color
TopPanel.ForegroundColor type:Color
TopPanel.FocusTraversable type:boolean
TopPanel.LayoutManager type:LayoutManager
TopPanel.MaximumSize type:Dimension
TopPanel.Opaque type:boolean
TopPanel.RequestFocusEnabled type:boolean
AttributesPanel.Model.Name type:String
AttributesPanel.Model.Size type:Dimension
AttributesPanel.Model.Location type:Point
AttributesPanel.Model.ID type:String
AttributesPanel.Model.Visible type:boolean
AttributesPanel.Model.Abstract type:boolean
AttributesPanel.Model.Subtype type:boolean
AttributesPanel.Model.GemsTag type:String
AttributesPanel.Model.Annotation type:String
AttributesPanel.Model.HorizontalGuide.Horizontal type:boolean
AttributesPanel.Model.HorizontalGuide.Position type:int
AttributesPanel.Model.VerticalGuide.Horizontal type:boolean
AttributesPanel.Model.VerticalGuide.Position type:int
AttributesPanel.Model.GemsPort type:boolean
AttributesPanel.Expanded type:boolean
AttributesPanel.Expandable type:boolean
AttributesPanel.ContentSwapPanel.Size type:Dimension
AttributesPanel.ContentSwapPanel.Location type:Point
AttributesPanel.ContentSwapPanel.Enabled type:boolean
AttributesPanel.ContentSwapPanel.Visible type:boolean
AttributesPanel.ContentSwapPanel.Bounds type:Rectangle
AttributesPanel.ContentSwapPanel.Font type:Font
AttributesPanel.ContentSwapPanel.MinimumSize type:Dimension
AttributesPanel.ContentSwapPanel.PreferredSize type:Dimension
AttributesPanel.ContentSwapPanel.ToolTip.Size type:Dimension
AttributesPanel.ContentSwapPanel.ToolTip.Parent type:IFigure
AttributesPanel.ContentSwapPanel.ToolTip.Location type:Point
AttributesPanel.ContentSwapPanel.ToolTip.Enabled type:boolean
AttributesPanel.ContentSwapPanel.ToolTip.Visible type:boolean
AttributesPanel.ContentSwapPanel.ToolTip.Bounds type:Rectangle
AttributesPanel.ContentSwapPanel.ToolTip.Cursor type:Cursor
AttributesPanel.ContentSwapPanel.ToolTip.Font type:Font
AttributesPanel.ContentSwapPanel.ToolTip.MinimumSize type:Dimension
AttributesPanel.ContentSwapPanel.ToolTip.PreferredSize type:Dimension
AttributesPanel.ContentSwapPanel.ToolTip.ToolTip type:IFigure
AttributesPanel.ContentSwapPanel.ToolTip.Border type:Border
AttributesPanel.ContentSwapPanel.ToolTip.BackgroundColor type:Color
AttributesPanel.ContentSwapPanel.ToolTip.ForegroundColor type:Color
AttributesPanel.ContentSwapPanel.ToolTip.FocusTraversable type:boolean
AttributesPanel.ContentSwapPanel.ToolTip.LayoutManager type:LayoutManager
AttributesPanel.ContentSwapPanel.ToolTip.MaximumSize type:Dimension
AttributesPanel.ContentSwapPanel.ToolTip.Opaque type:boolean
AttributesPanel.ContentSwapPanel.ToolTip.RequestFocusEnabled type:boolean
AttributesPanel.ContentSwapPanel.BackgroundColor type:Color
AttributesPanel.ContentSwapPanel.ForegroundColor type:Color
AttributesPanel.ContentSwapPanel.FocusTraversable type:boolean
AttributesPanel.ContentSwapPanel.LayoutManager type:LayoutManager
AttributesPanel.ContentSwapPanel.MaximumSize type:Dimension
AttributesPanel.ContentSwapPanel.Opaque type:boolean
AttributesPanel.ContentSwapPanel.RequestFocusEnabled type:boolean
AttributesPanel.ShowClosedPanel type:boolean
AttributesPanel.Size type:Dimension
AttributesPanel.Location type:Point
AttributesPanel.Enabled type:boolean
AttributesPanel.Visible type:boolean
AttributesPanel.Bounds type:Rectangle
AttributesPanel.Font type:Font
AttributesPanel.MinimumSize type:Dimension
AttributesPanel.Valid type:boolean
AttributesPanel.PreferredSize type:Dimension
AttributesPanel.ToolTip.Size type:Dimension
AttributesPanel.ToolTip.Location type:Point
AttributesPanel.ToolTip.Enabled type:boolean
AttributesPanel.ToolTip.Visible type:boolean
AttributesPanel.ToolTip.Bounds type:Rectangle
AttributesPanel.ToolTip.Font type:Font
AttributesPanel.ToolTip.MinimumSize type:Dimension
AttributesPanel.ToolTip.PreferredSize type:Dimension
AttributesPanel.ToolTip.BackgroundColor type:Color
AttributesPanel.ToolTip.ForegroundColor type:Color
AttributesPanel.ToolTip.FocusTraversable type:boolean
AttributesPanel.ToolTip.LayoutManager type:LayoutManager
AttributesPanel.ToolTip.MaximumSize type:Dimension
AttributesPanel.ToolTip.Opaque type:boolean
AttributesPanel.ToolTip.RequestFocusEnabled type:boolean
AttributesPanel.BackgroundColor type:Color
AttributesPanel.ForegroundColor type:Color
AttributesPanel.FocusTraversable type:boolean
AttributesPanel.LayoutManager type:LayoutManager
AttributesPanel.MaximumSize type:Dimension
AttributesPanel.Opaque type:boolean
AttributesPanel.RequestFocusEnabled type:boolean
ShowAttributes type:boolean
ShowTitle type:boolean
TitleTemplate type:String
ContentFigure.Size type:Dimension
ContentFigure.Location type:Point
ContentFigure.Enabled type:boolean
ContentFigure.Visible type:boolean
ContentFigure.Bounds type:Rectangle
ContentFigure.Font type:Font
ContentFigure.MinimumSize type:Dimension
ContentFigure.PreferredSize type:Dimension
ContentFigure.ToolTip.Size type:Dimension
ContentFigure.ToolTip.Location type:Point
ContentFigure.ToolTip.Enabled type:boolean
ContentFigure.ToolTip.Visible type:boolean
ContentFigure.ToolTip.Bounds type:Rectangle
ContentFigure.ToolTip.Font type:Font
ContentFigure.ToolTip.MinimumSize type:Dimension
ContentFigure.ToolTip.PreferredSize type:Dimension
ContentFigure.ToolTip.BackgroundColor type:Color
ContentFigure.ToolTip.ForegroundColor type:Color
ContentFigure.ToolTip.FocusTraversable type:boolean
ContentFigure.ToolTip.LayoutManager type:LayoutManager
ContentFigure.ToolTip.MaximumSize type:Dimension
ContentFigure.ToolTip.Opaque type:boolean
ContentFigure.ToolTip.RequestFocusEnabled type:boolean
ContentFigure.BackgroundColor type:Color
ContentFigure.ForegroundColor type:Color
ContentFigure.FocusTraversable type:boolean
ContentFigure.LayoutManager type:LayoutManager
ContentFigure.MaximumSize type:Dimension
ContentFigure.Opaque type:boolean
ContentFigure.RequestFocusEnabled type:boolean
ImageLabel.Text type:String
ImageLabel.LabelAlignment type:int
ImageLabel.Icon.Background type:Color
ImageLabel.IconDimension type:Dimension
ImageLabel.IconAlignment type:int
ImageLabel.IconTextGap type:int
ImageLabel.TextAlignment type:int
ImageLabel.TextPlacement type:int
ImageLabel.Size type:Dimension
ImageLabel.Location type:Point
ImageLabel.Enabled type:boolean
ImageLabel.Visible type:boolean
ImageLabel.Bounds type:Rectangle
ImageLabel.Font type:Font
ImageLabel.MinimumSize type:Dimension
ImageLabel.Valid type:boolean
ImageLabel.PreferredSize type:Dimension
ImageLabel.ToolTip.Size type:Dimension
ImageLabel.ToolTip.Location type:Point
ImageLabel.ToolTip.Enabled type:boolean
ImageLabel.ToolTip.Visible type:boolean
ImageLabel.ToolTip.Bounds type:Rectangle
ImageLabel.ToolTip.Font type:Font
ImageLabel.ToolTip.MinimumSize type:Dimension
ImageLabel.ToolTip.PreferredSize type:Dimension
ImageLabel.ToolTip.BackgroundColor type:Color
ImageLabel.ToolTip.ForegroundColor type:Color
ImageLabel.ToolTip.FocusTraversable type:boolean
ImageLabel.ToolTip.LayoutManager type:LayoutManager
ImageLabel.ToolTip.MaximumSize type:Dimension
ImageLabel.ToolTip.Opaque type:boolean
ImageLabel.ToolTip.RequestFocusEnabled type:boolean
ImageLabel.BackgroundColor type:Color
ImageLabel.ForegroundColor type:Color
ImageLabel.FocusTraversable type:boolean
ImageLabel.LayoutManager type:LayoutManager
ImageLabel.MaximumSize type:Dimension
ImageLabel.Opaque type:boolean
ImageLabel.RequestFocusEnabled type:boolean
NameLabel.Text type:String
NameLabel.LabelAlignment type:int
NameLabel.Icon.Background type:Color
NameLabel.IconDimension type:Dimension
NameLabel.IconAlignment type:int
NameLabel.IconTextGap type:int
NameLabel.TextAlignment type:int
NameLabel.TextPlacement type:int
NameLabel.Size type:Dimension
NameLabel.Location type:Point
NameLabel.Enabled type:boolean
NameLabel.Visible type:boolean
NameLabel.Bounds type:Rectangle
NameLabel.Font type:Font
NameLabel.MinimumSize type:Dimension
NameLabel.Valid type:boolean
NameLabel.PreferredSize type:Dimension
NameLabel.ToolTip.Size type:Dimension
NameLabel.ToolTip.Location type:Point
NameLabel.ToolTip.Enabled type:boolean
NameLabel.ToolTip.Visible type:boolean
NameLabel.ToolTip.Bounds type:Rectangle
NameLabel.ToolTip.Font type:Font
NameLabel.ToolTip.MinimumSize type:Dimension
NameLabel.ToolTip.PreferredSize type:Dimension
NameLabel.ToolTip.BackgroundColor type:Color
NameLabel.ToolTip.ForegroundColor type:Color
NameLabel.ToolTip.FocusTraversable type:boolean
NameLabel.ToolTip.LayoutManager type:LayoutManager
NameLabel.ToolTip.MaximumSize type:Dimension
NameLabel.ToolTip.Opaque type:boolean
NameLabel.ToolTip.RequestFocusEnabled type:boolean
NameLabel.BackgroundColor type:Color
NameLabel.ForegroundColor type:Color
NameLabel.FocusTraversable type:boolean
NameLabel.LayoutManager type:LayoutManager
NameLabel.MaximumSize type:Dimension
NameLabel.Opaque type:boolean
NameLabel.RequestFocusEnabled type:boolean
NameLabelImage.Background type:Color
Size type:Dimension
Parent.Size type:Dimension
Parent.Location type:Point
Parent.Enabled type:boolean
Parent.Visible type:boolean
Parent.Bounds type:Rectangle
Parent.Font type:Font
Parent.MinimumSize type:Dimension
Parent.PreferredSize type:Dimension
Parent.ToolTip.Size type:Dimension
Parent.ToolTip.Location type:Point
Parent.ToolTip.Enabled type:boolean
Parent.ToolTip.Visible type:boolean
Parent.ToolTip.Bounds type:Rectangle
Parent.ToolTip.Font type:Font
Parent.ToolTip.MinimumSize type:Dimension
Parent.ToolTip.PreferredSize type:Dimension
Parent.ToolTip.ToolTip.RequestFocusEnabled type:boolean
Parent.ToolTip.BackgroundColor type:Color
Parent.ToolTip.ForegroundColor type:Color
Parent.ToolTip.FocusTraversable type:boolean
Parent.ToolTip.LayoutManager type:LayoutManager
Parent.ToolTip.MaximumSize type:Dimension
Parent.ToolTip.Opaque type:boolean
Parent.ToolTip.RequestFocusEnabled type:boolean
Parent.BackgroundColor type:Color
Parent.ForegroundColor type:Color
Parent.FocusTraversable type:boolean
Parent.LayoutManager type:LayoutManager
Parent.MaximumSize type:Dimension
Parent.Opaque type:boolean
Parent.RequestFocusEnabled type:boolean
Location type:Point
Enabled type:boolean
Visible type:boolean
Bounds type:Rectangle
Font type:Font
MinimumSize type:Dimension
Valid type:boolean
PreferredSize type:Dimension
ToolTip.Size type:Dimension
ToolTip.Location type:Point
ToolTip.Enabled type:boolean
ToolTip.Visible type:boolean
ToolTip.Bounds type:Rectangle
ToolTip.Font type:Font
ToolTip.MinimumSize type:Dimension
ToolTip.PreferredSize type:Dimension
ToolTip.BackgroundColor type:Color
ToolTip.ForegroundColor type:Color
ToolTip.FocusTraversable type:boolean
ToolTip.LayoutManager type:LayoutManager
ToolTip.MaximumSize type:Dimension
ToolTip.Opaque type:boolean
ToolTip.RequestFocusEnabled type:boolean
BackgroundColor type:Color
ForegroundColor type:Color
FocusTraversable type:boolean
LayoutManager type:LayoutManager
MaximumSize type:Dimension
Opaque type:boolean
RequestFocusEnabled type:boolean

 

Customizing the GEMS Modeling Palette

 

Overriding the Default Menu Organization

To override the default palette organization, you can create a palette style file that tells GEMS how to organize the palette. The palette style file allows you to customize the icons, labels, drawers, and elements on the palette. 

To create a palette style file:

1.        Create a file called dsml.palette in the root of your modeling tool's Java project

2.        Double click on plugin.xml

3.        Select the "Build" tab

4.        Ensure that the checkboxes next to dsml.palette are checked in both the "Binary Build" and "Source Build" columns

 

Specifying Palette Drawers

 Each palette style is composed of a number of drawers and the elements within them. The default palette organization contains a single drawer called "Components". Drawers are added by created using the following syntax:

Bean Tools {

modelid:{_your_modeling_language's_DSMLID}; 

}

This will create an empty drawer called "Bean Tools" and use the specified modeling lanuage when resolving elements to create. To add some elements to the drawer, we use the following syntax:

Bean Tools {

/*The icon to use for the palette drawer */ 

image:resources/icons/BeanTools.gif; 

/* The SpringBeans DSMLID */ 

modelid:{http://www.sf.net/projects/gems/dsml/springbeans};

/* An element that should show up on the drawer with the label "SpringBean". Will crate instances of SpringBean */ 

SpringBean:SpringBean;

/*The tooltip description. */ 

SpringBean-desc:A basic bean.;

/*The image to use for the Bean */ 

SpringBean-image:resources/icons/SpringBean_s.gif;

 }

This example adds a single element to the drawer with the label "SpringBean". The first line specifies the icon to use for the drawer. The second statement tells GEMS to use the modeling lanugage with the DSMLID when attempting to resolve element types specified in the drawer. The thrid line uses the syntax <label>:<type>; to specify that an element with the label "SpringBean" should be created that allows the user to create instances of the SpringBean modeling element. The next line sets the tooltip for the palette entry. The final line specifies the image to use. 

Palette styles can also specify initialization parameters for model elements. For example, if you would like to create an element with a specific name, you can use initialization parameters to acheive this:

Property Tools {

  /* This property uses the -opts attribute to initialize the name
  * of the element.
  */

 My Custom Property:ValueProperty;
 My Custom Property-opts:Name=MyCustomProperty;
 My Custom Property-desc:This will add a special property to your model;
 My Custom Property-image:resources/icons/ValueProperty_s.gif;
}

The line:

My Custom Property-opts:Name=MyCustomProperty;

tells GEMS to automatically set the Name attribute of the newly created element to "MyCustomProperty".


Continuing the Spring Example:

1.        Create a new file called dsml.palette in the root folder of the generated plug-in's project

2.        Double click on plugin.xml

3.        Select the "Build" tab

4.        Ensure that the checkboxes next to dsml.palette are checked in both the "Binary Build" and "Source Build" columns

5.        Add the following palette options to the dsml.palette file:


Bean Tools {
 modelid:{http://www.sf.net/projects/gems/dsml/springbeans};
 SpringBean:SpringBean;
 SpringBean-desc:A basic bean.;
 SpringBean-image:resources/icons/SpringBean_s.gif;
}

Property Tools {
 Value Property:ValueProperty;
 Value Property-desc:This will add a ValueProperty to your model;
 Value Property-image:resources/icons/ValueProperty_s.gif;
 
 Reference Property:RefProperty;
 Reference Property-desc:This will add a RefProperty to your model;
 Reference Property-image:resources/icons/RefProperty_s.gif;
 
 /* This property uses the -opts attribute to initialize the name
  * of the element.
  */
 My Custom Property:ValueProperty;
 My Custom Property-opts:Name=MyCustomProperty;
 My Custom Property-desc:This will add a special property to your model;
 My Custom Property-image:resources/icons/ValueProperty_s.gif;
}

 

Before applying the palette style:

Image

 

After applying the palette style:

Image 

 

 

 

 

Code Generation, Model Interpreters, Model Analysis, Event Handling, etc...

 

Creating Event Listeners or Triggers

Triggers allow you to define conditions under which you would like a specific action to be invoked or a method in a specific class to be called. Triggers can also invoke scripts written in Bean Shell, OCL (if the ocl plug-in is installed), and Prolog (if the prolog plug-in is installed).  For example, you can create a trigger that is activated everytime a new SpringBeans RefProperty is created and invokes a wizard to select the element the RefProperty should be associated with. A trigger can also be notified when a change is about to happen. For example, a trigger can be created that is invoked when a user begins to create a connection from an element to another element and highlights the valid endpoints for the connection.

To create a trigger file:

1.        Add a file called "dsml.triggers" to the root folder of the project you generated your modeling tool into

2.        Open the plugin.xml for the project

3.        Select the build tab

4.        Ensure that the checkbox next to "dsml.triggers" in both the binary and source build columns is checked

Triggers are defined using a syntax similar to GEMS stylesheets. For example:

 property-added {
   on:SpringBean.BeanProperties;
   invoke:check-role;
}

this trigger is activated when a BeanProperty is added to a SpringBean. The "on" attribute specifies the event to watch for. In this case, the event is the change of the "BeanProperties" role of a SpringBean. The BeanProperties role was defined in the metamodel and maps to a containment relationship between a SpringBean and a BeanProperty. Whenever a SpringBean has a new BeanProperty added or removed from it, the trigger will be invoked. The "invoke" attribute specifies the action to invoke.

The event that is used to activate the trigger can take the following forms:

on:TypeName.*;   /* invoke on any change to elements of type TypeName */

on:TypeName.RoleName; /* invoke when any element of type TypeName has RoleName change

on:menuitem.MenuItemEventID; /* invoke when a menuitem is clicked with the specified menu item event id 

If you need to intercept events before they are committed to the model. For example, you would like to highlight valid destinations for a target. You can used the "allow-proposals" attribute to see events that have not been committed to the model but will be soon. For example:

 some-fancy-connection-guidance {
    on:RefProperty.ReferencedBean;
    allow-proposals:true;
    invoke:find-valid-connection-targets;
}

The "allow-propsals:true;" attribute causes this trigger to be invoked when a user has clicked on a RefProperty to create a connection but has not yet clicked on a destination for the connection. If a user selects a palette element, but has not yet selected a parent for the element, this same attirbute can be used to intercept the user's action and provide guidance, a wizard, etc... 

Actions (referred to by the "invoke" attribute) can be added to GEMS by extending the extension point "org.gems.designer.dsml.trigger.invokable" with a class that implements the interface org.gems.designer.dsml.trigger.Invokable. The interface specifies the following methods:

 run(); //this should specify the code for your action

setContext(List context); //this is provided the context information surrounding the invocation

The setContext method can be used to determine the element that changed and resulted in a trigger being activated. For example, the following code determines the model element that changed:

public void setContext(List context) {
        ModelObject el = null;
        if (context.get(0) instanceof ModelChangeEvent) {
            el = ((ModelChangeEvent) context.get(0)).getChangedElement();
        } else if (context.get(0) instanceof RoleChangeEvent) {
            el = ((RoleChangeEvent) context.get(0)).getContext();
        } else if (context.get(0) instanceof ModelObject) {
            el = ((ModelObject) context.get(0));
        }        

     myMemberVar = el; //save the context for when the run() method is called 

    }

If you don't want to go to the trouble of extending this extension point, you can use a special invokable to wrap an instance of a class you define and invoke a method on it. For example:

property-added {
   on:SpringBean.BeanProperties;

   invoke:bean;
   bean:org.your.fully.qualifed.ClassName;
   method:yourMethodName;

This trigger instantiates an instance of "org.your.fully.qualifed.ClassName" and passes the model element that was the context to the method "yourMethodName". The specified method must take a single org.gems.designer.model.ModelObject as a parameter or take no parameters.

Guards can be associated with triggers to provide more fine-grained event checking. Guards can be written in Bean Shell, OCL, Prolog, or the language of your choice (if you write an extension to "org.gems.designer.dsml.trigger.evaluator" that knows how to execute your language). To set the script language type used by a trigger:

my-trigger {

 on:MyType.MyEvent;

 

/* other valid options are prolog and java .... or if you extend the evaluator extension point the value returned by getType()*/

 expr-type:ocl;

 .... 

The "expr-type" attribute specifies that the trigger uses OCL as its expression language. If no expr-type is specified, GEMS defaults to Bean Shell. Once the expression language is set, you can create a guard. For example:

my-trigger {

 on:MyType.MyEvent;

 expr-type:java;

 test:{return context.getName().equals("foo");}   /*note that the code is surrounded in "{ }" VERY IMPORTANT */ 

 invoke:MyAction;

}

When this trigger is activated, it evaluates the code in "test" and if it returns "true", invokes the aciton. This trigger will only invoke MyAction if the element that generated the event was named "foo".

Scripts can also serve as the action of the trigger or as a preprocessor. For example:

my-trigger {

 on:MyType.MyEvent;

 expr-type:java;

 test:{return context.getName().equals("foo");}   /*note that the code is surrounded in "{ }" VERY IMPORTANT */ 

 evaluate: {context.setName("bar");}

 invoke:MyAction;

}

In this trigger, the code in evaluate will be run if the test succeeds and then MyAction will be called. 

The Bean Shell (java) script interpreter exposes the context of the event as the variable "context" and the invoking event as the variable "event". If multiple elements are selected (for triggers based on menu-items), the other elements are stored in the "selection" variable as a java.util.List.

The OCL script interpreter stores the context of the event in the "self" variable.

Prolog stores the invoking element in "Owner".

 

Adding a Script Interpreter

To create your own scripting language and interpreter, extend the "org.gems.designer.dsml.trigger.evaluator" extension point. The class used as the extension must implement two methods:

//The return value is the result of the interpretation of the script.

//The expr is the script code to execute.

//The env map contains the invoking element (under the key "context"), the invoking event (under the key "event"), and the current selection (if any) (under the key "selection"). 

public Object evaluate(String expr, Map env);

and

//The string this method returns is matched against the "expr-type" attribute to determine the appropriate

//evaluator 

public String getType(); 

 

The complete code for the OCLEvaluator used by GEMS is: 

public class OCLEvaluator implements Evaluator {

    public Object evaluate(String expr, Map env) {
        ModelObject obj = ((RoleChangeEvent) env.get("event")).getContext();
       
        EObject context = null;
        if(obj instanceof EMFModelElement)
            context = (EObject) ((EMFModelElement)obj).getEMFModelElement();
       
       
        Query query = QueryFactory.eINSTANCE.createQuery(expr, context.eClass());

        query.setExtentMap(AllInstancesManager.getInstance().getInstanceMap(obj.getModelInstanceID()));

        Object result = query.evaluate(context);
        return result;
    }

    public String getType() {
        return "ocl";
    }

}

 

Interpreters

By itself, the generated plug-in can’t generate any code or be executed. The plug-in can be extended to provide this functionality by extending some of GEMS’ extension points.

The most common type of extension is to create an interpreter which traverses the model and generates code. Interpreters can also interpret the model to provide executable semantics, perform analysis, or anything else you can think of.

The menus/menu items of the generated plug-in can also be customized via extension points. Each menu item can have custom event that it transmits. These events can then have ActionSets associated with them.

Finally, new element types can be plugged into existing models. As long as the elements plugged in are allowed by the generated DSML’s constraints checker, the new elements can be added to and serialized along with the model. These elements can allow third party developers to add new element types to models.

Extensions to the generated plug-in can be created either by editing the generated plugin.xml or by creating separate plug-ins which reference the extension points and generated DSML. Delivering the interpreters or extensions as separate entities allows the DSML and interpreter infrastructure to be developed and updated separately.

Creating a Plug-in project

1.      Creating a Plug-in Project for an Interpreter

a.       The first step in extending a generated plug-in is to create a new Eclipse Plug-in Project. Go to File->New->Project->Plug-in Development->Plug-in Project. Follow the steps of the project wizard.

b.      For our Services plug-in, we will create a new project called “DeploymentInterpreter.”

c.       Click Finish

d.      Open the new Project

e.       Open the folder Meta-Inf

f.        Open Manifset.mf

g.       Click on the “Dependencies” tab at the bottom

h.       Click Add

i.         Type org.gems.designer.dsml

j.        Click Ok

k.      Click Add

l.         Type org.gems.test.deployment

m.     Click Ok

n.       Save the Changes

Creating a Visitor-based interpreter

1.  To create a visitor-based interpreter for your model

1.      Creating a Visitor-based Interpreter

a.       In the package that your generated code was placed in, a default interpreter interface for you in the org.gems.test.deployment.DeploymentVisitor. For each model entity type you specified in your metamodel, a corresponding visit<Type>(...) method was generated in the interface. You provide your interpreter logic by creating a class that implements these methods.

b.      Right-click on your plug-in project and create a “Source Folder” named src

c.       In your new src folder, create the class DeploymentInterpreter in the package org.gems.test.deployment.interpret that inherits from the org.gems.designer.model.actions.AbstractInterpreter. Make the class implement the org.test.deployment.DeploymentVisitor interface.

d.      Add a constructor to the class that takes no arguments and calls the superclass constructor with the string “org.gems.test.deployment.interpret.DeploymentInterpreter”

e.       Override the visit<Type> methods to suit your needs.

f.        The complete code for a basic interpreter skeleton is below:

 package org.gems.test.deployment.interpret;

import org.gems.designer.model.Atom;
import org.gems.designer.model.Container;
import org.gems.designer.model.Model;
import org.gems.designer.model.ModelObject;
import org.gems.designer.model.Root;
import org.gems.designer.model.actions.AbstractInterpreter;
import org.gems.designer.model.actions.ModelActionResult;
import org.gems.test.deployment.Component;
import org.gems.test.deployment.DeploymentModel;
import org.gems.test.deployment.DeploymentVisitor;
import org.gems.test.deployment.Node;
import org.gems.test.deployment.Requirement;
import org.gems.test.deployment.Resource;

public class DeploymentInterpreter extends AbstractInterpreter implements DeploymentVisitor {

    public DeploymentInterpreter(){
        super("org.gems.test.deployment.interpret.DeploymentInterpreter");
    }
        
    
    @Override
    public ModelActionResult interpret(ModelObject root, String eid) {
        root.accept(this);
        return null;
    }

    public void visitDeploymentModel(DeploymentModel tovisit) {
    }

    public void visitNode(Node tovisit) {
        System.out.println("Visiting a Node");
        visitContainer(tovisit);
    }

    public void visitResource(Resource tovisit) {
    }

    public void visitComponent(Component tovisit) {
        System.out.println("Visiting a Component");
        visitContainer(tovisit);
    }

    public void visitRequirement(Requirement tovisit) {
    }

    public void visitRoot(Root root) {
        visitContainer(root);
    }

    public void visitModelObject(ModelObject obj) {
    }

    public void visitContainer(Container cont) {
        for(Object o : cont.getChildren()){
            ModelObject mo = (ModelObject)o;
            mo.accept(this);
        }
    }

    public void visitAtom(Atom atom) {
    }

    public void visitModel(Model model) {
    }

}

g.       In order to register your interpreter with the model (so that it appears on the right-click menu),  open the MANIFEST.MF file in the META-INF directory. Select the "extensions" tab at the bottom. Choose "Add." When the extension dialog appears, uncheck "show only extension points required for this plug-in" (bottom left). Select the "org.gems.designer.dsml.userinvokedactoin" extension point and click "Finish."

h.       Right click on the newly created userinvokedaction extension point, choose "Add," and then select "user-action." Select the new user-action and then edit its properties in the right hand column. You should set "name" to “Deployment Interpreter”. Set "models" to a comma separated list of the model id's you want this interpreter to be applied to (in this case, set it to: http://www.sf.net/projects/gems/dsml/dcenter). Set "id" and "eventID" to the fully qualified class name of the interpreter (org.gems.test.deployment.interpret.DeploymentInterpreter). Finally, click the browse button next to class and select your interpreter class (org.gems.test.deployment.interpret.DeploymentInterpreter).

i.         To test the interpreter, run the runtime workbench. After creating a model, right click in the model editor pane and choose the menu item “Deployment Interpreter”.

 

 

 

© 2007 The Generic Eclipse Modeling System (GEMS)