1.3 Building a simple model

---

1.3 Building a simple model

In this section, we build a simple but realistic model. The purpose is to demonstrate the main steps of the process. Later in our redbook, we use the Graphical Editing Framework (GEF), to build a workflow application on top of this model. The workflow editor will help us to create and visualize the content of the model. For more information, the application requirements and design can be found in "Sample application requirements" on page 188.

The model

Before starting to describe the modelling process using Eclipse and EMF, we need to understand the complete underlying UML model that we will build. This is shown in Figure 1-4 and discussed in more detail in "The workflow model" on page 192.

Figure 1-4: The complete UML model

1.3.1 Different ways of making the model

In EMF, the model can be created in three different ways:

• Write the XMI file directly.

• Export the XMI file, from tools like Rational® Rose® and the Omondo EclipseUML plug-in and load it into our project.

• Annotate Java interfaces with model properties.

To illustrate how to create a model, we demonstrate the use of the Omondo EclipseUML plug-in to generate the XMI and also show the use of the Java interface annotation mechanism.

1.3.2 The EclipseUML plug-in

The main advantage of UML is that it allows us to work at a very high level. In an EMF class diagram, we create classes and interfaces, we give them attributes and methods, and we set up their relationships.

plug-in installation

Omondo's EclipseUML plug-in can be downloaded from the site:

• http://www.eclipseuml.com

The current version is 1.2.1. The installation is an executable jar file. On Microsoft® Windows®, double-click its icon. On other operating systems, run the following command:

    java -jar eclipseuml-installer_1.1.4.jar 

Install the product in the same folder you installed the Eclipse product.

Note 

In our case, we did not install the versions of GEF and EMF that are provided with the EclipseUML plug-in, because we wanted to use the latest versions of GEF and EMF.

1.3.3 Initial project setup

Before doing the modeling itself, we need to create an Eclipse project environment to contain all the items that we are going to produce. The steps to take are as follows:

1. Create a new project:

   1. Click File -> New -> Other..., select Plug-in Development -> Plug-in Project, and click Next.

   2. Enter a project name, for example, WorkflowModel, and click Next.

   3. Select Create a Java project, and click Next.

   4. Select Create a blank plug-in project, and click Finish.

2. Create a Java Package:

   1. Click File -> New -> Other..., select Java -> Package, and click Next.

   2. Click Browse... to select the src folder in the WorkflowModel project.

   3. Enter a package name, for example, com.ibm.itso.sal330r.workflow, and click Finish. Figure 1-5 shows a view of the Eclipse workbench after we have completed our initial setup tasks.

      
      Figure 1-5: Initial project setup

Note 

Our project must be a plug-in project, but it also needs to be a Java project, in order to allow package creation. If we had selected Create a simple project, package creation would not have been possible. Creating an EMF Project directly is another way to achieve the same result.

1.3.4 Modeling using the EclipseUML plug-in

During our simple model creation, we iterate several times to achieve what we think is a good design. The graphical facilities of the EclipseUML plug-in are a great help during this process, and each intermediate diagram was used as a good start to support the next iteration of our modelling.

EMF class diagram creation

The whole model is contained in one EMF class diagram. Here are the steps to create this diagram:

1. Click File -> New -> Other..., select EMF Diagrams -> EMF Class Diagram, click Next:

   1. Choose the parent folder, for example, WorkflowModel project.

   2. Enter an EMF model file name, file extension is ecd, for example, Workflow.ecd

   3. Enter a package name, for example, com.ibm.itso.sal330r.workflow

   4. Check the association box, click Finish. See Figure 1-6.

      
      Figure 1-6: EMF class diagram window

Two files have been created: Workflow.ecd, which contains the class diagram; and workflow.ecore, which contains the core model definition.

Note 

1. In the Eclipse,new EMF class diagram dialog, the package name in the advanced section corresponds to the EMF EPackage.

2. With the EclipseUML plug-in, two types of diagram can be created: UML and EMF models. The file for UML extension is .u?? (ex: Workflow.ucd) while the extension for EMF is .e?? (ex: Workflow.ecd). Available modeling operations and data types are adapted to the type of file you are working in. Remember that if you work with an EMF model, only .e?? files and the associated editors give you access to EMF functionality.

Class diagram modeling

From the modeling point of view, the class diagram is complete, once we have defined a set of classes (EMF interfaces), and the relationships between them.

Interface design

