EclipseCon 2007: Effective Use of the Eclipse Modeling Framework

Christian W. Damus, Kenn Hussey, Ed Merks and Dave Steinberg IBM Rational Software Ottawa and Toronto, Canada EMF, EMFT, and MDT Projects Effective Use of the Eclipse Modeling Framework https://w3-03.ibm.com/legal/ipl/iplsite.nsf/pages/wtts-trademarks+home

Part 1: Introduction to the Eclipse Modeling Framework

Agenda
EMF in a Nutshell
EMF Components
The Ecore Metamodel
Code Generation, Regeneration and Merge
The EMF Runtime
Recording Changes
Validation
Summary

EMF Demo
Quickly generate a working graphical editor to create and manipulate instances of a UML model

What is EMF?
A modeling & data integration framework
Exploits the facilities offered in Eclipse to…
Generate code without losing user customizations (merge)
Automate important tasks (such as registering the runtime information)
Improve extensibility
Provide a UI layer
What is an EMF “model”?
Specification of your application’s data
Object attributes
Relationships (associations) between objects
Operations available on each object
Simple constraints (eg. cardinality) on objects and relationships
Essentially it represents the class diagram of the application

What does EMF Provide?
From a model specification, EMF can generate efficient, correct, and easily customizable implementation code
Out of the box, EMF provides support for
Java ™ interfaces
UML
XML Schema
EMF converts your models to Ecore (EMF metamodel)
Tooling support within the Eclipse framework (UI, headless mode, Ant and standalone), including support for generating Eclipse-based and RCP editors
Reflective API and dynamic model definition
Persistence API with out of box support for XML/XMI (de)serialization of instances of a model
And much more….

Why EMF?
EMF is middle ground in the modeling vs. programming worlds
Focus is on class diagram subset of UML modeling (object model)
Transforms models into Java code
Provides the infrastructure to use models effectively in your application
Very low cost of entry
EMF is free and open source
Full scale graphical modeling tool not required
Reuses your knowledge of UML, XML Schema, or Java
It’s real, proven technology (since 2002)

EMF History
First version was released in June, 2002
Originally based on MOF (Meta Object Facility)
From OMG (Object Management Group)
Abstract language and framework for specifying, constructing, and managing technology neutral metamodels
EMF evolved based on experience supporting a large set of tools
Efficient Java implementation of a practical subset of the MOF API
2003: EMOF defined (Essential MOF)
Part of OMG’s MOF 2 specification; UML2 based
EMF is approximately the same functionality
Significant contributor to the spec; adapting to it

Who is Using EMF Today?
Eclipse projects
Foundation for the Modeling Project: Graphical Modeling Framework (GMF), EMF Ontology Definition Metamodel (EODM), UML2…
Other uses: Web Tools Platform (WTP), Test and Performance Tools Platform (TPTP), Business Intelligence and Reporting Tools (BIRT), Data Tools Platform (DTP), Visual Editor (VE)…
Commercial offerings
IBM, Borland, Oracle, Omondo, Versata, MetaMatrix, Bosch, Ensemble…
Applied sciences
Darmstadt University of Technology, Mayo Clinic College of Medicine, European Space Agency…
Large open source community
Over 1,000,000 download requests in 2006

EMF at IBM
Pervasive usage across product lines
IBM ® Rational ® Software Architect
IBM Rational Application Developer for WebSphere Software
IBM WebSphere ® Integration Developer
IBM WebSphere Application Server
IBM Lotus ® Workplace
Emerging technology projects: alphaWorks ®
Emfatic Language for EMF Development (http://www.alphaworks.ibm.com/tech/emfatic)
Model Transformation Framework (http://www.alphaworks.ibm.com/tech/mtf)
XML Forms Generator (http://www.alphaworks.ibm.com/tech/xfg)

What Have People Said About EMF?
EMF represents the core subset that's left when the non-essentials are eliminated. It represents a rock solid foundation upon which the more ambitious extensions of UML and MDA can be built.
– Vlad Varnica, OMONDO Business Development Director, 2002
EMF provides the glue between the modeling and programming worlds , offering an infrastructure to use models effectively in code by integrating UML, XML and Java. EMF thus fits well into [the] Model-Driven Development approach, and is critically important for Model-Driven Architecture , which underpins service-oriented architectures [SOA].
– Jason Bloomberg, Senior analyst for XML & Web services, ZapThink, 2003
EMF was chosen because it (a) provides a lightweight, pragmatic approach to modeling with very low entry cost and is thus suitable for rapid prototyping, (b) unifies key technologies such as Java and XML, and (c) integrates well into Eclipse.
– Bruch, Bockisch, Schäefer, Mezini, Darmstadt Univ. of Technology, 2005
[As] a consultant with fiduciary responsibility to my customers, [...] given the enormous traction that Eclipse has gathered, we have to view the EMF metadata management framework as the de facto standard .
– David Frankel, as seen in Business Process Trends, March 2005

Creating the Ecore Model
Representing the modeled domain in Ecore is the first step in using EMF
Ecore can be created
Directly using the EMF editors
Through a graphical UI provided by external contributions
By converting a model specification for which a Model Importer is available
Model Importers available in EMF
Java Interfaces
UML models expressed in Rational Rose ® files
XML Schema
Choose the one matching your perspective or skills

Model Importers Available in EMF
Java Interfaces
public interface PurchaseOrder { String getShipTo (); void setShipTo(String value); String getBillTo (); void setBillTo(String value); List<Item> getItems (); } public interface Item { String getProductName (); void setProductName(String value); int getQuantity (); void setQuantity(int value) float getPrice (); void setPrice(float value); }

UML Class Diagram

XML Schema
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.com/SimplePO" xmlns:PO="http://www.example.com/SimplePO"> <xsd:complexType name=" PurchaseOrder "> <xsd:sequence> <xsd:element name=" shipTo " type="xsd:string"/> <xsd:element name=" billTo " type="xsd:string"/> <xsd:element name=" items " type="PO:Item" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="Item"> <xsd:sequence> <xsd:element name=" productName " type="xsd:string"/> <xsd:element name=" quantity " type="xsd:int"/> <xsd:element name=" price " type="xsd:float"/> </xsd:sequence> </xsd:complexType> </xsd:schema>

Unifying Java, XML and UML Technologies
The Model Importers available in EMF were carefully chosen to integrate today’s most important technologies
All three forms provide the same information
Different visualization/representation
The application’s “model” of the structure
From a model definition, EMF can generate
Java implementation code, including UI
XML Schemas
Eclipse projects and plug-in

Typical EMF Usage Scenario
Create an Ecore model that represents the domain you are working on
Import UML (e.g. Rose .mdl file)
Import XML Schema
Import annotated Java interfaces
Create Ecore model directly using EMF's Ecore editor or a graphical editor
Generate Java code for model
Prime the model with instance data using generated EMF model editor
Iteratively refine model (and regenerate code) and develop Java application
You will use the EMF generated code to implement the use cases of your application
Optionally, use EMF.Edit to build customized user interface

EMF and Java 5.0
EMF 2.3 exploits the capabilities of Java 5.0
Generics
Typesafe enums
Annotations
Enhanced for loop
Autoboxing
EMF 2.3 provides a 5.0-targeted runtime that can only be run on a Java 5.0 or later VM
The code generator can also produce application code that runs on a 1.4 VM against the EMF 2.2.x runtime
This is a recognition that Java 5.0 is the way forward, but the transition need not be painful for the user

EMF and Java 5.0
Want to know more about Java 5.0 and EMF?
Modeling Generics with Ecore
Tuesday, 11:10 am
Grand Ballroom D
Java 5: A Developer’s Experience
Thursday, 10:10 am
Room 203-204

Agenda
EMF in a Nutshell
EMF Components
The Ecore Metamodel
The EMF Runtime
Recording Changes
Validation
Summary

EMF Architecture EMF Runtime EMF Tools Core Edit Codegen Model Editor Application Generates Eclipse Platform

EMF Components
EMF Core
Ecore metamodel
Model change notification & validation
Persistence and serialization
Reflection API
Runtime support for generated models
EMF Edit
Helps integrate models with a rich user interface
Used to build editors and viewers for your model
Includes default reflective model editor
EMF Codegen
Code generator for core and edit based components
Extensible model importer/exporter framework

EMF Tools: Model Import and Generation
Generator Features:
Customizable JSP-like templates (JET)
JDT-integrated, command-line, or Ant
Fully supports regeneration and merge
I M P O R T GENERATE Ecore Model UML XML Schema Java model Java model Java edit Java editor* * Eclipse IDE-integrated or RCP-based

EMF Model Importers
UML
Rational Rose .mdl file
Eclipse UML2 project provides importer for .uml2
Annotated Java
Java interfaces representing modeled classes
Javadoc annotations using @model tags to express model properties not captured by method declarations
Lowest cost approach
XML Schema
Describes the data of the modeled domain
Provides richer description of the data, which EMF exploits
Ecore model (*.ecore file)
Just creates the generator model (discussed later)
Also handles EMOF (*.emof)

Ecore Model Creation
An Ecore model is created within an Eclipse project via a wizard
Input: one of the model specifications from the previous slide
Output:
modelname.ecore
Ecore model file in XMI format
Canonical form of the model
modelname.genmodel
A “generator model” for specifying generator options
Contains decorators for Ecore model elements, providing details that would otherwise pollute the model (e.g. target directories for code generation)
EMF code generator is an EMF .genmodel editor
Automatically kept in synch with .ecore file

Ecore Model Editor
A generated (and customized) EMF editor for the Ecore model
Create, delete, etc. model elements (EClass, EAttribute, EReference, etc.) using pop-up actions in the editor's tree
Set names, etc. in the Properties view

Ecore Model Editor
A graphical editor is a better approach
GMF Ecore Diagram Example (http://www.eclipse.org/gmf/)
Omondo EclipseUML (http://www.omondo.com/)

EMF Generator
Similar layout to Ecore model editor
Automatically keeps in synch with .ecore changes
Generate code with pop-up menu actions
Generate Model Code
Generate Edit Code
Generate Editor Code
Generate Test Code
Generate All
Code generation options in Properties view
Generator > Reload to reload .genmodel and .ecore files from original model form

Agenda
EMF in a Nutshell
EMF Components
The Ecore Metamodel
The EMF Runtime
Recording Changes
Validation
Summary

The Ecore (Meta) Model
Ecore is EMF's model of a model
Also called a “metamodel”
Persistent representation is XMI

The Ecore Metamodel

Partial List of Ecore Data Types
Ecore data types are serializable and custom data types are supported
java.lang.Float EFloatObject java.lang.Object EJavaObject java.lang.Boolean EBooleanObject byte[ ] EByteArray java.lang.String EString float EFloat char EChar boolean EBoolean Java Primitive Type or Class Ecore Data Type

Ecore Model for Purchase Orders is represented in Ecore as

Purchase Order Ecore XMI
Alternate serialization format is EMOF (Essential MOF) XMI
Part of OMG Meta Object Facility (MOF) 2.0 standard (http://www.omg.org/docs/ptc/04-10-15.pdf)
<eClassifiers xsi:type="ecore:EClass" name=" PurchaseOrder "> <eReferences name=" items " eType="#//Item" upperBound="-1" containment="true"/> <eAttributes name=" shipTo " eType="ecore:EDataType http:...Ecore#//EString"/> <eAttributes name=" billTo " eType="ecore:EDataType http:...Ecore#//EString"/> </eClassifiers>

Agenda
EMF in a Nutshell
EMF Components
The Ecore Metamodel
The EMF Runtime
Recording Changes
Validation
Summary

Code Generation
EMF framework is lightweight
Generated code is clean, simple, efficient
EMF can generate
Model implementation
UI-independent edit support
Editor and views for Eclipse IDE-integrated or RCP application
JUnit test skeletons
Manifests, plug-in classes, properties, icons, etc.

Generated Model Code
Interface and implementation for each modeled class
Includes get/set accessors for attributes and references
Usage example
public interface PurchaseOrder extends EObject { String getShipTo (); void setShipTo (String value); String getBillTo (); void setBillTo (String value); EList<Item> getItems (); } order .getItems().add( item );

Generated Model Code
Factory to create instances of model objects
Package class provides access to metadata
Also generated: switch utility, adapter factory base, validator, custom resource, XML processor
POFactory factory = POFactory.eINSTANCE ; PurchaseOrder order = factory .createPurchaseOrder(); POPackage poPackage = POPackage.eINSTANCE ; EClass itemClass = poPackage. getItem (); //or POPackage.Literals.ITEM EAttribute priceAttr = poPackage. getItem_Price (); //or itemClass.getEStructuralFeature( POPackage.ITEM__PRICE ) //or POPackage.Literals.ITEM__PRICE

Generated Edit/Editor Code
Viewing/editing code divided into two parts
UI-independent code
Item providers (adapters)
Item provider adapter factory
UI-dependent code
Model creation wizard
Editor
Action bar contributor
Advisor (RCP)
By default each part is placed in a separate Eclipse plug-in

Java 5.0 Constructs
For a new model, EMF 2.3 targets the compiler compliance level specified by the containing project (or the workspace default)
To generate code with Java 5.0 constructs for an existing model, use the “Compliance Level” property on the GenModel

Summary of Generated Artifacts
Model
Interfaces and classes
Type-safe enumerations
Package (metadata)
Factory
Switch utility
Adapter factory base
Validator
Custom resource
XML Processor
Edit (UI independent)
Item providers
Item provider adapter factory
Editor
Model Wizard
Editor
Action bar contributor
Advisor (RCP)
Tests
Test cases
Test suite
Stand-alone example
Manifests, plug-in classes, properties, icons...

Regeneration and Merge
Hand-written code can be added to generated code and preserved during regeneration
This merge capability has an Eclipse dependency, so is not available standalone
All generated classes, interfaces, methods and fields include @generated marker in their Javadoc
To replace generated code:
Remove @generated marker
Or include additional text, e.g.
@generated NOT
Methods without @generated marker are left alone during regeneration

Regeneration and Merge
Extend (vs. replace) generated method through redirection
Append “Gen” suffix to the generated method's name
/** *  *  * @generated */ public String getName Gen () { return name; } public String getName () { return format(getNameGen()); } /** *  *  * @generated */ public String getName () { return name; }

The Code Generation Process Java Code Model Importer JET Simplified version UML Java Model ? XML Schema GenModel Ecore

The Code Generation Process Java Code Merged Java Code Model Importer JET JMerge Generated Java Code Full version UML Java Model ? XML Schema GenModel Ecore

Agenda
EMF in a Nutshell
EMF Components
The Ecore Metamodel
The EMF Runtime
Recording Changes
Validation
Summary

EMF Runtime
Persistence and serialization of model data
Proxy resolution and demand load
Automatic notification of model changes
Bi-directional reference handshaking
Dynamic object access through a reflective API
Runtime environments
Eclipse
Full IDE
RCP
Standalone Java

Persistence and Serialization
Serialized data is referred to as a resource
Data can be spread out among a number of resources in a resource set
One resource is loaded at a time, even if it has references to objects in other resources in the resource set
Proxies exist for objects in other resources
Lazy or demand loading of other resources as needed
A resource can be unloaded

Resource Set
Context for multiple resources that may have references among them
Usually just an instance of ResourceSetImpl, or a customized subclass
Provides factory method for creating new resources in the set:
Also provides access to the registries, URI converter, and default load options for the set
ResourceSet rs = new ResourceSetImpl (); URI uri = URI.createFileURI("C:/data/po.xml"); Resource resource = rs. createResource (uri);

Resource Factory Registry
Returns a resource factory for a given type of resource
Based on the URI scheme or filename extension
Determines the type of resource, hence format for save/load
For models created from XML Schema, the generated custom resource factory implementation should be registered to ensure schema-conformant serialization
When running as a plug-in under Eclipse, EMF provides an extension point for registering resource factories
Generated plugin.xml registers generated resource factory against a package specific extension (e.g. “po”)
Global registry: Resource.Factory.Registry.INSTANCE
Consulted if no registered resource factory found locally
Resource.Factory.Registry reg = rs. getResourceFactoryRegistry (); reg. getExtensionToFactoryMap ().put(" xml ", new XMLResourceFactoryImpl ());

Package Registry
Returns the package identified by a given namespace URI
Used during loading to access the factory for creating instances
Global registry: EPackage.Registry.INSTANCE
Consulted if no registered package found locally
Running in Eclipse, EMF provides an extension point for globally registering generated packages
Even standalone, a package automatically registers itself when accessed:
EPackage.Registry registry = rs. getPackageRegistry (); registry.put( POPackage.eNS_URI , POPackage.eINSTANCE ); POPackage poPackage = POPackage.eINSTANCE;

Resource
Container for objects that are to be persisted together
Convert to and from persistent form via save() and load()
Access contents of resource via getContents()
EMF provides XMLResource implementation
Other, customized XML resource implementations, provided, too (e.g. XMI, Ecore, EMOF)
URI uri = URI.createFileURI("C:/data/po.xml"); Resource resource = rs.createResource(uri); resource. getContents ().add(p1); resource. save (null); <PurchaseOrder> <shipTo>John Doe</shipTo> <next>p2.xml#p2</next> </PurchaseOrder>

Proxy Resolution and Demand Load PurchaseOrder p2 = p1. getNext (); p1 p1.xml next p2 p2.xml proxyURI=“ p2.xml #p2” next proxyURI=“p2.xml#p2” next <PurchaseOrder> <shipTo>John Doe</shipTo> <next> p2.xml#p2 </next> </PurchaseOrder> p1.xml

Model Change Notification
Every EMF object is also a Notifier
Send notification whenever an attribute or reference is changed
EMF objects can be “observed” in order to update views and dependent objects
Adapter poObserver = ... purchaseOrder. eAdapters ().add(poObserver);

Observers or listeners in EMF are called adapters
An adapter can also extend class behavior without subclassing
For this reason they are typically added using an AdapterFactory
PurchaseOrder purchaseOrder = ... AdapterFactory somePOAdapterFactory = ... Object poExtensionType = ... if (somePOAdapterFactory. isFactoryForType (poExtensiontype)) { Adapter poAdapter = somePOAdapterFactory. adapt (purchaseOrder, poExtensionType); ... }

Efficient notification in “set” methods
Checks for listeners before creating and sending notification
public String getShipTo() { return shipTo; } public void setShipTo(String newShipTo) { String oldShipTo = shipTo; shipTo = newShipTo; if (eNotificationRequired()) eNotify(new ENotificationImpl(this, ... ); }

Bidirectional Reference Handshaking public interface PurchaseOrder { PurchaseOrder getNext (); void setNext (PurchaseOrder value); PurchaseOrder getPrevious (); void setPrevious (PurchaseOrder value); } Invariant imposed by the bidirectional reference: po.getNext().getPrevious() == po

Bidirectional Reference Handshaking p1. setNext (p3); p2 p1 p2 p3 previous next next previous next previous next previous change notification

Bidirectional Reference Handshaking
This multi-step procedure is implemented using InternalEObject methods:
eInverseRemove()
eInverseAdd()
Framework list implementations and generated setters directly invoke them on target objects as needed
Notifications are accumulated using a NotificationChain and fired off at the end
They are not used to implement the handshaking

Reflection
All EMF classes implement interface EObject
Provides an efficient API for manipulating objects reflectively
Used by the framework (e.g., serialization/deserialization, copy utility, generic editing commands, etc.)
Also key to integrating tools and applications built using EMF
public interface EObject { EClass eClass (); Object eGet (EStructuralFeature sf); void eSet (EStructuralFeature sf, Object val); ... }

Reflection Example
Setting an attribute using generated API:
Using reflective API:
PurchaseOrder po = ... po. setBillTo ("123 Elm St."); EObject po = ... EClass poClass = po.eClass(); po. eSet (poClass.getEStructuralFeature("billTo"), "123 Elm St.");

Reflective Performance
Efficient generated switch-based implementation of reflective methods
public Object eGet (int featureID, ...) { switch (featureID) { case POPackage.PURCHASE_ORDER__SHIP_TO: return getShipTo (); case POPackage.PURCHASE_ORDER__BILL_TO: return getBillTo (); ... } }

Reflection Benefits
Reflection allows generic access to any EMF model
Similar to Java’s introspection capability
Every EObject (that is, every EMF object) implements the reflection API
An integrator need only know your model!
A generic EMF model editor uses the reflection API
Can be used to edit any EMF model

Dynamic EMF
Ecore models can be defined dynamically in memory
No generated code required
Dynamic implementation of reflective EObject API provides same runtime behavior as generated code
Also supports dynamic subclasses of generated classes
All EMF model instances, whether generated or dynamic, are treated the same by the framework
A dynamic Ecore model can be defined by
Instantiating model elements with the Ecore API
Loading from a .ecore file

Dynamic EMF Example
Model definition using the Ecore API
EPackage poPackage = EcoreFactory.eINSTANCE. createEPackage (); poPackage. setName ("po"); poPackage. setNsURI ("http://www.example.com/PurchaseOrder"); EClass poClass = EcoreFactory.eINSTANCE. createEClass (); poClass. setName ("PurchaseOrder"); poPackage. getEClassifiers ().add(poClass); EAttribute billTo = EcoreFactory.eINSTANCE. createEAttribute (); billTo. setName ("billTo"); billTo. setEType (EcorePackage.eINSTANCE. getEString ()); poClass. getEStructuralFeatures ().add(billTo); ... EObject po = EcoreUtil.create(poClass); po.eSet(billTo,"123 Elm St.");

XML Processor
Simplified API for loading and saving XML
Handles resource set, registries, etc. under the covers
Can automatically create a dynamic Ecore representation of a schema
Load/save instance documents without generating code
Manipulate the objects using reflective EObject API
URI schemaURI = ... String instanceFileName = ... XMLProcessor processor = new XMLProcessor (schemaURI); Resource resource = processor. load (instanceFileName, null); EObject documentRoot = resource.getContents.get(0);

Agenda
EMF in a Nutshell
EMF Components
The Ecore Metamodel
The EMF Runtime
Recording Changes
Validation
Summary

Recording Changes
EMF provides facilities for recording the changes made to instances of an Ecore model
Change Model
An EMF model for representing changes to objects
Directly references affected objects
Includes “apply changes” capability
Change Recorder
EMF adapter
Monitors objects to produce a change description (an instance of the change model)

Change Model

Change Recorder
Can be attached to EObjects, Resources, and ResourceSets
Monitors changes to the objects and their contents trees
Produces a description of the changes needed to return to the original state (a reverse delta)
Result: a change description with one change, setting billTo to “123 Elm St.”
PurchaseOrder order = ... order.setBillTo("123 Elm St."); ChangeRecorder recorder = new ChangeRecorder(); recorder. beginRecording (Collections.singleton(order)); order.setBillTo("456 Cherry St."); ChangeDescription change = recorder. endRecording ();

Applying Changes
Given a change description, the change can be applied:
ChangeDescription.apply()
consumes the changes, leaving the description empty
ChangeDescription.applyAndReverse()
reverses the changes, leaving a description of the changes originally made (the forward delta)
The model is always left in an appropriate state for applying the resulting change description

Example: Transaction Capability
If any part of the transaction fails, undo the changes
ChangeRecorder changeRecorder = new ChangeRecorder(resourceSet); try { // modifications within resource set } catch (Exception e) { changeRecorder. endRecording (). apply (); }

Agenda
EMF in a Nutshell
EMF Components
The Ecore Metamodel
The EMF Runtime
Recording Changes
Validation
Summary

Validation Framework
Model objects validated by external EValidator
Detailed results accumulated as Diagnostics
Essentially a non-Eclipse equivalent to IStatus
Records severity, source plug-in ID, status code, message, other arbitrary data, and nested children
public interface Evalidator { boolean validate (EObject eObject, DiagnosticChain diagnostics, Map Context); boolean validate (EClass eClass, EOjbect eObject, DiagnosticChain, diagnostics, Map context); boolean validate (EDataType eDataType, Object value, DiagnosticChain diagnostics, Map context); ... }

Invariants and Constraints
Invariant
Defined directly on the class, as an operation with <<inv>> stereotype
Stronger statement about validity than a constraint
Constraint
Externally defined for the class via a method on the validator

Generated EValidator Implementations
Generated for each package that defines invariants or constraints
Dispatches validation to type-specific methods
For classes, a validate method is called for each invariant and constraint
Method body must be hand coded for invariants and named constraints

Schema-Based Constraints
In XML Schema, named constraints are defined via annotations:
Also, constraints can be defined as facets on simple types, and no additional coding is required
Constraint method implementation generated
<xsd:annotation> <xsd:appinfo source="http://www.eclipse.org/emf/2002/Ecore" ecore:key="constraints">VolumeDiscount</xsd:appinfo> </xsd:annotation> <xsd:simpleType name="SKU"> <xsd:restriction base="xsd:string"> <xsd:pattern value="d{3}-[A-Z]{2}"/> </xsd:restriction> </xsd:simpleType>

Framework EValidator Implementations
EObjectValidator validates basic EObject constraints:
Multiplicities are respected
Proxies resolve
All referenced objects are contained in a resource
Data type values are valid
Used as base of generated validators and directly for packages without additional constraints defined

Framework EValidator Implementations
Diagnostician walks a containment tree of model objects, dispatching to package-specific validators
Diagnostician.validate() is the usual entry point
Obtains validators from its EValidator.Registry
Diagnostician validator = Diagnostician.INSTANCE ; Diagnostic diagnostic = validator. validate (order); if (diagnostic.getSeverity() == Diagnostic.ERROR) { // handle error } for (Diagnostic child : diagnostic.getChildren()) { // handle child diagnostic }

Agenda
EMF in a Nutshell
EMF Components
The Ecore Metamodel
The EMF Runtime
Recording Changes
Validation
Summary

Summary
EMF is low-cost modeling for the Java mainstream
Boosts productivity and facilitates integration
Mixes modeling with programming to maximize the effectiveness of both

Summary
EMF provides…
A metamodel (Ecore) with which your domain model can be specified
Your model can be created from UML, XML Schema or annotated Java interfaces
Generated Java code
Efficient and straightforward
Code customization preserved
Persistence and Serialization
Resource-based serialization
Proxy resolution and demand loading
Default resource implementation is XMI (XML metadata interchange), but can be overridden

Summary
EMF provides…
Model change notification is built in
Just add adapters (observers) where needed
Reflection and dynamic EMF
Full introspection capability
Simple change recording and roll-back
Extensible validation framework
Standalone runtime support
A UI-independent layer for viewing and editing modeled data (EMF.Edit)

Part 2: Advanced Features of the Eclipse Modeling Framework

Agenda
Working with Resources and ResourceSets
Customizing the Code Generator
Tuning for Performance and/or Memory Footprint
Importers and Exporters
Supporting Backward and Forward Compatibility
Summary

Working with proxies
Identifying proxies
Using the Validation Framework to detect unresolved proxies
Using “fragment queries” to handle unresolved proxies
Cross-Resource Containment
Inverse References
Resource Tips & Tricks
Unloading
Tracking modification
Am I loading something?

Persistence and Serialization Review
Serialized data is referred to as a resource
Data can be spread out among a number of resources in a resource set
One resource is loaded at a time, even if it has references to objects in other resources in the resource set
Proxies exist for objects in other resources
Lazy or demand loading of other resources as needed
A resource can be unloaded

Identifying Proxies
In some scenarios it may be important to know up-front what are the proxies referenced by a given object
Check whether the user has everything that will be necessary to load the model
Extract missing resources from the repository
Decide whether loading a specific object is a long or short operation
org.eclipse.emf.ecore.util.EcoreUtil.ProxyCrossReferencer
A CrossReferencer that finds proxies without resolving them
For each object in a given context (resource, resource set, EObject, collection), checks if the referenced objects are in the same resource or not

Going Deeper: EcoreUtil’s CrossReferencers
Utility classes that find “uses” of an object
Also the data structures that hold the objects they find
A CrossReferecer is a java.util.Map
On each Map.Entry
Key: reference target
Value: list of EStructuralFeature.Setting with all the source object-feature pairs referencing the keyed target

Going Deeper: EStructuralFeature.Setting
Interface that represents the value held by a feature of an EObject
Exposes all the feature-related methods of EObject
eGet, eSet, eIsSet, and eUnset

Going Deeper: Types of Reference
Containment Reference
Has an “implicit” opposite (eObject.eContainer())
Container Reference
An explicit reference defined as the opposite of a containment reference
Cross-Reference
May or may not have an opposite
Any reference can refer to an EObject located in either the same or different resource

EcoreUtil.ProxyCrossReferencer public static void printProxiesDetails(ResourceSet resourceSet ) { int counter = 0; Map<EObject, Collection<EStructuralFeature.Setting>> map = ProxyCrossReferencer .find(resourceSet); for (Map.Entry<EObject, Collection<EStructuralFeature.Setting>> entry : map.entrySet()) { EObject proxyEObject = entry. getKey (); System.out.println ("" + ++counter + ". " + EcoreUtil.getURI(proxyEObject)); System.out.println ("Is Proxy: " + proxyEObject.eIsProxy()); for (EStructuralFeature.Setting setting : entry. getValue ()) { System.out.println (" Feature: " + setting. getEStructuralFeature ().getName()); EObject eObject = setting. getEObject (); EStructuralFeature nameFeature = eObject.eClass().getEStructuralFeature("name"); if (nameFeature != null) { System.out.println (" EObject.getName(): " + eObject.eGet(nameFeature)); } } } } 1. uri3.xmi#/0 Is Proxy: true Feature: home EObject.getName(): john

Validating Proxies
The validation framework can be used to validate proxies
The EObjectValidator checks if all the referenced objects of a given EObject are resolved
The proxy references are resolved during the validation
If a proxy is broken, the validation produces a Diagnostic with EObjectValidator. EOBJECT__EVERY_PROXY_RESOLVES as its error code

Validating Proxies public static void validateProxies(EObject eObject) { Diagnostic diagnostic = Diagnostician .INSTANCE. validate (eObject); if (diagnostic.getSeverity() == Diagnostic.ERROR) { if ( hasEveryProxyResolvesCode (diagnostic)) { System.out.println ("Broken proxies found!"); return; } } System.out.println ("Proxies are fine."); } public static boolean hasEveryProxyResolvesCode (Diagnostic diagnostic) { if (diagnostic. getCode () == EObjectValidator. EOBJECT__EVERY_PROXY_RESOLVES ) return true; for (Diagnostic childDiagnostic : diagnostic.getChildren()) { return hasEveryProxyResolvesCode (childDiagnostic); } return false; }

Handling Broken Proxies
Your application can provide a mechanism to handle broken proxies by
Reporting the error to the user
Avoiding use of the object(s) that could not be resolved
Recovering the missing object(s)
EMF doesn’t provide such a mechanism but provides hooks to help you implement one
Fragment query capability is one of these hooks

Stepping Back: Uniform Resource Identifier (URI)
A formatted string that serves as an identifier for a resource
Specification:
Definition: http://www.ietf.org/rfc/rfc1630.txt
Generic Syntax: http://www.ietf.org/rfc/rfc2396.txt
Syntax:
Generic
[ scheme : ] scheme-specific-part [ # fragment ]
Hierarchical
[ scheme : ][ // authority ][ path ][ ? query ][ # fragment ]
Used in EMF to identify a resource, an object in a resource, or an Ecore package (namespace URI)

Fragment Queries
The idea is to “decorate” the fragment portion of a URI with details that further describe the referenced object
The description can be used by a service to locate the object or to enrich an error message to be presented to the user
Query data
Added to the fragment portion of the object’s URI
Must be at the end of the URI fragment portion
Is delimited by “?”
Example: file:/c:/dir/library.xmi #//@books.0?Book.ISBN.0131425420?
Fragment Query URI Fragment

Saving Fragment Queries
If you are using a XMLResource to serialize your objects
Override the getURIFragmentQuery(Resource, EObject) method of org.eclipse.emf.ecore.xmi.impl.XMLHelperImpl to return the query that should be serialized for the given EObject
Override the createXMLHelper() method of org.eclipse.emf.ecore.xmi.impl.XMLResourceImpl to return an instance of your XMLHelper
The getURIFragmentQuery(…) method returns the string that is used as the “query”
The string should not contain the delimiter character ( ? )
A null string indicates that there is no query
The characters must be valid URI fragment characters (as defined by the specification)

Going Deeper: org.eclipse.emf.ecore.xmi.XMLHelper
Interface used by the default resource implementations
Not used by clients
Single place where the methods used to save and load objects are located
Simplifies customizations

Using Fragment Queries
EMF doesn’t enforce the use of fragment queries
Reasonable approach:
Load an object
Try to resolve its proxies
Identify the remaining (broken) proxies
Use the fragment query of the broken proxies to either report the problem to the user or recover the missing objects

Cross-Resource Containment
Allows an object hierarchy to be persisted across multiple resources
eObject.eResource() may be different from eObject.eContainer().eResource()
Must be explicitly enabled
The containment reference has to be set to resolve proxies
Also, on generated models, the value of the “Containment Proxies” generator model property has to be set to ‘true’

Enabling Cross-Resource Containment EReference houses = EcoreFactory.eINSTANCE.createEReference(); houses.setName("houses"); houses.setEType(house); houses.setUpperBound(ETypedElement.UNBOUNDED_MULTIPLICITY); houses.setContainment(true); houses. setResolveProxies ( true ); person.getEStructuralFeatures().add(houses); Dynamic Model Generated Model

Cross-Resource Containment { Library library = LibFactory.eINSTANCE.createLibrary(); Book book = LibFactory.eINSTANCE.createBook(); library .getBooks().add(book); System.out.println (library.eResource() + " - " + book.eResource()); Resource libraryResource = new ResourceImpl(URI.createURI(" lib ")); libraryResource .getContents().add( library ); System.out.println (library.eResource().getURI() + " - “ + book.eResource().getURI()); Resource bookResource = new ResourceImpl(URI.createURI(" book ")); bookResource .getContents().add( book ); System.out.println (library.eResource().getURI() + " - " + book.eResource().getURI()); bookResource .getContents().remove( book ); System.out.println (library.eResource().getURI() + " - " + book.eResource().getURI()); } null - null lib - lib lib - book lib - lib

EcoreUtil Methods for Cross-Resource Containment
When the containment tree is spread across multiple files, one may be interested in differentiating the “local” children of an object from children in other resources
The *Proper* methods available in EcoreUtil only deal with the “local” children of a containment tree
All children Local children

Inverse References
Sometimes it may be handy to retrieve the opposite of a unidirectional association end
For example, the use case you are implementing requires a navigation that was not anticipated when the model was defined
EMF provides two mechanisms
CrossReferencer
ECrossReferenceAdapter

Going Deeper: Associations and References
An association between two classes allows their instances to “communicate” with each other
Each navigable end of an association is represented by an EReference in Ecore
If the association is bidirectional, it will be represented by two references, r1 and r2 where r1.getEOpposite() == r2 && r2.getEOpposite() == r1
Associations References

Using a CrossReferencer
Dynamically computes a map with the target object and the list of settings that “refer” to it
This computation may be a long operation depending on the number of objects
The map represents a snapshot of the state of the objects
As the objects change, the settings’ values may become inconsistent with the map
Requires a context to compute the map
The context can be a collection of EObjects, a resource, or a resource set, or a combination of these
Objects that are not in the scope of the context won’t be available in the map

Using a CrossReferencer { Library library = LibFactory.eINSTANCE.createLibrary(); Book book = LibFactory.eINSTANCE.createBook(); book.setTitle("EMF"); Person dave = LibFactory.eINSTANCE.createPerson(); library .getBooks().add( book ); library .getWriters().add( dave ); book .getWriters().add( dave ); Map<EObject, Collection<EStructuralFeature.Setting>> map = EcoreUtil.CrossReferencer .find(Collections.singleton( library )); Collection<EStructuralFeature.Setting> settings = map.get(dave); if (settings != null) { for (EStructuralFeature.Setting setting : settings) { if (setting. getEObject () == book && setting. getEStructuralFeature () == LibPackage.Literals. BOOK__WRITERS ) { System.out.println ("Found it. The book is "" + book.getTitle() + """); } } } } Found it. The book is "EMF"

Using the ECrossReferenceAdapter
A special adapter that
Attaches itself to all objects in a containment hierarchy
May pose a memory footprint problem depending on the number of objects
Keeps a CrossReferencer in sync with the state of the objects
The application can determine and change the context used when computing the map

Using the ECrossReferenceAdapter { Library library = LibFactory.eINSTANCE.createLibrary(); ECrossReferenceAdapter adapter = new ECrossReferenceAdapter (); library.eAdapters().add( adapter ); Book book = LibFactory.eINSTANCE.createBook(); book.setTitle("EMF"); Person dave = LibFactory.eINSTANCE.createPerson(); library .getBooks().add( book ); library .getWriters().add( dave ); book .getWriters().add( dave ); Collection<EStructuralFeature.Setting> settings = adapter. getNonNavigableInverseReferences (dave); for (EStructuralFeature.Setting setting : settings) { if (setting. getEObject () == book && setting. getEStructuralFeature () == LibPackage.Literals. BOOK__WRITERS ) { System.out.println ("Found it. The book is "" + book.getTitle() + """); } } } Found it. The book is "EMF"

Unloading a resource
Resource.unload()
EMF’s default implementation performs the following steps:
Sets the loaded attribute to false;
Caches an iterator with all the proper contents of all objects held by the resource
Clears the resource’s content, error and warning lists
Turns each object returned by the iterator into a proxy and clears its adapter list
Fires a notification
Feature ID = Resource. RESOURCE__IS_LOADED
You may also remove the resource from the resource set

Tracking modification
Resource.setTrackingModification(boolean)
When activated, EMF’s default implementation performs the following steps:
Instantiates an Adapter and registers it on all proper objects
The adapter calls Resource.setModified(boolean) after receiving a notification
Registers the adapter on any object added to the resource and deregisters it from objects that are removed
When deactivated, the default implementation removes the adapter from the objects
You can manually define what is the isModified state of a resource

Am I loading something?
Resource.Internal.isLoading()
Every Resource is supposed to implement the Resource.Internal interface
When a resource is being loaded the isLoading() method returns true

Agenda
Summary

Generating Customized Code
The EMF code generator can be customized in various ways to meet the needs of your application
There are different levels of customization
Generator Options
Dynamic Templates
Generator Extension

Generator Options
The EMF code generator provides a number of options which can have a significant effect on the kind of code that is generated from the default templates
Suppress Interfaces
Suppress EMF Metadata
Root Extends Interface
Suppress EMF Types
Suppress EMF Model Tags

Generator Options
All can be adjusted as properties of the GenModel element, the root object in the generator

Suppress Interfaces /** * A representation of the model object * 'Library'. * @model * @generated */ public interface Library extends EObject { /** * Returns the value of the ‘Name' attribute. * @model * @generated */ String getName(); ... } /** * A representation of the model object * 'Library'. * @model * @generated */ public class Library extends EObjectImpl implements EObject { /** * The default value of the 'Name' attribute. * @model * @generated */ protected static final NAME_EDEFAULT = null; ... }

Suppress Interfaces
Improves performance since dispatch through an interface is slower and less likely to be in-lined by a JIT compiler
Reduces byte code footprint somewhat
Can only be used for models with no multiple inheritance

Suppress EMF Metadata
Helps produce an API with no visible EMF dependencies, i.e. a "pure" API
/** * The Package for the model. * @model kind="package" * @generated */ public interface LibraryPackage extends EPackage { /** * The package name. * @generated */ String eNAME = "library"; ... /** * The meta object id for the 'Book' class. * @generated */ int BOOK = 0; ... } /** * The Package for the model. * @model kind="package" * @generated */ public class LibraryPackageImpl extends EPackageImpl { /** * The package name. * @generated */ String eNAME = "library"; ... }

Root Extends Interface
Helps produce an API with no visible dependencies on EMF, or an API that visibly participates in another framework
‘ Root Extends Class’ and ‘Root Implements Interface’ are also available (classes must implement InternalEObject)
/** * A representation of the model object * 'Library'. * @model * @generated */ public interface Library { ... } /** * A representation of the model object * 'Library'. * @model * @generated */ public interface Library extends EObject { ... }

Suppress EMF Model Tags
Helps produce an API with no visible dependencies on EMF
/** * A representation of the model object * 'Library'. * @generated */ public interface Library extends EObject { ... /** * Returns the value of the Writers containment * reference list. * @generated */ EList<Writer> getWriters(); ... } /** * A representation of the model object * 'Library'. * @model * @generated */ public interface Library extends EObject { ... /** * Returns the value of the Writers containment * reference list. * @model containment="true" * type="org.eclipse.example.library.Writer" * @generated */ EList<Writer> getWriters(); ... }

Suppress EMF Types
EList, EMap, and EObject suppressed
Applies to feature, operation and parameter types
Helps produce an API with no visible dependencies on EMF
/** * Returns the value of the Writers containment * reference list. * @model containment="true“ * type="org.eclipse.exasmple.library.Writer" * @generated */ List <Writer> getWriters(); /** * Returns the value of the Writers containment * reference list. * @model containment="true" * type="org.eclipse.example.library.Writer" * @generated */ EList <Writer> getWriters();

Dynamic Templates
The content of the templates used by the EMF code generator can be changed or replaced by enabling dynamic templates
Set the value of the ‘Dynamic Templates’ generator model property to ‘true’
Set the value of the ‘Template Directory’ generator model property to the location of the custom templates
Dynamic templates can be customized in three ways
Replacement
Insertions
Overrides

Template Replacement
Copy default template to the dynamic template directory (with the same name and relative location) and modify as desired
Modified template is compiled dynamically and used in place of the default template
Must keep in sync with changes in default templates (“clone and own”)…

Template Insertions
Can insert content into default templates via insertion points identified using JET @include directive (fail=“silent”)
Dynamic template includes default template; insertions are included and compiled dynamically, result is used in place of the default template
By convention, insertions are placed in a folder named after the including template and end with a .insert.*jet extension
A number of insertion points have been defined for some commonly customized EMF templates (i.e. Class.javajet, ItemProvider.javajet, TestCase.javajet)

Template Overrides
Can override content of default templates via override points identified using JET @include directive (fail=“alternative”)
Dynamic template includes default template; overrides are included and compiled dynamically, result is used in place of the default template
By convention, overrides are placed in a folder named after the including template and end with a .override.*jet extension
A number of override points have been defined for some commonly customized EMF templates (i.e. Class.javajet, ResourceFactoryClass.javajet, TestCase.javajet)

Template Insertions and Overrides
Simplified example from Class.javajet:
<%@ include file="Class/genOperation.override.javajetinc" fail="alternative" %> <%@ start %> public <%=genOperation.getImportedType()%> <%=genOperation.getName()%>(...) { <%if (genOperation.hasBody()) {%> <%=genOperation.getBody(genModel.getIndentation(stringBuffer))%> ... <%} else {%> <%@ include file="Class/genOperation.TODO.override.javajetinc" fail="alternative" %> <%@ start %> // TODO: implement this method throw new UnsupportedOperationException(); <%@ end %> <%}%> } <%@ include file="Class/genOperation.insert.javajetinc" fail="silent" %> <%@ end %>

Generator Extension
EMF’s generator is extensible
Code generation is performed by visiting the elements in the model and invoking templates to generate artifacts for each element
Control over this process is delegated to GeneratorAdapters via one or more GeneratorAdapterFactory
Additional adapter factories can be plugged into the generator to create adapters that generate additional artifacts

Generator Extension
Contributing adapters via an extension point:
Adapters can be added directly, or via an adapter factory
A generic adapter factory is instantiated for each adapter added directly, so it’s more efficient to add multiple adapters via a factory
<extension point=" org.eclipse.emf.codegen.ecore.generatorAdapters "> < adapterFactory class="com.example.generator.MyGeneratorAdapterFactory"/> < adapter modelClass="GenModel" class="com.example.generator.MyGenModelGeneratorAdapter"/> </extension>

Generator Model Extension
It is possible, but not advised, to extend the generator model by subclassing its elements
New attributes can be added to support additional code generation options
These attributes can be exposed as properties in the generator UI by registering a specialized adapter factory via the org.eclipse.emf.edit.itemProviderAdapterFacotries extension point
Protected members of GenModel elements are not considered API: you may have to adapt to changes in the base implementation!
A better way to introduce new code generation options is using generator annotations

Going Deeper: GenAnnotations
GenAnnotations can be added to any instance of GenBase, i.e. any object in a GenModel containment tree (including GenAnnotations themselves)
GenBase provides two methods to work with GenAnnotations
getGenAnnotations()
getGenAnnotation(String source)
A GenAnnotation, like its close relative EAnnotation, defines
A source attribute, which is typically used to store a URI representing the type of the annotation
A details map attribute to store name-value pairs
Containment and non-containment references to EObjects

Going Deeper: GenAnnotations
The GenAnnotations are usually hidden in the Generator
You can unhide them by checking "Show Annotations" in the "Generator" menu

Agenda
Summary

Performance/Memory Overhead
EMF provides a number of mechanisms that can be used to tune the performance and/or memory overhead of your model implementation
Code Generator Options
Boolean Flags
Virtual Feature Delegation
Minimal Reflective Methods
XMLResource Options

Boolean Flags
Generates code that uses (a) consolidated bit field(s) instead of separate fields to represent the values of Boolean attributes and whether unsettable features are set
Set the value of the ‘Boolean Flags Field’ generator model property to the name of the bit field(s) to be generated or reused
Set the value of the ‘Boolean Flags Reserved Bits’ generator model property to the number of bits in the field(s) that are reserved (e.g. used by parent classes)
Helps reduce memory overhead for models with a large number of Boolean attributes or unsettable features

Virtual Feature Delegation
Generates code that uses a single, dynamically-allocated array field and associated index field(s) instead of separate fields to represent the values of non-primitive features
Set the value of the ‘Feature Delegation’ generator model property to ‘Virtual’
Helps reduce memory overhead for models with a large number of features that are often “sparsely” used

Minimal Reflective Methods
Generates reflective methods that delegate to super , i.e. they delegate switching for any non-matching features to the superclass implementation for dispatching
Set the value of the ‘Minimal Reflective Methods’ generator model property to ‘true’ (default)
Helps reduce memory (byte code) overhead for models with a large number of inherited features
May increase performance overhead for models with deep class hierarchies

XMLResource Options
XMLResource offers a set of options that can be used to tweak load and save behavior
The options are passed to the resource’s save and load methods as entries in a map
The key is the constant that represents the option
Each option requires an appropriate value

XMLResource Load Options
OPTION_DEFER_IDREF_RESOLUTION
Option value: Boolean
Defers resolving references within a resource until the whole document has been parsed
OPTION_USE_PARSER_POOL
Option value: org.eclipse.emf.ecore.xmi.XMLParserPool
Provides a parser pool, from which SAXParser instances are created and reused
OPTION_USE_XML_NAME_TO_FEATURE_MAP
Option value: java.util.Map
Enables sharing the cache of mappings between qualified XML names (namespace + local name) and corresponding Ecore features across invocations of load(…), or even among resources

XMLResource Load Options
OPTION_USE_CACHED_LOOKUP_TABLE
Option value: java.util.List
Specifies a list as a place holder for caching information during the subsequent saving of XML documents
OPTION_USE_DEPRECATED_METHODS
Use methods that were deprecated in EMF
The default value is Boolean.TRUE

XMLResource Save Options
OPTION_FLUSH_THRESHOLD
Option value: Integer
Specifies a maximum number of characters to allow in the output stream before flushing it
OPTION_USE_CACHED_LOOKUP_TABLE
Option value: java.util.List
Provides a placeholder to cache information about structure of the model (using qualified XML names as a key for caching information)
OPTION_CONFIGURATION_CACHE
Enables caching and reusing generic data in repeated save operations, avoiding the cost of reinitializing the data

XMLResource Save Options
OPTION_FORMATTED
Disables formatting of documents, omitting whitespaces and line brakes, to improve the performance of saving and, subsequently, loading the resulting document
OPTION_USE_FILE_BUFFER
Enables accumulating output during serialization in a temporary file, rather than an in-memory buffer

Agenda
Summary

Importers and Exporters Java model Annotated Java Model Importer EMF Model Exporter Java model UML Java model XML Schema Java model Ecore Java model ? Java model ? Java model XML Schema Java model XML Schema for XMI

Model Importers
A Model Importer (aka an importer) is responsible for creating an Ecore model from the description of a modeled domain
Each importer knows how to handle a specific format of description
An importer is also expected to create the generator model (.genmodel file) for the Ecore Model (.ecore file)
EMF provides importers that handle the following formats
Rational Rose models
XML Schemas
Annotated Java Interfaces
Ecore and EMOF files

Model Exporters
A Model Exporter (aka exporter) is able to read an Ecore model and generate another description of the same modeled domain
An exporter typically uses the information described in the Generator Model to accomplish its purposes
EMF provides two exporters
XML Schema
XML Schema for XMI
EMF also provides an HTML exporter example, which uses JET to produce a package summary

Going Deeper: Why is the Generator Model so important?
The generator model acts as a decorator for an Ecore model
It provides details that would pollute the model, such as the
Qualified name of an EPackage
Prefix for package-related class names
Actual location of the model, edit, editor, and test source folders
When a modeled domain is converted into an EMF model, the importer may be able to capture some generator model details and store them in a .genmodel file
The Java package of the annotated Java interfaces
Referenced XML Schemas that may or may not be already represented by Ecore models
The generator model is useful to an exporter because
It can be used to persist details about the exported artifact
Some details may be important to properly describe the modeled domain

Using Importers and Exporters
The importers and exporters are presented to the user as pages of a standard EMF wizard
The registered importers are presented during the execution of the new EMF model or EMF project wizards
The list of exporters is shown when the “Export Model…” action is invoked on a .genmodel file
The motivation of this design is to let the importers and exporters decide the input that the user needs to provide
Each implementation has total control over the number of pages of the wizard and their content
The Rose and XML Schema importers are also available as Eclipse applications and Ant tasks

Contributing an Importer via an Extension Point
The wizard must be a class that implements EMF’s IModelImporterWizard interface
Defines the setters that will be used by the new EMF model and project wizards to communicate the details about the model specification being imported
<extension point=" org.eclipse.emf.importer.modelImporterDescriptors "> <modelImporterDescriptor id ="com.mycompany.ModelImporterDescriptor.XYZ" name="XYZ class model" extensions="xyz" wizard ="com.mycompany.ImportWizard"/> </extension>

Contributing an Exporter via an Extension Point
The wizard must be a class that implements Eclipse’s IWorkbenchWizard interface
The first time the wizard is presented to the user, the method init(IWorkbench, IStructuredSelection) is invoked and the selection argument is either an IFile that contains the generator model or an instance of GenModel
<extension point=" org.eclipse.emf.importer.modelExporterDescriptors "> <modelExporterDescriptor id ="com.mycompany.ModelExporterDescriptor.XYZ" name="XYZ class model" wizard ="com.mycompany.ExportWizard"/> </extension>

Contributing Importers and Exporters via Global Registries
The idea is to add the importer/exporter description to the appropriate list
ModelImporterManager.INSTANCE.getModelConverterDescriptors()
ModelExporterManager.INSTANCE.getModelConverterDescriptors()
The importer and exporter descriptions are quite similar, which led to the creation of a common parent interface

Agenda
Summary

Backward/Forward Compatibility
EMF provides mechanisms that can be used to support migration of data between different versions of a model (or between two different models, for that matter):
Use Ecore2Ecore and Ecore2XML to define a mapping between the different model(s) (versions)
Use Ecore2XMLExtendedMetaData with save/load options to handle unrecognized data
Use a resource handler to pre/post-process data that cannot be mapped automatically
Source and target models must have different namespace URIs and XML references must not be based on feature names

Ecore2Ecore Mappings
Describe a mapping between two Ecore models
Can be created from an Ecore (*.ecore) model via the ‘Map To Ecore…’ context menu item in the Package Explorer or Resource Navigator
Typically used as a development-time artifact (only)
Can include one-to-one, one-to-many, many-to-one, many-to-many, and one-sided mappings
Only one-to-one and one-sided (one-to-none, none-to-one) mappings are useful for data migration

Ecore2XML Mappings
Describe a mapping between an Ecore model and its XML representation
Can be generated from an Ecore2Ecore (*.ecore2ecore) model via the ‘Generate Ecore to XML Mapping…’ context menu item in the Package Explorer or Resource Navigator
Often used as a run-time artifact (in conjunction with Ecore2XMLExtendedMetaData)
Can include one-to-one and many-to-one mappings, but only the former are useful for data migration

Ecore2XMLExtendedMetaData
Can be used with the OPTION_EXTENDED_META_DATA save/load option defined on XMLResource to affect how data are serialized/deserialized
Will consult registered Ecore2XML mappings to determine the XML representation of objects
my.y my.x x_2_y.ecore2xml

OPTION_RECORD_UNKNOWN_FEATURE
Load option defined on XMLResource
Will record data for unrecognized types and features in an extension map (XMLResource#getEObjectToExtensionMap()) on the resource
Recorded data will be serialized again when the resource is saved (unless the entries in the map have been cleared)
my.x my.y y => x

Resource Handlers
Interface XMLResource.ResourceHandler defines callbacks that can be implemented to do special processing before/after a resource is loaded/saved
Used with OPTION_RESOURCE_HANDLER save/load option defined on XMLResource
Can support backward compatibility by extracting data from a resource’s extension map after it is loaded
Can support forward compatibility by inserting data into a resource’s extension map before it is saved

Enabling Data Migration
Create a package registry and add entries which map the source namespace URI and target Ecore model location to the target package
Create an Ecore2XML registry and add an entry which maps the source namespace URI to the Ecore2XML mapping
Create an instance of Ecore2XMLExtendedMetaData based on the package and Ecore2XML registries; pass this extended metadata as the value for the XMLResource.OPTION_EXTENDED_META_DATA load/save option

Enabling Data Migration
Pass Boolean.TRUE as the value for the XMLResource.OPTION_RECORD_UNKNOWN_FEATURE load option
If required, pass an implementation of XMLResource.ResourceHandler as the value for the XMLResource.OPTION_RESOURCE_HANDLER load/save option

Agenda
Summary

Summary
We have seen examples of how flexible and extensible the Eclipse Modeling Framework is
Hopefully you have gained greater insight into how some of the more “advanced” features of EMF can be exploited to meet your application’s needs

Part 3: Eclipse Modeling Framework Technologies – Query, Transaction, Validation

Agenda
EMFT in a Nutshell
Validating Models
Querying Models
Working with Transactions
Working with the Operation History
Summary

What is EMFT?
A collection of components that “add on” to EMF to provide value-added capabilities for rich applications
Currently includes:
Validation – a flexible framework for contributing 3 rd -party constraints to model validation
Query – an SQL-like Java API for querying EMF resources
Transaction – a transaction protocol for concurrent access to EMF resources
CDO, Teneo – object-relational mappings for persistence of EMF resources in RDBMSes
JET Editor – a rich editor for JET templates

What was EMFT?
Formerly in EMFT:
OCL – an implementation of the Object Constraint Language for Ecore and UML metamodels; now a component of MDT
EODM – an implementation of the Ontology Definition Metamodel for Ecore; now a component of MDT
JET (a.k.a. JET2) – next generation of the Java Emitter Templates; now a component of M2T
This tutorial will explore the Validation, Query, and Transaction components with a little OCL added for flavour

What does the Validation Framework Provide?
Extensibility:
Constraint providers contribute constraints from any source they deem fit, including the plugin.xml, constraints embedded in models, or external models
Constraint parsers contribute support for constraint specification languages. Out of the box, the framework implements Java and OCL support.
Traversal strategies contribute knowledge of the model structure and how to discover its extent to validate it
Constraint categories and bindings help to organize constraints and activate them in specific applications
Validation listeners are notified whenever validation occurs, to provide an appropriate response from the application

What does the Validation Framework Provide?
Invocation (Triggers)
“Batch” validation: initiated by the user or by the system on some important event, validates all or a selected subset of a model
“Live” validation: initiated automatically by the system to validate a set of changes performed during some transaction. The semantics of “transaction” are defined by the client
Constraints can specify which particular changes trigger them (by feature and event type)
Support for OCL constraints
EMFT Validation uses the OCL component of the MDT project to provide out-of-box support for specifying constraints using OCL

What does the Query Framework Provide?
A convenient Java API for querying an EMF-based model
The API is designed to look and feel like SQL, with SELECT and UPDATE statements, FROM clauses, etc.
Offers a wide array of reusable and recombinable predicate objects for specifying WHERE clause conditions
Supports nested and compound queries
Easily customizable for special requirements in traversing models, etc.
Support for OCL
Provides predicate classes that specify WHERE conditions as OCL constraints (with context or, optionally, context-free)

What does the Transaction API Provide?
A transactional editing environment
Safe read and write access to EMF resources from multiple concurrent threads
Commit protocol providing mechanisms for ensuring model integrity:
Validation of the changes performed during the transaction (constraints) using the Validation Framework
Pre-commit listeners proactively performing concomitant changes (triggers) to maintain consistency of dependencies
Automatic rollback of changes on failure to validate or complete triggers
Supports transaction nesting

Read/write transactions
Give a thread exclusive access to a ResourceSet for the purpose of modifying its content
Ensure that other threads do not observe interim (uncommitted) states of the data (“dirty reads”)
Read-only transactions
Protect against threads concurrently initializing concrete state of the ResourceSet (such as duplicate resolution of proxies or duplicate initialization of ELists)
Can be shared cooperatively by multiple reading threads

Change events
Commit of a transaction sends a ResourceSetChangeEvent to interested listeners, with a summary of the changes that the transaction performed
Changes are sent as a single batch, and only on successful commit, so that UI refreshes etc. don’t get any “noise”
Integration with Eclipse Workbench APIs
Support for delegating the EMF CommandStack to an IOperationHistory
Leverages the IUndoContext to support separate undo/redo “stacks” where independent changes occur in a single ResourceSet

Agenda
EMFT in a Nutshell
Validating Models
Querying Models
Summary

Constraint Providers
Constraint providers are of two flavours: static and dynamic
Static providers declare their constraints in the plugin.xml of a client plug-in of the constrained model
Dynamic providers obtain constraints from an arbitrary source at run-time
Both kinds of providers can declare constraint categories and include their constraints in categories defined by any provider
Categories are hierarchical namespaces for constraints
Constraints are grouped by category in the preference page

Static Constraint Provider <extension point=" org.eclipse.emf.validation.constraintProviders "> < category name ="Library Constraints" id ="com.example.library"> <constraintProvider> < package namespaceUri ="http:///www.eclipse.org/Library/1.0.0"/> <constraints categories ="com.example.library"> <constraint lang ="Java" class ="com.example.constraints.UniqueLibraryName" severity ="WARNING" mode ="Batch" name="Library Must have a Unique Name" id="com.example.library.LibraryNameIsUnique" statusCode="1"> <description>Libraries have unique names.</description> <message>{0} has the same name as another library.</message> < target class ="Library"/> </constraint> </constraints> </constraintProvider> </extension>

Dynamic Constraint Provider
Registered by name of a class implementing the IModelConstraintProvider interface
Indicate the packages for which they supply constraints
Biggest difference is the absence of a <constraints> element
System can optionally cache the provided constraints
<extension point=" org.eclipse.emf.validation.constraintProviders "> < category name ="Library Constraints" id ="com.example.library"> <constraintProvider class ="com.example.MyConstraintProvider" cache ="false"> < package namespaceUri ="http:///www.eclipse.org/Library/1.0.0"/> </constraintProvider> </extension>

Dynamic Constraint Provider
A dynamic constraint provider implements the IModelConstraintProvider interface
A descriptor supplies meta-data about a constraint
The validation algorithm is supplied by the constraint object in the validate() method

Constraints
Descriptor provides:
ID and localizable name
Evaluation mode
Target EClasses
Triggering events (live)
Severity, error message
Categorization
Enabled state
Much of this information appears in the preference page
Users can choose which constraints to activate

Evaluation Modes
Batch validation is usually explicitly requested by the user, via a menu action or toolbar button
Live validation is performed automatically as changes are made to EMF resources
Live constraints indicate which specific changes trigger them
<constraint mode ="Live" … > <description>Libraries have unique names.</description> <message>{0} has the same name as: {1}.</message> <target class="Library"> < event name ="Set"> < feature name ="name"/> </ event > </target> </constraint>

Validation Service
Evaluation of constraints is performed via the Validation Service
The service provides validators corresponding to the available evaluation modes
By default, batch validation includes live constraints, also, for completeness

Validation Service
To validate one or more elements, in batch mode, simply create a new validator and ask it to validate:
List objects = myResource.getContents(); // objects to validate // create a validator IValidator validator = ModelValidationService.getInstance() . newValidator (EvaluationMode. BATCH ); // use it! IStatus results = validator. validate (objects); if (!results.isOK()) { ErrorDialog.openError(null, "Validation", "Validation Failed", results); }

Validation Service
Live validation does not validate objects, but rather Notification s indicating changes to objects
List< Notification > notifications = … ; // some changes that we observed // create a validator IValidator validator = ModelValidationService.getInstance() .newValidator(EvaluationMode. LIVE ); // use it! IStatus results = validator.validate( notifications ); if (!results.isOK()) { ErrorDialog.openError(null, "Validation", "Validation Failed", results); }

Creating Constraints
Specifying a constraint doesn’t necessarily require any code
Requires the OCL component of the MDT project
<constraint lang=" OCL " mode="Batch" … > <description>Libraries have unique names.</description> <message>{0} has the same name as: {1}.</message> <target class="Library"/> <![CDATA[ Library.allInstances()->forAll(l | l <> self implies l.name <> self.name) ]]> </constraint>

Creating Constraints
Sometimes the easiest or best way to formulate a constraint is in Java
Java constraints extend the AbstractModelConstraint class
The validation context provides the validate() method with information about the validation operation

Validation Context
Provides the element being validated (the target)
Indicates the current evaluation mode (live or batch)
In case of live invocation, provides the changed feature and the event type
Allows constraints to cache arbitrary data for the duration of the current validation operation
Provides convenient methods for reporting results
Provides the ID of the constraint that is being invoked

Creating Constraints public class LibraryNameIsUnique extends AbstractConstraint { public IStatus validate (IValidationContext ctx) { Library target = (Library) ctx. getTarget (); // object to validate // does this library have a unique name? Set<Library> libs = findLibrariesWithName(target.getName()); if (libs.size() > 1) { // report this problem against all like-named libraries ctx. addResults (libs); // don’t need to validate these other libraries libs.remove(target); ctx. skipCurrentConstraintFor (libs); return ctx.createFailureStatus(new Object[] { target, libs}); } return ctx. createSuccessStatus (); } }

Listening for Validation Events
Every validation operation executed by the Validation Service generates an event
The event indicates the kind of validation performed, on what objects, and what were the results (incl. severity)
Listeners registered on the extension point are lazily initialized when their selection criteria are met
<extension point=" org.eclipse.emf.validation.validationListeners "> < listener class ="com.example.validation.ProblemsReporter"> < clientContext id ="com.example.MyClientContext"/> </listener> </extension>

Reporting Problems
Problems are reported as IConstraintStatus objects. A status knows:
The constraint that was violated
The objects that violated it
The severity and error message, as usual for an IStatus
The marker utility encodes all of this information in a problem marker on the appropriate resource, to show in the Problems view

Reporting Problems public class ProblemsReporter implements IValidationListener { public void validationOccurred (ValidationEvent event) { if (event. matches (IStatus.WARNING | IStatus.ERROR)) { // fabricate a multi-status for the MarkerUtil to consume List results = event. getValidationResults (); IConstraintStatus multi = new MultiStatus( "com.example.MyPlugin", 1, (IStatus[])results.toArray(new IStatus[results.size()]), "Problems were found by validation", null); try { // create problem markers on the appropriate resources MarkerUtil.createMarkers (multi); } catch ( CoreException e ) { // creation of problem markers failed for some reason MyPlugin.getLog().log(e.getStatus()); } } } }

Agenda
EMFT in a Nutshell
Validating Models
Querying Models
Summary

Query Statements
SELECT statements filter the objects provided by a FROM clause according to the conditions specified in the WHERE clause
SELECT s are IEObjectSource s, so they can be used in FROM clauses to nest queries
UPDATE statements use a SET clause to update the objects provided by the FROM clause (filtered, of course, by the WHERE clause)

The FROM Clause
Uses EMF’s tree iterators to walk the objects being queried
Optionally specifies an EObjectCondition filter
Search scope is encapsulated in an IEObjectSource
provides objects via an iterator. The FROM descends into the contents of these objects if it is a hierarchical IteratorKind

The WHERE Clause
The WHERE clause specifies a single filter condition
This filter condition can be arbitrarily complex
Filters can be combined in innumerable ways using the common boolean operators
The IN filter detects whether an object is an element of a supplied set (as in SQL)

The WHERE Clause
The framework provides a condition on the model type of objects
Can also filter for objects that are identical to some target ( EObjectInstanceCondition )

The WHERE Clause
The framework provides conditions that filter objects based on values of their features
In particular, the EObjectReferencerCondition filters for cross-references to a particular object

The WHERE Clause: Condition Policies
For multi-valued structural features, the ConditionPolicy determines whether a Condition must match all values or just any value
Correspond to the relational  (for-all) and  (exists) quantifiers

The WHERE Clause: Prune Handlers
Just as with EMF’s tree iterators, a query’s iteration over its scope can be pruned
Any EObjectCondition can have a PruneHandler that determines whether the search tree can be pruned
This allows the query to skip over entire sub-trees when a condition knows that it will never be satisfied for any of the contents of the current object
The default prune handler in most cases is NEVER which, as the name implies, never prunes

The WHERE Clause: Other Conditions
The framework includes a variety of conditions for working with primitive-valued EAttribute s
Including strings, booleans, and numbers of all kinds
Adapters convert inputs to the required data type
Default implementations simply cast, assuming that the values already conform
Can be customized to convert values by whatever means is appropriate

OCL Conditions
OCL can be used to specify WHERE clause conditions
Only available when the OCL component of MDT is installed
An OCLConstraintCondition specifies a boolean-valued expression (i.e., a constraint) that selects those elements for which the expression is true
OCL expressions can be contextful or context-free

The UPDATE Statement
The UPDATE statement behaves much like a SELECT , except that it passes its result objects through the client-supplied SET clause
The result of the UPDATE is the subset of the selected objects for which the SET clause returned true (indicating that they were, in fact, modified)

SELECT Query in Action
Queries can be used for anything from simple search functions to complex structural analysis
They can even be used to implement validation constraints!
IQueryResult result = new SELECT ( new FROM (res.getContents()), new WHERE (new EObjectAttributeValueCondition ( EXTLibraryPackage.Literals.WRITER__NAME, new StringRegularExpressionValue (".*Da.*")))).execute(); for (EObject next : result .getEObjects()) { Writer writer = (Writer) next; System.out.println (“Found “ + writer.getName()); } Found Dave Steinberg Found Christian Damus

SELECT Query with OCL Condition
Context-free OCL conditions are applied to any element on which they can be parsed
IQueryResult result = new SELECT( new FROM(res.getContents()), new WHERE(new OCLConstraintCondition ( " self.books->isEmpty() ", null /* no EClass implies context-free */))).execute(); for (EObject next : result.getEObjects()) { String label = ((IItemLabelProvider) adapterFactory.adapt( next, IItemLabelProvider.class)).getText(next); System.out.println ("Found " + label); } Found Library New Library Found Writer Unpublished Author

UPDATE Query in Action IQueryResult result = new UPDATE ( new FROM(res.getContents()), new WHERE(new OCLConstraintCondition( "Employee->forAll(e | e.manager <> self)", EXTLibrary.Literals.EMPLOYEE)), new SET () { public boolean set(EObject eObject) { Employee emp = (Employee) eObject; emp. setSalary (emp.getSalary() * 1.05)); return true ; // updated this one }}).execute(); for (EObject next : result .getEObjects()) { Employee emp = (Employee) next; System.out.println (“Updated “ + emp.getFirstName() + " " + emp.getLastName()); } Updated Ed Merks Updated Dave Steinberg Updated Kenn Hussey Updated Christian Damus

Agenda
EMFT in a Nutshell
Validating Models
Querying Models
Summary

What is a Transaction?
A transaction is a discrete unit of work in a resource set
This work may be reading and writing the resource set contents or simply reading
Transactions provide model integrity guarantees
Isolation of concurrent threads to prevent data corruption
Validation of changes on commit, rolling back (undoing those changes) automatically when data integrity is violated
Automatic execution of triggers on commit, to proactively maintain data integrity
This is not a concurrent transactional environment
Transactions on multiple threads execute in strictly serial order

What is a Transaction?
Transactions in a resource set are managed by a TransactionalEditingDomain
Read/write transactions are created by execution of commands on the domain’s TransactionalCommandStack
Read-only transactions are created by execution of Runnable s via TransactionalEditingDomain::runExclusive()
Most clients will never need to interact directly with Transaction objects, but only with the editing domain

Creating Transactional Editing Domains
Transactional editing domains are created by factories
Use the TransactionalEditingDomain.Factory.INSTANCE shared instance to create a private domain for your editor
To share one domain instance amongst multiple editors in an application, register a domain ID
Add your editing domain instance to the TransactionalEditingDomain.Registry.INSTANCE
Or, register it statically on the editingDomains extension point, specifying a factory for the registry to create it on demand
<extension point=" org.eclipse.emf.transaction.editingDomains "> < domain id ="com.example.MyEditingDomain" factory ="com.example.domain.MyCustomFactory"/> <!– factory is optional; implied default is the shared instance --> </extension>

Obtaining the Editing Domain
Any editor that needs to access the registered editing domain simply gets it from the registry
It is lazily created, using the associated factory, on first access
static final String DOMAIN_ID = “ com.example.MyEditingDomain ”; public void init(IEditorSite site, IEditorInput input) throws PartInitException { // get our editing domain domain = TransactionalEditingDomain. Registry.INSTANCE .getEditingDomain(DOMAIN_ID); // load our input resource String fileName = ((IFileEditorInput) input).getFile() .getLocation(); resource = domain. loadResource (fileName); }

Creating Read/Write Transactions
To do work in a read/write transaction, simply execute a Command on the TransactionalCommandStack
Just like using a regular EMF Editing Domain
If the transaction needs to roll back, it will be undone automatically and will not be appended to the stack
In order to find out when rollback occurs, use the TransactionalCommandStack::execute(Command, Map) method, which throws RollbackException , instead of using CommandStack::execute(Command)
This method also accepts a map of options to configure the transaction that will be created (more on options, later)

RecordingCommands
The RecordingCommand class is a convenient command implementation for read/write transactions
Uses the change information recorded (for possible rollback) by the transaction to “automagically” provide undo/redo
TransactionalCommandStack stack; stack. execute (new RecordingCommand () { protected void doExecute () { Iterator iter = resource.getAllContents(); while (iter.hasNext()) { // changes are determined on-the-fly Object next = iter.next(); if (next instanceof Library) { ((Library) next).getBooks().add( LibraryFactory.eINSTANCE.createBook()); } } }}, Collections.EMPTY_MAP);

Transaction Options
The TransactionalCommandStack::execute() method accepts a map of options defined by the Transaction interface that determine how changes occurring during the transaction are handled:
OPTION_NO_NOTIFICATIONS : changes are not included in post-commit change events
OPTION_NO_TRIGGERS : changes are not included in pre-commit change events
OPTION_NO_VALIDATION : changes are not validated
OPTION_NO_UNDO : changes are not recorded for undo/redo and rollback. Use with extreme caution!

Transaction Options
(continued from previous slide)
OPTION_UNPROTECTED : implies OPTION_NO_UNDO , OPTION_NO_VALIDATION , and OPTION_NO_TRIGGERS . In addition, permits writing to the resource set even in an otherwise read-only context. Use with even more extreme caution!
The CommandStack::undo() and ::redo() methods use the following options for the undo/redo transaction:
OPTION_NO_UNDO : because we are undoing or redoing a previous recording, there is no need to record anew
OPTION_NO_TRIGGERS : triggers performed during execution were recorded and are automatically undone; any additional changes would be inappropriate
OPTION_NO_VALIDATION : there is no need to validate a reversion to a previous state of the data

Transaction Options
The pre-defined options only apply to read/write transactions
Permitted on read-only transactions but have no effect
Extensions of the transaction API can define custom options
TransactionalCommandStack stack; Library library; // don’t tell the UI that we are changing the library name stack. execute ( SetCommand.create(domain, library, EXTLibraryPackage.Literals.LIBRARY__NAME, "Secret Name"), Collections.singletonMap( Transaction. OPTION_NO_NOTIFICATIONS , Boolean.TRUE));

Creating Read-Only Transactions
To read the contents of the resource set safely, use the runExclusive() API:
TransactionalEditingDomain domain; domain. runExclusive (new Runnable () { public void run () { Iterator iter = resource.getAllContents(); while (iter.hasNext()) { Object next = iter.next(); if (next instanceof Library) { Library lib = (Library) next; System.out.println (lib.getName() + " inventory: " + lib.getBooks().size() + " books"); } } }}, Collections.EMPTY_MAP); Main Branch inventory: 3033 books West Branch inventory: 2570 books South Branch inventory: 1318 books

Transaction Sharing
Read-only transactions on multiple threads can be interleaved by cooperatively yielding their read lock
Recommended for long-running read operations
Call TransactionalEditingDomain::yield() to yield read access to other threads waiting for read-only transactions
Yielding thread waits until other threads return read access to it either by finishing their transactions or by yielding
Yielding is fair: read access is always passed to the thread that has waited longest
Write access is not shared in this way
Readers cannot yield to writers
Writers cannot yield to any others

Transaction Sharing final TransactionalEditingDomain domain; final IProgressMonitor monitor; // acquire read transaction on this thread domain. runExclusive (new Runnable () { public void run() { while (moreToRead()) { // … do a bunch of reading … readSomeStuff(); // checking the progress monitor is a good opportunity to // yield to other readers if (monitor.isCancelled()) { forgetIt(); break; } domain. yield (); // just returns if no readers waiting } }});

Transaction Sharing
A thread that owns a transaction can lend it to another thread using a PrivilegedRunnable
The privileged runnable takes over the transaction for the duration of its run() method
Can be used to share read-only and read-write transactions
Ideal for runnables that need to access the resource set and the UI thread at the same time:
Pass the privileged runnable to Display.syncExec(Runnable) API to run on the UI thread
Must only be used with synchronous inter-thread communication such as syncExec
The originator thread loses the transaction during the runnable

Transaction Sharing TransactionalEditingDomain domain; final org.eclipse.swt.widgets.List bookList; // acquire read transaction on this thread domain. runExclusive (new Runnable () { public void run() { // hand it off to the UI thread to read the library and update // the list widget Display.syncExec (domain. createPrivilegedRunnable ( new Runnable() { public void run () { // the UI thread now has the transaction List<String> bookTitles = new ArrayList<String>(); for (Book book : library.getBooks) { bookTitles.add(book.getTitle()); } } // the UI thread gives up the transaction }));

Change Listeners
EMF provides an Adapter mechanism to notify listeners when objects change
In a transactional environment, though, we can end up reacting to changes only to find that they are reverted when a transaction rolls back
Enter the ResourceSetListener
Post-commit event notifies a listener of all of the changes, in a single batch, that were committed by a transaction
If a transaction rolls back, no event is sent because there were no changes
There are exceptions for changes that are not (and need not be) undone, such as resource loading and proxy resolution

Change Listeners
ResourceSetChangeEvent provides the changes that occurred
Transaction additionally has a ChangeDescription summarizing the changes
Listeners can declare filters to receive only events of interest to them
ResourceSetListenerImpl is a convenient base class providing no-ops for the listener call-backs

Change Listeners
Resource set listeners are added to the transactional editing domain
Listeners can be registered statically against an editing domain ID
Ensures that the listener is attached as soon as the domain comes into being
Resolves the problem of timing the addition of listeners
domain. addResourceSetListener (new MyListener ()); <extension point=" org.eclipse.emf.transaction.listeners "> < listener class ="com.example.MyListener"> < editingDomain id ="com.example.MyEditingDomain"/> </listener> </extension>

Post-Commit Listeners
A post-commit listener just overrides ResourceSetListenerImpl.resourceSetChanged()
DemultiplexingListener implements this by dispatching the notifications one by one to the handleNotification() method
class MyListener extends ResourceSetListenerImpl { public void resourceSetChanged (ResourceSetChangeEvent event) { System.out.println("Domain " + event .getEditingDomain().getID() + " changed " + event .getNotifications().size() + " times"); } } class MyDemuxedListener extends DemultiplexingListener { protected void handleNotification (TransactionalEditingDomain domain, Notification notification) { System.out.println("Domain " + domain .getID() + " changed: " + notification .getNotifier()); } }

Post-Commit Listeners
Advantages of the ResourceSetChangedEvent include:
Listeners know that the changes are permanent
Notifications can be processed efficiently as an aggregate
Don’t need to worry about dependency on “future” changes
No further changes can occur while the change event is being dispatched
Listeners are invoked in read-only transactions, so that they can safely read the resource set while analyzing the changes
Listeners need to be aware that notifications are delayed relative to the timing of the changes
Notifications are only received after all changes are complete
Any given notification may not correspond to the current state of the resource set, depending on subsequent changes

Pre-Commit Listeners
Before a transaction closes, pre-commit listeners are notified of the changes performed
Listeners can provide additional changes, in the form of commands, to be appended to the transaction
As with post-commit listeners, the pre-commit listener is invoked in a read-only transaction, so it does not make changes “directly”
These commands implement proactive model integrity, as do triggers in RDBMS. Hence the term “trigger command”
Trigger commands are executed in a nested transaction
This procedure is recursive: the nested transaction also invokes pre-commit listeners when it commits

Pre-Commit Listeners class MyListener extends ResourceSetListenerImpl { MyListener() { // only interested in changes to Library objects super(NotificationFilter. createNotifierTypeFilter ( EXTLibraryPackage.Literals.LIBRARY)); } public Command transactionAboutToCommit (ResourceSetChangeEvent event) { List commands = new ArrayList(); Iterator iter = event.getNotifications().iterator(); while (iter.hasNext()) { Notification next = (Notification) iter.next(); Library library = (Library) next.getNotifier(); if (library.getName() == null) commands.add( SetCommand.create ( event.getEditingDomain(), library, EXTLibraryPackage.Literals.LIBRARY__NAME, "A library")); } return commands.isEmpty()? null : new CompoundCommand(commands) ; } }

Pre-Commit Listeners
The TriggerListener class is convenient for processing notifications one by one, where appropriate
class MyTriggerListener extends TriggerListener { MyListener() { // only interested in changes to Library objects super(NotificationFilter.createNotifierTypeFilter( EXTLibraryPackage.Literals.LIBRARY)); } protected Command trigger (TransactionalEditingDomain domain , Notification notification ) { Library library = (Library) next.getNotifier(); if (library.getName() == null) { return SetCommand.create(domain, library, EXTLibraryPackage.Literals.LIBRARY__NAME, "A library"); } return null; } }

Transaction Validation
When a read/write transaction commits, all of the changes that it performed are checked using the Validation Framework’s live validation capability
If problems of error severity or worse are detected, then the transaction rolls back
Pre-commit listeners can also force the transaction to roll back by throwing a RollbackException
If a pre-commit listener cannot construct the command that it requires to maintain integrity, then it should roll back

Transaction Nesting
Both read-only and read-write transactions can nest to any depth
Post-commit events are sent only when the root transaction commits
Because even after a nested transaction has committed, it can be rolled back if its parent (or some ancestor) rolls back
Pre-commit events are sent at every level of nesting
Because a parent transaction may assume data integrity conditions guaranteed by triggers when it resumes
Validation is performed on all changes when a root transaction commits
Because triggers must be invoked first, in nested transactions

Transaction Nesting
Nested transactions inherit options from their parents
The standard options cannot be disinherited. e.g., if a parent transaction does not send post-commit notifications, then none of its descendents will, either, even if they explicitly specify Boolean.FALSE for that option
Nested transactions can, however, apply more options than their parents
e.g., a child transaction can disable notifications. When its parent commits, the changes that it reports will simply exclude any that occurred during the execution of the child
The inheritance of custom options in an extension of the transaction API is defined by that extension

Transaction Lifecycle Overview

UI Utilities
The Transaction API includes some utilities for building transactional editors
Use the editing domain to create read-only and/or read-write transactions as necessary
Substitute for the default EMF.Edit implementations

Agenda
EMFT in a Nutshell
Validating Models
Querying Models
Summary

Workbench Integration
The WorkspaceEditingDomainFactory creates editing domains whose command stacks delegate undo/redo history to the Eclipse Workbench’s IOperationHistory

Workbench Integration
To use the operation-history-enabled editing domain with your editor, simply register it with the appropriate factory class
The IWorkspaceCommandStack delegates to an operation history
Using IUndoContext s, editors for different resources in the same editing domain can provide undo/redo menus that show only the changes affecting that editor
<extension point=" org.eclipse.emf.transaction.editingDomains "> <editingDomain id="com.example.MyEditingDomain" factory=" org.eclipse.emf.workspace.WorkspaceEditingDomainFactory "/> </extension>

EMF Operations
The command stack internally wraps EMF Command s in undoable operations and executes them on the operation history
Clients can also construct Abstract- EMFOperation s and execute them on the history
CompositeEMFOperation s can freely compose both EMF and non-EMF changes

EMF Operations
AbstractEMFOperation s execute themselves within a transaction on their editing domain
Provides rollback support and automatic undo/redo just as the RecordingCommand does
CompositeEMFOperation s can compose EMF operations and operations on other domains
e.g., a composite can change objects in an EMF resource as well as edit parts in a GEF drawing surface and code in Java source files that are all interrelated
Undo/redo is fully supported and preserves ordering dependencies between EMF and non-EMF changes
Transaction rollback correctly undoes non-EMF changes

EMF Operations IOperationHistory history = workbench.getOperationSupport() .getOperationHistory(); IUndoableOperation operation = new AbstractEMFOperation (domain, “ Create Books in Libraries”) { protected IStatus doExecute (IProgressMonitor monitor, Iadaptable info) throws ExecutionException { Iterator iter = resource.getAllContents(); while (iter.hasNext()) { // changes are determined on-the-fly Object next = iter.next(); if (next instanceof Library) { ((Library) next).getBooks().add( LibraryFactory.eINSTANCE.createBook()); } } return Status.OK_STATUS; }}; operation. addUndoContext (myEditorContext); history. execute (operation, new NullProgressMonitor(), null);

Transaction Options
As is the case with Command s, EMF operations can execute with transaction options
A Map of options can be passed to the operation constructor. These are used during execution to initialize the transaction
The AbstractEMFOperation::undo() and ::redo() methods use the following transaction options:
OPTION_NO_UNDO : because we are undoing or redoing a previous recording, there is no need to record anew
OPTION_NO_TRIGGERS : triggers performed during execution were recorded and are automatically undone; any additional changes would be inappropriate
OPTION_NO_VALIDATION : there is no need to validate a reversion to a previous state of the data

Resource Undo Context
The editing domain for workbench integration automatically applies contexts to operations that are executed on its history
For each resource affected by a transaction, a resource undo context is applied to the operation
A resource is affected by any change to an object that it contains or by a change in another resource that adds a cross-reference to it
An editor that uses a resource context as its editor context will populate its undo and redo menus with operations that affected its resource

Undo/Redo Actions
The workbench integration API provides replacements for EMF’s undo/redo actions that delegate to the operation history API’s action handlers
These wrappers create undo/redo action handlers on the undo context obtained by adapting the active editor part to the IUndoContext type
Usually this undo context is a ResourceUndoContext

Agenda
EMFT in a Nutshell
Validating Models
Querying Models
Summary

Summary
We have learned how to
validate EMF resources on demand and on-the-fly using the EMFT Validation Framework
search EMF resources using the EMFT Query Framework
implement data integrity in EMF resources in a concurrent programming environment using the EMFT Transaction API
integrate EMF-based editors with the Eclipse Workbench’s undo/redo framework using the EMFT Transaction API

Resources
EMF documentation in Eclipse help
Overviews, tutorials, API reference
EMF project Web site
http://www.eclipse.org/modeling/emf/
Overviews, tutorials, newsgroup, Bugzilla
Eclipse Modeling Framework by Frank Budinsky et al.
Addison-Wesley; 1st edition (August 13, 2003)
ISBN: 0131425420.

Resources
EMFT documentation in the Eclipse on-line help
Overviews, tutorials, and API reference (Javadocs)
EMFT components Web site
Home page: http://www.eclipse.org/emft
Newsgroup: news://news.eclipse.org/eclipse.technology.emft
Bugzilla: https://bugs.eclipse.org/bugs/
Wiki: http://wiki.eclipse.org/EMFT

Legal Notices
IBM, Rational, WebSphere, Lotus, alphaWorks, and Rational Rose are registered trademarks of International Business Machines Corp. in the United States, other countries, or both.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Other company, product, or service names may be trademarks or service marks of others.

EclipseCon 2007: Effective Use of the Eclipse Modeling Framework

by Dave Steinberg on Apr 03, 2010

Accessibility

Categories

Upload Details

Usage Rights

1 Embed 15

Statistics

EclipseCon 2007: Effective Use of the Eclipse Modeling Framework Presentation Transcript