IBM Rational Software Modeler
Release 6.0

Package com.ibm.xtools.emf.msl

Modeling Services Layer (MSL).

See:
          Description

Interface Summary
IEObjectHelper An interface that provides various utility functions to manage and validate EObject and its proxies.
IOperationEvent An event that describes the notifications that are batched when an API executes.
IValidationStatus An extension of the Eclipse core status interface that provides additional information about the violation of a constraint during the validation of a model.
 

Class Summary
EditingDomain A class that exposes an editing domain in the modeling platform.
EventTypes A list of event types that the modeling platform supports.
OperationListener A listener to IOperationEvents.
ResourceSetModifyOperation A ResourceSetOperation whose execution can potentially modify models.
ResourceSetOperation An abstract base class for operations that an EditingDomain executes.
ResourceSetReadOperation A ResourceSetOperation whose execution can read models.
 

Package com.ibm.xtools.emf.msl Description

Modeling Services Layer (MSL). This package exposes classes and interfaces to manage Eclipse Modeling Framework (EMF) models.

Package Specification

This package fulfills two roles:

EMF-Based Model Management

EditingDomain is the central class that manages the EMF-based models that are manipulated by tools that are built on the modeling platform.

Model Access

EMF-based models typically persist in Resources. Each Resource that the EditingDomain manages is a member of the domain's ResourceSet. The ResourceSet is accessible from EditingDomain.getResourceSet.

To ensure proper concurrency support and notification batching, the EditingDomain must supervise access to and modification of models that are members of the EditingDomain's ResourceSet. Model access and modifications are implemented in ResourceSetOperations. To read or modify models, a client passes a ResourceSetReadOperation or a ResourceSetModifyOperation to EditingDomain.run, respectively.

The following example illustrates model read access:

	editingDomain.run( new ResourceSetReadOperation() {

		protected void execute(IProgressMonitor monitor)
			throws InvocationTargetException, InterruptedException {
			
			// Insert code to read the editing domain's models here
			...
		}
	}, new NullProgressMonitor());

The code that performs the read access is guaranteed that every model in the ResourceSet will remain unchanged for the duration of the operation.

The following example illustrates model modification access:

	editingDomain.run( new ResourceSetModifyOperation("MyOperationTitle") {

		protected void execute(IProgressMonitor monitor)
			throws InvocationTargetException, InterruptedException {
			
			// Insert code to modify the editing domain's models here
			...
		}
	}, new NullProgressMonitor());

The code that modifies the model has exclusive access to every model in the ResourceSet for the duration of the operation. The modeling platform automatically provides undo and redo support for any model modification that the operation performs. The title that is passed to ResourceSetModifyOperation appears on the Edit > Undo <title> and Edit > Redo <title> menus.

Notifications

The EditingDomain batches the notifications that operations issue. To receive these notifications, a client should register and unregister OperationListener through EditingDomain.addOperationListener and EditingDomain.removeOperationListener respectively.

An OperationListener is notified in three situations:

Each of these OperationListener methods receives an IOperationEvent parameter. Listeners can receive the list of notifications that were batched during an operation through IOperationEvent.getNotifications. Each item in the returned list is an instance of Notification or one of its derived classes. Notification.getEventType should be used to determine the exact nature of the change that this notification represents. EventTypes. exposes possible event types.

For nested operations, notifications are sent only after the outermost operation is completed.

If operations are executed from within an OperationListener.done implementation, the label that appears on the Edit > Undo <title> and Edit > Redo <title> menus remains the title of the ResourceSetModifyOperation at the root of the event chain. The title of the operation that the listener executes is not be used.

A ResourceSetModifyOperation should NEVER be executed from within implementations of OperationListener.undone or OperationListener.redone.

It is good practice to always assume that the title of a ResourceSetModifyOperation is used for user consumption, because the modeling platform cannot guarantee IOperationEvents are only sent as the result of a ResourceSetOperation. In this case, the title of the event listener's operation is used.

EObject, through its Notifier implementation, exposes an API to register listeners. This API should NEVER be used because the notifications that this API sends are not batched. Consequently, listeners could access a model that is in an inconsistent state, or could modify the model and break the contract with the running ResourceSetModifyOperation that stipulates exclusive access to the resources of the ResourceSet.

EObject Management

IEObjectHelper is a helper interface for using EObjects.

IEObjectHelper provides support for the following actions:


IBM Rational Software Modeler
Release 6.0


Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2004. All rights reserved.