org.eclipse.stp.core.infrastructure.emf
Interface IEditModelScribbler


public interface IEditModelScribbler

The IEditModelScribbler provides a mechanism to modify, save or revert a set of EMF resources as a single atomic unit.

IEditModelScribblers describe the resources they are interested by one or more IEdtingDomains. The set of IScribblerDomains are specified when the IEditngModelScribbler is created from an IEditModel.createScribbler(IScribblerDomain[], boolean). The IEditModelScribbler may be used to create resources, acquire resources, or delete resources.

The IEditModelScribbler also serves as the IUndoContext for any operations that are executed against the org.eclipse.core.commands.operations.IOperationHistory. The IUndoContext is determined by the set of IScribblerDomains used to create the IEditModelScribbler.

What this means is that if two IEditModelScribblers are created on the same set of IScribblerDomains, the IEditModel will have a reference count for each current IEditModelScribbler (remember there are two instances in this example), and operations executed against one IEditModelScribbler (serving as the IUndoContext) will be undoable in the "context" of the other IEditModelScribbler.

This behavior is important for cases where an editor spawns a wizard or an operation that creates an IEditModelScribbler on the same IScribblerDomain(s) as the editor. The operation's IEditModelScribbler will be an equivalent IUndoContext, so if the user requests an undo of the last undoable operation just after the operation completes, then the IUndoContext of the editor will match that of the operation, and the operation will be undone.


Field Summary
static int OPTION_LOAD_AS_READ_ONLY
           
static int OPTION_LOAD_RESOURCE
           
static int OPTION_NONE
           
 
Method Summary
 void close(IProgressMonitor monitor)
          Close the resources described by this IEditModelScribbler's IScribblerDomains.
 Resource createResource(IResourceDescriptor aResourceDescriptor, IProgressMonitor monitor)
          Creates a new Resource based on the ResourceDescriptor, adds it to the underlying ResourceSet, indicates that it should be tracked by the underlying IEditModel, and returns it for use.
 ITechnologyFlavor createTechnologyFlavor(java.lang.String technologyFlavorLifecycleId, IAdaptable input)
          Return a TechnologyFlavor that can be used to manage model elements associated with a particular technology not modeled as EMF.
 boolean deleteResource(IResourceDescriptor aResourceDescriptor, IProgressMonitor monitor)
          A deleted resource will only be removed from disk once save() is invoked.
 void discard(IProgressMonitor monitor)
          Discard changes in the resources described by this IEditModelScribbler's IScribblerDomains.
 IStatus execute(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable args)
          Provides a convenience method for supplying and operation with the correct context, executing an operation, and adding it to the IOperationHistory managed by the IEditModel for this IEditModelScribbler.
 void flushOperationHistory(IProgressMonitor monitor)
          Flushes the operation history for this IEditModelScribbler.
 Resource getResource(IPath aWorkspaceRelativePath)
          Return a Resource based on an IPath.
 Resource getResource(IPath aWorkspaceRelativePath, int options)
          Return a Resource based on an IPath.
 java.util.Set getScribblerDomains()
          Return an unmodifiable set of IScribblerDomains Implemented.
 Resource[] getSortedResources()
          Resources returned sorted by XMI first, then XML.
 IUndoContext getUndoContext()
          Returns the IUndoContext for this IEditModelScribbler which can be used to associate all operations with this scribbler which are executed on data managed by the scribbler.
 IHumanInteractionController getUserInterfaceController()
          Return the IUserInterfaceController currently set.
 boolean isDirty()
          Implemented.
 boolean isReadOnly()
          Implemented.
 boolean matches(IUndoContext context)
           This IUndoContext is equivalent to all other IEditModelScribblers who contain an equivalent set of IScribblerDomains.
 IStatus redo(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable args)
          Provides a convenience method for supplying and operation with the correct context, executing an operation, and adding it to the IOperationHistory managed by the IEditModel for this IEditModelScribbler.
 IStatus redoLast(IProgressMonitor monitor, IAdaptable args)
          Requests the last operation that can be undone for the IUndoContext supplied by this IEditModelScribbler.
 void revert(IProgressMonitor monitor)
          Revert all of the resources described by the set of IScribblerDomains used by this IEditModelScribbler.
 void save(boolean force, IProgressMonitor monitor)
          Persist all changes from the set of resources described by the IScribblerDomains.
 void setUserInterfaceController(IHumanInteractionController userInterfaceController)
          A UserInterfaceController should be provided that allows the IEditModelScribbler to prompt the user for advice when necessary.
 IStatus undo(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable args)
          Provides a convenience method for supplying and operation with the correct context, executing an operation, and adding it to the IOperationHistory managed by the IEditModel for this IEditModelScribbler.
 IStatus undoLast(IProgressMonitor monitor, IAdaptable args)
          Requests the last operation that can be undone for the IUndoContext supplied by this IEditModelScribbler.
 