We first create the root interface, which is called WorkflowElement, then we implement the WorkflowNode hierarchy, the Port hierarchy, and finally Workflow, Edge, and Comment.

To do the WorkflowElement interface creation:

1. Open the EMF class diagram editor:

   1. Select Workflow.ecd in the WorkflowModel project in the navigator view of Eclipse.

   2. Right-click Open with -> EMF Class Diagram Editor — or simply double-clicking the file tree item should work fine also.

2. Create a class in the editor:

   1. Click the icon for the class creation tool on the editor tool palette, click in the working area of the editor, and a new a window opens.

   2. Enter a name, for example, WorkflowElement, and choose the boxes, Is an interface and Is abstract, then click Finish.

Attribute creation

Now we add an id attribute to the WorkflowElement interface:

1. Select the WorkflowElement, by clicking close to the border of the visual in the editor. A rectangle should appear; right-click and choose New -> Attribute.

   1. Enter the name of the attribute, for example, id.

   2. Select the type of the attribute, for example, EString. Most of the EMF types, which are equivalent to the Java basic types, are available.

   3. Choose the features you want to give to the attribute. See Figure 1-7 for an example and refer to 1.3.6, "EMF features" on page 24 for more information on the features themselves.

      
      Figure 1-7: The new attribute window

   4. Choose the cardinality associated to the attribute, and click OK.

At any point, if you realize that something is wrong or that you have forgotten something, do not worry; most of the time, you do not have to delete your model and start again. Simple corrections can be made in the property view, and more complex corrections can be made using either the Sample Ecore Model editor or the default text editor. These give you different ways of accessing the underlying model, and allow you to correct, enhance, or even totally redefine the model.

Available editors

To open the Sample Ecore Model or the text editor:

• Select the Workflow.ecore file, right-click and either choose Open With -> Sample Ecore Model Editor or Open With -> Text Editor. See Figure 1-8 for an example of using the Ecore Model Editor.

  
  Figure 1-8: EMF Class Diagram and Sample Ecore Model Editor together

Note 

The Workflow.ecd file cannot be open in the EMF Class Diagram editor and the text editor at the same time. To chose the editor to open the file in, select the file, right-click Open With -> EMF Class Diagram Editor, or Open With -> Text Editor.

The property view

Some properties are not directly supported by the EclipseUML plug-in, but they can still be changed using the property view.

To show the property view in Eclipse:

1. Click Window -> Show View -> Other…

2. Select Basic -> Properties, and click OK.

We use the property view to complete the id attribute. We have to mention that the id is an ID, which will be used for serialization later. We set the ID property of the id attribute to true as shown in Figure 1-9.

Figure 1-9: The property view with the ID attribute set to true

We complete the WorkflowElement interface by adding all the other attributes. Each WorkflowElement in a workflow has a name, is located at position x and y on the canvas, and has a height and a width. Table 1-1 shows the properties of all the WorkflowElement attributes.

Table 1-1: WorkflowElement attribute properties

Name	Type	Features and properties
id	EString	volatile="true" lowerBound="1"
name	EString
comment	EString
x	EInt	defaultValueLiteral="0"
y	EInt	defaultValueLiteral="0"
width	EInt	defaultValueLiteral="-1"
height	EInt	defaultValueLiteral="-1"

We repeat the same process to create the other classes of the Workflow model. See Table 1-2 for a summary of their attributes, features, and properties. For the classes which are not in the table, but are in the model, depicted in Figure 1-4 on page 9, simply create them with no attribute. Do not forget that WorkflowElement and WorkflowNode are two abstract classes.

Table 1-2: Interface attributes properties

Interface Name/attribute	Type	Features and properties
WorkflowNode (abstract)
isStart	EBoolean	defaultValueLiteral="false" lowerBound="1"
isFinish	EBoolean	defaultValueLiteral="false" lowerBound="1"
Transformation
transformExpression	EString
LoopTask
whileCondition	EString	lowerBound="1"
ConditionalOutputPort
condition	EString	lowerBound="1"

Note 

The Default Value Literal can only be set in the property editor.

Figure 1-10 shows what the model should like after these steps.

Figure 1-10: The workflow model classes, before relationship definition

Generalization definition

Generalization or inheritance links are made using the generalization tool. Select the tool by clicking its icon, which is an arrow with a big triangle at the end. Click the specialized interface, hold the mouse button down, then move to the generalized interface or connect to a generalization link going to the superclass. Figure 1-11 shows our model with the generalization relationships added.

