Debian Codegraph @

doc/org.eclipse.emf.doc/references/overview/EMF.Edit.html

raw
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">&nbsp;</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 &quot;real&quot; (EMF) model objects whose
184 item providers also happen to be (EMF) adapters, and &quot;phantom&quot; 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 &quot;true&quot; 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">&nbsp;</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 &quot;editing&quot; to mean
310 undoable modification, as opposed to simple &quot;writing&quot; 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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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>