Field Detail

OPTION_NONE

static final int OPTION_NONE
See Also:
Constant Field Values

OPTION_LOAD_RESOURCE

static final int OPTION_LOAD_RESOURCE
See Also:
Constant Field Values

OPTION_LOAD_AS_READ_ONLY

static final int OPTION_LOAD_AS_READ_ONLY
See Also:
Constant Field Values
Method Detail

getScribblerDomains

java.util.Set getScribblerDomains()
Return an unmodifiable set of IScribblerDomains Implemented.

Returns:
An unmodifiable set of IScribblerDomain

getResource

Resource getResource(IPath aWorkspaceRelativePath)
Return a Resource based on an IPath. The Resource should already exist. The path should be a fully-qualified workspace relative path to a file. Using this method will always result in a Resource object being created, even if no physical file exists for it on disk. Implemented.

Parameters:
aUri -
Returns:

getResource

Resource getResource(IPath aWorkspaceRelativePath,
                     int options)
Return a Resource based on an IPath. The Resource should already exist. If OPTION_LOAD_RESOURCE is used, then the a Resource object will always be created, even if no physical file exists for it on disk.

The options could specify OPTION_LOAD_RESOURCE, OPTION_NONE, OPTION_LOAD_AS_READ_ONLY. This pattern of using an integer bitmask for extensibility and evolution of an API is consistent with the Eclipse Platform.

Implemented.

Parameters:
aDescriptor -
options - One of OPTION_LOAD_RESOURCE or OPTION_NONE
Returns:

getSortedResources

Resource[] getSortedResources()
Resources returned sorted by XMI first, then XML. NOT Implemented.


createResource

Resource createResource(IResourceDescriptor aResourceDescriptor,
                        IProgressMonitor monitor)
Creates a new Resource based on the ResourceDescriptor, adds it to the underlying ResourceSet, indicates that it should be tracked by the underlying IEditModel, and returns it for use. NOT Implemented.

Parameters:
aResourceDescriptor -
Returns:

deleteResource

boolean deleteResource(IResourceDescriptor aResourceDescriptor,
                       IProgressMonitor monitor)
                       throws EditModelException
A deleted resource will only be removed from disk once save() is invoked. If a call to deleteResource() is not followed at some point by a call to save(), then the resource will not be deleted. Calling revert() will forget the call to deleteResource(). Implemented.

Parameters:
aResourceDescriptor -
monitor -
Returns:
Throws:
EditModelException

close

void close(IProgressMonitor monitor)
           throws EditModelException
Close the resources described by this IEditModelScribbler's IScribblerDomains. If there are unsaved changes in any of the resources, the user will be prompted to save or discard those changes. PARTIALLY Implemented.

Throws:
EditModelException

discard

void discard(IProgressMonitor monitor)
             throws EditModelException
Discard changes in the resources described by this IEditModelScribbler's IScribblerDomains. No changes will be persisted and the underlying resources that have been modified will be reverted. This IEditModelScribbler will no longer be usable after a call to discard().

This method will force requests to deleteResource() to be forgotten.

NOT Implemented.

Throws:
EditModelException

save

void save(boolean force,
          IProgressMonitor monitor)
          throws EditModelException
Persist all changes from the set of resources described by the IScribblerDomains. Changes in similar or related resources from the underlying IEditModel not described by this IEditModelScribbler's IScribblerDomains will not be persisted.

This method will also persist any requests to delete resource (from deleteResource()).

Implemented.

Parameters:
force - Specifies whether the save should be forced if other IEditModelScribblers existing on the set of IScribblerDomains in use by this IEditModelScribbler.
Throws:
EditModelException

revert

void revert(IProgressMonitor monitor)
            throws EditModelException
Revert all of the resources described by the set of IScribblerDomains used by this IEditModelScribbler.

This method will force requests to deleteResource() to be forgotten.

Implemented.

Throws:
EditModelException

isDirty

boolean isDirty()
Implemented.

Returns:
True if any of the interesting resources have been modified but not saved.

isReadOnly

boolean isReadOnly()
Implemented.

Returns:
True if the scribbler is loaded as read-only

matches

