This package fulfills two roles:
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.
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.
IEObjectHelper provides support for the following actions: