EMFEditOverview

EMF.edit Overview

---

EMF.edit is a model editing framework in EMF that provides adapters (ItemProviders), property sources, a command creation and execution framework, and automated code generators for model editors. It is designed primarily to work with JFace UI widgets and viewers, but can work within any UI framework.

According to IBM's EMF.Edit Framework article (publib.boulder.ibm.com), the EMF.edit framework specifically provides:

• Content and label provider classes, property source support, and other convenience classes that allow EMF models to be displayed using standard desktop (JFace) viewers and property sheets.
• A command framework, including a set of generic command implementation classes for building editors that support fully automatic undo and redo.
• A code generator capable of generating everything needed to build a complete editor plug-in for your EMF model. It produces a properly structured editor that conforms to the recommended style for Eclipse EMF model editors. You can then customize the code however you like, without losing your connection to the model.

This article will give an overview of how the EMF.Edit framework relates specifically to REAL, and will brainstorm some ideas of what methods can be used to achieve the goals of an expanded GUI (in-cell editing, sorting, pop-ups, expanded context menus, etc.).

[TOC]

Content Providers

---

Content providers navigate the contents of a model object saved to a resource. They must implement a content provider interface (e.g. ITreeContentProvider, IStructuredContentProvider). Each JFace viewer in the generated editor code sets its content provider to new instance of an AdapterFactoryContentProvider which implements IContentProvider, ITreeContentProvider, and IStructuredContentProvider (See below).

Setting a Content Provider for a Viewer in REALEditor.java

public void createPages() {

...
    // This is the page for the tree viewer
    //
    {
      ...
      treeViewer.setContentProvider(new AdapterFactoryContentProvider(adapterFactory));
    }
...

AdapterFactoryContentProvider and adapterFactory

An AdapterFactoryContentProvider serves as a wrapper for an AdapterFactory, specifically adapterFactory in the code. The adapterFactory is an instance of a ComposedAdapterFactory which contains a ResourceItemAdapterFactory, a RealItemProviderAdapterFactory, and a ReflectiveItemProviderAdapterFactory(http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.emf.doc/references/javadoc/org/eclipse/emf/edit/provider/ReflectiveItemProviderAdapterFactory.html). The RealItemProviderAdapterFactory creates/contains all of the ItemProviders needed for our EMF model objects (the others are not of great importance right now).



In REALEditor.java code:

protected void initializeEditingDomain() {

    // Create an adapter factory that yields item providers.
    //
    adapterFactory = new ComposedAdapterFactory(ComposedAdapterFactory.Descriptor.Registry.INSTANCE);

adapterFactory.addAdapterFactory(new ResourceItemProviderAdapterFactory());
adapterFactory.addAdapterFactory(new RealItemProviderAdapterFactory());
adapterFactory.addAdapterFactory(new ReflectiveItemProviderAdapterFactory());
...

Usage

All access to the EMF object contents is provided through the content providers. For instance, when a user expands a parent item in a TreeViewer object in the UI, the TreeViewer will use its content provider to call getChildren() to retrieve its children's contents. Specifically, AdapterFactoryContentProvider will delegate to its adapterFactory member variable, which will in turn use its RealItemProviderAdapterFactory to grab the appropriate ItemProvider to call its own get getChildren() method.



The chain of method calls:
|TreeViewer (User expands EMF object in the UI)|->|AdapterFactoryContentProvider (as IContentProvider calling getChildren())|->|adapterFactory (delegating adapt())|->|RealItemProviderFactory (calling adapt() to adapt the object to an ITreeItemContentProvider)|->|ItemProvider (as ITreeItemContentProvider calling getChildren())|->|EMF Object|

Thoughts

To change how content is provided to the UI, AdapterFactoryContentProvider should be subclassed and appropriate changes should be made in item providers (see NMIVOS for more details).

Label Providers

---

Label providers retrieve label text and icons from EMF objects in a resource. They must implement some form of an ILabelProvider. Each JFace viewer in the EMF generated editor sets its label provider to an AdapterFactoryLabelProvider which implements ILabelProvider, IBaseLabelProvider and ITableLabelProvider.

Setting a Label Provider for a Viewer in REALEditor.java

public void createPages() {

...
    // This is the page for the tree viewer
    //
    {
      ...
      treeViewer.setLabelProvider(new AdapterFactoryLabelProvider(adapterFactory));
    }
...

AdapterFactoryLabelProvider and adapterFactory

Similar to the relationship between AdapterFactoryContentProvider and adapterFactory, AdapterFactoryLabelProvider serves as a wrapper for adapterFactory. See above for more information.

Usage

Viewers get the text and icons for EMF objects by calling getText() and getImage(), respectively. As usual, this involves a long delegation chain from UI viewer to EMF object.



The chain of method calls:
|TreeViewer|->|AdapterFactoryLabelProvider (as ILabelProvider)|->|adapterFactory (delegating adapt())|->|RealItemProviderFactory (calling adapt())|->|ItemProvider (as IItemLabelProvider)|->|EMF Object|

Thoughts

Like content providers, changes in label behavior can be made by subclassing AdapterFactoryLabelProvider and/or changes to item providers.

Property Sheet

---

The property sheet is an Eclipse viewer which specializes in allowing the user to retrieve and edit modeled object properties. The property sheet, propertySheetPage, is an instance of the Eclipse UI object PropertySheetPage that uses an AdapterFactoryContentProvider acting as an IPropertySourceProvider to retrieve an IPropertySource corresponding to a specific EMF object. The IPropertySource (a wrapper for the UI independent IItemPropertySource, which the item providers implement) is used to retrieve the properties (i.e. the contents of the object) and a list of IPropertyDescriptors that contain the ID and property labels of the EMF Object.

Retrieval of an IPropertySource

The IPropertySourceProvider retrieves an IPropertySource by a call to getPropertySource().
|PropertySheetPage|->|AdapterFactoryContentProvider (as IPropertySourceProvider calling getPropertySource())|->|adapterFactory (delegating adapt()) |->|REALItemProviderAdapterFactory (calling adapt())|->|ItemProvider (as an IItemPropertySource wrapped in a newly created IPropertySource)|->|EMF Object|

Retrieval of IPropertyDescriptors

Once an IPropertySource is retrieved, the property sheet calls getPropertyDescriptors() on the property source to retrieve a list of IPropertyDescriptors. getPropertyDescriptors() is implemented in the item providers using a similar wrapping pattern to getPropertySource() (see pg 50, fig. 3.8 in the EMF book for more details).

EMF Reference

---

• AdapterFactoryContentProvider
• AdapterFactoryLabelProvider
• AdapterFactoryEditingDomain
• ComposedAdapterFactory
• ItemProviderAdapter
  
  
  
  
  

Source Code

---

• AdapterFactoryContentProvider
• AdapterFactoryLabelProvider
• AdapterFactoryEditingDomain
• ComposedAdapterFactory
• ItemProviderAdapter
  
  
  
  
  

See Also

---

• [RealEditor]
• [AdapterFactory]