boolean matches(IUndoContext context)
This IUndoContext is equivalent to all other IEditModelScribblers who contain an equivalent set of IScribblerDomains.


setUserInterfaceController

void setUserInterfaceController(IHumanInteractionController userInterfaceController)
A UserInterfaceController should be provided that allows the IEditModelScribbler to prompt the user for advice when necessary. The IUserInterfaceController will be invoked to prompt the user when a Resource inconsistency (between disk and memory) is detected, or when no explicit save() is invoked and the IEditModelScribbler is close()ed. Implemented.

Parameters:
userInterfaceController -

getUserInterfaceController

IHumanInteractionController getUserInterfaceController()
Return the IUserInterfaceController currently set. Only one IUserInterfaceController may be set. Implemented.

Returns:

execute

IStatus execute(IUndoableOperation operation,
                IProgressMonitor monitor,
                IAdaptable args)
Provides a convenience method for supplying and operation with the correct context, executing an operation, and adding it to the IOperationHistory managed by the IEditModel for this IEditModelScribbler. Implemented.

See Also:
org.eclipse.core.commands.operations.IOperationHistory#execute(org.eclipse.core.commands.operations.IUndoableOperation, org.eclipse.core.runtime.IProgressMonitor, org.eclipse.core.runtime.IAdaptable)

undo

IStatus undo(IUndoableOperation operation,
             IProgressMonitor monitor,
             IAdaptable args)
Provides a convenience method for supplying and operation with the correct context, executing an operation, and adding it to the IOperationHistory managed by the IEditModel for this IEditModelScribbler. Should this method return false if it cannot succeed or throw an Exception? Implemented.

See Also:
org.eclipse.core.commands.operations.IOperationHistory#undoOperation(org.eclipse.core.commands.operations.IUndoableOperation, org.eclipse.core.runtime.IProgressMonitor, org.eclipse.core.runtime.IAdaptable)

redo

IStatus redo(IUndoableOperation operation,
             IProgressMonitor monitor,
             IAdaptable args)
Provides a convenience method for supplying and operation with the correct context, executing an operation, and adding it to the IOperationHistory managed by the IEditModel for this IEditModelScribbler. Should this method return false if it cannot succeed or throw an Exception? Implemented.

See Also:
org.eclipse.core.commands.operations.IOperationHistory#redoOperation(org.eclipse.core.commands.operations.IUndoableOperation, org.eclipse.core.runtime.IProgressMonitor, org.eclipse.core.runtime.IAdaptable)

undoLast

IStatus undoLast(IProgressMonitor monitor,
                 IAdaptable args)
Requests the last operation that can be undone for the IUndoContext supplied by this IEditModelScribbler. If an operation is available, a request is made to undo that operation. The operation may not have been executed by this specific IEditModelScribbler; it could be the operation associated with another IEditModelScribbler with a matching set of IScribblerDomains. Implemented.

Returns:
See Also:
org.eclipse.core.commands.operations.IOperationHistory#undo(org.eclipse.core.commands.operations.IUndoContext, org.eclipse.core.runtime.IProgressMonitor, org.eclipse.core.runtime.IAdaptable)

redoLast

IStatus redoLast(IProgressMonitor monitor,
                 IAdaptable args)
Requests the last operation that can be undone for the IUndoContext supplied by this IEditModelScribbler. If an operation is available, a request is made to redo that operation. The operation may not have been executed by this specific IEditModelScribbler; it could be the operation associated with another IEditModelScribbler with a matching set of IScribblerDomains. Implemented.

Returns:
See Also:
org.eclipse.core.commands.operations.IOperationHistory#redo(org.eclipse.core.commands.operations.IUndoContext, org.eclipse.core.runtime.IProgressMonitor, org.eclipse.core.runtime.IAdaptable)

flushOperationHistory

void flushOperationHistory(IProgressMonitor monitor)
Flushes the operation history for this IEditModelScribbler. Implemented.

Parameters:
monitor -

createTechnologyFlavor

ITechnologyFlavor createTechnologyFlavor(java.lang.String technologyFlavorLifecycleId,
                                         IAdaptable input)
Return a TechnologyFlavor that can be used to manage model elements associated with a particular technology not modeled as EMF. The flavor must be cast to the appropriate implementation.

Parameters:
technologyFlavorLifecycleId -
Returns:

getUndoContext

IUndoContext getUndoContext()
Returns the IUndoContext for this IEditModelScribbler which can be used to associate all operations with this scribbler which are executed on data managed by the scribbler.

Returns: