Introduction to Programming with DSF

Summary

Table of Contents

• 1 Introduction
• 2 Examples
• 3 Asynchronous Methods
  • 3.1 Request Monitor
  • 3.2 Data Request Monitor
  • 3. 3 Multi-Request Monitor
• 4 Concurrency
  • 4.1 Query
  • 4.2 Synchronization
  • 4.3 Annotations
• 5 Timers Example
• 6 Services
  • 6.1 OSGi
  • 6.2 Session
  • 6.3 Executor
  • 6.4 Tracker
  • 6.5 Initialization / Shutdown
  • 6.6 Events
• 7 Data Model
  • 7.1 IDMContext
  • 7.2 Context Hierarchy
  • 7.3 DMContexts
• 8 View Model
  • 8.1 Flexible Hierarchy
  • 8.2 Adapter Problem
  • 8.4 API
  • 8.5 Content Provider
  • 8.6 Model Event Proxy
  • 8.7 Property Provider / Label Provider
• 9 Next Steps

Copyright

• Wind River Systems - initial content
  

1 Examples

1. Download and install the Eclipse SDK 3.4 (http://download.eclipse.org/eclipse/downloads)
2. Install the Eclipse IDE for C/C++ 5.0:
   
1. Using Update Manager, install the C and C++ Development SDK, found in the Ganymede Discovery Site.
3. Install the DSF SDK feature to build against, by performing either:
   
1. Using update manager, install the Debugger Services Framework end-user and extender SDK, found in the Ganymede Discovery Site under Remote Access and Device Development.
2. Check out org.eclipse.dd.dsf and org.eclipse.dd.dsf.ui plugins, found in the /cvsroot/dsdp repository in the org.eclipse.dd.dsf/plugins directory.
4. Check out the org.eclipse.dd.examples.dsf plugin, found /cvsroot/dsdp under org.eclipse.dd.dsf/plugins directory.
5. Build the examples plugin:
1. Execute the build the first time to build and run the exercises preprocessor.
2. Refresh the resources in the plugin (right-click on project in Navigator and select Refresh), in order to recognize the sources generated by the preprocessor.
3. Build the plugin again to compile the generated sources.
6. Launch the examples
1. Examples in data org.eclipse.dd.examples.dsf.requestmonitor and org.eclipse.dd.examples.dsf.dataviewer packages each contain a public main() function.  They can be launched using the Java Application launch type.
2. The timers example in org.eclipse.dd.examples.dsf.timers requires an Eclipse Application to be launched (see the Timers Example section for more details).
   

2 Asynchronous Methods

2.1 Request Monitor

• Executor - A argument to the request monitor constructor allows the user to specify what executor should be used to invoke the callback method. 
  
• Status - Asynchronous methods that take a callback can always set the status indicating the success or failure of the call.
• Callback Methods - The request monitor declares several protected methods which are invoked when the callback is invoked: handleCompleted(), handleOK(), handleError(), etc.  The users may override these methods as needed to perform additional processing upon asynchronous method completion.
• Parent Request Monitor - If the method calling an asynchronous method is itself asynchronous, it may set its argument request monitor as the parent of the request monitor it is creating.  The parent request monitor will be automatically invoked when the lower level request monitor is completed.

 26: public class AsyncHelloWorld {

 28:     public static void main(String[] args) {
 29:         Executor executor = ImmediateExecutor.getInstance();
 30:         RequestMonitor rm = new RequestMonitor(executor, null);
 31:         asyncHelloWorld(rm);
 32:     }

 34:     static void asyncHelloWorld(RequestMonitor rm) {
 35:         System.out.println("Hello world");
 36:         rm.done();
 37:     }

• Line 29 creates an "immediate executor".  Unlike more sophisticated executors, the immediate executor simply invokes the runnable it receives immediately.  It does not use any threads and it will never throw a RejectedExecutionException.
• Line 30 creates the request monitor.  This program does not perform any processing after the callback is invoked, so it does not override RequestMonitor's completion methods.
• Line 36 marks the callback as completed and implicitly invokes the callback method.  As a contract with the caller, the asynchronous method has to invoke done() when its finished.  As there is no compiler support for ensuring that the asynchronous method completes the request monitor,  failure to do so results in common but often subtle and difficult to track down bug

Image 1: Sequence diagram of the AsyncHelloWorld example.

2.2 Data Request Monitor

 22: public class Async2Plus2 {
 23:     
 24:     public static void main(String[] args) {
 25:         Executor executor = ImmediateExecutor.getInstance();
 26:         DataRequestMonitor<Integer> rm = 
 27:             new DataRequestMonitor<Integer>(executor, null) {
 28:                 @Override
 29:                 protected void handleCompleted() {
 30:                     System.out.println("2 + 2 = " + getData());
 31:                 }
 32:             };
 33:         asyncAdd(2, 2, rm);
 34:     }

 36:     static void asyncAdd(int value1, int value2, DataRequestMonitor<Integer> rm) {
 37:         rm.setData(value1 + value2);
 38:         rm.done();
 39:     }
 40: }

• Lines 26-27 create the data request monitor using a local class declaraion.  Note the type parameter to DataRequestMonitor allows for compiler checking of the type when calling getData() and setData() methods.
• Lines 29-31 override the standard callback to print the result of the calculation to the console.
  

2.3 Multi-Request Monitor

 42:     static void asyncQuicksort(final int[] array, final int left, 
 43:         final int right, final RequestMonitor rm) 
 44:     {
 45:         if (right > left) {
 46:             int pivot = left;
 48:             int newPivot = partition(array, left, right, pivot);
 49:             printArray(array, left, right, newPivot);

 51:             CountingRequestMonitor countingRm = new CountingRequestMonitor(fgExecutor, rm);
 52:             asyncQuicksort(array, left, newPivot - 1, countingRm);
 53:             asyncQuicksort(array, newPivot + 1, right, countingRm);
 54:             countingRm.setDoneCount(2);
 55:         } else {
 56:             rm.done();
 57:         }
 58:     }

• Line 51 creates the CountingRequestMonitor.  Its parent request monitor is set to the request monitor from the asyncQuicksort() argument.  This parent request monitor is automatically called when the counting request monitor is completed. (see note)
  
• Lines 52 and 53, use the same instance of counting request monitor when calling the sub-routine.  Each sub-routine will call done() on the counting request monitor.
• Line 54 sets the count to the number of sub-routines called with the counting request monitor.  Note that the done count can be set after calling the sub-routines, because the counting request monitor will not be completed until the count is set.
  
• Line 55: Don't forget to complete the request monitor in all execution paths!

3 Concurrency

The IDataGenerator interface contains the following two asynchronous data access methods:

 49:  void getCount(DataRequestMonitor<Integer> rm);
 50:  void getValue(int index, DataRequestMonitor<String> rm); 

The example is intended to simulate a realistic problem therefore, it can be assumed that these methods do not complete the request monitor immediately, but rather that the requests are completed on a separate thread and with some delay.  There are two implementations of this service provided:

1. DataGeneratorWithThread - Uses a java thread directly and various synchronization mechanisms for data integrity.
   
2. DataGeneratorWithExecutor - Uses a DSF executor for both asynchronous execution and synchronization.

1. SyncDataViewer - Table-based viewer which implements a synchronous IStructuredContentProvider interface.
   
2. AsyncDataViewer - Table-based viewer which implements an asynchronous ILazyContentProvider interface.

3.1 Query

 59:         // Create the query object for reading data count. 
 60:         Query<Integer> countQuery = new Query<Integer>() {
 61:             @Override
 62:             protected void execute(DataRequestMonitor<Integer> rm) {
 63:                 fDataGenerator.getCount(rm);
 64:             }
 65:         };
 66:         
 67:         // Submit the query to be executed.  A query implements a runnable
 68:         // interface and it has to be executed in order to do its work.
 69:         ImmediateExecutor.getInstance().execute(countQuery);
 70:         int count = 0;
 71:         
 72:         // Block until the query completes, which will happen when the request
 73:         // monitor of the execute() method is marked done.
 74:         try {
 75:             count = countQuery.get();
 76:         } catch (Exception e) { 
 77:             // InterruptedException and ExecutionException can be thrown here.
 78:             // ExecutionException containing a CoreException will be thrown 
 79:             // if an error status is set to the Query's request monitor.
 80:             return new Object[0]; 
 81:         } 

• Line 60 creates the query object. 
  
• On line 63, inside the execute() method, the asynchronous getCount() method is called
• Line 69 submits the query to an executor.  This is very important, because a Query object simply implements Runnable, it will not perform the work in its exectute() method unless it is submitted to an executor. 
  
• Line 75 blocks while calling the java.util.concurrent.Future.get() method, implemented by Query, until the request monitor from the execute() method is completed.

Image 2: Detailed sequence of calling IDataGenerator.getCount() in SyncDataViewer.getElements().

3.2 Synchronization

174:     public void addListener(final Listener listener) {
175:         try {
176:             fExecutor.execute( new DsfRunnable() {
177:                 public void run() {
178:                     fListeners.add(listener);
179:                 }
180:             });
181:         } catch (RejectedExecutionException e) {}
182:     }

• Line 174 declares the addListener() method which can be called on any thread.
• Line 176 submits a local runnable to the DSF executor.
• Line 178 accesses the protected data: fListeners.

Image 3: Synchronization using multiple locks on data.	Image 4: Synchronization using a single DSF executor thread.

139:     public void run() {
140:         try {
141:             while(true) {
142:                 // Get the next request from the queue.  The time-out 
143:                 // ensures that that the random changes get processed. 
144:                 final Request request = fQueue.poll(100, TimeUnit.MILLISECONDS);
145:                 
146:                 // If a request was dequeued, process it.
147:                 if (request != null) {
148:                     // Simulate a processing delay.
149:                     Thread.sleep(PROCESSING_DELAY);
150:                     
151:                     if (request instanceof CountRequest) {
152:                         processCountRequest((CountRequest)request);
153:                     } else if (request instanceof ItemRequest) {
154:                         processItemRequest((ItemRequest)request);
155:                     } else if (request instanceof ShutdownRequest) {
156:                         // If shutting down, just break out of the while(true) 
157:                         // loop and thread will exit.
158:                         request.fRequestMonitor.done();
159:                         break;
160:                     }
161:                 }
162:                 
163:                 // Simulate data changes.
164:                 randomChanges();
165:             }
166:         }
167:         catch (InterruptedException x) {}
168:     } 

• Line 141 creates the loop that runs continuously until the break statement on line 159.
• Line 149 implements the artificial processing delay that is executed for each request.

In contrast the executor-based generator uses a dedicated method for servicing the queue, which is called by every method that adds a new request to the queue:

197:     private void serviceQueue() {
...
201:         // If a queue servicing is already scheduled, do nothing.
202:         if (fServiceQueueInProgress) {
203:             return;
204:         }
205:         
206:         if (fQueue.size() != 0) {
207:             // If there are requests to service, remove one from the queue and 
208:             // schedule a runnable to process the request after a processing
209:             // delay.
210:             fServiceQueueInProgress = true;
211:             final Request request = fQueue.remove(0);
212:             fExecutor.schedule(
213:                 new DsfRunnable() {
214:                     public void run() {
215:                         if (request instanceof CountRequest) {
216:                             processCountRequest((CountRequest)request);
217:                         } else if (request instanceof ItemRequest) {
218:                             processItemRequest((ItemRequest)request);
219:                         } 
220:                         
221:                         // Reset the processing flag and process next
222:                         // request.
223:                         fServiceQueueInProgress = false;
224:                         serviceQueue();
225:                     }
226:                 }, 
227:                 PROCESSING_DELAY, TimeUnit.MILLISECONDS);
228:         }
229:     }

• On line 202, the fServiceQueueInProgress flag is used to ensure that the queue servicing runnable is not scheduled too often.
• Line 211 removes the top request from the queue.
  
• Line 212 calls the ExecutorService.schedule() method to run the queue servicing runnable, with a delay that simulates the request processing time.
• Line 224, after servicing runnable is finished, calls serviceQueue() again to process the next item in the queue.

3.3 Annotations

DSF synchronization annotations defined in org.eclipse.dd.dsf.concurrent

• ThreadSafe - Indicates that the given element can be accessed on any thread.  Typically, if this annotation is used, the given member or class uses synchronized or atomic objects to protect its data.
• Immutable - Immutable objects cannot be modified after they are created, thus they are also thread-safe.  The easiest way to make an object immutable, is to declare all its fields final and make sure that its fields are also immutable.  Examples of immutable objects are Java Strings, primitive object types, etc.
• ConfinedToDsfExecutor(executor) - Indicates that the given object can only be accessed using the given executor.  The executor parameter is a string (since that's the only allowable parameter type to annotations), but it should indicate the executor, using classe's member and method names.
• ThreadSafeAndProhibitedFromDsfExecutor(executor) - Rarely used, it indicates that the given element can be accessed on any thread except using the given executor.  An example of such a method would be the SyncDataViewer.getElements() method, which should never be called using the executor belonging to the data provider.
  

4 Timers Example

Timer example defines the following two services:

• TimerService - This service manages a set of timers where each timer's value is incremented every second.  The timer service contains the following features:
  
• startTimer() method - Allows user to create a new timer.  It returns the Data Model context for the new timer.
  
• killTimer() method - Allows the user to delete the given timer.  It requires a timer context.
  
• getTimers() method - Returns the array of contexts for existing timers.
  
• getTimerValue() method - Returns the current value for the given timer context.
  
• TimerTickDMEvent event class - An event that is generated for every timer, every time its value changes (once per second).  The event contains the timer's context.
  
• AlarmService - This service manages a set of triggers and alarms.  Triggers can be created and destroyed independently.  Alarms represent a timer and a trigger combined.  The Alarm service has the following features:
• createTrigger() method - Creates a new trigger with a given value.  It returns a context to the new trigger.
  
• deleteTrigger() method - Deletes the trigger for the given context.
  
• setTriggerValue() method - Sets the value of a trigger to the given value.
  
• getAlarm() method - Gets the alarm for the specified timer and trigger contexts.  It returns an alarm context object.
  
• AlarmTriggeredDMEvent event class - An event that is generated for every timer that trips the given trigger by surpassing its value.  The event contains an alarm context.
  

Image 5: Screen shot of the Timers view.

• New Timer action - Adds a new timer, which immediately shows up in the view.
• New Trigger action - Opens a dialog where the user enters the value of the new trigger.  Upon OK, the dialog creates a new trigger that is added to the view.
• Remove action - Removes a timer or a trigger, whichever is currently selected in the viewer.
  
• Toggle Layout action - Switches the hierarchy in the tree to either Timers->Triggers->Alarm or Triggers->Timers->Alarm
• Edit Trigger Value cell editor - changes the value of the selected trigger.
  

5 Services

5.1 OSGi

• Registration - Services need to register and unregister themselves with OSGi framework
• BundleContext.registerService() - registers a service, it returns a ServiceRegistration object which should be retained by the caller.
• ServiceRegistration.unregister() - unregisters a service.
• References - Clients wishing to use a service, need to obtain a reference to the service.  OSGi features reference counting for services.
• BundleContext.getServiceReference(), BundleContext.getServiceReferences(), BundleContext.getAllServiceReferences() - methods for retrieving a reference to a service using a class name and/or a property filter.
• BundleContext.ungetService() - Releases a service reference and decrements its use count.
• Events - Clients using services should listen to service events.  Events are issued when services are added/removed/modified.
• org.osgi.framework.ServiceListener - interface for a service listener.  Objects implementing this interface can be registered with the BundleContext

5.2 Session

DSF Session features include:

• Unique Session ID - This ID is used to distinguish services from different sessions.  Clients may also obtain a session instance using an ID through a static method.
  
• Session Life cycle Events - Clients may register to listen when sessions are started and ended.
  
• DSF Executor - Each session has a (single-threaded) DSF Executor  associated with it, though multiple sessions could share a single executor.  More about session executor in the next section.
• Service Events - The session is used to dispatch service events.  More on events in following sections.
• Model Adapters - A session allows an adapter to be registered, which will be returned by all Data Model contexts in a given session for a given adapter type.  More information about Data Model is described in the Data Model section.
  

5.3 Executor

5.4 Tracker

5.5 Initialization / Shutdown

Starting up a large number of DSF services requires calling a number of asynchronous method in a pre-defined sequence.  Implementing this startup code can be cumbersome and DSF provides a utility for implementing it: org.eclipse.dd.dsf.concurrent.Sequence. 

Here's an example of how the Sequence is extended to perform the task of shutting down the services in the Timers example:

 25: public class ServicesShutdownSequence extends Sequence {

 27:     // Session to that the services are running in.
 28:     final private DsfSession fSession;
 29:     
 30:     // DSF Services is created as the first step of the sequence.  It 
 31:     // cannot be created by the constructor because it can only be called
 32:     // in the session thread.
 33:     DsfServicesTracker fTracker;

 35:     public ServicesShutdownSequence(DsfSession session) {
 36:         super(session.getExecutor());
 37:         fSession = session;
 38:     }
 39:     
 40:     Step[] fSteps = new Step[] {
 41:         new Step() { 
 42:             @Override
 43:             public void execute(RequestMonitor requestMonitor) {
 44:                 fTracker = new DsfServicesTracker(DsfExamplesPlugin.getBundleContext(), fSession.getId());
 45:                 requestMonitor.done();
 46:             }
 47:             
 48:             @Override
 49:             public void rollBack(RequestMonitor requestMonitor) {
 50:                 // Dispose the tracker in case shutdown sequence is aborted
 51:                 // and is rolled back.
 52:                 fTracker.dispose();
 53:                 fTracker = null;
 54:                 requestMonitor.done();
 55:             } 
 56:         },
 57:         new Step() { 
 58:             @Override
 59:             public void execute(RequestMonitor requestMonitor) {
 60:                 shutdownService(AlarmService.class, requestMonitor);
 61:             }
 62:         },
 63:         new Step() { 
 64:             @Override
 65:             public void execute(RequestMonitor requestMonitor) {
 66:                 shutdownService(TimerService.class, requestMonitor);
 67:             }
 68:         },
 69:         new Step() { 
 70:             @Override
 71:             public void execute(RequestMonitor requestMonitor) {
 72:                 // Dispose the tracker after the services are shut down.
 73:                 fTracker.dispose();
 74:                 fTracker = null;
 75:                 requestMonitor.done();
 76:             }
 77:         }
 78:     };
 79:     
 80:     @Override
 81:     public Step[] getSteps() { return fSteps; }

 83:     // A convenience method that shuts down given service.  Only service class 
 84:     // is used to identify the service. 
 85:     private <V extends IDsfService> void shutdownService(Class<V> clazz, RequestMonitor requestMonitor) {
 86:         IDsfService service = fTracker.getService(clazz);
 87:         if (service != null) {
 88:             service.shutdown(requestMonitor);
 89:         }
 90:         else {
 91:             requestMonitor.setStatus(new Status(
 92:                 IStatus.ERROR, DsfExamplesPlugin.PLUGIN_ID, 
 93:                 IDsfService.INTERNAL_ERROR,  
 94:                 "Service '" + clazz.getName() + "' not found.", null));             
 95:             requestMonitor.done();
 96:         }
 97:     }
 99: }

• Line 40 initializes an array of Step objects which are invoked by the Sequence logic.  Each Step class is an inner class with access to
  shared data in the ServicesShutdownSequence class.
• Line 81 implements the protected method used by the Sequence class to access the steps.
• Line 85 encapsulates the repetitive logic of finding and shutting down a given service.
• Line 73 disposes the DsfServicesTracker used by the sequence.

Below is the code snipped that invokes the ServicesShutdownSequence in the Timers example:

181:             ServicesShutdownSequence shutdownSeq = 
182:                 new ServicesShutdownSequence(fSession);
183:             fSession.getExecutor().execute(shutdownSeq);
184:             try {
185:                 shutdownSeq.get();
186:             } catch (InterruptedException e) { assert false;
187:             } catch (ExecutionException e) { assert false;
188:             }

• Line 183 submits the sequence to the session executor. 
  
• Line 185 calls the Future.get() method of the sequence to block the calling thread until the sequence completes.

5.6 Events

To generate an event a service must:

1. Call DsfSession.dispatchEvent(Object event, Dictionary<String, String> serviceProperties) method.  The second parameter allows service listeners to filter events using specific service properties.

1. Declare a public event listener method (method name is not important), which takes an event parameter. The type of the event parameter depends on the event, where the listener will receive all service events which can be cast to the declared type.  A second optional parameter of type Dictionary<String, String> allows the event listener to examine the properties of the service that is sending the event.
2. Add itself as a service event listener by calling DsfSession.addServiceEventListener().

6 Data Model

6.1 IDMContext

What a Data Model context is:

• It is hierarchical.  Contexts can have other contexts as parents.  The hierarchy of contexts in a given system roughly defines that system's overall Data Model.  More on context hierarchy
  
• It extends the org.eclipse.core.runtime.IAdaptable interface.  This allows decorators, retargetable actions, etc. to be associated with a context.
• It is associated with a single DSF session.  The IDMContext.getSessionID() returns the session ID of the given context.  This allows all clients to get a handle on the session and the executor needed to access the DSF services that the context originated from.
  
• It is thread safe. This allows context objects to be stored and compared in viewers, caches, and other clients which may implement their own threading model.
  
• It is light-weight and preferably immutable. This allows contexts to be stored by clients that may persist beyond the life of the services that originated them.  If a context holds references to a lot of data or it may prevent that data from being garbage collected.

• It is NOT a reference to a service.  Context should not return a reference to a service directly because clients should use the appropriate OSGi APIs to obtain references to DSF services. 
  
• It is NOT persistable.  Since a context returns a context ID, it is valid only for the life of a single DSF session. 

6.2 Context Hierarchy

The use of the context hierarchy may be best explained with use of the Timers example.  In the timers example there are three contexts that are used:

1. Timer - no parent contexts
   
2. Trigger - no parent contexts
   
3. Alarm - requires both a timer and a trigger as parent contexts

209:     public boolean isAlarmTriggered(AlarmDMContext alarmCtx) {
210:         // Extract the timer and trigger contexts.  They should always be part 
211:         // of the alarm.
212:         TimerService.TimerDMContext timerCtx = DMContexts.getAncestorOfType(
213:             alarmCtx, TimerService.TimerDMContext.class);
214:         TriggerDMContext triggerCtx = DMContexts.getAncestorOfType(
215:             alarmCtx, TriggerDMContext.class);

217:         assert triggerCtx != null && timerCtx != null;

219:         // Find the trigger and check whether the timers value has surpassed it. 
220:         if (fTriggers.containsKey(triggerCtx)) {
221:             int timerValue = getServicesTracker().getService(TimerService.class).
222:                 getTimerValue(timerCtx);
223:             
224:             return timerValue >= fTriggers.get(triggerCtx);
225:         }
226:         
227:         return false;
228:     }

• Lines 212 and 214 search the context hierarchy of the alarm context for the timer and trigger contexts. 
  

6.3 DMContexts

• getAncestorOfType() - Searches for a context of a specific type in the hierarchy of the given context.
• isAncestorOf() - Checks whether the one of the argument contexts is in the hierarchy of the other.
• toList() - Converts all the contexts in a hierarchy of the give context into a list.

7 View Model

7.1 Flexible Hierarchy

1. There are provider interfaces for every aspect of data presentation in the viewer (content, label, columns, etc.). 
   
2. The provider interfaces are retrieved by the viewer for each element in the viewer.  This allows the view content to be populated from multiple sources.
3. Provider interfaces are asynchronous. 
   

7.2 Adapter Problem

Image 6: Diagram illustrating problem of multiple views sharing a single element, when using the adapter mechanism.

Image 7: Diagram illustrating use of wrappers to allow different adapters to be associated with the same element, for use with different views.

7.3 API

1. IVMAdapter - The adapter is the top-level object in the view model hierarchy. It implements some of the flexible hierarchy provider interfaces and it is returned by the elements as the single adapter implementing those interfaces  The main function the VM Adapter is to redirect the provider requests based on the view ID that the requests originated from.
   
2. IVMProvider - In the View Model hierarchy, the provider object supplies view content for a single view.
3. IVMNode - The node allows for grouping of like-elements in the view.  Examples of such nodes are: threads node, stack frames node, variables node, etc.
4. IVMContext - The VM Context is the interface of the wrapper objects that are held by the flexible hierarchy viewers.  The context holds a reference to the element that is being wrapped, as well as to the VM Node and VM Adapter that it originated from.
   

7.4 Content Provider

 20: public interface IElementContentProvider {

 22:         /**
 23:          * Updates the number of children for the given parent elements in the
 24:          * specified requests.
 25:          * 
 26:          * @param updates Each update specifies an element to update and provides
 27:          *  a store for the result.  The update array is guaranteed to have at least 
 28:          *  one element, and for all updates to have the same presentation context.
 29:          */
 30:         public void update(IChildrenCountUpdate[] updates);
 31:         
 ...
 39:         public void update(IChildrenUpdate[] updates);
 40:         
 ...
 48:         public void update(IHasChildrenUpdate[] updates);
 49:         
 50: }

 23: public interface IViewerUpdate extends IRequest {

 25:     /**
 26:      * Returns the context this update was requested in.
 27:      * 
 28:      * @return context this update was requested in
 29:      */
 30:     public IPresentationContext getPresentationContext();
 31:     
 32:     /**
 33:      * Returns the model element associated with this request.
 34:      * 
 35:      * @return associated model element
 36:      */
 37:     public Object getElement();
 38:     
 39:     /**
 40:      * Returns the viewer tree path to the model element associated with this
 41:      * request. An empty path indicates a root element.
 42:      * 
 43:      * @return tree path, possibly empty
 44:      */
 45:     public TreePath getElementPath();
 46:     
 47:     /**
 48:      * Returns the element that was the viewer input at the time the
 49:      * request was made, possibly <code>null</code>.
 50:      * 
 51:      * @return viewer input element, possibly <code>null</code>
 52:      */
 53:     public Object getViewerInput();
 54: }

1. VM Adapter receives the update request.  For example the update(IChildrenUpdate[]) method is called by a viewer.
2. VM Adapter retrieves the ID in the IPresentationContext object associated with the update.
3. VM Adapter finds the VM Provider that is assigned for that presentation context, creating it if necessary.
4. VM Provider finds and calls the VM Node (or nodes) that should process the given update. 
   
5. VM Node retrieves fills the data in the update and marks it as completed.

 86:     protected void updateElementsInSessionThread(final IChildrenUpdate update) {
 87:         if (!checkService(AlarmService.class, null, update)) return;

 89:         // Retrieve the timer DMContexts, create the corresponding VMCs array, and 
 90:         // set them as result.
 91:         TimerDMContext[] timers = 
 92:             getServicesTracker().getService(TimerService.class).getTimers();
 93:         fillUpdateWithVMCs(update, timers);
 94:         update.done();
 95:     }

• Lines 91-92 retrieve the Data Model contexts from the service.
• Line 93 calls a convenience method which creates VM Context wrappers for each element in the timers array, and sets those VM Contexts to the update.
• Line 94 completes the update.
  

7.5 Model Event Proxy

1. An root element is added into the view.  The root element could be the view input or another element which is designated as the root of a model hierarchy.
2. The viewer gets the IModelProxyFactory adapter from the element.
3. The viewer calls IModelProxyFactory.createModelProxy() which returns the IModelProxy instance.
4. The viewer adds itself as a listener to model events with the model proxy object.
5. The model proxy notifies its listeners (including the viewer) with model deltas whenever the model has changed.
6. When the root element is removed from the viewer, the viewer disposes the model proxy.
   

Event handling in VM Provider

The following listing from the Timers example shows the handling of a model event:

108:     @DsfServiceEventHandler
109:     public void eventDispatched(final TimersChangedEvent event) {
110:         if (isDisposed()) return;

112:         try {
113:             getExecutor().execute(new Runnable() {
114:                 public void run() {
115:                     if (isDisposed()) return;
116:                     handleEvent(event);
117:                 }
118:             });
119:         } catch (RejectedExecutionException e) {}
120:     }

• Line 108 declares the eventDispatched() method as a service event handler.
• Line 113 switches execution to the View Model executor thread.  The event handler is called on the session executor thread, however the standard View Model implementation classes have their own single-threaded executor which is used to protect its state.
• Line 116 calls the AbstractVMProvider.handleEvent() protected method which continues the event processing.
  

Processing events in VM Nodes

141:     public int getDeltaFlags(Object e) {
142:         // This node generates delta if the timers have changed, or if the 
143:         // label has changed.
144:         if (e instanceof TimerService.TimerTickDMEvent) {
145:             return IModelDelta.STATE;
146:         } else if (e instanceof TimerService.TimersChangedEvent) {
147:             return IModelDelta.CONTENT;
148:         }
149:         return IModelDelta.NO_CHANGE;
150:     }

152:     public void buildDelta(Object e, VMDelta parentDelta, int nodeOffset, RequestMonitor requestMonitor) {
153:         if (e instanceof TimerService.TimerTickDMEvent) {
154:             // Add delta indicating that the given timer has changed.
155:             parentDelta.addNode( createVMContext(((TimerService.TimerTickDMEvent)e).getDMContext()), IModelDelta.STATE );
156:         } else if (e instanceof TimerService.TimersChangedEvent) {
157:             // The list of timers has changed, which means that the parent 
158:             // node needs to refresh its contents, which in turn will re-fetch the
159:             // elements from this node.
160:             parentDelta.setFlags(parentDelta.getFlags() | IModelDelta.CONTENT);
161:         }
162:         requestMonitor.done();
163:     }

• Lines 141 declares the getDeltaFlags() method, which tells the event processing logic what flags if any can be generated by the given node for the given event.  Depending on its return value, the event processing logic may or may not call the buildDelta() method.
• Lines 144-148 return appropriate flags for the events that this node can process.
• Lines 153-155 process the TimerTickEvent. They add a delta element corresponding to the changed timer instructing the viewer to repaint this timer.
• Lines 156-160 process the TimersChangedEvent.  They add a flag to the parent delta element, instructing it to refresh all the elements managed by this node.
  

7.6 Property Provider / Label Provider

Below is the listing from the Timers VM Node that configures the label provider:

 53:     private static final PropertyBasedLabelProvider fgLabelProvider;
 54:     static {
 55:         fgLabelProvider = new PropertyBasedLabelProvider();

 57:         LabelColumnInfo idCol = new LabelColumnInfo(
 58:             new LabelAttribute[] { 
 59:                 new LabelText(new MessageFormat("Timer #{0}"), 
 60:                     new String[] { PROP_TIMER_NUMBER }), 
 61:                 new LabelImage(DsfExamplesPlugin.getDefault().getImageRegistry().
 62:                     getDescriptor(DsfExamplesPlugin.IMG_ALARM))
 63:             });
 64:         fgLabelProvider.setColumnInfo(TimersViewColumnPresentation.COL_ID, idCol);
 65:         
 66:         LabelColumnInfo valueCol = ...
 ...
 74:     }

• Line 55 creates the label provider.
• Lines 58-62 create the display attributes to use in the Name column.  These attributes use named properties as parameters in calculating the data, such as the label string.
• Line 64 registers the column info object with the label provider.

 98:     public void update(final IPropertiesUpdate[] updates) {
 99:         // Switch to the session thread before processing the updates.
100:         try {
101:             getSession().getExecutor().execute(new DsfRunnable() {
102:                 public void run() {
103:                     for (IPropertiesUpdate update : updates) {
104:                         updatePropertiesInSessionThread(update);
105:                     }
106:                 }});
107:         } catch (RejectedExecutionException e) {
108:             for (IViewerUpdate update : updates) {
109:                 handleFailedUpdate(update);
110:             }
111:         }
112:     }

114:     @ConfinedToDsfExecutor("getSession#getExecutor")
115:     private void updatePropertiesInSessionThread(final IPropertiesUpdate update) {
116:         // Find the timer context in the element being updated
117:         final TimerDMContext dmc = findDmcInPath(
118:             update.getViewerInput(), update.getElementPath(), TimerDMContext.class);
119:         
120:         // If either update or service are not valid, fail the update and exit.
121:         if (!checkDmc(dmc, update) || 
122:             !checkService(TimerService.class, null, update)) 
123:         {
124:            return;
125:         }
126:         
127:         TimerService timerService = 
128:             getServicesTracker().getService(TimerService.class, null);
129:         int value = timerService.getTimerValue(dmc);
130:         
131:         if (value == -1) {
132:             handleFailedUpdate(update);
133:             return;
134:         }

136:         update.setProperty(PROP_TIMER_NUMBER, dmc.getTimerNumber());
137:         update.setProperty(PROP_TIMER_VALUE, value);
138:         update.done();
139:     }

• Lines 98-112 handle switching into the session executor thread.
• Lines 117-118 call a convenience method to extract the Data Model timer context from the viewer update.  Normally this requires casting the object returned by IViewerUpdate.getElement() to the expected VM Context class.  Then extracting the model object from the VM Context wrapper.
• Line 127 retrieves element data from the service.
• Lines 136-137 write the element properties into the property update.

8 Next Steps