EssentialEMF

By Ed Merks and James Sugrue

About the Eclipse Modeling Framework

The Eclipse Modeling Framework (EMF) is a powerful framework and code generation facility for building Java applications based on simple model definitions. Designed to make modeling practical and useful to the mainstream Java programmer, EMF unifies three important technologies: Java, XML, and UML. Software is focused on manipulating data that can be modeled, hence, models drive software development. This refcard will get you started with the Eclipse Modeling Framework.

Generating a Model-Quick Start

Here is a step-by-step overview for creating an EMF model quickly in Eclipse.

Regeneration and Merging

The EMF generator produces files that are intended to be a combination of generated pieces and handwritten pieces. You are expected to edit the generated classes to add methods and instance variables. You can regenerate your model as required, and you can preserve the changes that you have made by modifying the @generated marker.

Regeneration and Merging, continued

Only declarations with the @generated marker will be regenerated. If you leave out the @generated annotation, or specify @generated NOT, a pattern that is encouraged when modifying generated methods directly, then your changes will not be overwritten.

A useful alternative is to redirect a generated method by adding a Gen suffix to the method name, leaving the @generated annotation intact. You can then implement your own version of the method with the original signature and can call the “Gen” version, which will continue to be regenerated in the future.

You can use @generated NOT on a class or interface to disable merging for the entire class.

Within a Javadoc comment, you can include handwritten content between the <!--begin-user-doc--> and <!--end-user-doc--> tags, i.e., within the user documentation section. This content will be merged into the user documentation section of the generated comment during merging.

The Ecore Model

During development, the Ecore model is the primary source of information for the EMF generator, which produces the code that we use to manipulate instances of the model. It’s even possible to create instances of an Ecore model, before generating code: from the context menu of any class, invoke Create Dynamic Instance. Think of an Ecore model as the intersection where Java, XML Schema, and UML overlap augmented with some of the most powerful features specific to each. Ecore is closely aligned

The Ecore Model, continued

with the Object Modeling Group’s Essential Meta Object Facility (EMOF), so EMF is able to read and write Ecore instances in a format that conforms to the standard XML Metadata Interchange (XMI) serialization of EMOF.

As a metamodel, Ecore is of course a simple model for describing models and includes support for:

• Classification of objects
• Attributes of those objects

The Ecore Model, continued

• Relationships or associations between those objects
• Operations on those objects
• Simple constraints on those objects, and their attributes and relationships

As a graphic demonstration of its simplicity, the bulk of the Ecore model can be represented as a UML-like diagram that fits a single page. The Ecore Tools project was used to render this diagram!

Figure 1: Putting it all together – a definitive view of the relations, attributes and operations of Ecore model elements

The Ecore Model, continued

• Changed whether the value of the feature can be modified.
• Derived whether the value of the feature is to be computed from those of other related features.
• Transient whether the value of the feature is omitted from the object’s persistent serialization.
• Unsettable whether the value of the feature has an unset state distinguishable from the state of being set to any specific value.
• Volatile whether the feature has no storage field generated in the implementation class.

Generics in Ecore

To support the style of generics introduced by Java 5.0, Ecore was augmented in an analogous way. Parameterized types and
operations can be specified, and types with arguments can be used in places where previously only regular types could be
used. The same notion of Java 5.0 erasures applies, i.e., the older Ecore API can be regarded as what’s left over when all use
of generics has been erased. The changes are described by a single simple diagram to augment the basic API.

When a generic type references a classifier with type parameters, it’s generally expected to specify type arguments in one-toone correspondence to those type parameters. These type arguments recursively are also generic types. In this context, the generic type can have all its references unspecified to represent a wildcard, i.e., '?', and an upper or lower bound (but not both) can be specified to represent ‘? extends Type’ or ‘? super Type’,respectively. In this way, anything expressible in Java, can be directly expressed in Ecore.

Generics in Ecore, continued

Figure 2: Extending Ecore to support generics

Structural Feature Control Flags

There are a number of flags that can be set on a model feature to control the generated code pattern for that feature as well as to direct its dynamic behavior. Typically, the default settings of these flags (shown in bold below) will be appropriate, so you shouldn't need to change them very often.

  boolean isSetLabel();
  void unsetLabel();
in addition to the original two, e.g.,
  String getLabel();
  void setLabel(String value);

Structural Feature Control Flags, continued

EObject Reflection , Int ros pection ,and Notification

All EMF modeled objects, i.e., instances of EClasses are EObjects and support reflection, i.e., you can ask an object for its class, from that class determine all the features, and then use eGet, eSet, eIsSet, and eUnset to introspect their values. An object knows its container and even the containment reference of that container which holds it. You can easily walk the contents, the children referenced by containment, and the cross references, the objects referenced by non-containment references. It’s even possible to visit all the contents, i.e., the entire containment tree, via a tree iterator.

EObject Reflection, Introspection, and Notification,continued

Figure 3: Reflective operations supported by all EObjects

An EObject is a Notifier, so you can listen to any changes made to an object as follows:

eObject.eAdapters().add(
 new AdapterImpl() {
  @Override
  public void notifyChanged(Notification notification) {
    // Listen for changes to features.
  }});

Manipulatin g/Persisting EMF Instances

EMF’s persistence framework is based on the principles of Representation State Transfer (REST). Objects are stored in resources that are identified by Uniform Resource Identifiers (URIs). A URI typically consists of /-separated components of the form `[scheme:][//authority][/path][?query][#fragment]’, e.g.,

http://www.eclipse.org/modeling/emf/?project=emf#related
file://c:/workspace/project/file.extension#id
platform:/resource/project/file.extension#id

An absolute URI starts with a scheme; it’s recommended to always use absolute URIs to identify resources. Relative URIs are useful within resources for referring to other resources collocated in the same authority; this supports easier relocation of groups of related resources. For example:

#id
../directory/file.extension
file.extension

Deresolving is the process of converting an absolute URI against a base absolute URI to yield the equivalent absolute URI e.g., deresolving platform:/resource/a/foo.html against platform:/resource/b/bar.html yields../a/foo.html. This is used when serializing a resource to produce relative URIs in the serialized result. When a resource is deserialized, resolving a relative URI against a base absolute URI of the referencing document yields the absolute URI relative to that base, e.g., resolving ../a/foo.html against platform:/resource/b/bar. html yields platform:/resource/a/foo.html. By consistently assigning absolute URIs to resources, you’ll ensure that relative URIs will be used in their serialization whenever possible, and that will help make related collections of resources more portable.

Here is the prototypical pattern for creating a model instance and serializing it.

// Create a resource set to hold the resources.
ResourceSet resourceSet = new ResourceSetImpl();

Manipulating/Persisting EMF Instances, continued

// Create a new empty resource.
Resource resource =
  resourceSet.createResource
   (URI.createFileURI("c:/My.tree"));
   
// Create and populate instances.
Node rootNode = TreeFactory.eINSTANCE.createNode();
rootNode.setLabel("root");
Node childNode = TreeFactory.eINSTANCE.createNode();
childNode.setLabel("child");
rootNode.getChildren().add(childNode);

// Add the root object to a resource and save it.
resource.getContents().add(rootNode);
resource.save(null);

Note that when running stand-alone, rather than when running as an Eclipse application, it’s important to keep in mind that Eclipse’s convenient plugin extension registrations will not be available and hence explicit registrations will be required, e.g., registration of the package and the resource factory will be needed, if it’s not handled elsewhere already.

// Register the appropriate resource factory
// to handle all file extensions.
resourceSet.getResourceFactoryRegistry().getExtensionToFactoryMap().
  put
    (Resource.Factory.Registry.DEFAULT_EXTENSION,
     new XMIResourceFactoryImpl());
// Register the package to make it available during loading.
resourceSet.getPackageRegistry().put
  (TreePackage.eNS_URI,
   TreePackage.eINSTANCE);

Here’s the prototypical pattern to load an instance.

// Demand load the resource into the resource set.
Resource resource =
  resourceSet.getResource
    (URI.createFileURI("c:/My.tree"), true);

// Extract the root object from the resource.
Node rootNode = (Node)resource.getContents().get(0);

Once the resource is loaded, the instance can be processed using the generated API. Note that a ready-to-run example just like the above is generated when you invoke Generate Test Code. It’s a good place to write code to start exploring your generated API and the capabilities of EMF.

EMF Model Using Annotated Java

Many Java developers prefer to define their initial model through Java interfaces. Leveraging the power of Javadoc annotations, you can switch between your Ecore model and your Java code seamlessly. Your code should be annotated with the @model annotation as follows:

/**
  * @model
  */
public interface Node {
 /**
  * @model opposite="parent" containment="true"
  */
 List<Node> getChildren();
 /**
  * @model opposite="children"
  */
 Node getParent();
}

EMF Model Using Annotated Java, continued

@model Properties for Classes
The Java specification for an EClass is a Java interface preceded by an @model tag.

@model Properties for Typed Elements
An ETypedElement is specified as a method in the interface corresponding to the EClass that contains the typed element.

@model Properties for Structural Features An EStructuralFeature is specified as an accessor method in the interface corresponding to the EClass that contains the feature. The properties for ETypedElement also apply.

EMF Model Using Annotated Java, continued

@model Properties for References An EReference is specified as a method in the interface corresponding to the EClass that contains the reference. The properties for EStructuralFeature, and hence, ETypedElement also apply.

@model Properties for Operations An EOperation is specified as a method in the Java interface corresponding to the EClass that contains the operation. The properties for ETypedElement also apply.

EMF Model Using XML Schema

An advantage to using XML schema to define your model is that, when serialized, instances of the model will conform to your XML schema. At a high level, the mapping to Ecore is quite simple:

EMF Extensions to XML Schema

Ecore namespace attributes can be used to tailor the default mapping onto Ecore as follows:

<?xml version="1.0" encoding="UTF-8"?>

  <xsd:element name="tree" type="tree:Node"/>
  <xsd:complexType name="Node">
	 <xsd:sequence>
	  <xsd:element ecore:opposite="parent"
	    maxOccurs="unbounded" minOccurs="0" name="children"
        type="tree:Node"/>
	</xsd:sequence>
	<xsd:attribute name="label" type="xsd:string"/>
  </xsd:complexType>
</xsd:schema>

EMF Model Using XML Schema, continued

EMF Model Using XML Schema, continued

EMF Model Using XML Schema, continued

About The Author

Ed Merks

Ed Merks leads the top-level Eclipse Modeling Project along with Rich Gronback (Borland), and the Eclipse Modeling Framework subproject. He holds a Ph.D. in Computing Science from Simon Fraser University. Ed has his own small company, Macro Modeling, and his work at Eclipse is funded by itemis AG. Ed is well recognized for his dedication to the Eclipse community, posting literally thousands of newsgroup answers each year.

Publication

EMF: Eclipse Modeling Framework, 2nd Edition, coauthor with Dave Steinberg, Frank Budinsky, and Marcelo Paternostro, Addison Wesley Publications

James Sugrue

James Sugrue is a software architect at Pilz Ireland, a company using many Eclipse technologies. James also works as editor on EclipseZone and JavaLobby. He follows the Eclipse projects closely and is interested in their application in many industries.

Recommended Book

The second edition contains more than 40% new material. The authors illuminate the key concepts and techniques of EMF modeling, analyze EMF’s most important framework classes and generator patterns, guide you through choosing optimal designs, and introduce powerful framework customizations and programming techniques.

---

BUY NOW

books.dzone.com/books/emf