Figure 1-11: Generalization relationships

Association definition

Using the association tool, we set up the associations between the classes. We show how to set up the association between Workflow and Edge, then we provide a summary of all the other associations with their features; see Table 1-3.

Table 1-3: Association properties

Origin	End	Association end	Attributes
Workflow	Edge	edges	upperBound="-1" containment="true"
		workflow	lowerBound="1"
	WorkflowNode	nodes	upperBound="-1" containment="true"
		workflow	lowerBound="1"
	Comment	comments	upperBound="-1" containment="true"
		workflow	lowerBound="1"
WorkflowNode	InputPort	inputs	lowerBound="1" upperBound="-1" containment="true"
		node	lowerBound="1"
	OutputPort	outputs	lowerBound="1" upperBound="-1" containment="true"
		node	lowerBound="1"
OutputPort	Edge	edges	upperBound="-1"
		source	lowerBound="1"
InputPort	Edge	edges	upperBound="-1"
		target	lowerBound="1"
Compound task	Workflow	subworkflow	lowerBound="1" containment="true"

Here are the steps to set up the Workflow to Edge association:

1. Click the source interface, which is Workflow.

2. Click the target interface, which is Edge.

3. Give the association properties, see Figure 1-12.

   
   Figure 1-12: Association property window

   Add 's' to the association name, click Containment, select -1 as the upper bound cardinality, and click OK. See Figure 1-12.

Each association has two endpoints. So far, we have defined the characteristics of the Workflow to Edge association, now we complete the opposite association end, which is called Workflow.

We complete the second association endpoint, by:

1. Clicking the 2nd Association End tab.

2. Changing the lower bound cardinality to be 1, then clicking OK.

We do the same for all the associations in the model. Any mistake can be corrected later, by simple double-clicking the link itself in the editor. Table 1-3 shows the associations that you should create.

Note 

Take care, that:

1. The link between CompoundTask and Worklow is only a one-way link, navigable from CompoundTask to Workflow. Open the 2nd association end of the link and unset Navigable.

2. The Edge to OutputPort association name is called source and the one from Edge to InputPort is named target, because an Edge connects an OutputPort to the next InputPort.

The model will now be like that shown in Figure 1-13.

Figure 1-13: Workflow complete model

1.3.5 Modeling using Java interface annotation

To define a model by means of Java interface annotations, we need to provide the same set of information we gave during the graphical modeling. We need to create a set of interfaces, one for each of the model elements. Each interface contains methods. The annotation mechanism enhances the code by adding some @model tags in the comment of any code element.

Interface definition

The abstract=" true" attribute is used for WorkflowElement and WorkflowNode. Example 1-1 shows the @model tag for the WorkflowNode. All the other interfaces use the standard @model tag to enhance the model.

Example 1-1: The WorkflowNode interface@model tag

 package com.ibm.itso.sal330r.workflow; import org.eclipse.emf.ecore.EObject; /**  * @author Vanderheyden  *  * @model abstract="true"  */ public interface WorkflowElement extends EObject{ } 

Adding attributes

An attribute is not added directly to the interface, instead, we have to define an accessor for it. Code generation completes the interface by defining the setter and provides the implementation of both the setter and the getter. Example 1-2 shows the x attribute @model tag.

Example 1-2: The x attribute @model tag

    /**     * @model default="0"     */    int getX(); 

Adding associations

For each reference, we have to define:

• The type of object it gives access to.

• If it is a containment reference.

• The name of the second association endpoint.

• If it is required or not.

  See Example 1-3

  Example 1-3: The WorkflowNode to OutputPort reference @model tag

   package com.ibm.itso.sal330r.workflow; import org.eclipse.emf.common.util.EList; /**  * @model abstract="true"  */ public interface WorkflowNode extends WorkflowElement{    /**     * @model type="com.ibm.itso.sal330r.workflow.OutputPort" opposite="node" containment="true" required="true"     */    EList getOutputs(); } 

Note 

The complete rebuild of the model using the Java annotation mechanism is a very long process, and there is no real added value in providing complete instructions in the context of our redbook.

Here is a short summary of what has to be done, for those who want to do it:

1. Create an EMF project.

2. Create a Java package.

3. Create a Java interface for all the model objects.

4. Add a getter method for each attribute.

5. Add a method for each association which is navigable. Two methods are added for navigation navigable from both ends.

6. Create an EMF model inside the EMF project, by using the Java annotation mechanism.

Java annotation and the code generation process

