| 1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| 2 |
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 3 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| 4 |
<head> |
| 5 |
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> |
| 6 |
<link rel="stylesheet" href="images/../../../css/book.css" type="text/css"/> |
| 7 |
<link rel="stylesheet" href="images/../../../css/emf-book.css" type="text/css"/> |
| 8 |
<title>EMF.Edit Overview</title> |
| 9 |
</head> |
| 10 |
<body lang="EN-US" xml:lang="EN-US"> |
| 11 |
<h1>EMF.Edit Overview</h1> |
| 12 |
|
| 13 |
<p>Last updated: June 1, 2004</p> |
| 14 |
|
| 15 |
<p>This document assumes familiarity with basic EMF (Eclipse Modeling Framework) |
| 16 |
concepts. For more information on EMF, refer to the |
| 17 |
<a href="../../references/overview/EMF.html">EMF Overview</a>.</p> |
| 18 |
|
| 19 |
|
| 20 |
<h2>Contents</h2> |
| 21 |
<p><a href="#introduction">Introduction</a><br/> |
| 22 |
<a href="#jface">Displaying EMF Objects in JFace Viewers</a><br/> |
| 23 |
<a href="#providers">Item Provider Implementation Classes</a><br/> |
| 24 |
<a href="#commands">Modifying EMF Models Using Commands</a><br/> |
| 25 |
<a href="#generator">Using the EMF.Edit Code Generator</a></p> |
| 26 |
|
| 27 |
<h2><a name="introduction">Introduction</a></h2> |
| 28 |
|
| 29 |
<p>If you have an EMF-based model that you've generated code for using the EMF |
| 30 |
generator, and you are now ready to add user interfaces to your model and code, |
| 31 |
you can use the EMF.Edit framework to make your job easier.</p> |
| 32 |
|
| 33 |
<p>EMF.Edit is an Eclipse framework that includes generic reusable classes for |
| 34 |
building editors for EMF models. It provides:</p> |
| 35 |
|
| 36 |
<ul> |
| 37 |
<li>Content and label provider classes, property source support, and other |
| 38 |
convenience classes that allow EMF models to be displayed using standard desktop |
| 39 |
(JFace) viewers and property sheets.</li> |
| 40 |
<li>A command framework, including a set of generic command implementation |
| 41 |
classes for building editors that support fully automatic undo and redo.</li> |
| 42 |
<li>A code generator capable of generating everything needed to build a complete |
| 43 |
editor plug-in for your EMF model. It produces a properly structured editor that |
| 44 |
conforms to the recommended style for Eclipse EMF model editors. You can then |
| 45 |
customize the code however you like, without losing your connection to the |
| 46 |
model.</li> |
| 47 |
</ul> |
| 48 |
|
| 49 |
<p>This paper gives an overview of the basic concepts of the EMF.Edit frameowrk |
| 50 |
and generator tool. For more in-depth information, you can refer to the |
| 51 |
documentation for the framework classes, which covers in detail their specific |
| 52 |
behaviors and capabilities.</p> |
| 53 |
|
| 54 |
<h2><a name="jface">Displaying EMF Objects in JFace Viewers</a></h2> |
| 55 |
|
| 56 |
<h3>What's a content provider?</h3> |
| 57 |
|
| 58 |
<p>The Eclipse user interface framework (JFace) includes a set of reusable |
| 59 |
viewer classes (for example TreeViewer, TableViewer) for displaying structured |
| 60 |
models. Rather than requiring the model objects being viewed to adhere to some |
| 61 |
specific protocol (that is, implement some specific interface), JFace viewers |
| 62 |
work with any kind of object (that is, any java.lang.Object subclass). This is |
| 63 |
possible because the viewers, instead of navigating the model objects directly, |
| 64 |
access the model objects through an adapter object called a <dfn>content |
| 65 |
provider</dfn>.</p> |
| 66 |
|
| 67 |
<p>Each viewer class uses a content provider that implements a specific provider |
| 68 |
interface. For example, a TreeViewer uses a content provider that implements the |
| 69 |
following interface:</p> |
| 70 |
|
| 71 |
<pre> |
| 72 |
public interface ITreeContentProvider ... |
| 73 |
{ |
| 74 |
public Object[] getChildren(Object object); |
| 75 |
public Object getParent(Object object); |
| 76 |
... |
| 77 |
} |
| 78 |
</pre> |
| 79 |
|
| 80 |
<p>The basic structure is shown in the following diagram:</p> |
| 81 |
|
| 82 |
<img src="images/EMF.Edit/image001.gif" border="0" width="481" height="207" alt="JFace content provider"/> |
| 83 |
|
| 84 |
<p>As far as the TreeViewer is concerned it is displaying a tree of objects (it |
| 85 |
calls them items) on the screen, all of which, except the input (root) object, |
| 86 |
are provided to it by calling getChildren() on its content provider.</p> |
| 87 |
|
| 88 |
<p>Other kinds of viewers are handled similarly, although each viewer requires |
| 89 |
the content provider to implement its specific interface. Although all of the |
| 90 |
viewer interfaces are different, a content provider can often implement several |
| 91 |
of them at once, allowing the same content provider class to be used for many |
| 92 |
kinds of viewers.</p> |
| 93 |
|
| 94 |
<h3>Providing content for an EMF model</h3> |
| 95 |
|
| 96 |
<p>The EMF.Edit framework provides a generic content provider implementation |
| 97 |
class that can be used to provide content for EMF models. Class |
| 98 |
AdapterFactoryContentProvider implements the content provider interfaces by |
| 99 |
delegating to EMF adapters that know how to navigate the model objects (items) |
| 100 |
for the viewers. For example, the EMF adapter class used to support a tree |
| 101 |
viewer would implement the following EMF.Edit interface:</p> |
| 102 |
|
| 103 |
<pre> |
| 104 |
public interface ITreeItemProvider |
| 105 |
{ |
| 106 |
public Collection getChildren(Object object); |
| 107 |
public Object getParent(Object object); |
| 108 |
... |
| 109 |
} |
| 110 |
</pre> |
| 111 |
|
| 112 |
<p>Notice the similarity of this interface to the content provider interface |
| 113 |
ITreeContentProvider described above. The AdapterFactoryContentProvider |
| 114 |
implements the content provider interface by locating and then delegating to an |
| 115 |
adapter (implementing the item provider interface) for the required item. The |
| 116 |
shift in terminology from objects to items is deliberate: from the viewer's |
| 117 |
point of view, they are items, not objects.</p> |
| 118 |
|
| 119 |
<p>The EMF picture looks like this:</p> |
| 120 |
|
| 121 |
<img src="images/EMF.Edit/image002.gif" border="0" width="607" height="231" alt="AdapterFactoryContentProvider delegation to item providers"/> |
| 122 |
|
| 123 |
<p class="Note">Note: you can automatically generate an |
| 124 |
ItemProviderAdapterFactory and ItemProvider classes for a given EMF model using |
| 125 |
the generator provided with the EMF.Edit framework. More about this later.</p> |
| 126 |
|
| 127 |
<p>The AdapterFactoryContentProvider is constructed with an adapter factory |
| 128 |
which, like any other EMF adapter factory, serves to create and locate adapters |
| 129 |
of a specific type (ItemProviders in this case). The content provider services a |
| 130 |
request like getChildren() by calling adapt(item) on the |
| 131 |
ItemProviderAdapterFactory, which will create or return the ItemProvider |
| 132 |
(adapter) for the specified item. It then simply delegates to the getChildren() |
| 133 |
method of the required interface (in this case, ITreeItemProvider).</p> |
| 134 |
|
| 135 |
<p>The getChildren() method in AdapterFactoryContentProvider looks something |
| 136 |
like this:</p> |
| 137 |
|
| 138 |
<pre> |
| 139 |
public Object[] getChildren(Object object) |
| 140 |
{ |
| 141 |
ITreeItemContentProvider adapter = |
| 142 |
(ITreeItemContentProvider) |
| 143 |
adapterFactory.adapt(object, ITreeItemContentProvider.class); |
| 144 |
return adapter.getChildren(object).toArray(); |
| 145 |
} |
| 146 |
</pre> |
| 147 |
|
| 148 |
<p>This same pattern is used for all of the content provider methods. As stated |
| 149 |
previously, the AdapterFactoryContentProvider does nothing more than simply |
| 150 |
delegate content provider methods to the specific item provider (adapter) that |
| 151 |
knows how to service the request.</p> |
| 152 |
|
| 153 |
<p>In the getChildren() method above, the object being passed to |
| 154 |
adapterFactory.adapt() is a simple java.lang.Object (not an |
| 155 |
org.eclipse.emf.ecore.EObject). This is an important feature of the EMF.Edit |
| 156 |
framework. The framework has been carefully designed to accommodate views on EMF |
| 157 |
models that may be different from the model itself (that is, views that suppress |
| 158 |
objects or include additional, phantom, objects). To allow this mixture of EMF |
| 159 |
and non-EMF objects, the framework base class for adapter factories provides an |
| 160 |
implementation of adapt() that works something like this:</p> |
| 161 |
|
| 162 |
<pre> |
| 163 |
public Object adapt(Object object, Object type) |
| 164 |
{ |
| 165 |
if (object instanceof Notifier) |
| 166 |
return this.adapt((Notifier)object, type); |
| 167 |
else |
| 168 |
return object; |
| 169 |
} |
| 170 |
</pre> |
| 171 |
|
| 172 |
<p>If the specified object is not an EMF |
| 173 |
Notifier<sup><a class="footnote" href="#fn1">[1]</a><a name="ref1"> </a></sup>, |
| 174 |
it returns the object itself. With this design, an item provider that wants to |
| 175 |
add non-EMF items to a view can simply return (for example, from its |
| 176 |
getChildren() method) any non-EMF object it wants. As long as the returned |
| 177 |
object implements the viewer's required item provider interface (for example, |
| 178 |
ITreeItemProvider) it will be treated like all the other EMF items.</p> |
| 179 |
|
| 180 |
<p>This aspect of the design highlights why we prefer to call the |
| 181 |
provider/adapter classes item providers instead of adapters. In nontrivial |
| 182 |
applications, the view model (that is, the one provided by the viewer's content |
| 183 |
provider) will often be a mixture of "real" (EMF) model objects whose |
| 184 |
item providers also happen to be (EMF) adapters, and "phantom" objects |
| 185 |
whose item providers are the objects themselves. So, while all of the adapters |
| 186 |
are also item providers, the reverse is not necessarily true.</p> |
| 187 |
|
| 188 |
<h3>JFace label providers</h3> |
| 189 |
|
| 190 |
<p>In the previous sections we described how JFace viewers use a content |
| 191 |
provider to get their content items. A similar approach is used for getting the |
| 192 |
label image and text for the items being displayed by a viewer. Instead of |
| 193 |
asking the items themselves for their labels, a viewer uses another object |
| 194 |
called a label provider (similar to a content provider). A TreeViewer, for |
| 195 |
example, delegates to an object implementing the ILabelProvider interface to get |
| 196 |
the labels of the items in the tree.</p> |
| 197 |
|
| 198 |
<h3>Providing labels for EMF objects</h3> |
| 199 |
|
| 200 |
<p>The EMF.Edit framework uses the same mechanism for implementing label |
| 201 |
providers for EMF models as it uses for providing the content. A generic label |
| 202 |
provider implementation class, AdapterFactoryLabelProvider (working exactly like |
| 203 |
AdapterFactoryContentProvider), delegates the ILabelProvider interface to the |
| 204 |
item providers for the model (the same item providers that provide the content). |
| 205 |
The expanded picture looks like this:</p> |
| 206 |
|
| 207 |
<img src="images/EMF.Edit/image003.gif" border="0" width="608" height="326" alt="AdapterFactoryLabelProvider delegation to item providers"/> |
| 208 |
|
| 209 |
<p>The content and label provider can (and usually will) delegate to the same |
| 210 |
adapter factory and, consequently, the same item providers. Just as for the |
| 211 |
content provider, the item providers are where the work actually gets done.</p> |
| 212 |
|
| 213 |
<p>Using the EMF.Edit provider classes, a user might construct a TreeViewer for |
| 214 |
some EMF model as follows:</p> |
| 215 |
|
| 216 |
<pre> |
| 217 |
myAdapterFactory = ... |
| 218 |
|
| 219 |
treeViewer = new TreeViewer(); |
| 220 |
|
| 221 |
treeViewer.setContentProvider(new AdapterFactoryContentProvider(myAdapterFactory)); |
| 222 |
treeViewer.setLabelProvider(new AdapterFactoryLabelProvider(myAdapterFactory)); |
| 223 |
</pre> |
| 224 |
|
| 225 |
<p>This TreeViewer can then be displayed in, for example, an editor window in |
| 226 |
the usual (JFace prescribed) way.</p> |
| 227 |
|
| 228 |
<p>You might be thinking this all seems quite trivial so far, but only because |
| 229 |
all we've shown is how to delegate to somebody else (that is, the adapter |
| 230 |
factory). We haven't implemented any of the methods yet, we've just delegated |
| 231 |
them away. However, the method implementation is supported by EMF.Edit, which |
| 232 |
includes a code generator that generates most of the item provider and factory |
| 233 |
code for you. Before we get into that, we'll first take a look at how item |
| 234 |
providers do their job.</p> |
| 235 |
|
| 236 |
<h2><a name="providers">Item Provider Implementation Classes</a></h2> |
| 237 |
|
| 238 |
<p>As shown in the previous section, the real work of providing content for EMF |
| 239 |
models is done by the item provider adapters attached to the model. The number |
| 240 |
and types of ItemProvider adapters in the previous diagram was left |
| 241 |
intentionally vague. This is because the EMF.Edit framework supports two |
| 242 |
different patterns for the item provider adapters:</p> |
| 243 |
|
| 244 |
<ol> |
| 245 |
<li>Stateful adapters - one adapter object for every object in the model</li> |
| 246 |
<li>Singleton adapters - one adapter object for every type of object in the |
| 247 |
model (recommended when possible)</li> |
| 248 |
</ol> |
| 249 |
|
| 250 |
<p>The item providers for a given model can be implemented with either of these |
| 251 |
patterns or with a mixture of them both.</p> |
| 252 |
|
| 253 |
<h3>Stateful item provider adapters</h3> |
| 254 |
|
| 255 |
<p>With the first pattern, every object in a model has a one-to-one |
| 256 |
correspondence with its adapter. Each adapter has a pointer (called target) to |
| 257 |
the one-and-only object it's adapting.</p> |
| 258 |
|
| 259 |
<p>The picture looks like this:</p> |
| 260 |
|
| 261 |
<img src="images/EMF.Edit/image004.gif" border="0" width="615" height="257" alt="Stateful item provider adapters"/> |
| 262 |
|
| 263 |
<p>As shown, this pattern doubles the number of objects in the application, and |
| 264 |
therefore only makes sense in applications where the instances are needed to |
| 265 |
carry additional state. That's why we call it the Stateful pattern.</p> |
| 266 |
|
| 267 |
<h3>Singleton item provider adapters</h3> |
| 268 |
|
| 269 |
<p>A better approach, that avoids most of the extra objects, is the Singleton |
| 270 |
pattern. With this pattern we use a single item provider adapter for all the |
| 271 |
items of the same type. It looks like this:</p> |
| 272 |
|
| 273 |
<img src="images/EMF.Edit/image005.gif" border="0" width="615" height="257" alt="Singleton item provider adapters"/> |
| 274 |
|
| 275 |
<p>In this picture, the objects have adapter pointers, as usual, but the item |
| 276 |
providers (which are shared) have no pointers back to the objects. If you |
| 277 |
remember the tree item provider interface that we looked at previously in the |
| 278 |
content provider section, you may have noticed that all the methods took an |
| 279 |
extra argument (an object):</p> |
| 280 |
|
| 281 |
<pre> |
| 282 |
public interface ITreeItemProvider |
| 283 |
{ |
| 284 |
public Collection getChildren(Object object); |
| 285 |
public Object getParent(Object object); |
| 286 |
... |
| 287 |
} |
| 288 |
</pre> |
| 289 |
|
| 290 |
<p>The object argument was added to each item provider interface specifically to |
| 291 |
support this pattern. In the Stateful case, this object will always be the same |
| 292 |
as the adapter's target.</p> |
| 293 |
|
| 294 |
<p>Another question you may be asking yourself, is why don't we support a |
| 295 |
"true" Singleton adapter pattern - that is, exactly one adapter for |
| 296 |
all the objects? The answer is simply that while it is another possible pattern |
| 297 |
(compatible with the EMF.Edit |
| 298 |
framework)<sup><a class="footnote" href="#fn2">[2]</a><a name="ref2"> </a></sup>, |
| 299 |
we discourage it because a completely dynamic implementation, although simple, |
| 300 |
is difficult to customize (without lots of messy instanceof() checks). The |
| 301 |
alternative of having typed item provider classes, whose inheritance hierarchy |
| 302 |
mirrors the model's, provides a convenient dispatch point for implementing nice |
| 303 |
clean object-oriented view code for a model.</p> |
| 304 |
|
| 305 |
<h2><a name="commands">Modifying EMF Models Using Commands</a></h2> |
| 306 |
|
| 307 |
<p>So far we've only shown how to view EMF models using content and label |
| 308 |
providers. Another feature of the EMF.Edit framework is its support for |
| 309 |
command-based editing of a model. We use the term "editing" to mean |
| 310 |
undoable modification, as opposed to simple "writing" of a model.</p> |
| 311 |
|
| 312 |
<h3>Editing domains</h3> |
| 313 |
|
| 314 |
<p>The EMF.Edit interface EditingDomain is used to provide editing access to an |
| 315 |
EMF model. Another EMF.Edit implementation class, AdapterFactoryEditingDomain, |
| 316 |
works like the content and label providers by delegating its implementation to |
| 317 |
the item providers (through the ItemProviderAdapterFactory):</p> |
| 318 |
|
| 319 |
<img src="images/EMF.Edit/image006.gif" border="0" width="608" height="249" alt="Editing domain"/> |
| 320 |
|
| 321 |
<p>As shown, it also provides access to a command stack through which all |
| 322 |
modifications to the model will be made. The editing domain provides two |
| 323 |
fundamental services:</p> |
| 324 |
|
| 325 |
<ul> |
| 326 |
<li>A factory for commands</li> |
| 327 |
<li>A provider of model-specific details for generic EMF.Edit commands (like |
| 328 |
Add, Remove, Copy, and so on).</li> |
| 329 |
</ul> |
| 330 |
|
| 331 |
<p>The best way to think about an editing domain is as the modification or write |
| 332 |
provider to the model, while the content and label providers are the viewing or |
| 333 |
read provider. Here's the big picture:</p> |
| 334 |
|
| 335 |
<img src="images/EMF.Edit/image007.gif" border="0" width="607" height="331" alt="Read and write providers"/> |
| 336 |
|
| 337 |
<h3>Modifying a model</h3> |
| 338 |
|
| 339 |
<p>Let's look at a simple example of modifying a model.</p> |
| 340 |
|
| 341 |
<p>Assume class Company has a one-to-many reference, named departments, to class |
| 342 |
Department. To remove a department from the company (to implement, for example, |
| 343 |
an editor delete action) we could simply write the following code:</p> |
| 344 |
|
| 345 |
<pre> |
| 346 |
Department d = ... |
| 347 |
Company c = ... |
| 348 |
c.getDepartments().remove(d); |
| 349 |
</pre> |
| 350 |
|
| 351 |
<p>Although simple, this code does nothing more than simply make the |
| 352 |
modification.</p> |
| 353 |
|
| 354 |
<p>If instead, we use the EMF.Edit remove command |
| 355 |
(org.eclipse.emf.edit.command.RemoveCommand) to remove the department, we would |
| 356 |
write the following:</p> |
| 357 |
|
| 358 |
<pre> |
| 359 |
Department d = ... |
| 360 |
Company c = ... |
| 361 |
EditingDomain ed = ... |
| 362 |
RemoveCommand cmd = |
| 363 |
new RemoveCommand(ed, c, CompanyPackage.eINSTANCE.getCompany_Departments(), d); |
| 364 |
ed.getCommandStack().execute(cmd); |
| 365 |
</pre> |
| 366 |
|
| 367 |
<p>Deleting the department this way has several advantages:</p> |
| 368 |
|
| 369 |
<ol> |
| 370 |
<li>The deletion can be undone by calling ed.getCommandStack().undo().</li> |
| 371 |
<li>We can find out if a model is dirty (to enable a save menu, for example) by |
| 372 |
checking if there are commands on the command stack, assuming all modifications |
| 373 |
are done using commands (which is what the EMF.Edit framework advocates). |
| 374 |
</li> |
| 375 |
<li>We could have checked if the command is valid (to enable a delete menu, for |
| 376 |
example) before executing it by calling cmd.canExecute();</li> |
| 377 |
</ol> |
| 378 |
|
| 379 |
<p>Using commands this way, pervasively, is the way to enable all kinds of |
| 380 |
function that the EMF.Edit framework can give you.</p> |
| 381 |
|
| 382 |
<h3>Creating commands using the editing domain</h3> |
| 383 |
|
| 384 |
<p>In the previous example we created a RemoveCommand using a simple new call. |
| 385 |
This worked fine, but is not very reusable; the code fragment is doing a very |
| 386 |
specific thing, removing a department from a company. If instead we want to |
| 387 |
write, for example, a reusable delete action capable of deleting any kind of |
| 388 |
object, we can do that by using the EditingDomain to help with the job.</p> |
| 389 |
|
| 390 |
<p>The EditingDomain interface contains (among other things) a command factory |
| 391 |
method, createCommand(), that can be used, instead of new, to create |
| 392 |
commands:</p> |
| 393 |
|
| 394 |
<pre> |
| 395 |
public interface EditingDomain |
| 396 |
{ |
| 397 |
... |
| 398 |
Command createCommand(Class commandClass, CommandParameter commandParameter); |
| 399 |
... |
| 400 |
} |
| 401 |
</pre> |
| 402 |
|
| 403 |
<p>To use this method to create a command you would first need to create a |
| 404 |
CommandParameter object, set command parameters into it, and then call the |
| 405 |
create method, passing it the desired command class (for example, |
| 406 |
RemoveCommand.class) and the parameters.</p> |
| 407 |
|
| 408 |
<p>Rather then making clients go through all that, we use a convention of |
| 409 |
providing static convenience create() methods in every command class. Using the |
| 410 |
static create() method, you can create and execute a RemoveCommand like this: |
| 411 |
</p> |
| 412 |
|
| 413 |
<pre> |
| 414 |
Department d = ... |
| 415 |
EditingDomain ed = ... |
| 416 |
Command cmd = RemoveCommand.create(ed, d); |
| 417 |
ed.getCommandStack().execute(cmd); |
| 418 |
</pre> |
| 419 |
|
| 420 |
<p>As you can see, this is just a small syntactic change (RemoveCommand.create() |
| 421 |
instead of new RemoveCommand). But there are fundamental differences. We only |
| 422 |
passed one argument (that is, the object being removed), aside from the editing |
| 423 |
domain, instead of the three arguments previously. Notice how this piece of code |
| 424 |
can now be used to remove any kind of object. By delegating the creation of the |
| 425 |
command to the editing domain, we're letting it fill in the missing |
| 426 |
arguments.</p> |
| 427 |
|
| 428 |
<h3>How does an Editing Domain handle a createCommand() request?</h3> |
| 429 |
|
| 430 |
<p>To understand how it all works, let's follow through with the |
| 431 |
RemoveCommand.create() call. As stated previously, the static create() method is |
| 432 |
just a convenience method that delegates to the editing domain something like |
| 433 |
this:</p> |
| 434 |
|
| 435 |
<pre> |
| 436 |
public static Command create(EditingDomain domain, Object value) |
| 437 |
{ |
| 438 |
return domain.createCommand( |
| 439 |
RemoveCommand.class, |
| 440 |
new CommandParameter(null, null, Collections.singleton(value))); |
| 441 |
} |
| 442 |
</pre> |
| 443 |
|
| 444 |
<p>The AdapterFactoryEditingDomain then takes the request and passes it along to |
| 445 |
an item provider using the standard delegation pattern (as |
| 446 |
AdapterFactorContentProvider delegated getChildren() earlier):</p> |
| 447 |
|
| 448 |
<pre> |
| 449 |
public Command createCommand(Class commandClass, CommandParameter commandParameter) |
| 450 |
{ |
| 451 |
Object owner = ... // get the owner object for the command |
| 452 |
IEditingDomainItemProvider adapter = |
| 453 |
(IEditingDomainItemProvider) |
| 454 |
adapterFactory.adapt(owner, IEditingDomainItemProvider.class); |
| 455 |
return adapter.createCommand(owner, this, commandClass, commandParameter); |
| 456 |
} |
| 457 |
</pre> |
| 458 |
|
| 459 |
<p class="Note">Note: if you look at the actual createCommand() method you will |
| 460 |
notice that it's actually considerably more complicated. That's because it's |
| 461 |
designed to also handle, among other things, deleting collections of objects at |
| 462 |
once. This is, nevertheless, all it's doing conceptually.</p> |
| 463 |
|
| 464 |
<p>The createCommand() method uses an owner object to access the item provider |
| 465 |
to delegate to (that is, the owner is used in the adapterFactory.adapt() call). |
| 466 |
The owner in our example will be the company object (that is, the parent of the |
| 467 |
department being removed). The editing domain determines the owner by calling |
| 468 |
the getParent() method on the item provider of the object being deleted.</p> |
| 469 |
|
| 470 |
<p>The effect of all this is that the method createCommand() is finally called |
| 471 |
on the item provider of the parent of the object being removed (that is, the |
| 472 |
CompanyItemProvider for company c in the original code fragment). So, the |
| 473 |
CompanyItemProvider could implement createCommand() by doing something like |
| 474 |
this:</p> |
| 475 |
|
| 476 |
<pre> |
| 477 |
public class CompanyItemProvider ... |
| 478 |
{ |
| 479 |
... |
| 480 |
|
| 481 |
public Command createCommand(final Object object, ..., Class commandClass, ...) |
| 482 |
{ |
| 483 |
if (commandClass == RemoveCommand.class) |
| 484 |
{ |
| 485 |
return new RemoveCommand(object, |
| 486 |
CompanyPackage.eINSTANCE.getCompany_Departments(), |
| 487 |
commandParameter.getCollection()); |
| 488 |
} |
| 489 |
... |
| 490 |
} |
| 491 |
} |
| 492 |
</pre> |
| 493 |
|
| 494 |
<p>This would get the job done, but there is a better way.</p> |
| 495 |
|
| 496 |
<p>Every item provider class (that is also an EMF adapter) extends from an |
| 497 |
EMF.Edit convenience base class, ItemProviderAdapter, which provides a default |
| 498 |
implementation of, among other things, createCommand(). It implements |
| 499 |
createCommand() for all the standard commands provided by the EMF.Edit framework |
| 500 |
by calling out to a few simple methods (which are used for more than just this |
| 501 |
purpose) that are implemented in the item provider subclasses. This is an |
| 502 |
example of the Template Method design pattern.</p> |
| 503 |
|
| 504 |
<p>To make our RemoveCommand example work, CompanyItemProvider only needs |
| 505 |
to implement the following method:</p> |
| 506 |
|
| 507 |
<pre> |
| 508 |
public Collection getChildrenFeatures(Object object) |
| 509 |
{ |
| 510 |
return Collections.singleton(CompanyPackage.eINSTANCE.getCompany_Departments()); |
| 511 |
} |
| 512 |
</pre> |
| 513 |
|
| 514 |
<p>As shown, this method returns the one or more features (in this case, only |
| 515 |
the deparments reference) that are used for referencing children of the object. |
| 516 |
After calling this method, the default implementation of createCommand() will |
| 517 |
then figure out which feature to use (if more than one is returned) and create |
| 518 |
the RemoveCommand with the right one.</p> |
| 519 |
|
| 520 |
<h3>Overriding commands</h3> |
| 521 |
|
| 522 |
<p>Another advantage of creating commands through an editing domain is that it |
| 523 |
allows us to plug in different subclasses or completely different |
| 524 |
implementations of standard commands and have standard editors just pick them |
| 525 |
up. For example, assume that we want to do some extra cleanup whenever we remove |
| 526 |
a department from a company. The simplest way to achieve that might be to create |
| 527 |
a subclassof RemoveCommand called RemoveDepartmentCommand like this:</p> |
| 528 |
|
| 529 |
<pre> |
| 530 |
public class RemoveDepartmentCommand extends RemoveCommand |
| 531 |
{ |
| 532 |
public void execute() |
| 533 |
{ |
| 534 |
super.execute(); |
| 535 |
// do extra stuff ... |
| 536 |
} |
| 537 |
} |
| 538 |
</pre> |
| 539 |
|
| 540 |
<p>That part's easy enough.</p> |
| 541 |
|
| 542 |
<p>Now, if our editor uses the static RemoveCommand.create() method (which calls |
| 543 |
editingDomain.createCommand()) instead of new RemoveCommand(), then we can |
| 544 |
easily substitute our RemoveDepartmentCommand for the standard RemoveCommand by |
| 545 |
overriding createCommand() in the item provider like this:</p> |
| 546 |
|
| 547 |
<pre> |
| 548 |
public class CompanyItemProvider ... |
| 549 |
{ |
| 550 |
... |
| 551 |
|
| 552 |
public Command createCommand(final Object object, ...) |
| 553 |
{ |
| 554 |
if (commandClass == RemoveCommand.class) |
| 555 |
{ |
| 556 |
return new RemoveDepartmentCommand(...); |
| 557 |
} |
| 558 |
return super.createCommand(...); |
| 559 |
} |
| 560 |
} |
| 561 |
</pre> |
| 562 |
|
| 563 |
<p>Actually, if the command we want to specialize is one of the predefined ones |
| 564 |
(like RemoveCommand), the substitution is even easier because the default |
| 565 |
implementation of createCommand() dispatches the creation of each command to |
| 566 |
command-specific convenience methods, something like this:</p> |
| 567 |
|
| 568 |
<pre> |
| 569 |
public Command createCommand(final Object object, ... |
| 570 |
{ |
| 571 |
... |
| 572 |
if (commandClass == RemoveCommand.class) |
| 573 |
return createRemoveCommand(...); |
| 574 |
else if (commandClass == AddCommand.class) |
| 575 |
return createAddCommand(...); |
| 576 |
else ... |
| 577 |
} |
| 578 |
</pre> |
| 579 |
|
| 580 |
<p>So, we could have created our RemoveDepartmentCommand more simply by just |
| 581 |
overriding createRemoveCommand(), instead of the createCommand() method itself: |
| 582 |
</p> |
| 583 |
|
| 584 |
<pre> |
| 585 |
protected Command createRemoveCommand(...) |
| 586 |
{ |
| 587 |
return new RemoveDepartmentCommand(...); |
| 588 |
} |
| 589 |
</pre> |
| 590 |
|
| 591 |
<p>To summarize, the key point is that the editing domain is our hook to adjust |
| 592 |
command parameters, including the command class itself, so we can easily control |
| 593 |
the behavior of any editing command on our model.</p> |
| 594 |
|
| 595 |
<h3>Model change notification</h3> |
| 596 |
|
| 597 |
<p>One thing we haven't talked about yet is change notification. How do we get |
| 598 |
the viewers to refresh after a command changes something in the model? The |
| 599 |
answer is that it works using a combination of standard EMF adapter notification |
| 600 |
and a viewer refresh mechanism provided by EMF.Edit.</p> |
| 601 |
|
| 602 |
<p>When constructed, an AdapterFactoryContentProvider registers itself as a |
| 603 |
listener (i.e. org.eclipse.emf.edit.provider.INotifyChangedListener) of its |
| 604 |
adapter factory (which implements the |
| 605 |
org.eclipse.emf.edit.provider.IChangeNotifier interface). The adapter factory in |
| 606 |
turn passes itself to every item provider it creates so it can be the central |
| 607 |
change notifier for the model. The AdapterFactoryContentProvider also records |
| 608 |
(in the inputChanged() method) the viewer for which it is providing content, so |
| 609 |
that it can update its viewer when it receives a change notification.</p> |
| 610 |
|
| 611 |
<p>The following diagram shows how a change in an EMF model object (for example, |
| 612 |
changing a company name) will make its way, through the adapter factory, back to |
| 613 |
the viewers of the model.</p> |
| 614 |
|
| 615 |
<img src="images/EMF.Edit/image008.gif" border="0" width="607" height="251" alt="Model change notification"/> |
| 616 |
|
| 617 |
<p>Whenever an EMF object changes state, the method notifyChanged() is called on |
| 618 |
all the object's adapters, including the item providers (in this case, |
| 619 |
CompanyItemProvider). The notifyChanged() method in the item provider is |
| 620 |
responsible for determining whether each event notification should be passed on |
| 621 |
to the viewer, and if so, what type of update it should result in.</p> |
| 622 |
|
| 623 |
<p>To do so, it wraps interesting notifications in a ViewerNotification, a |
| 624 |
simple implementation of interface IViewerNotification. This interface extends |
| 625 |
the basic Notification interface like this:</p> |
| 626 |
|
| 627 |
<pre> |
| 628 |
public interface IViewerNotification extends Notification |
| 629 |
{ |
| 630 |
Object getElement(); |
| 631 |
boolean isContentRefresh(); |
| 632 |
boolean isLabelUpdate(); |
| 633 |
} |
| 634 |
</pre> |
| 635 |
|
| 636 |
<p>These methods specify which item in the viewer to update, whether to refresh |
| 637 |
the content under that element, and whether to update the label of that element. |
| 638 |
Since the item provider determines the children and label for an object, it must |
| 639 |
also determine how to efficiently update the viewer.</p> |
| 640 |
|
| 641 |
<p>The notifyChanged() method in class CompanyItemProvider looks like this:</p> |
| 642 |
|
| 643 |
<pre> |
| 644 |
public void notifyChanged(Notification notification) |
| 645 |
{ |
| 646 |
... |
| 647 |
switch (notification.getFeatureID(Company.class)) |
| 648 |
{ |
| 649 |
case CompanyPackage.COMPANY__NAME: |
| 650 |
fireNotifyChanged(new ViewerNotification(notification, ..., false, true)); |
| 651 |
return; |
| 652 |
case CompanyPackage.COMPANY__DEPARTMENT: |
| 653 |
fireNotifyChanged(new ViewerNotification(notification, ..., true, false)); |
| 654 |
return; |
| 655 |
} |
| 656 |
super.notifyChanged(notification); |
| 657 |
} |
| 658 |
</pre> |
| 659 |
|
| 660 |
<p>In this implementation, a change to the name attribute results in a label |
| 661 |
update, and a change to the department reference causes a content refresh. Any |
| 662 |
other change notifications have no effect on the viewer.</p> |
| 663 |
|
| 664 |
<p>The fireNotifyChanged() method is a convenience method in class |
| 665 |
ItemProviderAdapter (the base class of all the item provider adapters) which |
| 666 |
simply forwards the notification to the adapter |
| 667 |
factory<sup><a class="footnote" href="#fn3">[3]</a><a name="ref3"> </a></sup>. |
| 668 |
The adapter factory (change notifier) proceeds to dispatch the notification to |
| 669 |
all its listeners (in this example, just the tree viewer's content provider). |
| 670 |
Finally, the content provider updates the viewer, as directed by the |
| 671 |
notification.</p> |
| 672 |
|
| 673 |
<h3>Composed adapter factories</h3> |
| 674 |
|
| 675 |
<p>EMF models are often tied together by cross-model references. Whenever you |
| 676 |
need to build an application to edit or display objects that span more than one |
| 677 |
EMF model, you'll need an adapter factory capable of adapting the union of the |
| 678 |
objects from the two (or more) models.</p> |
| 679 |
|
| 680 |
<p>Often, you already have adapter factories for the individual models and all |
| 681 |
that you need is to glue them together. Another EMF.Edit convenience class, |
| 682 |
ComposedAdapterFactory, can be used for this purpose:</p> |
| 683 |
|
| 684 |
<img src="images/EMF.Edit/image009.gif" border="0" width="607" height="250" alt="Adapter factory composition"/> |
| 685 |
|
| 686 |
<p>A ComposedAdapterFactory is used to provide a common interface to other |
| 687 |
adapter factories, to which it simply delegates its implementation.</p> |
| 688 |
|
| 689 |
<p>To set up a composed adapter factory, you would write something like this: |
| 690 |
</p> |
| 691 |
|
| 692 |
<pre> |
| 693 |
model1AdapterFactory = ... |
| 694 |
model2AdapterFactory = ... |
| 695 |
|
| 696 |
ComposedAdapterFactory myAdapterFactory = new ComposedAdapterFactory(); |
| 697 |
myAdapterFactory.addAdapterFactory(model1AdapterFactory); |
| 698 |
myAdapterFActory.addAdapterFActory(model2AdapterFactory); |
| 699 |
|
| 700 |
myContentProvider = new AdapterFactoryContentProvider(myAdapterFactory); |
| 701 |
... |
| 702 |
</pre> |
| 703 |
|
| 704 |
<h2><a name="generator">Using the EMF.Edit Code Generator</a></h2> |
| 705 |
|
| 706 |
<p class="Note">Note: a step-by-step tutorial for generating an EMF model, as |
| 707 |
well as an EMF.Edit editor, can be found in |
| 708 |
<a href="../../tutorials/clibmod/clibmod.html">Tutorial: Generating an EMF |
| 709 |
Model</a>.</p> |
| 710 |
|
| 711 |
<p>Given an EMF model definition, the EMF.Edit code generator can produce a |
| 712 |
fully functional editor tool that will allow you to view instances of the model |
| 713 |
using several common viewers and to add, remove, cut, copy, and paste model |
| 714 |
objects, or modify the objects in a standard property sheet, all with full |
| 715 |
undo/redo support.</p> |
| 716 |
|
| 717 |
<p>The EMF.Edit generator produces complete working plug-ins that include the |
| 718 |
following:</p> |
| 719 |
|
| 720 |
<ol> |
| 721 |
<li>ItemProviderAdapterFactory</li> |
| 722 |
<li>ItemProviders (one per model class)</li> |
| 723 |
<li>Editor</li> |
| 724 |
<li>ModelWizard</li> |
| 725 |
<li>ActionBarContributor</li> |
| 726 |
<li>Plugin</li> |
| 727 |
<li>plugin.xml</li> |
| 728 |
<li>Icons</li> |
| 729 |
</ol> |
| 730 |
|
| 731 |
<p>Once generated, the editor should run. It will come up, but it may or may not |
| 732 |
be working as you expected (that is, the default choices that the generator made |
| 733 |
may have been inappropriate for your model). It should, however, be pretty easy |
| 734 |
to tweak the generated code in a few places to quickly get a basic working |
| 735 |
editor up and running.</p> |
| 736 |
|
| 737 |
<p>The following takes a closer look at some of the more interesting generated |
| 738 |
classes.</p> |
| 739 |
|
| 740 |
<h3>ItemProviderAdapterFactory</h3> |
| 741 |
|
| 742 |
<p>The generated ItemProviderAdapterFactory is a simple subclass of the |
| 743 |
generated AdapterFactory class that you got when you generated your EMF model. |
| 744 |
</p> |
| 745 |
|
| 746 |
<p class="Note">Note: the generated EMF adapter factory creates adapters by |
| 747 |
dispatching to a type-specific create() method that subclasses (like |
| 748 |
ItemProviderAdapterFactory) are required to override. The EMF adapter factory |
| 749 |
(for example, ABCAdapterFactory) uses another generated class, (ABCSwitch), to |
| 750 |
implement the dispatch efficiently.</p> |
| 751 |
|
| 752 |
<p>When using the Stateful pattern, the adapter factory create methods simply |
| 753 |
return a new object like this:</p> |
| 754 |
|
| 755 |
<pre> |
| 756 |
class ABCItemProviderAdapterFactory extends ABCAdapterFactoryImpl |
| 757 |
{ |
| 758 |
... |
| 759 |
public Adapter createCompanyAdapter() |
| 760 |
{ |
| 761 |
return new CompanyItemProvider(this); |
| 762 |
} |
| 763 |
... |
| 764 |
} |
| 765 |
</pre> |
| 766 |
|
| 767 |
<p>If, instead, the Singleton pattern is used, the adapter factory also keeps |
| 768 |
track of the singleton instance and returns it for each call:</p> |
| 769 |
|
| 770 |
<pre> |
| 771 |
protected DepartmentItemProvider departmentItemProvider; |
| 772 |
|
| 773 |
public Adapter createDepartmentAdapter() |
| 774 |
{ |
| 775 |
if (departmentItemProvider == null) |
| 776 |
{ |
| 777 |
departmentItemProvider = new DepartmentItemProvider(this); |
| 778 |
} |
| 779 |
return departmentItemProvider; |
| 780 |
} |
| 781 |
</pre> |
| 782 |
|
| 783 |
<h3>The ItemProvider classes</h3> |
| 784 |
|
| 785 |
<p>For each class in the model, a corresponding item provider class is |
| 786 |
generated. The generated item providers mix in all the interfaces needed to |
| 787 |
support the standard viewers, commands, and the property sheet:</p> |
| 788 |
|
| 789 |
<pre> |
| 790 |
public class DepartmentItemProvider extends ... |
| 791 |
implements |
| 792 |
IEditingDomainItemProvider, |
| 793 |
IStructuredItemContentProvider, |
| 794 |
ITreeItemContentProvider, |
| 795 |
IItemLabelProvider, |
| 796 |
IItemPropertySource |
| 797 |
{ |
| 798 |
... |
| 799 |
} |
| 800 |
</pre> |
| 801 |
|
| 802 |
<p>If a model class is a root (that is, it has no explicit base class) then the |
| 803 |
generated item provider will extend from the EMF.Edit item provider base class, |
| 804 |
ItemProviderAdapter:</p> |
| 805 |
|
| 806 |
<pre> |
| 807 |
public class EmployeeItemProvider extends ItemProviderAdapter ... |
| 808 |
</pre> |
| 809 |
|
| 810 |
<p>If, instead, the model class inherits from a base class, then the generated |
| 811 |
item provider will extend from the base item provider like this:</p> |
| 812 |
|
| 813 |
<pre> |
| 814 |
public class EmployeeItemProvider extends PersonItemProvider ... |
| 815 |
</pre> |
| 816 |
|
| 817 |
<p>For a multiply inheriting class, the generated item provider will extend from |
| 818 |
the first base class's item provider (as in the single inheritance case) and it |
| 819 |
will implement the provider function for the rest of the base classes.</p> |
| 820 |
|
| 821 |
<p>If you look at the generated item provider classes, you'll notice that a lot |
| 822 |
of their function is actually implemented in the item provider base class. The |
| 823 |
most important functions of the generated item provider subclasses are:</p> |
| 824 |
|
| 825 |
<ol> |
| 826 |
<li>Identifying the children and parent</li> |
| 827 |
<li>Setting up the property descriptors</li> |
| 828 |
<li>Passing on the "interesting" notification events.</li> |
| 829 |
</ol> |
| 830 |
|
| 831 |
<h3>Editor and ModelWizard</h3> |
| 832 |
|
| 833 |
<p>The generated Editor and ModelWizard show how to put all the other generated |
| 834 |
pieces together with standard JFace components to produce a working editor.</p> |
| 835 |
|
| 836 |
<p>The ModelWizard can be used to create new resources of the model's type. If |
| 837 |
instead, you already have a resource that was created some other way, you can |
| 838 |
import it into your desktop workspace and launch the editor on it, bypassing the |
| 839 |
ModelWizard completely.</p> |
| 840 |
|
| 841 |
<br/><hr noshade="noshade" size="1"/> |
| 842 |
|
| 843 |
<p><sup><a class="footnote" href="#ref1">[1]</a><a name="fn1"> </a></sup>Notifier |
| 844 |
is the base interface in EMF for objects that can register adapters and send |
| 845 |
notifications to them. It is extended by EObject, the base interface for all |
| 846 |
model objects.</p> |
| 847 |
|
| 848 |
<p><sup><a class="footnote" href="#ref2">[2]</a><a name="fn2"> </a></sup>Actually, |
| 849 |
EMF adapter factories are inheritance driven, so you can choose to use a base |
| 850 |
adapter to handle subclasses at any level in your model, EObject being the |
| 851 |
extreme case.</p> |
| 852 |
|
| 853 |
<p><sup><a class="footnote" href="#ref3">[3]</a><a name="fn3"> </a></sup>In |
| 854 |
addition to the adapter factory, which acts as the change notifier for viewers, |
| 855 |
an ItemProviderAdapter can also have other (direct) listeners which are also |
| 856 |
called in ItemProviderAdapter.fireNotifyChanged().</p> |
| 857 |
</body> |
| 858 |
</html> |