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

{@link com.ibm.xtools.emf.msl.EditingDomain 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 {@link org.eclipse.emf.ecore.resource.Resource Resource}s. Each Resource that the EditingDomain manages is a member of the domain's {@link org.eclipse.emf.ecore.resource.ResourceSet ResourceSet}. The ResourceSet is accessible from {@link com.ibm.xtools.emf.msl.EditingDomain#getResourceSet 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 {@link com.ibm.xtools.emf.msl.ResourceSetOperation ResourceSetOperation}s. To read or modify models, a client passes a {@link com.ibm.xtools.emf.msl.ResourceSetReadOperation ResourceSetReadOperation} or a {@link com.ibm.xtools.emf.msl.ResourceSetModifyOperation ResourceSetModifyOperation} to {@link com.ibm.xtools.emf.msl.EditingDomain#run 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 {@link com.ibm.xtools.emf.msl.OperationListener OperationListener} through {@link com.ibm.xtools.emf.msl.EditingDomain#addOperationListener EditingDomain.addOperationListener} and {@link com.ibm.xtools.emf.msl.EditingDomain#removeOperationListener EditingDomain.removeOperationListener} respectively.

An OperationListener is notified in three situations:

Each of these OperationListener methods receives an {@link com.ibm.xtools.emf.msl.IOperationEvent IOperationEvent} parameter. Listeners can receive the list of notifications that were batched during an operation through {@link com.ibm.xtools.emf.msl.IOperationEvent#getNotifications IOperationEvent.getNotifications}. Each item in the returned list is an instance of {@link org.eclipse.emf.common.notify.Notification Notification} or one of its derived classes. {@link org.eclipse.emf.common.notify.Notification#getEventType Notification.getEventType} should be used to determine the exact nature of the change that this notification represents. {@link com.ibm.xtools.emf.msl.EventTypes 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 {@link com.ibm.xtools.emf.msl.OperationListener#done 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 {@link com.ibm.xtools.emf.msl.OperationListener#undone OperationListener.undone} or {@link com.ibm.xtools.emf.msl.OperationListener#redone 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 {@link org.eclipse.emf.common.notify.Notifier 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

{@link com.ibm.xtools.emf.msl.IEObjectHelper IEObjectHelper} is a helper interface for using {@link org.eclipse.emf.ecore.EObject EObject}s.

IEObjectHelper provides support for the following actions: