Generating an Extended EMF Model

Last updated: May 31, 2006

This tutorial is a follow-on to Generating an EMF Model, in which a simple library model is generated. In that tutorial, we showed how an EMF model can be generated very easily from a Rose model or a set of Java interface files. In this tutorial, we will show you how to generate an EMF model that extends an existing model.

First of all, let us look back at the library model:

We are now going to extend this library model by creating a new package, schoollibrary. This package contains three classes, two of which extend classes in the library model:

This tutorial will show you step-by-step how to generate an EMF model of this schoollibrary package, using the library model that you've already created. As in the previous tutorial, we will demonstrate creating this new model from a Rose model and from a set of Java interfaces.

The screenshots are based on version 3.2.0 RC6 of the Eclipse SDK and version 2.2.0 RC6a of EMF.

Contents

 contents

Step 0: Prerequisites

The library model and editor were generated in the previous tutorial, Generating an EMF Model.

• Launch Eclipse and verify that these three projects are shown in the Navigator view in the Resource perspective: "library", library.edit", and "library.editor".
  
   

If these packages are not listed, you will need to work through the previous tutorial, or see the Appendix for how to create both models at once.

 contents

Step 1a: Import the Model from Rose

Save the Rose model file schoollibrary.mdl somewhere on your workstation. It contains both the library and schoollibrary packages.

When sharing packages among various models, we really should place each package in its own .cat file, and just reference them in an .mdl file. However, for the purposes of this tutorial, we have simply duplicated and extended the library package in a single model file. The generator behaves exactly the same, whether packages are contained inside a single .mdl file or referenced in external .cat files.

Create a new EMF project in the workspace:

• Bring up the "File/New/Project..." dialog.
  
   
• Expand "Eclipse Modeling Framework" and select "EMF Project". Click the "Next" button.
  
   
• Give the project a name, say, "schoollibrary", and then click the "Next" button.
  
   
• Select "Rose class model" and click the "Next" button.
  
   
• Click on the "Browse" button and use the file dialog to locate the Rose model file. The file will be examined, and a default generator model name will be suggested. You can change the name in the entry box if you wish. Then, click the "Next" button.
  
   
• The Rose model contains two packages, "org.eclipse.example.library" and "org.eclipse.example.schoollibrary". We select only the package that we wish to generate, "org.eclipse.example.schoollibrary". However, because the latter package contains references to classes in the former, we need to specify where to find that model, so that it can be reused. Click the "Browse" button.
  
   
• In the file selection dialog, expand the folder that contains the library model, and select the generator model, "library.genmodel". Click the "OK" button.
  
   
• Expand the "Library" model, and select the "org.eclipse.example.library" package. Note that the error message disappears. Click the "Finish" button.
  
   
• An Ecore model (schoollibrary.ecore) and a generator model (schoollibrary.genmodel) will be created. The latter is opened in the main view.
  
   

 contents

Step 1b: Define the Model Using Annotated Java

Here are the annotated Java interfaces for the schoollibrary package. We can generate the EMF model from these interface files, instead of a Rose model.

SchoolLibrary.java 

package org.eclipse.example.schoollibrary; import org.eclipse.example.library.Library; /** * @model */ public interface SchoolLibrary extends Library { /** * @model */ String getLocation(); }

Asset.java 

package org.eclipse.example.schoollibrary; /** * @model */ public interface Asset { /** * @model */ float getValue(); }

SchoolBook.java 

package org.eclipse.example.schoollibrary; import org.eclipse.example.library.Book; /** * @model */ public interface SchoolBook extends Book, Asset { }

Create a new empty EMF project in the workspace:

• Bring up the "File/New/Project..." dialog.
  
   
• Expand "Eclipse Modeling Framework" and select "Empty EMF Project". Click the "Next" button.
  
   
• Give the project a name, say, "schoollibrary", and click the "Finish" button.
  
   

Add a plug-in dependency on the existing library project:

• In the Package Explorer view, expand "schoollibrary/META-INF" and double-click "MANIFEST.MF" to open the Plug-in Manifest Editor.
  
   
• Switch to the "Dependencies" tab, and click the "Add..." button under "Required Plug-ins."
  
   
• Select the "library" plug-in and click the "OK" button.
  
   
• Save the change to the manifest file and close the editor.
  
   

You could create and type in the interfaces as in the previous tutorial, but instead, we will show here how to import them from the zip file schoollibrary.zip. Save this file somewhere on your workstation, or in an otherwise empty project in your workspace.

• Right-click the "src" folder and select "Import..." from the pop-up menu.
  
   
• Expand "General" and select "Archive file" as the import source. Click the "Next" button.
  
   
• Click the "Browse" button and locate the zip file. Ensure that all of the zip file's contents are selected. You can expand the folder tree and click "schoollibrary" to see the files it contains. Ensure that they will be imported into "schoollibrary/src". Click the "Finish" button.
  
   
• Expand the "src" folder and observe that the interfaces were imported.
  
   

Create the EMF model:

• Right-click the "model" folder and select "New/Other..." from the pop-up menu.
  
   
• Expand "Eclipse Modeling Framework" and select "EMF Model". Click the "Next" button.
  
   
• Change the file name to "schoollibrary.genmodel" and click the "Next" button.
  
   
• Select "Annotated Java" and click the "Next" button.
  
   
• Select the "org.eclipse.example.schoollibrary" package and click the "Finish" button.
  
   
• An Ecore model (schoollibrary.ecore) and a generator model (schoollibrary.genmodel) will be created. The latter is opened in the main view.
  
   

 contents

Step 2: Generate the EMF Model and Editor Code

The generator model shows a root object, representing the whole model. This model object's children represent the packages in the model.

• Expand the model to see its various elements. Notice that the icon for the "Library" package has a overlayed arrow, indicating that it is a reference to the package defined in the existing library project.
  
   
• You can generate the model code and the editors for all the packages in the model in a single step by right-clicking on the root element and selecting "Generate All" from the pop-up menu. This will also create a tests plug-in, containing generated JUnit test code.
  
   
• Code is generated into the schoollibrary, schoollibrary.edit, schoollibrary.editor, and schoollibrary.tests projects. No code for the referenced model, library, will be generated.
  
   

The code should be compiled automatically as it is generated, and should recompile whenever it is changed. If you have disabled automatic building in the workbench preferences, do not forget to rebuild the code whenever it changes.

 contents

Step 3: Run the Generated Editor

In order to test the new plug-ins, a second instance of Eclipse must be launched. The plug-ins will run in this workbench.

• Select one of the projects and choose "Run As/Eclipse Application" from the "Run" menu or toolbar drop-down.
  
   
• Wait for a second instance of the Eclipse IDE to come up. Bring up the "Help/About Eclipse Platform" dialog, click on the "Plug-in Details" button, and verify that the generated plug-ins are there.
  
   

The Schoollibrary Model wizard can now be used to create a new instance of the model.

• Bring up the "File/New/Project..." dialog. Expand "General", select "Project", and click the "Next" button. Give the project a name and click the "Finish" button.
  
   
• Right-click the project and select "New/Other..." from the pop-up menu.
  
   
• Expand "Example EMF Model Creation Wizards" and select "Schoollibrary Model". Click the "Next" button.
  
   
• Enter a file name for the schoollibrary model. Make sure it ends with a ".schoollibrary" extension. Then, click the "Next" button.
  
   
• Select "SchoolLibrary" as the model object and click the "Finish" button.
  
   
• The newly created model is opened in the main view.
  
   

The root object in this editor corresponds to the My.schoollibrary resource. Note that the object beneath it is indeed a school library.

• Expand the "platform:/resource/librarytest/My.schoollibrary" resource to see the "School Library" object. Select it.
  
   
• If the Properties view isn't already showing, right-click the "School Library" object and select "Show Properties View" from the pop-up menu. Enter some values for the "Location" and "Name" attributes.
  
   
• Right-click the school library and select "New Child" from the pop-up menu. Notice that three kinds of objects can be created under a school library: "Writer", "Book", and "School Book". Writer and Book are defined in the library package, while SchoolBook is defined in the schoollibrary package.
  
   
• Create a couple writers, a book, and a school book. Notice that SchoolBook inherits all the attributes of Book and adds an extra attribute (value), as we intended.
  
   
• Save the model.
  
   

Quit the second instance of Eclipse, returning to original, development workbench.

 contents

Step 4: Modify the Editor

This part of the tutorial will show how to modify the code that gets generated. We'll just change a label in the generated editor, but we'll do it in a few different, illustrative ways.

First, we'll make a change in the generator model, which will affect the code that gets generated.

• In the school library generator model, select the "SchoolLibrary" class. In the Properties view, change the "Label Feature" to the "location : EString" attribute. This determines which feature will be used in the label for SchoolLibrary objects.
  
   
• To have this change take effect, we only need to regenerate the item provider class for SchoolLibrary. Save your changes, then right-click "SchoolLibrary" and select "Generate Edit Code" from the pop-up menu. This generates just this one item provider, along with the edit artifacts for the containing package and model. There is also no harm in regenerating all the code, however, it just takes longer.
  
   

The following table summarizes the files that are generated by the "Generate Model Code", "Generate Edit Code", "Generate Editor Code", and "Generate Tests Code" menu items in the context-sensitive menus of different objects. The "Generate All" menu item is equivalent to selecting all three menu items.

* These files are not generated by default.

Now, we can test our change.

• Launch a second instance of Eclipse again ("Run/Run As/Eclipse Application") open the "My.schoollibrary" resource. Expand the resource object and select the school library. Notice that the location of the school library is shown in the label, instead of its name.
  
   

Suppose now that you don't like the prefix "School Library" in the label and want to get rid of it. The only way to do this is to edit the code, but it is an easy change to make.

As described in the EMF.Edit Framework Overview, EMF.Edit uses item providers to, among other things, determine what label to display for a given type of object. In particular, it is the getText() method that does this, and that we'll need to change.

• In the Package Explorer, expand the "schoollibrary.edit" project. Locate and open "SchoolLibraryItemProvider.java".
  
   
• Locate the "getText()" method in the Outline view and select it.
  
   
• The cursor in the Java editor will move to that method.
  
   
• Remove the second getString() invocation, which preprends the externalized class name string, from the return statement. To ensure the change is not lost when the code is regenerated, the "@generated" Javadoc tag needs to be removed as well.
  
   
• Save the change, launch the second instace of Eclipse again, and open "My.schoollibrary". Notice that the label for the school library now contains just the value of its location attribute.
  
   

We have changed the implementation of getText() from what was originally generated. The label feature property on the SchoolLibrary class in the generator model no longer has any effect on the generated code. This is because we have removed the @generated Javadoc tag, preventing this method from being overwritten during code generation.

Now suppose that you have not yet decided whether the editor should display the value of the location attribute or of the name attribute. Instead, you want to be able to change it via the generator model later. However, you know that you don't want the "School Library" prefix to be displayed. Essentially, you would like to keep the generated implementation available to be used by a hand-coded method that removes the prefix from whatever it returns. The new method must be called "getText()", so the generated method must be renamed.

Fortunately, the EMF code generator supports this: when a method it is going to generate would conflict with a method that does not have an @generated tag, it looks for a method with the same name plus the suffix "Gen". If the method exists and is tagged with "@generated", the implementation will be generated into this method, instead.

• Rename the getText() method to "getTextGen(), keeping its "@generated" tag intact. To show that it will really be regenerated, remove the method body and replace it by a single return statement. Create a getText() method that removes the prefix from the string returned by getTextGen().
  
   
• Save SchoolLibraryItemProvider.java, switch back to the generator model, select "SchoolLibrary", and regenerate the edit code.
  
   
• Switch back to the getTextGen() method in SchoolLibraryItemProvider.java. Notice that the original implementation has been generated back into it.
  
   

You can go back to the generator model, change the label feature property, regenerate the code, and verify that that does indeed affect the generated code.

 contents

Appendix: An Alternative Way to Generate the Model

If you do not already have the base library model its editor generated in separate projects, you can generate both the library and school library models into the same set of projects in a single step. This can be done either from the Rose model or the set of annotated Java interfaces.

Starting with the Rose model, the process is the same as described above, except that both packages are selected for code generation.

• On the last page of the New Project wizard, select both the "org.eclipse.example.library" and "org.eclipse.example.schoollibrary" packages, instead of referencing one.
  
   

Starting with annotated Java interfaces, both packages are imported into a single empty EMF project before any code generation is done.

• Import the packages from library.zip and schoollibrary.zip.
   
• On the last page of the New Models wizard, select both the "org.eclipse.example.library" and "org.eclipse.example.schoollibrary" packages.
  
   

When you launch the run-time workspace to test the new editor, you may notice one small difference in the editor for the library model, as compared to when we generated it separately from the schoollibrary model.

• Create or open a library model, expand the resource object, and right-click the "Library" object. Select the "New Child" menu item.
  
   

Notice that there are three types of children available, whereas in the previous tutorial, there were only two. Specifically, "School Book", which comes from the schoollibrary package, is included. Previously, the code generator was not aware of it when generating the item provider for Library. Now, since the two packages were generated together, the base package knows all about the package that extends it.

contents