Each @model tag annotates the Java code to provide model related information. Those directive are used by the code generator in order to generate the corresponding implementation code. The code generation process is a non-destructive process. No @model annotations are lost during code generation. Generated code will contain the @generated tag to indicate that it has been generated and can be replaced again.

1.3.6 EMF features

EMF features are associated with attributes and associations. The code generator uses them to generate the implementation code.

EMF features for an attribute

Table 1-4 provides a short description of the EMF features that can be associated with an attribute.

Table 1-4: EMF features for an attribute

EMF feature	Description
Transient	Transient is the opposite to persistent. The attribute value is not supposed to be saved, persisted.
Volatile	A cache behavior is implemented for attribute value. Volatile is a way to prevent caching.
Unique	If the attribute is multi valued (upperBound="-1"), each value must be unique in that case
Changeable	Indicates if an attribute can be modified.
Unsettable	Indicates if an attribute can be set in a state that mean it has no value.

EMF features for an association

Table 1-5 provides a short description of the EMF features that can be associated with an association.

Table 1-5: EMF features for an association

EMF feature	Description
Transient	The object referenced through this association will not get persisted.
Volatile	Prevents the object caching.
Unique	All referenced objects are unique.
Changeable	If true, the value of the attribute is not hard coded, fixed.
Resolve Proxies	Indicates whether proxy reference should be resolved automatically.
Containment	If true, it means that any object, called the containment, which is referenced by this one, called the container, are considered as being part of it.

1.3.7 EMF model creation

Once the model has been completed, by means of EMF modeling or Java interface definition, we can generate the corresponding code to implement it. We need to create a new generator model resource, which is based on our Ecore file, or our Java interfaces.

These are the steps to create an EMF model from an EMF class diagram:

1. Create the model:

   Click File -> New -> Other..., select Eclipse Modeling Framework -> EMF Models, click Next.

2. Choose the parent folder, for example, WorkflowModel project, define the EMF model file name with a genmodel extension, for example, Workflow.genmodel, and click Next.

3. Select Load from an EMF core model, and click Next.

4. Choose the .ecore file for which you want to create a model.

   Click Browse Workspace..., navigate to the WorkflowModel project, select Workflow.ecore file, and click Next. See Figure 1-14.

   
   Figure 1-14: Ecore file selection window

5. Choose Workflow package selection, and click Finish.

These are the steps to create an EMF model from Java interface annotations:

1. Create an EMF Model:

   Click File -> New -> Other..., choose Eclipse Modeling Framework and EMF Models and click Next.

2. Choose the project and the package you want to contain the generator model resource. Define a file name for the model, for example, Workflow.genmodel, and click Next.

3. Select load from annotated Java and click Next.

4. Choose the package selection, and click Finish.

The workflow.ecore and Workflow.genmodel files have been created.

1.3.8 Code generation facility

Once the Workflow.genmodel has been created and opened in an EMF Generator editor by Eclipse, the code generation can take place:

1. Open the EMF Generator Editor:

   Select the Workflow.genmodel file, right-click Open With -> EMF Generator.

2. Generate the code:

   In the editor, click Generator -> Generate Model Code or select the root element in the tree and right-click Generate Model Code.

1.3.9 Compiling the code

Before compiling, the Java build path has to be updated, in order to resolve the EMF classes.

To update the Java Build Path:

1. Open project properties:

   1. Select the WorkflowModel project, right-click Properties, select Java Build Path.

2. Open the Libraries tab:

   1. Click Add Variable.

   2. Select ECLIPSE_HOME - C:\Program Files\eclipse.

   3. Click Extend..., select ecore.jar, common.jar and common.resource.jar, and click OK. See Figure 1-15.

      
      Figure 1-15: EMF jar files

3. Click the Order and Export tab

   1. Select the three jars, click Up to move them to the correct position in the path, click OK.

4. Compile the code, select Project -> Rebuild All.

1.3.10 Conclusion

We have demonstrated how to create an EMF model, which can be used directly as the model for our application. For more information on the Object, View, and Interaction Diagram (OVID) vocabulary used, see:

• http://www-3.ibm.com/ibm/easy/eou_ext.nsf/Publish/589

Accordingly, our model contains all the model objects that we need and all the object relationships and navigation paths to easily move from one object to the next. The model needs to be enhanced with some convenience methods, for example, the connectTo() method in the Workflow object, that will even encapsulate more of the model specifics and give a higher level model entry point.

---