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 org.eclipse.gmf.runtime.emf.core.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 org.eclipse.gmf.runtime.emf.core.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 org.eclipse.gmf.runtime.emf.core.ResourceSetOperation ResourceSetOperation}s. To read or modify models, a client passes a {@link org.eclipse.gmf.runtime.emf.core.ResourceSetReadOperation ResourceSetReadOperation} or a {@link org.eclipse.gmf.runtime.emf.core.ResourceSetModifyOperation ResourceSetModifyOperation} to {@link org.eclipse.gmf.runtime.emf.core.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 org.eclipse.gmf.runtime.emf.core.OperationListener OperationListener} through {@link org.eclipse.gmf.runtime.emf.core.EditingDomain#addOperationListener EditingDomain.addOperationListener} and {@link org.eclipse.gmf.runtime.emf.core.EditingDomain#removeOperationListener EditingDomain.removeOperationListener} respectively.

An OperationListener is notified in three situations:

Each of these OperationListener methods receives an {@link org.eclipse.gmf.runtime.emf.core.IOperationEvent IOperationEvent} parameter. Listeners can receive the list of notifications that were batched during an operation through {@link org.eclipse.gmf.runtime.emf.core.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 org.eclipse.gmf.runtime.emf.core.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 org.eclipse.gmf.runtime.emf.core.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 org.eclipse.gmf.runtime.emf.core.OperationListener#undone OperationListener.undone} or {@link org.eclipse.gmf.runtime.emf.core.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 org.eclipse.gmf.runtime.emf.core.IEObjectHelper IEObjectHelper} is a helper interface for using {@link org.eclipse.emf.ecore.EObject EObject}s.

IEObjectHelper provides support for the following actions: