Transactional * A self-composing undoable operation that has a {@link CommandResult} and a * list of affected {@link IFile}s. * * Executing, undoing or redoing a command can have a result which clients can * obtain by using the {@link #getCommandResult()} method. For example, * executing a command that create a new entity may wish to make the new entity * accessible to clients through the {@link #getCommandResult()} method. * * The command provides a list of {@link IFile}s that are expected to be * modified when the it is executed, undone or redone. An * {@link IOperationApprover} is registered with the * {@link OperationHistoryFactory#getOperationHistory()} to validate the * modification to these resources. * * If an error occurs, or the progress monitor is canceled during execute, undo * or redo, the command should make every effort to roll back the changes it has * made up to that point. * * @author khussey * @author ldamus * * @canBeSeenBy %partners * Retrieves the result of executing, undoing, or redoing this command, * depending on which of these operations was last performed. This value can * be <code>null</code> if the operation has no meaningful result. * * The value of this result is undefined if the command has not yet been * executed, undone or redone. * * @return The result of executing, undoing or redoing this command. * Returns the list of {@link IFile}s that are expected to be modified by * this command. * * @return the list of {@link IFile}s that will be modified * Returns a new command object that represents a composition of this * command with the specified <code>command</code> parameter. * * @param operation * The operation that is to be composed with this command. * @return A command that represents a composition of this command with the * specified command. * Returns the simplest form of this command that is equivalent. Use this * method to remove unnecessary nesting of commands. * * @return the simplest form of this command that is equivalent * Since not all commands have names, reduce() should propogate label from an * upper command that may be thrown away to the resultant reduced command. The * method is needed to assign the label to a nameless command, because * <code>IUndoableOperation</code> is missing this method. * * @param label command's new label * A self-composing undoable operation that is has a {@link CommandResult}, a * list of affected {@link IFile}s, and is composed of child operations. * * Does not extend <code>ICompositeOperation</code> because * <UL> * <LI> {@link #remove(IUndoableOperation)} does not dispose the removed * operation</LI> * <LI> Children are explicitely composed by the client. Adding to an open * composite through the operation history is not supported.</LI> * </UL> * * @author ldamus * * Add the specified operation as a child of this operation. * * * @param operation * the operation to be added. If the operation instance has * already been added, this method will have no effect. * * Remove the specified operation from this operation. * * * Unlike {@link ICompositeOperation}, this does not dispose of the removed * operation since the composite did not create the operation. * * * @param operation * the operation to be removed. The operation should be disposed * by the receiver. This method will have no effect if the * operation instance is not already a child. * Answers whether or not this composite operation has children. * * @return <code>true</code> if the operation does not have children, * <code>false</code> otherwise. * Queries the number of child operations that I contain. * * @return my size * Obtains an iterator to traverse my child operations. Removing children * via this iterator correctly maintains my undo contexts. * * @return an iterator of my children * Obtains an iterator to traverse my child operations in either direction. * Adding and removing children via this iterator correctly maintains my * undo contexts. * * Note that, unlike list iterators generally, this one does not * permit the addition of an operation that I already contain (the composite * does not permit duplicates). Moreover, only {@link IUndoableOperation}s * may be added, otherwise <code>ClassCastException</code>s will result. * * * @return an iterator of my children * Obtains an iterator to traverse my child operations in either direction, * starting from the specified <code>index</code>. Adding and removing * children via this iterator correctly maintains my undo contexts. * * Note that, unlike list iterators generally, this one does not * permit the addition of an operation that I already contain (the composite * does not permit duplicates). Moreover, only {@link IUndoableOperation}s * may be added, otherwise <code>ClassCastException</code>s will result. * * * @param index * the index in my children at which to start iterating * * @return an iterator of my children * An abstract superclass for GMF {@link IUndoableOperation}s that do not * modify EMF model resources. * * The operation provides a list of {@link IFile}s that are expected to be modified when * the operation is executed, undone or redone. An {@link IOperationApprover} is * registered with the {@link OperationHistoryFactory#getOperationHistory()} to * validate the modification to these resources. * * This class is meant to be extended by clients. * * @author khussey * @author ldamus * * @see org.eclipse.gmf.runtime.common.core.command.ICommand * @canBeSeenBy %partners * Returns the {@link IFile}s that may be modified when the operation is * executed, undone or redone. * Sets the command result. * * @param result * the new result for this command. * Delegates to {@link #doExecuteWithResult(IProgressMonitor, IAdaptable)} and sets * the command result. * Performs the actual work of executing this command. Subclasses must * implement this method to perform some operation. * * @param progressMonitor * the progress monitor provided by the operation history. Must * never be <code>null</code>. * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. * * @return The result of executing this command. May be <code>null</code> * if the execution status is OK, but there is no meaningful result * to be returned. * * @throws ExecutionException * if, for some reason, I fail to complete the operation * Delegates to {@link #doRedoWithResult(IProgressMonitor, IAdaptable)} and sets the * command result. * Performs the actual work of redoing this command. Subclasses must * implement this method to perform the redo. * * @param progressMonitor * the progress monitor provided by the operation history. Must * never be <code>null</code>. * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. * * @return The result of redoing this command. May be <code>null</code> * if the execution status is OK, but there is no meaningful result * to be returned. * * @throws ExecutionException * on failure to redo * Delegates to {@link #doUndoWithResult(IProgressMonitor, IAdaptable)} and sets the * command result. * Performs the actual work of undoing this command. Subclasses must * implement this method to perform the undo. * * @param progressMonitor * the progress monitor provided by the operation history. Must * never be <code>null</code>. * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. * * @return The result of undoing this command. May be <code>null</code> * if the execution status is OK, but there is no meaningful result * to be returned. * * @throws ExecutionException * on failure to undo * Internal method to set the command result. * * @param result CommandResult to set * @deprecated internal API * An undoable command that is composed of child {@link IUndoableOperation}s * that are not known to modify EMF model resources, but can contain * model-affecting children. Execute, undo, redo and dispose result in execute, * undo, redo and dispose on each child operation. The operation provides a list * of {@link IFile}s that may be modified when the operation is executed, * undone or redone. * * The children are explicitly composed by a client before the composite is * executed. Children cannot be added or removed after the composite has been * executed. * * The undo contexts of the composite are a union of the undo contexts of its * children. * * If a child command returns a cancel or an error status during execution, undo * or redo, the remaining child commands are not processed and those that have * already been executed are rolled back. * * @author ldamus * Custom iterator implementation that maintains my undo contexts correctly * when elements are removed. * * @author ldamus * Custom list-iterator implementation that maintains my undo contexts * correctly, as well as uniqueness of the list contents. * * @author ldamus * Answers whether or not this composite operation has children. * * @return <code>true</code> if the operation does not have children, * <code>false</code> otherwise. * Obtains my nested operations. Note that the return result is mutable and * is identical to my child-operation storage, so subclasses should be * careful of adding or removing contents. This should ordinarily be done * only via the {@link #add(IUndoableOperation)} and * {@link #remove(IUndoableOperation)} methods because these maintain the * undo contexts (or, equivalently, using the iterators). * * @return my list of children * * @see #add(IUndoableOperation) * @see #remove(IUndoableOperation) * @see #iterator() * @see #listIterator(int) * Adds a child operation to me. This should only be done before I am * executed. Has no effect if I already contain this operation as a child. * * @param operation * a new child operation * * @throws IllegalStateException * if I have already been successfully executed * Updates my undo contexts for the addition of a new child operation. * * @param operation * a new child operation * Removes a child operation from me. This should only be done before I am * executed. Has no effect if I do not contain this operation as a child. * * Note that I do not dispose an operation when it is removed from * me. Although this is specified in the contract of the * {@link ICompositeOperation} interface, this would not be correct, as I * did not create that operation. * * * @param operation * a child operation to remove * * @throws IllegalStateException * if I have already been successfully executed * Updates my undo contexts for the removal of a child operation. * * @param operation * the child operation that was removed * Queries whether any of my children has the specified context. * * @param ctx * a context * * @return <code>false</code> if none of my children has the specified * context; <code>true</code>, otherwise * I can execute if I am not empty and all of my children can execute. * I can redo if I am not empty and all my children can all be redone. * I can undo if I am not empty and all my children can all be undone. * Disposes of each of my children. * Adds <code>command</code> to the list of commands with which this * composite is composed. * * @param operation * The command with which to compose this command. * @return <code>this</code>. * Appends a command onto a (possibly) existing composeite of commands. * * @param command an existing command, which may be a composite, a single * command, or <code>null</code> * @param next a command to append to the composite (may also be * <code>null</code>, which produces no effect) * * @return the new composite, which is just <code>next</code> if * <code>command</code> was <code>null</code> * Returns the simplest form of this command that is equivalent. This is * useful for removing unnecessary nesting of commands. * * If the composite has a single command, it returns the reduction of that * single command. Otherwise, it returns itself. * * @return the simplest form of this command that is equivalent * Returns a list containing all of the return values from * <code>ICommand</code> children. * Implements the execution logic by sequential execution of my children. * Undoes the previous operations in the iterator. * * @param iter * the execution iterator * @param info * the execution info * I redo by asking my children to redo, in forward order. * Undoes the previous operations in the iterator. * * @param iter * the execution iterator * @param info * the execution info * I undo by asking my children to undo, in reverse order. * Redoes the next operations in the iterator. * * @param iter * the execution iterator * @param info * the execution info * Creates a suitable aggregate from these statuses. If there are no * statuses to aggregate, then an OK status is returned. If there is a * single status to aggregate, then it is returned. Otherwise, a * multi-status is returned with the provided statuses as children. * * @param statuses * the statuses to aggregate. May have zero, one, or more * elements (all must be {@link IStatus}es) * * @return the multi-status * Answers whether or not I have been executed. * * @return <code>true</code> if I have been executed, <code>false</code> * otherwise. * Asserts that I have not yet been executed. Changes to my children are not * permitted after I have been executed. * Returns a list containing all of the affected files from * <code>ICommand</code> children. * Obtains an iterator to traverse my child operations. Removing children * via this iterator correctly maintains my undo contexts. * * @return an iterator of my children * Obtains an iterator to traverse my child operations in either direction. * Adding and removing children via this iterator correctly maintains my * undo contexts. * * Note that, unlike list iterators generally, this implementation * does not permit the addition of an operation that I already contain (the * composite does not permit duplicates). Moreover, only * {@link IUndoableOperation}s may be added, otherwise * <code>ClassCastException</code>s will result. * * * @return an iterator of my children * Obtains an iterator to traverse my child operations in either direction, * starting from the specified <code>index</code>. Adding and removing * children via this iterator correctly maintains my undo contexts. * * Note that, unlike list iterators generally, this implementation * does not permit the addition of an operation that I already contain (the * composite does not permit duplicates). Moreover, only * {@link IUndoableOperation}s may be added, otherwise * <code>ClassCastException</code>s will result. * * * @param index * the index in my children at which to start iterating * * @return an iterator of my children * An abstract superclass for GMF {@link IUndoableOperation}s that modify EMF * model resources. * * The operation provides a list of {@link IFile}s that are expected to be * modified when the operation is executed, undone or redone. An * {@link IOperationApprover} is registered with the * {@link OperationHistoryFactory#getOperationHistory()} to validate the * modification to these resources. * * Subclasses must return the command execution result in their implementation * of {@link #doExecuteWithResult(IProgressMonitor, IAdaptable)}. * * This class is meant to be extended by clients. * * @author ldamus * Convenience method to get a list of workspaces files associated with * <code>eObject</code>. * * @param eObject * the model object, may be <code>null</code> * @return the list of {@link IFile}s * Convenience method to get a list of workspaces files associated with * {@link EObject}s in <code>eObject</code>. * * @param eObjects * the list of model object * @return the list of {@link IFile}s * Returns the {@link IFile}s for resources that may be modified when the * operation is executed, undone or redone. * Sets the command result. * * @param result * the new result for this command. * Implemented by subclasses to perform the model changes. These changes * are applied by manipulation of the EMF metamodel's API, not * by executing commands on the editing domain's command stack. * * @param monitor the progress monitor provided by the operation history * @param info the adaptable provided by the operation history * * @return the result of the execution * * @throws ExecutionException if, for some reason, I fail to complete * the operation * Delegates to {@link #doExecuteWithResult(IProgressMonitor, IAdaptable)} * to perform the model changes. Sets the command result and calls * {@link #cleanup()} to give subclasses a chance to dispose of any objects * that were required for the execution but will not be required for undo or * redo. * Overrides superclass to set the command result. * Overrides superclass to set the command result. * Considers that the aggregate status may be different from the present * status, and updates the command result accordingly. * Subclasses may implement this method to dispose of objects that were * required for execution, but are no longer require to undo or redo this * operation. * * This method is invoked at the end of * {@link #doExecute(IProgressMonitor, IAdaptable)}. * Internal method to set the command result. * * @param result CommandResult to set * @deprecated internal API * An undoable operation that is composed of child {@link IUndoableOperation}s * that are expected to modify EMF model resources. * * The operation provides a list of {@link IFile}s that are expected to be * modified when the operation is executed, undone or redone. An * {@link IOperationApprover} is registered with the * {@link OperationHistoryFactory#getOperationHistory()} to validate the * modification to these resources. * * This class is meant to be instantiated by clients. * * @author ldamus * Returns the {@link IFile}s for resources that may be modified when the * operation is executed, undone or redone. * Sets the command result. * * @param result * the new result for this command. * Returns a list containing all of the return values from * <code>ICommand</code> children. * Overrides the superclass implementation to set the command result. * Returns the simplest form of this command that is equivalent. This is * useful for removing unnecessary nesting of commands. * * If the composite has a single command, it returns the reduction of that * single command. Otherwise, it returns itself. * * @return the simplest form of this command that is equivalent * Answers whether or not this composite operation has children. * * @return <code>true</code> if the operation does not have children, * <code>false</code> otherwise. * I can execute if I am not empty and all of my children can execute. * I can redo if I am not empty and all my children can all be redone. * I can undo if I am not empty and all my children can all be undone. * Internal method to set the command result. * * @param result CommandResult to set * @deprecated internal API * An {@link IUndoContext} that tags an EMF operation with the editing domain * that it affects. Two editing domain contexts match if and only if they * reference the same {@link EditingDomain} instance. * * @author ldamus * I match another <code>context</code> if it is a * <code>EditingDomainUndoContext</code> representing the same editing * domain as I. * I am equal to other <code>EditingDomainUndoContext</code> on the same * editing domain as mine. * Obtains the editing domain. * * @return my editing domain * The string representation of this operation. Used for debugging purposes only. * This string should not be shown to an end user. * * @return The string representation. * Edit command to configure a new model element with the characteristics of its * element type. * * @author ldamus * The element type. * Gets the element type. * * @return the element type * Abstract superclass for commands that modify model elements. * * @author ldamus * The element to be modified. * The edit request that carries the required command parameters. * The kind of model element that can be modified by this command. * Checks that the element to be modified by this command is of the correct * kind. * Gets the element to be modified by this command. * * @return the element to be modified * Sets the element to be modified by this command. * * @return the element to be modified * Gets the edit request. * * @return the edit request * Gets the kind of element that can be modified by this command. * * @return the kind of element * Sets the kind of element that can be modified by this command. * * @param eClass * the kind of element * Convenience method to check the status of <code>commandRequest</code>. * * @param commandResult * the command result to check * @return <code>true</code> if the result is OK, <code>false</code> * otherwise. * Edit command to configure a new relationship element with the characteristics * of its element type. * * @author ldamus * Command to create a new model element. * * @author ldamus * The newly created element. * The element type to be created. * The containment feature in which the new element will be created. * Status of the default element creation. * Creates the request to configure the new element. * * @return the request * Subclasses should implement this to override the basic element creation. * * @return the new model element that has been created * Gets the status of the default element creation. * * @return the status * @since 1.2 * Sets the status of the default element creation. * * @param status * the new status * @since 1.2 * Initializes the container of the new element by asking the create to * create the container, if necessary. * Gets the EClass of the element to be edited. * * @return the EClass * Gets the containment feature for the new element. * * @return the containment feature * Sets the containment feature for the new element. * * @param containmentFeature * the containment feature for the new element * Gets the element type for the new element. * * @return the element type * Gets the create request. * * @return the create request * Gets the new element that was created by this command. Will be * <code>null</code> if the command has not been executed. * * @return the new element * Command to create a new relationship element using the EMF action protocol. * * If the containment feature is not specified in the request, the first feature * in the container that can contain the new kind of relationship will be used. * * @author ldamus * The relationship source. * The relationship target. * Gets the relationship source. * * @return the relationship source * Gets the relationship target. * * @return the relationship target * Command to set the value of a feature of a model element. The model element * is not known at the time of command construction. Subclasses can override * {@link #getElementToEdit()} to compute or find the elementToEdit. * * @author ldamus * Always executable when we can't get the elementToEdit. * Command to set the value of a feature of a model element. * * @author ldamus, mmostafa * The feature whose value should be set. * The new value. * Checks that the feature is a modifiable feature of the element whose * value will be set by this command. Also checks that the new value is of * the correct type for the feature. * Command to create a model element using the EMF action protocol. * * @author ldamus * @author Christian W. Damus (cdamus) * The element to be destroyed. * Convenience method for destroying the specified object by executing a * <code>DestroyElementCommand</code> on it, if it is attached to a * resource. Detached elements cannot be destroyed. * * Note that the command will not be executed on the operation * history. * * * @param eObject an element to destroy * Tears down references to the object that we are destroying, from all other * objects in the resource set. * * @param destructee the object being destroyed * Tears down outgoing unidirectional references from the object being * destroyed to all other elements in the resource set. This is required * so that reverse-reference queries will not find the destroyed object. * * @param destructee the object being destroyed * Gets the element to be destroyed. * @return the element to be destroyed * Command to destroy a reference from one element to another. * * @author ldamus * The element that contains the reference. * The feature in the <code>container</code> that contains the reference. * The referenced object. * Gets element that contains the reference. * * @return the element that contains the reference * Gets the feature in the <code>container</code> that contains the * reference. * * @return the feature in the <code>container</code> that contains the * reference. * Gets the referenced object. * * @return the referenced object. * Command to get the edit context for a given request. * * @author ldamus * The edit context. * Gets the edit context. * * @return the edit context * Sets the edit context. * * @param editContext * the edit context * Command to move model elements using the EMF action protocol. * * If the target features are not specified in the request, and the features * fomerly containing the moved elements exists in the target element, they will * be used. * * @author ldamus * The map of <code>EObject</code>s to be moved. Keyed on * <code>EObject</code>. Each value is the <code>EReference</code> * feature in the target element into which the element should be moved. * * If the feature is not specified for a given element, then a default * feature is found in the target. * The target container into which the element will be moved. * Gets the feature in the target element that should contain * <code>element</code> after it is moved. * * Looks for the feature first in the elements map. If none is specified, * tries to use the same feature that contained the element in its old * location. If the old containment feature doesn't exist in the new target, * uses the MSL utility to find the first feature in the target that can * contain the element being moved. * * @param element * the element to be moved * @return the feature that will contain the element in the target * Gets the target container. * * @return the target container * Gets the map of elements to be moved. Each entry in the map consists of * an <code>EObject</code> key, which is the element to be moved to the * new target, and an <code>EReference</code> value, which is the feature * in the new target that should contain the moved element. * * @return the map of elements to be moved * Sets the reference feature into which an element should be moved. * * @param element * the element to be moved * @param targetFeature * the target feature * GEF command stack that delegates to an {@link IOperationHistory}. * * @author sshaw * @author Tauseef A, Israr * @author ldamus * Gets my operation history event. * * @return my operation history event. * Adds a listener to this CommandStack. * * @param listener * The Object listening to this CommandStack. * Returns <code>true</code> if there is a Command to redo. * * @return <code>true</code> if there is a Command to redo. * Returns <code>true</code> if the last Command executed can be undone. * * @return <code>true</code> if the last Command executed can be undone. * Executes the given Command if it can execute. * * @param command * The Command to execute. * Executes the given Command if it can execute. * * @param command * The Command to execute. * @param progressMonitor * exectus a the supplied command * * @param command * the command to execute * executes the supplied command * * @param command * the command to exectue * @param progressMonitor * Converts a GEF {@link Command} into a GMF {@link ICommand} * * @param command * the GEF command * @return the GMF command * Removes redundancies from <code>command</code> by stripping out layers * of command wrappers used to accomodate the use of GEF commands on an * {@link IOperationHistory} and {@link ICommand}s on the GEF * {@link CommandStack}. * * @param command * the command to be processed * @return a command representing the simplified form of the input command. * May be a new command. * Returns the most recently executed command. * * @return The most recently executed command. * getRedoCommand Returns the command at the top of the redo stack. * * @see org.eclipse.gef.commands.CommandStack#getRedoCommand() * getUndoCommand() Returns the next command to be undone. * * @see org.eclipse.gef.commands.CommandStack#getUndoCommand() * Executes the last undone Command. * Removes the given CommandStackListener. * * @param listener * The object to be removed from the list of listeners. * Undoes the last executed Command. * Returns the editDomain. * * @return IDiagramEditDomain * Gets my operation history delegate. * * @return my operation history delegate * Sets my operation history delegate. * * @param operationHistory * my operation history delegate * Gets the return values of the given executed command * * @param c * The command * @return A collection of values returned by the given command * gets the return the values for the supplied command. * * @param cmd * command to use * @return a collection of return values * gets the return the values for the supplied command. * @param cmd command to use * @return a collection of return values * gets the return the values for the supplied command. * * @param cmd * command to use * @return a collection of return values * Gets my undo context. I add my context to all commands executed through * me. * * @return my undo context * Sets my undo context. * * @param undoContext * my undo context * Diagram Edit Domain Interface * @author melaasar * * Returns the DiagramCommandStack to be used with ICommands. * @return The command stack for this edit domain. * Returns the ActionManager * @return the Action Manager * A Command Wrapper for a GMF ICommand. * * @author melaasar The wrapped command * gets the warapped <code>ICommand</code> * @return the wrapped command * {@link ICommand} that delegates to a GEF {@link Command}. * * @author sshaw The wrapped command * Returns the wrapped command. * * @return Command * The arrange command implementation * <li> Delegates to the layout provider only during the execution of the command. * <li> {@link #canExecute()} asks the layout service whether it can layout the nodes * (e.g some layouts won't layout if nodes are laid out already) * * @author aboyko * @since 1.4 * Nodes to layout * <code>true</code> if only a part of the graph is being laid out, * <code>false</code> - the whole graph is being laid out * The layout hint parameter * Creates the list of nodes to layout from the editparts required to be arranged * * @param editparts the editparts required to be arranged * Creates the actual layout command to execute. The command is created based on the {@link LayoutService} * * @return the actual graph layout command * Class containing commands utility methods. * * @author aboyko * * This utility function determines whether the command is redoable. * Since GEF commands API doesn't support for canRedo method, this * utility will help to travel through the contents of GEF wrapper * commands and determine redoability of the GEF command based on * the redoability of the commands it contains. * * @param command The command to be examined * @return <code>true</code> if the passed command is redoable * Determines the files affected by <code>command</code>. Since GEF * command API has no support for #getAffectedFiles, this utility will * traverse the contents of GEF wrapper commands and determine the files * affected by the <code>ICommands</code> it contains. * * @param command * the command * @return the affected files * A helper that inspects the command for the most severe command result. * * @param command * @return IStatus in the command or null if no result can be obtained from the command. * @since 1.2 * Creates a suitable aggregate from these statuses. If there are no * statuses to aggregate, then an null status is returned. If there is a * single status to aggregate, then it is returned. Otherwise, a * multi-status is returned with the provided statuses as children. * * @param statuses * the statuses to aggregate. May have zero, one, or more * elements (all must be {@link IStatus}es) * * @return the multi-status or null * @since 1.2 the view descriptor The container view * Return the cached view descriprot. * * @return view descriprot * give access to the view, where that will contain the created view * @return the conatiner view * returns true if the view that will be created will be a transient view, transient views * will not dirty the model and will never get serialized in the saved file * @return true if persisted false if transient * * A command that pops up a menu which can allow the user to select whether they * want to create a new type, select an existing element, or leave it * unspecified. * * * * The content can be customized, one or more of the above options are * permitted. The constants <code>UNSPECIFIED</code> and * <code>SELECT_EXISTING</code> can be used as the content of a menu item. * * * * The displayed strings can be customized with a custom label provider. * * * * The options are: * <li>Unspecified</li> * <li>Select Existing Element</li> * <li>Create New Type A</li> * <li>Create New Type B</li> * * * If a "Select Existing" menu item is chosen, an additional dialog appears * allowing the user to choose an element. * * * The <code>getResultAdapter()</code> method returns an adaptable to the * result. * * * @author cmahoney * Add this to the content list of the popup menu to add an 'unspecified' * option. * Add this to the content list of the popup menu to add a 'select existing' * option. * Add this to the content list of the popup menu to add a 'create without * binding' option. * The result to be returned from which the new element or type info can be * retrieved. The dialog to be used if "Select Existing Element" is chosen * The default label provider for the the menu items used in this command. * Adds the "Create new " text to the objects of type * <code>IElementType</code>. * @see org.eclipse.jface.viewers.ILabelProvider#getText(java.lang.Object) * Pops up the dialog with the content provided. If the user selects 'select * existing', then the select elements dialog also appears. * * @see org.eclipse.gmf.runtime.common.core.sandbox.AbstractCommand2#doExecute(org.eclipse.core.runtime.IProgressMonitor) * Gets the selectElementDialog. * * @return Returns the selectElementDialog. * Sets the selectElementDialog. * * @param dialog * The dialog to set. * Gets the resultAdapter. * * @return Returns the resultAdapter. * Gets the label provider that is to be used to display each item in the * popup menu. * * @return the label provider * A command that pops up a <code>PopupMenu</code> or a * <code>PopupDialog</code> when it executes. The result from the * <code>PopupMenu</code> or <code>PopupDialog</code> is retrieved via * <code>getCommandResult().getReturnValue()</code>. * * @author cmahoney * The popup menu style for this command. * The popup dialog style for this command. The parent shell for this menu. * The popup menu to appear when this command is executed if the popup menu * is not <code>null</code>. * The dialog to appear when this command is executed, if the dialog * is not <code>null</code>. * Gets the parentShell. * @return Returns the parentShell. * Sets the parentShell. * @param parentShell The parentShell to set. * Gets the popupMenu. * @return Returns the popupMenu. * Sets the popupMenu. Sets the popup dialog to null. * @param popupMenu The popupMenu to set. * Gets the popupDialog. * @return Returns the popupDialog. * Sets the popupDialog. Sets the popup menu to null. * @param popupDialog The popupDialog to set. * A command used to optionally create a new view and new element. This command * is used when it is not known at command creation time whether or not an * element should be created as well. For example, when creating a connection to * an unspecified target, did the user want to * <li>create a new element for the target (view and element)?</li> * <li>use an existing element and its view already on the diagram (nothing * created)?</li> * <li>use an existing element and add a new view to the diagram (view only)? * * * Note: This command will pop up a dialog box if the element exists already and * there is a view for it on the diagram to ask the user what they want to do. * * * @author cmahoney * Adapts to the element, if null at command execution time, an element is * to be created. The location to create the new view. The container editpart to send the view request to. The command executed, saved for undo/redo. The result to be returned from which the new view can be retrieved. * The hint used to find the appropriate preference store from which general * diagramming preference values for properties of shapes, connections, and * diagrams can be retrieved. This hint is mapped to a preference store in * the {@link DiagramPreferencesRegistry}. * Searches the container editpart to see if the element passed in already * has a view. * * @param element * @return IView the view if found; or null * Returns an immediate child editpart of the editpart passed in whose * element is the same as the element passed in if it exists; returns null * if such an editpart does not exist. * * @param editpart * the parent editpart * @param theElement * the element to match * @return an immediate child editpart of the editpart passed in whose * element is the same as the element passed in if it exists; null * otherwise * Prompts the user to see if they would like to use an existing view on the * diagram. Clients may subclass this method to customize the message * dialog. * * @param view * the existing view * @return true if this view should be used; false otherwise * <li>If the element adapter is empty, this command creates a new element * and view for it.</li> * <li>If the element adapter is not empty, and a view for this element * exists in the container, this command will prompt the user to see if they * want to use the existing view or create a new view for the element and * then execute accordingly.</li> * <li>If the element adapter is not empty, and a view for this element * does not exist in the container, this command will create a new element * and view.</li> * * @return the adapter from which the view can be retrieved. * Sets the result to adapt to the view passed in. * @param viewAdapter * Gets the elementAdapter. * @return Returns the elementAdapter. * Sets the elementAdapter. * @param elementAdapter The elementAdapter to set. * Gets the location. * @return Returns the location. * Sets the location. * @param location The location to set. * Gets the containerEP. * @return Returns the containerEP. * Sets the containerEP. * @param containerEP The containerEP to set. * Gets the preferences hint that is to be used to find the appropriate * preference store from which to retrieve diagram preference values. The * preference hint is mapped to a preference store in the preference * registry <@link DiagramPreferencesRegistry>. * * @return the preferences hint * Sets the preferences hint that is to be used to find the appropriate * preference store from which to retrieve diagram preference values. The * preference hint is mapped to a preference store in the preference * registry <@link DiagramPreferencesRegistry>. * * @param preferencesHint the preferences hint * Gets the command. * @return Returns the command. * Sets the command. * @param command The command to set. * a command to create the both of the View and Semantic of the connection, but * the editparts of target and source to obtain the command has not been created * yet, since we have the ViewAdapter to we can use it to get its editpart once * it is created and hence on execution time we can get its editpart to get the * command for our request and then execute it. * * * This command can handle both * <code>CreateConnectionViewAndElementRequest</code> and * <code>CreateConnectionViewRequest</code>. * * * @author choang * gives access to the connection source edit part, which is the edit part * of the connection's source <code>View</code> * * @return the source edit part * gives access to the connection target edit part, which is the edit part * of the connection's target <code>View</code> * * @return the source edit part * Finds the source and target editparts by extracting the views from the * view adapters and searching in the editpart viewer. Creates a connection * view and element using the request. * * @see org.eclipse.gmf.runtime.common.core.command.ICommand#getLabel() * This command is used to create a connection view between two editparts, when * only the view adapters are available at the time of creating the command. The * editparts are required to get the correct create connection command, so this * command defers getting the create connection command until execution time at * which point it can get the editparts from the editpart registry and the view * adapters. * * @author cmahoney the element for the connection's semantic element the connection's semantic hint the source adapter from which a View can be retrieved * the target adapter from which a View can be retrieved the graphical viewer used to get the editpart registry the command saved for undo and redo * The hint used to find the appropriate preference store from which general * diagramming preference values for properties of shapes, connections, and * diagrams can be retrieved. This hint is mapped to a preference store in * the {@link DiagramPreferencesRegistry}. * Finds the source and target editparts by extracting the views from the * view adapaters and searching in the editpart viewer. Creates a connection * view between the source and target. * * This command is used to arrange editparts on a diagram, when only the view * adapters are available at the time of creating the command. It is necessary * to have the editparts when creating a layout command so this command defers * the creation of the layout command until execution time at which point it can * get the editparts from the editpart registry using the view adapters. * * @author cmahoney the type of layout to be performed the IAdaptables from which an View can be retrieved the diagram editpart used to get the editpart registry * Executes a layout command with all the editparts for the view adapters. * * gets the container edit part's figure * @return the container figure * gets the container edit part * @return the container edit part * gets a list of <code>IAdaptable</code> that can adapt to <code> * View</code> * @return view adapters * Command to open a diagram. * * @author jcorchis Remember the element to be opened. * returns the element associated with that command * @return the element associated with that command * set the element to open * @param element the element to open * This command can only be executed if the element is a diagram. * @see org.eclipse.gmf.runtime.common.core.command.ICommand#isExecutable() * Create a new editor to display the corresponding diagram. * * @see org.eclipse.gmf.runtime.common.core.sandbox.AbstractCommand2#doExecute(org.eclipse.core.runtime.IProgressMonitor) * Paste Command for the views * * @author Vishy Ramaswamy * The clipboard data * Method pasteFromString. * pastes the clipboard contents on to self * @param clipboard The clipboard contents - serialization used during copy * @return List The list of IView resulting from the paste * @param mu the <code>MeasurementUnit</code> for the notation diagram. * @param edges the <code>Set</code> of edges to convert the bendpoints of. * @param retval the <code>List</code> of <code>Node</code> objects to convert the constraint of. * @param mu the <code>MeasurementUnit</code> for the notation diagram. * @return the <code>Set</code> of <code>Edge</code> views that are attached to the list of nodes * Add offset node position. * @param node * @param constraintRect * @return * Get map mode associated with this Paste command. * @return * * A command that pops up a menu which can allow the user to select the type of * connection to be created and whether they want to create a new type or select * an existing element for the other end of the connection. * * * * The <code>getRelationshipTypeAdapter()</code> method returns an adaptable * to the relationship type result. * * * * The <code>getEndAdapter()</code> method returns an adaptable to the end * type result. * * * @author cmahoney * This can be added to the content list to add a 'select existing' option. Label provider of the popup menu for the connection types. Label provider of the submenus for the other end element. Adapts to the connection type result. Adapts to the other end type result. * The request to create a connection. It may contain the connection type or * it may be a <code>CreateUnspecifiedTypeConnectionRequest</code>. The container editpart to send the view request to. * Label provider of the first popup menu with the relationship types. * Label provider of the second popup (submenus) for the type of the other * end. * Label provider of the first and only popup for the type of the other end * when there is only one connection type (e.g. a single relationship type * palette tool is used). the known connection item * Gets the connection item. * * @return the connection item * Gets a list of all the connection items that will represent the * connection choices and will appear in the first part of the popup menu. * * * If the objects in this are not <code>IElementTypes</code> or they * require a special label provider, then * {@link #getConnectionLabelProvider()} should be overridden to provide * this. * * * When this command has executed, the connection adapter result ({@link #getConnectionAdapter()}) * will be populated with the connection item chosen. * * * @return the list of connection items to appear in the popup menu * Gets a list of all the end items that will represent the other end * choices and will appear in the submenu popup of the given connection * item. * * * If the objects in this are not <code>IElementTypes</code> or they * require a special label provider, then {@link #getEndLabelProvider()} * should be overridden to provide this. * * * When this command has executed, the end adapter result ({@link #getEndAdapter()}) * will be populated with the end item chosen. * * * @param connectionItem * the connection item for which this will be a submenu * @return the list of end items to appear in the popup menu * Gets the content to be used in the popup menu from the Modeling Assistant * Service and creates the popup menu. * * @return the top-level popup menu * Returns a new list with all the types from the list given that can be * created. * * @param allTypes * a list of <code>IElementTypes</code>. * Pops up the dialog with the content provided. If the user selects 'select * existing', then the select elements dialog also appears. * Checks if the <code>ModelingAssistantService</code> supports the * ability to open a dialog for the user to select an existing element * * @param connectionType * @return true if the supported by the modeling assistant service; false * otherwise * Gets the connectionAdapter. * * @return Returns the connectionAdapter. * Gets the endAdapter. * * @return Returns the endAdapter. * Returns true if the request is a reversed * <code>CreateUnspecifiedTypeConnectionRequest</code>. * * @return Returns true if the request is a reversed * <code>CreateUnspecifiedTypeConnectionRequest</code>; false * otherwise * Gets the known end, which even in the case of a reversed * <code>CreateUnspecifiedTypeConnectionRequest</code>, is the source * editpart. * * @return the known end * Gets the label provider that is to be used in the first menu of the popup * where the user is to choose the connection to be created. * * @return the connection label provider * Gets the label provider that is to be used in the second menu of the * popup where the user is to choose the end (could be source or target) to * be created. * * @return the end label provider * Gets the label provider that is to be used when there is only one option * for the connection type so the popup menu consists of a single menu * identifying the connection type to be created and options for the other * end of which the user must choose * * @param connectionItem * the single known connection item * @return the label provider * A Wrapper around a real element creation command * The main use of this command is to ensure that the semantic * adapter is updated appropriately upon undo and redo of the real command * * @author melaasar the request adapter the real element creation command * If the command was properly executed, the result will be set during * execution. If the command failed execution, the result may contain status * information for feedback purposes. * * @return * The command result either from this command executed * properly or the wrapped realSemanticCommand in case status information * needs to be returned. * Propagates the contexts from my wrapped command. * Adds the context to my wrapped command. * Removes the context from my wrapped command. * A command to set the bounds (location/size) of a <code>View</code> * * @author melaasar * Command that sets the view's mutability. if a view is Mutability state is used * by the Diagram Listener to decide if a view can move from the transient childern * list of its container to the persisted list. so a mutable view will never be persisted * keep in mind that the mutability state of the view is a transient state so as soon as the * model is closed and opened again all views will be immutable. * @author mhanner cached non-persisted views. immutable flag. * Convenience method returning a command to make the supplied views mutable. * @param viewAdapters views to be associated with the command * @return <code>SetViewMutabilityCommand</code> * Convenience method returning a command to make the supplied view mutable. * @param viewAdapter view to be associated with the command * @return <code>SetViewMutabilityCommand</code> * Convenience method returning a command to make the supplied views immutable. * @param viewAdapters views to be associated with the command * @return <code>SetViewMutabilityCommand</code> * Convenience method returning a command to make the supplied view immutable. * @param viewAdapter views to be associated with the command * @return <code>SetViewMutabilityCommand</code> * gets an unmodifiable copy of the cached view adapters. * @return view adapters Set the mutability flag on all views. * Returns the view that would be affected if this * command were executed, undone, or redone. * @return views adapter Collection * An interface that every command is expected to support. * A command can be tested for executability, * it can be executed, * it can be tested for undoability, * it can be undone, * and can then be redone. * A command also provides access to a result collection, an affected-objects collection, * a label, and a description. * * * There are important constraints on the valid order in which the various methods may be invoked, * e.g., you cannot ask for the result before you've executed the command. * These constraints are documented with the various methods. * Returns whether the command is valid to <code>execute</code>. * The {@link UnexecutableCommand#INSTANCE}.<code>canExecute()</code> always returns <code>false</code>. * This must be called before calling <code>execute</code>. * @return whether the command is valid to <code>execute</code>. * Performs the command activity required for the effect. * The effect of calling <code>execute</code> when <code>canExecute</code> returns <code>false</code>, * or when <code>canExecute</code> hasn't been called, is undefined. * Returns whether the command can be undone. * The result of calling this before <code>execute</code> is well defined, * but the result of calling this before calling <code>canExecute</code> is undefined, i.e., * a command that returns <code>false</code> for <code>canExecute</code> may return <code>true</code> for canUndo, * even though that is a contradiction. * @return whether the command can be undone. * Performs the command activity required to <code>undo</code> the effects of a preceding <code>execute</code> (or <code>redo</code>). * The effect, if any, of calling <code>undo</code> before <code>execute</code> or <code>redo</code> have been called, * or when canUndo returns <code>false</code>, is undefined. * Performs the command activity required to <code>redo</code> the effect after undoing the effect. * The effect, if any, of calling <code>redo</code> before <code>undo</code> is called is undefined. * Note that if you implement <code>redo</code> to call <code>execute</code> * then any derived class will be restricted by that decision also. * Returns a collection of things which this command wishes to present as it's result. * The result of calling this before an <code>execute</code> or <code>redo</code>, or after an <code>undo</code>, is undefined. * @return a collection of things which this command wishes to present as it's result. * Returns the collection of things which this command wishes to present as the objects affected by the command. * Typically should could be used as the selection that should be highlighted to best illustrate the effect of the command. * The result of calling this before an <code>execute</code>, <code>redo</code>, or <code>undo</code> is undefined. * The result may be different after an <code>undo</code> than it is after an <code>execute</code> or <code>redo</code>, * but the result should be the same (equivalent) after either an <code>execute</code> or <code>redo</code>. * @return the collection of things which this command wishes to present as the objects affected by the command. * Returns a string suitable to represent the label that identifies this command. * @return a string suitable to represent the label that identifies this command. * Returns a string suitable to help describe the effect of this command. * @return a string suitable to help describe the effect of this command. * Called to indicate that the command will never be used again. * Calling any other method after this one has undefined results. * Returns a command that represents the composition of this command with the given command. * The resulting command may just be this, if this command is capable of composition. * Otherwise, it will be a new command created to compose the two. * * Instead of the following pattern of usage * <pre> * Command result = x; * if (condition) result = result.chain(y); * </pre> * you should consider using a {@link org.eclipse.emf.common.command.CompoundCommand} * and using {@link org.eclipse.emf.common.command.CompoundCommand#unwrap()} to optimize the result: * <pre> * CompoundCommand subcommands = new CompoundCommand(); * subcommands.append(x); * if (condition) subcommands.append(y); * Command result = subcommands.unwrap(); * </pre> * This gives you more control over how the compound command composes it's result and affected objects. * @param command the command to chain. * @return a command that represents the composition of this command with the given command. * An exception thrown when a command's {@link Command#execute() execution} is to be silently aborted. * This is a signal to the command stack to behave as if {@link Command#canExecute() canExecute} returned <code>false</code>. * Only a command that has not changed the state of the model should be aborted in this way. * An abstract implementation of a basic command. * Each derived class <bold>must</bold> implement {@link Command#execute} and {@link Command#redo}, * <bold>must</bold> either implement {@link #undo} or implement {@link #canUndo} to return false, * and <bold>must</bold> either override {@link #prepare} (this is the preferred approach) or can override {@link #canExecute} directly. * * * It is very convenient to use prepare, as it is guaranteed to be called only once just before canExecute is to be tested. * It can be implemented to create any additional commands that need to be executed, * and the result it yields becomes the permanent cached return value for canExecute. * * Keeps track of whether prepare needs to be called. * It is tested in {@link #canExecute} so that {@link #prepare} is called exactly once to ready the command for execution. * Keeps track of whether the command is executable. * It is set in {@link #canExecute} to the result of calling {@link #prepare}. * Holds a short textual description of the command * as returned by {@link #getDescription} and set by {@link #setDescription}. * Holds the label of the command as returned by {@link #getLabel} and set by {@link #setLabel}. * A marker interface implemented by commands that don't dirty the model. * Called at most once in {@link #canExecute} to give the command an opportunity to ready itself for execution. * The returned value is stored in {@link #canExecute}. * In other words, you can override this method to initialize * and to yield a cached value for the all subsequent calls to canExecute. * @return whether the command is executable. * Calls {@link #prepare}, * caches the result in {@link #isExecutable}, * and sets {@link #isPrepared} to <code>true</code>; * from then on, it will yield the value of isExecutable. * @return whether the command can execute. * Returns <code>true</code> because most command should be undoable. * @return <code>true</code>. * Throws a runtime exception. * @exception UnsupportedOperationException always. * Returns an empty list. * @return an empty list. * Returns an empty list. * @return an empty list. * Sets the label after construction. * @param label the new label. * Sets the description after construction. * @param description the new description. * Creates a new compound command, containing this command and the given command, * that delegates chain to {@link CompoundCommand#append}. * @param command the command to chain with this one. * @return a new chained compound command. * Returns an abbreviated name using this object's own class' name, without package qualification, * followed by a space separated list of <tt>field:value</tt> pairs. * @return string representation. * A basic and obvious implementation of an undoable stack of commands. * See {@link Command} for more details about the command methods that this implementation uses. * The list of commands. * The current position within the list from which the next execute, undo, or redo, will be performed. * The command most recently executed, undone, or redone. * The {@link CommandStackListener}s. * The value of {@link #top} when {@link #saveIsDone} is called. * This is called to ensure that {@link CommandStackListener#commandStackChanged} is called for each listener. * Handles an exception thrown during command execution by logging it with the plugin. * Called after a save has been successfully performed. * Returns whether the model has changes since {@link #saveIsDone} was call the last. * @return whether the model has changes since <code>saveIsDone</code> was call the last. * A simple and obvious interface for an undoable stack of commands with a listener. * See {@link Command} for more details about the command methods that this implementation uses * and {@link CommandStackListener} for details about the listener. * Clears any redoable commands not yet redone, adds the command, and then executes the command. * @param command the command to execute. * Returns whether the top command on the stack can be undone. * @return whether the top command on the stack can be undone. * Moves the top of the stack down, undoing what was formerly the top command. * Returns whether there are commands past the top of the stack that can be redone. * @return whether there are commands past the top of the stack that can be redone. * Returns the command that will be undone if {@link #undo} is called. * @return the command that will be undone if {@link #undo} is called. * Returns the command that will be redone if {@link #redo} is called. * @return the command that will be redone if {@link #redo} is called. * Returns the command most recently executed, undone, or redone. * @return the command most recently executed, undone, or redone. * Moves the top of the stack up, redoing the new top command. * Disposes all the commands in the stack. * Adds a listener to the command stack, which will be notified whenever a command has been processed on the stack. * @param listener the listener to add. * Removes a listener from the command stack. * @param listener the listener to remove. * A listener to a {@link org.eclipse.emf.common.command.CommandStack}. * Called when the {@link org.eclipse.emf.common.command.CommandStack}'s state has changed. * @param event the event. * A command that wraps another command. * All the {@link Command} methods are delegated to the wrapped command. * * * There are two typical usage patterns. * One typical use for this command is to modify the behaviour of a command that you can't subclass, i.e., a decorator pattern: *<pre> * Command decoratedCommand = * new CommandWrapper(someOtherCommand) * { * public void execute() * { * doSomethingBeforeExecution(); * super.execute(); * doSomethingAfterExecution(); * } * public Collection getResult() * { * return someOtherResult(); * } * }; *</pre> * The other typical use is to act as a proxy for a command who's creation is delayed: *<pre> * Command proxyCommand = * new CommandWrapper() * { * public Command createCommand() * { * return createACommandSomehow(); * } * }; *</pre> * The command for which this is a proxy or decorator. * Returns the command for which this is a proxy or decorator. * This may be <code>null</code> before {@link #createCommand} is called. * @return the command for which this is a proxy or decorator. * Create the command being proxied. * This implementation just return <code>null</code>. * It is called by {@link #prepare}. * @return the command being proxied. * Returns whether the command can execute. * This implementation creates the command being proxied using {@link #createCommand}, * if the command wasn't given in the constructor. * @return whether the command can execute. * Delegates to the execute method of the command. * Delegates to the canUndo method of the command. * Delegates to the undo method of the command. * Delegates to the redo method of the command. * Delegates to the getResult method of the command. * @return the result. * Delegates to the getAffectedObjects method of the command. * @return the result. * Delegates to the getLabel method of the command. * @return the label. * Delegates to the getDescription method of the command. * @return the description. * Delegates to the dispose method of the command. * A command that comprises a sequence of subcommands. * Derived classes can control the way results are accumulated from the individual commands; * the default behaviour is to return the result of the last command. * The list of subcommands. * When {@link #resultIndex} is set to this, * {@link #getResult} and {@link #getAffectedObjects} are delegated to the last command, if any, in the list. * When {@link #resultIndex} is set to this, * {@link #getResult} and {@link #getAffectedObjects} * are set to the result of merging the corresponding collection of each command in the list. * The index of the command whose result and affected objects are forwarded. * Negative values have special meaning, as defined by the static constants. * A value of -1 indicates that the last command in the list should be used. * We could have more special behaviours implemented for other negative values. * Returns whether there are commands in the list. * @return whether there are commands in the list. * Returns an unmodifiable view of the commands in the list. * @return an unmodifiable view of the commands in the list. * Returns the index of the command whose result and affected objects are forwarded. * Negative values have special meaning, as defined by the static constants. * @return the index of the command whose result and affected objects are forwarded. * @see #LAST_COMMAND_ALL * @see #MERGE_COMMAND_ALL * Returns whether all the commands can execute so that {@link #isExecutable} can be cached. * An empty command list causes <code>false</code> to be returned. * @return whether all the commands can execute. * Calls {@link Command#execute} for each command in the list. * Returns <code>false</code> if any of the commands return <code>false</code> for {@link Command#canUndo}. * @return <code>false</code> if any of the commands return <code>false</code> for <code>canUndo</code>. * Calls {@link Command#undo} for each command in the list, in reverse order. * Calls {@link Command#redo} for each command in the list. * Determines the result by composing the results of the commands in the list; * this is affected by the setting of {@link #resultIndex}. * @return the result. * Returns the merged collection of all command results. * @return the merged collection of all command results. * Determines the affected objects by composing the affected objects of the commands in the list; * this is affected by the setting of {@link #resultIndex}. * @return the affected objects. * Returns the merged collection of all command affected objects. * @return the merged collection of all command affected objects. * Determines the label by composing the labels of the commands in the list; * this is affected by the setting of {@link #resultIndex}. * @return the label. * Determines the description by composing the descriptions of the commands in the list; * this is affected by the setting of {@link #resultIndex}. * @return the description. * Adds a command to this compound command's list of commands. * @param command the command to append. * Checks if the command can execute; * if so, it is executed, appended to the list, and true is returned, * if not, it is just disposed and false is returned. * A typical use for this is to execute commands created during the execution of another command, e.g., * <pre> * class MyCommand extends CommandBase * { * protected Command subcommand; * * //... * * public void execute() * { * // ... * Compound subcommands = new CompoundCommand(); * subcommands.appendAndExecute(new AddCommand(...)); * if (condition) subcommands.appendAndExecute(new AddCommand(...)); * subcommand = subcommands.unwrap(); * } * * public void undo() * { * // ... * subcommand.undo(); * } * * public void redo() * { * // ... * subcommand.redo(); * } * * public void dispose() * { * // ... * if (subcommand != null) * { * subcommand.dispose(); * } * } * } * </pre> * Another use is in an execute override of compound command itself: * <pre> * class MyCommand extends CompoundCommand * { * public void execute() * { * // ... * appendAndExecute(new AddCommand(...)); * if (condition) appendAndExecute(new AddCommand(...)); * } * } * </pre> * Note that appending commands will modify what getResult and getAffectedObjects return, * so you may want to set the resultIndex flag. * @param command the command. * @return whether the command was successfully executed and appended. * Adds a command to this compound command's the list of commands and returns <code>true</code>, * if <code>command.{@link org.eclipse.emf.common.command.Command#canExecute() canExecute()}</code> returns true; * otherwise, it simply calls <code>command.{@link org.eclipse.emf.common.command.Command#dispose() dispose()}</code> * and returns <code>false</code>. * @param command the command. * @return whether the command was executed and appended. * Calls {@link Command#dispose} for each command in the list. * Returns one of three things: * {@link org.eclipse.emf.common.command.UnexecutableCommand#INSTANCE}, if there are no commands, * the one command, if there is exactly one command, * or <code>this</code>, if there are multiple commands; * this command is {@link #dispose}d in the first two cases. * You should only unwrap a compound command if you created it for that purpose, e.g., * <pre> * CompoundCommand subcommands = new CompoundCommand(); * subcommands.append(x); * if (condition) subcommands.append(y); * Command result = subcommands.unwrap(); * </pre> * is a good way to create an efficient accumulated result. * @return the unwrapped command. * A command that always produces the same result. * An empty instance of this object. * Keeps track of the result returned from {@link #getResult}. * Returns <code>true</code>. * @return <code>true</code>. * Do nothing. * Do nothing. * Do nothing. * Return the identity result. * @return the identity result. * A composite command which assumes that later commands in the list * may depend on the results and side-effects of earlier commands in the list. * Because of this, it must implement {@link Command#canExecute} more carefully, * i.e., in order to determine canExecute for the composite, it doesn't simply test each command. * It tests the first command to see if it can execute; * then, if there is another command in the list, it checks if the first command can undo and then goes ahead and executes it! * This process is repeated until the last command that is not followed by another, which then determines the final result. * (For efficiency, when this processing gets to the last command, that command is tested for canUndo too and that result is cached.) * All the commands that have been executed are then undone, if {@link #isPessimistic} is <code>true</code>; * by default it's <code>false</code>. * * * It is important for all but the last command to have no visible side-effect! * Multiple commands with visible side-effects must be composed into a single command using just a {@link CompoundCommand} * and that composite could be the last command of a strict composite. * * * Here is an example of how this can be used in conjunction with a {@link CommandWrapper}. * <pre> * Command strictCompoundCommand = new StrictCompoundCommand(); * Command copyCommand = new CopyCommand(...); * strictCompoundCommand.add(copyCommand); * * Command addCommand = * new CommandWrapper() * { * public Command createCommand() * { * new AddCommand(parent, copyCommand.getResult()); * } * }; * strictCompoundCommand.append(addCommand); * </pre> * Here the add command won't know which command to create until it has the result of the copy command. * The proxy makes sure the creation of the add command is deferred and the strict composite ensures that execution dependencies are met. * The result for {@link Command#canUndo}. * Whether commands that have been tentatively executed need to be undone. * Remember to call redo instead of execute for any command at or before this index in the list. * Returns <code>false</code> if any command on the list returns <code>false</code> for {@link Command#canExecute}, * or if some command before the last one can't be undone and hence we can't test all the commands for executability. * @return whether the command can execute. * Calls {@link Command#execute} for each command in the list, * but makes sure to call redo for any commands that were previously executed to compute canExecute. * In the case that {@link #isPessimistic} is false, only the last command will be executed * since the others will have been executed but not undone during {@link #prepare}. * Calls {@link Command#undo} for each command in the list. * In the case that {@link #isPessimistic} is false, only the last command will be undone * since the others will have been executed and not undo during {@link #prepare}. * Calls {@link Command#redo} for each command in the list. * In the case that {@link #isPessimistic} is false, only the last command will be redone * since the others will have been executed and not undo during {@link #prepare}. * Checks if the command can execute; * if so, it is executed, appended to the list, and <code>true</code> is returned, * if not, it is just disposed and <code>false</code> is returned. * A typical use for this is to execute commands created during the execution of another command, e.g., * <pre> * class MyCommand extends AbstractCommand * { * protected Command subcommand; * * //... * * public void execute() * { * // ... * StrictCompoundCommand subcommands = new StrictCompoundCommand(); * subcommands.appendAndExecute(new AddCommand(...)); * if (condition) subcommands.appendAndExecute(new AddCommand(...)); * subcommand = subcommands.unwrap(); * } * * public void undo() * { * // ... * subcommand.undo(); * } * * public void redo() * { * // ... * subcommand.redo(); * } * * public void dispose() * { * // ... * if (subcommand != null) * { * subcommand.dispose(); * } * } * } * </pre> * @return whether the command was successfully executed and appended. * A singleton {@link UnexecutableCommand#INSTANCE} that cannot execute. * The one instance of this object. * Returns <code>false</code>. * @return <code>false</code>. * Throws an exception if it should ever be called. * @exception UnsupportedOperationException always. * Returns <code>false</code>. * @return <code>false</code>. * Throws an exception if it should ever be called. * @exception UnsupportedOperationException always. * Specification of a transaction in a {@link TransactionalEditingDomain}. All * reading and writing of data in a <code>TransactionalEditingDomain</code> is * performed in the context of a transaction. * * This interface is not intended to be implemented by clients. It is used * internally and by frameworks extending this API. It is mostly of use to * {@link ResourceSetListener}s to find out the state of a transaction in the * event call-backs. * * * @author Christian W. Damus (cdamus) * * @see TransactionalEditingDomain * @see TransactionalCommandStack * @see ResourceSetListener * Option to suppress the post-commit event upon completion of the * transaction. This does not suppress the pre-commit triggers. * * The value is a {@link Boolean}; the default is {@link Boolean#FALSE}. * * Option to suppress the pre-commit event that implements triggers. * This does not suppress the post-commit event. * * The value is a {@link Boolean}; the default is {@link Boolean#FALSE}. * * Option to suppress validation. Note that it does not suppress triggers, * so a transaction could still roll back on commit if a pre-commit * listener throws. * * The value is a {@link Boolean}; the default is {@link Boolean#FALSE}. * * Option to suppress undo/redo recording. This has two effects: it * prevents rollback of the transaction, as this requires the undo * information. It also prevents undo/redo of any {@link RecordingCommand}s * executed in the scope of this transaction. * * The value is a {@link Boolean}; the default is {@link Boolean#FALSE}. * * Option to enable a read/write transaction in the scope of a (nesting) * read-only transaction. Because this option deliberately violates the * read-write exclusion mechanism for model integrity, this option also * suppresses undo recording, triggers, and validation. It does not * suppress post-commit events. * * The value is a {@link Boolean}; the default is {@link Boolean#FALSE}. * * An informational option that tags the transaction as a transaction that * is performing the undo or redo of a command. * * The value is a {@link Boolean}; the default is {@link Boolean#FALSE}. * * Note that this option should not be applied by clients of the * transaction API. Clients may only check to see whether a transaction * has this option, e.g., in a * {@linkplain ResourceSetListener#resourceSetChanged post-commit listener}. * * * @since 1.1 * * Option indicating that a transaction is to validate-edit the resource * that it has modified when it commits, and to roll back if any resources * are not modifiable. * * The value is either a {@link Boolean} indicating whether to validate or * not, or an instance of the {@link ValidateEditSupport} interface that * provides a custom validate-edit implementation. * * * @see ValidateEditSupport * @see #OPTION_VALIDATE_EDIT_CONTEXT * * @since 1.2 * The context object to use when validating edit. This is usually a * <tt>org.eclipse.swt.widgets.Shell</tt> providing a UI context for * interaction with the user. * * @see #OPTION_VALIDATE_EDIT * * @since 1.2 * Queries the editing domain in which I am transacting. Note that this * is available also before I start and after I close. * * @return my editing domain * My parent transaction, if any. The thread that owns an editing domain's * active transaction can create nested transactions simply by starting * new ones. Nested transactions commit differently from top-level * transactions: although they send * {@link ResourceSetListener#transactionAboutToCommit(ResourceSetChangeEvent) pre-commit} * events, they do not send post-commit events, nor are they validated. * Validation is performed only by the top-level transaction to validate * all changes made in its scope, and only the top-level transaction then * can send the post-commit event. Nested transactions can roll back their * changes without affecting their parent transactions. * * Transactions can nest as follows: * * <ul> * <li>read-only transactions can be nested in read-only or * read/write transactions</li> * <li>read/write transactions can only be nested in read/write * transactions</li> * </ul> * @return my parent transaction * Queries the thread that owns me. Only this thread is allowed to read * or write (in the case of read/write transactions) the editing domain's * resource set while I am open. * * @return my owning thread * Queries whether I am a read-only transaction. Even my owning thread * is not permitted to make changes to the model if I am read-only. * * @return <code>true</code> if I am read-only; <code>false</code>, otherwise * Obtains the special options with which I was created. The options * (map keys) are defined by the {@link #OPTION_NO_NOTIFICATIONS Transaction} * interface. * * @return an unmodifiable view of my options * Queries whether I am active. I am active after I have started and * before I have closed (committed or rolled back). * * @return whether I am active * Temporarily yields access to another read-only transaction. The * {@link TransactionalEditingDomain} supports any number of pseudo-concurrent * read-only transactions. Transactions that are expected to be * long-running should yield frequently, as a task running in a progress * monitor is expected to check for cancellation frequently. However, there * is a higher cost (in time) associated with yielding, so it should not * be overdone. * * Only read-only transactions may yield, and only the transaction that * is currently active in the editing domain may yield. The yielding * transaction may be nested, but not within a read/write transaction * at any depth. * * * Upon yielding, some other read-only transaction that is attempting to * start or to return from a yield will take control of the editing domain. * Control is never yielded to a read/write transaction (not even to a * read-only transaction nested in a read/write) because this would * introduce dirty reads (transactions reading uncommitted changes). * If there are no other read-only transactions to receive the transfer of * control, then the call returns immediately. Otherwise, control is * transferred in FIFO fashion to waiting transactions. * * Attempts to commit the transaction. The transaction may only commit if * it is the currently active transaction in the editing domain. After the * transaction has committed, it is no longer active and cannot be started * again. * * Commit proceeds in three phases: pre-commit events and triggers, * validation, and the post-commit events. * * * Pre-commit notifications are sent to the editing domain's registered * {@link ResourceSetListener}s to inform them that the transaction is * committing. If any listener throws a {@link RollbackException}, then * the transaction is rolled back and the exception is propagated to the * caller. Any trigger commands returned by pre-commit listeners are * executed after all listeners are invoked, in a nested transaction. * This nested transaction, then, follows the commit protocol to send out * pre-commit notifications again. This process continues until no more * trigger commands are executed or some listener causes rollback. * * * After all pre-commit processing completes, the transaction is validated. * Validation checks all of the notifications received from the model * during the transaction (including any nested transactions, esp. those * that executed triggers). If the validation yields an error status (or * more severe), then the transaction is rolled back, throwing a * {@link RollbackException} with the validation status. * * * The final phase, if validation passes, is to send out the post-commit * event to the resource set listeners. This event includes all of the * notifications received during the transaction, including triggers. * Note that, because these listeners can read the model, they may cause * further notifications (by resolving proxies, loading resources, etc.). * Listeners are invoked in a nested read-only transaction, so it will * also commit and send out a post-commit event if necessary with additional * notifications. * * * Note that even a {@link #isReadOnly() read-only} transaction can * roll back. This should only occur, however, if it is corrupted by a * concurrent modification by another thread, which means that invalid data * could have been read. * * * @throws RollbackException if a listener or validation caused the * transaction to roll back instead of committing successfully * Rolls back the transaction, undoing all of the pending model changes. * Once it has rolled back, the transaction is no longer active and cannot * be started again. No events are sent when the transaction rolls back; * to listeners it appears that nothing ever happened. * Obtains the change description summarizing the changes made to the model * during the execution of the transaction. The change description must * not be used until after the transaction has successfully committed. * If the transaction rolls back, then it has no change description. * * @return the change description, or <code>null</code> if the transaction * rolled back or is still {@link #isActive() active} * Obtains the status of the transaction. This may provide warning or * or error messages from validation (after I have committed/rolled back) or * other sources, or it might be OK. * * Note that while I am still active, my status is usually OK. * It may not be OK if I have been aborted, in which case I will * roll back on attempt to commit. * * * @return my status, most interesting after I have closed * * An interface that allows clients to query certain meta-data about * transaction options. * * * This interface is not intended to be implemented by clients. Extend the * {@link BasicTransactionOptionMetadata} class, instead. * * * @noimplement This interface is not intended to be implemented by clients. * @noextend This interface is not intended to be extended by clients. * * @author Christian W. Damus (cdamus) * * @since 1.3 * * @see BasicTransactionOptionMetadata * @see Registry * Obtains the key of the option that I describe. This is the key that * would be used in the options map of a transaction. * * @return my option * * Queries whether the option is a tag, meaning that it adorns a * transaction with client-specific information but that it does not * otherwise affect the semantics (or behaviour) of the transaction. * * * Unrecognized options are assumed to be tags, because a transaction * would not be able to interpret their meaning. * * * @return <code>true</code> if the option key is a tag option or if it * is not recognized by this meta-data instance; * <code>false</code> if it is recognized and is known not to be * a tag * * Queries whether the option is inherited by nested transactions. * * * Unrecognized options are assumed to be inherited. * * * @return <code>true</code> if the option is inherited or if it is not * recognized; <code>false</code> if it is not inherited * * Obtains the type value of an option. * * * The type of an unrecognized option is assumed to be {@link Object}. * * * @return the default value of the option, or <code>Object</code> if it * is not known * * Obtains the default value of an option. * * * The default value of an unrecognized option is assumed to be * <code>null</code>. * * * @return the default value of the option, or <code>null</code> if it * is not known * Gets the value (implicit/default or explicit) of my option in the * specified map. * * @param options * an options map * * @return my value in the map * Queries whether the specified map has a setting for my option. * * @param options * an options map * @return whether it has a setting for my option * Queries whether the specified options maps have the same value of my * option, whether that be implicit or explicit. That is, this method * accounts for default values and such complex cases as the * {@link Transaction#OPTION_VALIDATE_EDIT} in which values of two * different types may mean the same thing. * * @param options1 * an options map * @param options2 * another options map * * @return whether the two maps have the same setting of my option * Updates the options map of a child transaction to inherit the setting * in a parent transaction, if it is a hereditary option and the child * does not already have a setting for it. * * @param parentOptions * the options map to inherit a value from. It is conceivable * that inheritance of an option may depend on more than one * option in this parent map * @param childOptions * the map that is to inherit the option setting * @param force * whether to inherit the option anyway despite that it is * not hereditary. This is used for application of default * options, and can be ignored by the implementor if * necessary. Also, clients must not use this parameter to * attempt to override an existing child setting; a * well-behaved option will not do that * * A registry of metadata describing transaction options. The default * implementation of the {@link TransactionalEditingDomain} interface * provides a transaction option registry as an adapter. Access to the * registry is thread-safe. * * * This interface is not intended to be implemented by clients. * * * @noimplement This interface is not intended to be implemented by * clients. * @noextend This interface is not intended to be extended by clients. * * @author Christian W. Damus (cdamus) * * @since 1.3 * The shared transaction option metadata registry. * Obtains a metadata object describing the specified transaction * option. For unrecognized options, a default meta-data is provided * that gives reasonable answers. * * @param option * an option key * @return the option meta-data (never <code>null</code>) * Internal interface that must be provided by any implementation of the public * {@link TransactionalEditingDomain} API, in order to function correctly in the transactional * editing domain framework. * * @author Christian W. Damus (cdamus) * Creates and starts a new transaction. The current thread is blocked * until I grant it exclusive access to my resource set. * * @param readOnly <code>true</code> if the transaction is intended only * to read the resource set; <code>false</code> if it will modify it * @param options the options to apply to the transaction (as specified by * the {@link TransactionalCommandStack} interface * * @return the newly started transaction * * @throws InterruptedException if the current thread is interrupted while * waiting for the transaction to start * @throws IllegalArgumentException if the current thread does not * {@link Transaction#getOwner() own} the transaction that it wants * to start or if it is attempting to start a transaction in an * inappropriate context * * @see #activate(InternalTransaction) * Obtains the transaction that currently has access to me, and whose * thread of execution is active. * * @return my active transaction, or <code>null</code> if no transaction * is currently active * Activates (starts) the specified transaction. The current thread is * blocked until the transaction is activated, at which point it will be * my {@linkplain #getActiveTransaction() active transaction} until it either * yields (in the case of a read-only transaction) or closes. * * Note that only the thread that owns a transaction may activate it. Also, * a nested read-write transaction cannot be activated if its parent * transaction is read-only, unless the read-write transaction has the * {@linkplain Transaction#OPTION_UNPROTECTED 'unprotected' option}. * * * @param tx the transaction to activate * * @throws InterruptedException if the current thread is interrupted while * waiting for me to activate its transaction * @throws IllegalArgumentException if the current thread does not * {@linkplain Transaction#getOwner() own} the transaction that it wants * to activate or if it is attempting to activate a transaction in an * inappropriate context * * @see #getActiveTransaction() * @see TransactionalEditingDomain#yield() * @see #startTransaction(boolean, Map) * @see #deactivate(InternalTransaction) * Performs the pre-commit notifications and processing of trigger comamnds. * This method must be called at the beginning of the * {@linkplain Transaction#commit() commit} of a read/write transaction (not a * read-only transaction), unless it has the * {@linkplain Transaction#OPTION_NO_TRIGGERS 'no triggers' option}. * * @param tx the transaction that is being committed * * @throws RollbackException if any of the pre-commit listeners forces * rollback of the transaction. The caller must honour this rollback * request by actually {@linkplain Transaction#rollback() rolling back} * the transaction * * @see Transaction#commit() * @see Transaction#rollback() * @see ResourceSetListener#transactionAboutToCommit(org.eclipse.emf.transaction.ResourceSetChangeEvent) * Deactivates the specified transaction. After this method completes, the * transaction is no longer my * {@link #getActiveTransaction() active transaction}. * * The current thread must own the transaction that it is attempting to * deactivate and this transaction must currently be my active transaction. * * * Note that a transaction must ensure that this method is * called when it closes, either by commit or by rollback, and at most once. * * * @param tx the transaction to deactivate * * @throws IllegalArgumentException if either the transaction is not the * active transaction, or the current thread does not own it * * @see #activate(InternalTransaction) * @see Transaction#commit() * @see Transaction#rollback() * Obtains the change recorder that I use to track changes in my resource * set. Transactions are expected to use this change recorder as follows: * <ul> * <li>Start recording a fresh change description on * {@linkplain InternalTransaction#start() starting} and * {@linkplain InternalTransaction#resume(org.eclipse.emf.transaction.TransactionChangeDescription) resuming}</li> * <li>End recording (storing the change description) on * {@linkplain Transaction#commit() committing} and * {@linkplain InternalTransaction#pause() pausing}</li> * <li>End recording (applying the change description) on * {@linkplain Transaction#rollback() rolling back}</li> * </ul> * * @return my change recorder * Gets the validator that transactions should use to validate themselves * upon committing. A transaction must ask the validator to validate after * performing the pre-commit phase (if needed), unless it has the * {@linkplain Transaction#OPTION_NO_VALIDATION 'no validation' option}. * * @return my transaction validator * Broadcasts the specified notification to listeners as a singleton list, * in a situation where batching is not possible because events are * occurring outside of any transaction context. This can only occur in * the case of {@linkplain NotificationFilter#READ read notifications}. * * @param notification the notification to send to resource set listeners * * @see NotificationFilter#READ * @see ResourceSetListener * @see FilterManager#selectUnbatched(java.util.List, NotificationFilter) * Retrieves the undo/redo options that should be used when creating * transactions. * * @return A map with undo/redo options. * Transfers ownership of this editing domain to the specified * privileged runnable. * * @param runnable the runnable whose thread is to borrow me * Returns me to my previous owner, upon completion of the specified * privileged runnable. * * @param runnable the runnable whose thread had borrowed me * Partial implementation of the {@link TransactionalCommandStack} interface, * useful for subclasses to define their specific handling of transactions and * other concerns. * * @author Christian W. Damus (cdamus) * * @since 1.1 * Ensures that the specified transaction is rolled back, first rolling * back a nested transaction (if any). * * @param tx a transaction to roll back * Extends the inherited method by first aborting the active * transaction (if any) and passing the exception along to * the registered exception handler (if any). * Does the specified exception indicate that the user canceled execution, * undo, or redo of a command? * * @param exception an exception * @return <code>true</code> if it is an {@link OperationCanceledException} * or a {@link RollbackException} that was caused by operation cancel * Default implementation delegates to the subclass implementation of * {@link #doExecute(Command, Map)}, handling the roll-back exception if the * command is rolled back. Note that <code>doExecute()</code> is only * called if the command is {@linkplain Command#canExecute() executable}. * Implemented by subclasses to perform the execution of the specified * <code>command</code>. Invoked by the {@link #execute(Command, Map)} * method. * * @param command the command to execute * @param options the transaction options to apply to execution of the command * * @throws InterruptedException if the current thread is interrupted while * waiting to start the transaction * @throws RollbackException if the execution of the command is rolled back * Handles the roll-back of the specified <code>command</code> execution. * This default implementation disposes the command and notifies * command-stack listeners so that they may get the latest information, in * case they were already notified of command execution, for example. * * @param command the command whose execution was rolled back (may be * <code>null</code> if not known) * @param rbe the roll-back exception (may be <code>null</code> if no * exception is to be thrown) * Redefines the inherited method by forwarding to the * {@link TransactionalCommandStack#execute(Command, Map)} method. Any * checked exception thrown by that method is handled by * {@link #handleError(Exception)} but is not propagated. * Provides access to the {@link BasicCommandStack} implementation of the * {@link #execute(Command)} method, as this class overrides it to delegate * to the {@link TransactionalCommandStack#execute(Command, Map)} method. * * @param command the command to execute * Obtains my editing domain's default undo/redo transaction options. * * @return my editing domain's transaction options for undo/redo * Customizes the specified <code>options</code> for the case of a transaction * that executes trigger commands. The original map is not affected. * * @param options a client-supplied options map * @return a derived map of options suitable for trigger transactions * An internal interface that must be provided by any implementation of the public * {@link TransactionalCommandStack} interface, in order to function correctly in the * transactional editing domain framework. * * @author Christian W. Damus (cdamus) * Obtains the editing domain in which I create transactions. * * @return my editing domain * * @see #createTransaction(Command, Map) * Assigns the editing domain in which I create transactions. * * @param domain my editing domain * * @see #createTransaction(Command, Map) * Creates a read/write transaction in my editing domain for the purpose * of executing the specified command. The resulting transaction is * expected to be started when it is returned (hence the possibility of * interruption). * * @param command a command that I need to execute * @param options the options to apply to the resulting transaction * @return the command transaction * * @throws InterruptedException if the current thread is interrupted while * waiting for the transaction to start * * @see #getDomain() * Executes the specified list of trigger commands. All of the commands are * executed within a single child transaction of the transaction that executed * the triggering <code>command</code>; they must not be "piggy-backed" on * the currently active transaction. * * @param command the command whose execution triggered additional commands * (from pre-commit listeners) * @param triggers a list of zero or more {@link Command}s to execute. * If there are none, then no transaction needs to be started * @param options the options to apply to the child transaction * * @throws InterruptedException if the current thread is interrupted while * waiting for the trigger transaction to start * @throws RollbackException if the trigger transaction rolls back on commit * * @see ResourceSetListener#transactionAboutToCommit(org.eclipse.emf.transaction.ResourceSetChangeEvent) * @see #createTransaction(Command, Map) * Disposes of my state and any additional resources that I may be * retaining. I am only disposed when my {@link #getDomain() editing domain} * is disposed. * A transaction implementation use by the command stack to wrap the execution * of {@link Command}s, to provide them the write access that they need. * The transaction knows the {@link #getCommand() command} that it is * servicing. * * @author Christian W. Damus (cdamus) * Obtains the command for which I provide read/write access to the * editing domain. * * @return my command * Given the specified options and command, computes an options map that * has the same options as those provided, plus the specified command as * the executing-command option. * * @param options a map of options * @param command the command that we are executing in this transaction * @return a new map of options that increments those supplied with the * appropriate executing-command option * The default transaction implementation. * * @author Christian W. Damus (cdamus) * This option, when provided to a transaction that inherits from this implementation * class and has children transactions that are using this implementation class, * provides an optional block of the normal propagation of change descriptions * to the parent transaction by any transaction in the child subtree of this transaction. * The child exercises its option to negate the propagation of change descriptions by * adding the {@link #BLOCK_CHANGE_PROPAGATION} option to its own options with * the value of {@link Boolean#TRUE}. This option IS inherited by child transactions. * This option blocks the propagation of change descriptions to the parent transaction. The option * has no effect unless the parent transaction has allowed this negation to happen by having the * {@link #ALLOW_CHANGE_PROPAGATION_BLOCKING} option added either directly or through * option inheritance. Note that to enable this option it must be added to the options map with * the value of {@link Boolean#TRUE}. This option is NOT inherited by child transactions. * An informative option that tags the transaction as a transaction that is * executing trigger commands. * An internal option that identifies the {@link Command} that a transaction * was created to execute, in the case that it is an * {@link EMFCommandTransaction}. * * @since 1.3 * The transaction options that should be used when undoing/redoing changes * on the command stack. Undo and redo must not perform triggers because * these were implemented as chained commands during the original execution. * Moreover, validation is not required during undo/redo because we can * only return the model from a valid state to another valid state if the * original execution did so. Finally, it is not necessary to record * undo information when we are undoing or redoing. * * As of the 1.2 release, this map is immutable. * * Obtains the life-cycle adapter, if any, of my editing domain, with which * I will notify it of my lifecycle events. * * @return my domain's lifecycle adapter, or <code>null</code> if my editing * domain does not provide one * * @since 1.3 * Queries whether I have been aborted. * * @return <code>true</code> if I have been aborted; <code>false</code>, otherwise * * @see InternalTransaction#abort(IStatus) * Produces a status object combining live-validation status with * validate-edit status. * * @param validationStatus a live-validation status, or <code>null</code> * if validation is disabled * @param editStatus a validate-edit status, or <code>null</code> if it is * not enabled * * @return an appropriate status, which may even by OK just because both * inputs are <code>null</code> * Obtains my owning editing domain as the internal interface. * * @return the internal view of my editing domain * Starts recording changes upong activation or resumption from a child * transaction, unless undo recording is disabled by my options. * Stops recording changes and adds them to my composite change description, * unless undo recording is disabled by my options. * Closes me. This is the last step in committing or rolling back, * deactivating me in my editing domain. Also, if I have a parent * transaction, I {@link InternalTransaction#resume(TransactionChangeDescription) resume} * it. * * If a subclass overrides this method, it must ensure that this * implementation is also invoked. * * Validates me. Should only be called during commit. * * @return the result of validation. If this is an error or worse, * then I must roll back * Queries whether the specified transaction should record undo information, * according to its {@link Transaction#getOptions() options} and * {@link Transaction#isReadOnly() read-only state}. * * @param tx a transaction * @return <code>true</code> if the transaction should record undo * information; <code>false</code>, otherwise * Queries whether the specified transaction should validate changes, * according to its {@link Transaction#getOptions() options} and * {@link Transaction#isReadOnly() read-only state}. * * @param tx a transaction * @return <code>true</code> if the transaction should validate * changes; <code>false</code>, otherwise * Queries whether the specified transaction should invoke pre-commit, * listeners, according to its {@link Transaction#getOptions() options} and * {@link Transaction#isReadOnly() read-only state}. * * @param tx a transaction * @return <code>true</code> if the transaction should perform the pre-commit * procedures; <code>false</code>, otherwise * Queries whether the specified transaction should send post-commit events, * according to its {@link Transaction#getOptions() options}. * * @param tx a transaction * @return <code>true</code> if the transaction should send post-commit * events; <code>false</code>, otherwise * Queries whether the specified transaction is an unprotected write, * according to its {@link Transaction#getOptions() options} and * {@link Transaction#isReadOnly() read-only state}. * * @param tx a transaction * @return <code>true</code> if the transaction is an unprotected write * transaction; <code>false</code>, otherwise * Queries whether the specified transaction collects notifications for * broadcast to listeners or for validation. This is determined by * the transaction's options. * * @param tx a transaction * * @return <code>true</code> any of notification, triggers, and validation * are enabled; <code>false</code>, otherwise * * @see #isNotificationEnabled(Transaction) * @see #isTriggerEnabled(Transaction) * @see #isValidationEnabled(Transaction) * Queries whether the specified transaction has a boolean option. * * @param tx a transaction * @param option the boolean-valued option to query * @return <code>true</code> if the transaction has the option; * <code>false</code> if it does not * Obtains the default transaction options, if any, of the specified editing * domain. * * @param domain an editing domain * @return its default transaction options, or an empty map if none are * defined * * @since 1.2 * The editing domain manager initializes editing domain instances from the * <code>org.eclipse.emf.transaction.editingDomains</code> extension point. * It also configures listeners from the * <code>org.eclipse.emf.transaction.listeners</code> point. * * @author Christian W. Damus (cdamus) * Gets the singleton instance. * * @return the instance * Creates the editing domain registered on the extension point under the * specified <code>id</code>, if an appropriate extension exists. * * @param id the editing domain ID to initialize * * @return the corresponding editing domain, or <code>null</code> if no * such extension was found * Queries whether the specified editing domain ID is statically registered * on our extension point. * * @param id the domain ID to query * * @return whether it is statically registered * Asserts that the specified editing domain ID is dynamically registered, * not statically registered on the extension point. * * @param id * the ID of an editing domain * * @throws IllegalArgumentException * if the specified ID is statically registered * * @since 1.3 * Creates (if necessary) listeners registered against the specified * editing domain ID and and adds them to it. Note that this includes * listeners registered against all domains (by not specifying an ID). * * At most a single instance of any registered listener is created. * * * @param id the editing domain ID * @param domain the editing domain to which to add the listeners * Removes from the editing domain the listeners that are registered against * its ID. Note that this includes * listeners registered against all domains (by not specifying an ID). * * @param id the editing domain ID * @param domain the editing domain from which to remove the listeners * Retrieves the configuration element for the extension providing * the specified domain ID. * * @param id the domain ID to retrieve * @return the corresponding configuration element, or <code>null</code> if this * ID is not registered on the extension point * Retrieves the configuration elements for listeners registered on the specified * editing domain ID. This includes listeners that are registered against all * editing domains. * * @param id the domain ID to retrieve * @return the configuration elements for listeners registered to this ID * Retrieves the configuration elements for listeners that are registered on all * editing domains. * * @return the configuration elements for universal listeners * Initializes a listener from the extension point configuration element. * The <code>create</code> argument determines whether to lazily create the * listener; it should be <code>true</code> when adding listeners to editing * domains and <code>false</code> when removing them. * * @param config the configuration element * @param create if the listener does not exist yet, create it * @return the listener, or <code>null</code> if either the configuration is * invalid or <code>create = false</code> and the listener does not yet exist * An object that manages the filtering of notifications. This class can implement * optimizations to reduce the effort of filtering notification lists for listeners * that have similar filters. * * @author Christian W. Damus (cdamus) * Obtains the singleton instance of this class. * * @return the singleton instance * Selects the notifications in the given list that match the specified * filter. * * For unbatched notifications, it is better to use the * {@link #selectUnbatched(List, NotificationFilter)} method. * * * @param notifications a list of notifications to select from * @param filter a notification filter * @param cache A cache list that is precisely the same size as the notifications * list but is used and reused as a scratch pad. Its purpose is to cut down the * number of objects created and garbage collected while propagating filtered * events to a group of listeners. Note that it will be repeatedly cleared and * populated each time it is given to this method. * * @return the notifications that match the filter * * @see #selectUnbatched(List, NotificationFilter) * Selects the notifications in the given list that match the specified * filter. * * For unbatched notifications, it is better to use the * {@link #selectUnbatched(List, NotificationFilter)} method. * * * @param notifications a list of notifications to select from * @param filter a notification filter * * @return the notifications that match the filter * * @see #selectUnbatched(List, NotificationFilter) * Selects the notifications in the given singleton list of an unbatched * notification that match the specified filter. The result is, thus, * either an empty list or the original list back again. * * This method is more efficient for processing unbatched notifications than * is the {@link #select(List, NotificationFilter)} method. * * * @param notification a singleton list containing the unbatched * notification * @param filter a notification filter * * @return the original list or an empty list, according to the filter * * @see #select(List, NotificationFilter) * * Internal adapter interface that must be provided by a * {@link TransactionalEditingDomain} implementation that provides a * {@link Lifecycle} adapter. It is required by transactions, to send their * life-cycle notifications. * * This interface is not intended to be implemented by clients, but by * editing domain providers. * * * @author Christian W. Damus (cdamus) * * @see TransactionalEditingDomain.Lifecycle * * @since 1.3 * Notifies me that a transaction has commenced its start sequence. There * may be any number of steps implemented before requesting the editing * domain to * {@linkplain InternalTransactionalEditingDomain#activate(InternalTransaction) * activate} it. * * @param transaction * a transaction that is starting * Notifies me that a transaction has been interrupted in its start * sequence. There may be any number of steps implemented by the transaction * that can be interrupted. * * @param transaction * a transaction thatwas interrupted while starting * Notifies me that a transaction has completed its start sequence. There * may be any number of steps implemented after requesting the editing * domain to * {@linkplain InternalTransactionalEditingDomain#activate(InternalTransaction) * activate} it. * * @param transaction * a transaction that has started * Notifies me that a transaction has commenced its commit or rollback * sequence. There may be any number of steps implemented before requesting * the editing domain to * {@linkplain InternalTransactionalEditingDomain#deactivate(InternalTransaction) * deactivate} it. * * @param transaction * a transaction that is closing * Notifies me that a transaction has completed its commit or rollback * sequence. There may be any number of steps implemented after requesting * the editing domain to * {@linkplain InternalTransactionalEditingDomain#deactivate(InternalTransaction) * deactivate} it. * * @param transaction * a transaction that has closed * An internal interface that must be provided by any implementation of the * public {@link Transaction} interface, in order to function correctly in * the transactional editing domain framework. * * @author Christian W. Damus (cdamus) * Obtains the root transaction (the one that has no parent). This could * be me if I am the root. * * @return the root transaction in a nested transaction structure * Assigns my parent transaction (the one in which I am nested). This * must be done by the editing domain immediately upon activating me. * * @param parent my parent transaction * Starts me. Usually, this will delegate to the editing domain * to {@link InternalTransactionalEditingDomain#activate(InternalTransaction) activate} * me. * * Note that this call should block the current thread until the * editing domain grants exclusive access. * * * @throws InterruptedException if the current thread is interrupted while * waiting for activation * Aborts the transaction with a reason given by the specified status. This is * used, for example, when a transaction is corrupted by another thread * concurrently writing the model (obviously without an active transaction!). * The transaction is expected to rollback when it attempts to commit, and to * propagate this status up to the root transaction. * * @param status a status object providing the reason. It should be the status * attached to the eventual {@link RollbackException}, and should be * set as my {@link #setStatus(IStatus) status} * Adds the specified notification to the list of notifications received * during this transaction. * * @param notification the notification to add * * @see #getNotifications() * Obtains the list of notifications that were received during execution * of this transaction. These are the notifications that later will * be sent to pre-commit listeners, validation, and eventually to * post-commit listeners (if I successfully commit). * * @return my notifications * * @see #add(Notification) * Pauses me while a child transaction is active, so that I do not collect * either notifications or recorded changes during that time. * Resumes me after completion of a child transaction. If the child * committed, then I add its change description to my changes. * * @param nestedChanges the nested transaction's recorded changes, or * <code>null</code> if it rolled back (in which case, I do not add * anything to my changes) * Sets the status of the transaction. * * @param status my status * Queries whether this transaction or any of its ancestors is in the * process of rolling back. * * @return <code>true</code> if I or my * {@link Transaction#getParent() parent} (if any) am rolling back; * <code>false</code> otherwise * Obtains the triggers that were executed during my commit. * * @return my pre-commit trigger commands, or <code>null</code> if I have * no triggers (perhaps because the {@link Transaction#OPTION_NO_TRIGGERS} * was applied). This may be a single {@link Command} or a * compound of multiple * Adds a group of triggers that were executed during my commit. * * @param triggers the triggers to add * Transfers ownership of this transaction to the specified * privileged runnable. * * @param runnable the runnable whose thread is to borrow me * Returns me to my previous owner, upon completion of the specified * privileged runnable. * * @param runnable the runnable whose thread had borrowed me * Implementation of the privileged runnable, which allows a thread to lend * its transaction to another cooperating thread for synchronous execution. * * @param <T> the result type of the runnable * * @author Christian W. Damus (cdamus) * Obtains the transaction to which I provide access. * * @return my transaction * Obtains the thread that created and owns me. This thread is the * original owner of my {@linkplain #getTransaction() transaction}. * * @return my owner * Runs my delegate in the context of the transaction that I share. * The change recorder for a {@link org.eclipse.emf.transaction.TransactionalEditingDomain}, * used by transactions to record rollback information and to detect changes that * violate the transaction protocol. It also forwards notifications to the * domain's currently active transaction. * * @author Christian W. Damus (cdamus) * * @see InternalTransactionalEditingDomain#getChangeRecorder() * @see TransactionValidator * @see InternalTransaction#add(Notification) * Obtains the editing domain that I assist. * * @return my editing domain * Starts recording changes in my editing domain. * * @throws IllegalStateException if I have been {@link #dispose() disposed} * Extends the inherited implementation to clear the reference to the * change description returned. * * @throws IllegalStateException if I have been {@link #dispose() disposed} * Overrides the superclass method to * <ul> * <li>ignore the "originalTargetObjects" since we never resume recording * a paused change description</li> * <li>ignore the "targetObjects" because we will never find, upon * upon consolidating changes, that any target object is unexpectedly * orphaned (as we always listen to everything in the resource set, * so will always get the appropriate removal notifications). Also, * because we manage an entire resource set on behalf of an editing * domain, disposal by removing ourselves from the adapters lists of * our targets is not an issue because we cannot cause a memory leak * outside of the scope of the editing domain and its resource set</li> * </ul> * Detects whether the change indicated by the specified notification * violates the transaction protocol and/or how it changes the load state of * a resource (if it all), in addition to recording the change (if I am * currently recording) and passing it along to the domain's current * transaction (if any). * Analyzes a resource set notification for changes in the load state of * resources and violations of the transaction protocol before passing it * to the active transaction (if any). * * @param notification a notification from the resource set * Analyzes a resource notification for changes in its load state * and violations of the transaction protocol before passing it * to the active transaction (if any). * * @param notification a notification from a resource * Analyzes an object notification for violations of the transaction * protocol before passing it to the active transaction (if any). * * @param notification a notification from a model element * Appends the specified notification to the batch for the active * transaction, to be distributed when it commits. If there is no * active transaction, then it is sent immediately to post-commit * listeners (unbatched). This method applies the read/write transaction * protocol check to this notification. * * @param notification the notification to append * * @throws IllegalStateException if the notification is not a result of * reading the resource set and no transaction is active or the * active transaction is read-only * Implements the read/write transaction protocol check. * * @throws IllegalStateException if no transaction is active or the * active transaction is read-only * Temporarily pauses the recording of the current change description. * * @throws IllegalStateException if I am not currently recording * * @see ChangeRecorder#isRecording() * @see #isPaused() * @see #resume() * Queries whether I am currently paused in my recording. * * @see ChangeRecorder#isRecording() * @see #pause() * @see #resume() * Resumes the paused recording of the current change description. * * @throws IllegalStateException if I am not currently paused * * @see ChangeRecorder#isRecording() * @see #pause() * @see #isPaused() * Extends the inherited implementation to remove myself from all adapters * that I can find in my editing domain. * * @since 1.1 * Sets my validate-edit support, if applicable, for the duration of a * root transaction. * * @param validateEdit my validate-edit support, or <code>null</code> * * @since 1.2 * Interface for an object that validates a transaction when it commits. * Different implementations are provided for read and for write transactions. * * @author Christian W. Damus (cdamus) * * @see ReadOnlyValidatorImpl * @see ReadWriteValidatorImpl * @see Transaction#commit() * A "null" instance that is suitable for use when there is no active * transaction. It does not provide any notifications, nor does it validate * anything. * Adds a transaction for eventual validation. Transactions must be added * to the editing domain's current validator as soon as they are activated, * so that it does not miss any notifications. * * @param transaction the transaction (root or a nested transaction) to add * Removes a transaction that has rolled back. Transactions must be removed * as soon as they roll back. Removal ensures that we do not pass to the * resource set listeners any notifications of changes that were rolled back. * * Note that, for efficiency, transactions that have successfully committed * should also be removed after they have been deactivated. This ensures * that they are no longer referenced by validator and can, therefore, be * reclaimed (the validator retains the notifications, only). * * * @param transaction the transaction (root or a nested transaction) to remove * Performs the validation step of a commit. * * @param tx the transaction to validate * * @return the status of validation. If the severity is error or worse, * then the transaction must roll back, and this status * included in the exception * * @see Transaction#commit() * @see RollbackException * Obtains the notifications received, in order, during the execution of * the (possibly nested) transaction(s) that I am validating. * * @param tx the transaction to be validated * * @return the transaction's notifications, or <code>null</code> if the * transaction has not started yet * Obtains the notifications that I need to broadcast in a pre-commit * resource-change event for the specified transaction. Note that this * does not include notifications from "no-triggers" transactions. * * @param tx the transaction to be broadcast * * @return those of the transaction's notifications that are eligible to * be broadcast, or <code>null</code> if the transaction has not started * Obtains the notifications that I need to broadcast in a post-commit * resource-change event for the specified transaction. Note that this * does not include notifications from "silent" transactions. * * @param tx the transaction to be broadcast * * @return those of the transaction's notifications that are eligible to * be broadcast, or <code>null</code> if the transaction has not started * Disposes me by clearing my state and cleaning up any resources that I * am retaining. * Interface that clients implement to define a validator factory. * * @since 1.1 * * @author David Cummings (dcummin) * The shared default implementation of the validator factory interface. * Creates and returns a <code>TransactionValidator</code> which is * used to validate a read write transaction. * * @since 1.1 * * @return the transaction validator that will validate the * read write transaction * Creates and returns a <code>TransactionValidator</code> which is * used to validate a read only transaction. * * @since 1.1 * * @return the transaction validator that will validate the * read only transaction * A validator for read-only transactions. It provides all of the notifications * (in order) that occurred during the transaction, but does not validate them * (validation always passes with no problems). * * A read-only validator should be created for the root transaction of any * nested read-only transaction structure, when the root transaction is * activated. As child transactions are activated, they must be * {@link #add(InternalTransaction) added} to me so that I may correctly track * which notifications were received during which transaction, and at which * time relative to the start and completion of nested transactions. * * * @author Christian W. Damus (cdamus) * * @see ReadWriteValidatorImpl * I always return an OK status because there is never anything to validate * in a read-only transaction. * * @return an OK status, always * A validator for read/write transactions. It provides all of the notifications * (in order) that occurred during the transaction, and validates them to detect * changes that would violate model integrity. * * A read/write validator should be created for the root transaction of any * nested read/write transaction structure, when the root transaction is * activated. As child transactions are activated, they must be * {@link #add(InternalTransaction) added} to me so that I may correctly track * which notifications were received during which transaction, and at which * time relative to the start and completion of nested transactions. * * * Whenever a transaction (nested or otherwise) is rolled back, it must be * {@link #remove(InternalTransaction) removed} from me so that I may forget * the notifications received for any changes that it or its nested transactions * made. * * * @author Christian W. Damus (cdamus) * * @see ReadOnlyValidatorImpl Bit indicating that we are collecting notifications for validation. Bit indicating that we are collecting notifications for pre-commit. Bit indicating that we are collecting notifications for post-commit. * A tree mirroring the nesting structure of transactions. The tree * records, for every transaction: * <ul> * <li>the notifications (by directly referencing the mutable * notification list)</li> * <li>tree nodes for corresponding to the the children of the transaction * (transactions otherwise only know their parents)</li> * <li>the number of notifications in the parent transaction that * preceded its activation, if it has a parent</li> * <li>a bit mask indicating which kinds of notifications (pre/post commit * and validation) the transaction provides</li> * </ul> * * The third item above is important in reconstructing the complete * ordering (in linear time) of the notifications received during nesting * transactions, so that both validation and post-commit listeners get * the correct sequence of events. * * * @author Christian W. Damus (cdamus) * Adds a child transaction to me. If this transaction has no parent, * then it is the root transaction. * * @param child the child transaction to add * @param notificationMask a mask of the {@link #POSTCOMMIT}, {@link #PRECOMMIT}, and * {@link #VALIDATION} bits of the kinds of notifications that the * transaction collects * Obtains my child nodes, storing the notifications from my * transaction's children. * * @return my children * Collects all of the notifications from me and my children, in the * correct time-linear order. * * @param purpose a bit indicating what kind of notifications * to collect (for what purpose we are collecting them) * * @return my notifications (which might be an empty list) * * @see ReadWriteValidatorImpl#VALIDATION * @see ReadWriteValidatorImpl#PRECOMMIT * @see ReadWriteValidatorImpl#POSTCOMMIT * Recursive implementation of the {@link #collectNotifications()} method. * * @param notifications the accumulator list * @param purpose a bit indicating what kind of notifications * to collect (for what purpose we are collecting them) * * @see #collectNotifications() * Indicates that my transaction has been rolled back. This will * reduce the list of notifications that I store to only those indicating * changes that rollback did not revert (i.e., resource-level changes * that are not semantic changes, such as resource load/unload, URI * change, etc.). * Determines whether the specified notification indicates an undoable * change to a model element. This filters out non-model changes such * as changes to the modification/loaded state of resources, their * URIs, etc. * * @param notification a notification * @return <code>true</code> if it represents an undoable change to an * object or a resource (the contents list, in particular) * Obtains my corresponding transaction's notifications. * * @return my notifications * Detaches the node from its transaction. * Adds the specified transaction to me for validation. This must be called * when the transaction is activated. * Removes the specified transaction from me. This must be called * when the transaction is rolled back, and is recommended also after a * successful commit. * Finds the specified transaction's corresponding node in the notification * tree structure that I maintain. * * @param tx the transaction to search for * * @return the corresponding notification tree node, or * <code>null</code> if this transaction has not yet been added to me * or has already completed (in which case, it is no longer in my map) * Creates a validator which will be responsible for the transaction validation * * @since 1.1 * * @return the validator * Computes a mask of notification kinds that the specified transaction * supports. The notification kinds indicate which functions that use * notifications are enabled for the transaction. * * @param transaction a transaction * @return a mask of the {@link #POSTCOMMIT}, {@link #PRECOMMIT}, and * {@link #VALIDATION} bits * The resource set manager keeps track of the load state of {@link Resource}s * in a resource set managed by a transactional editing domain. It assists in * the enforcement of write transaction semantics for certain kinds of changes * to the state of a resource (in particular, its contents). * * The resource set manager is a singleton rather than a per-editing-domain * instance primarily because the notification filters need to be able to * distinguish events coming from loading/unloading resources, and filters do * not have any editing domain context. This is not a problem, as the resources * are tracked by their object identity, so their states are absolute, not * relative to any particular editing domain. * * * @author Christian W. Damus (cdamus) * Obtains the singleton manager instance. * * @return the singleton instance * Observes the specified resource set, usually only when the editing domain * is initialized. This resource set may already contain resources in a * variety of states, so I will examine each of them in turn and record * their states. * * @param rset a resource set * Analyzes a notification from a resource set for any potential state * changes in its resources. * * @param rset a resource set sending a notification * @param notification the notification from the resource set * Analyzes the current state of a resource. * * @param res a resource to analyze * Analyzes a notification from a resource for any potential state change. * * @param res a resource * @param notification the notification from the resource * Queries whether the specified resource is currently loaded. * * @param res a resource * @return <code>true</code> if the resource has completed loading and is * not now unloading; <code>false</code>, otherwise * Queries whether the specified resource is currently loading. * * @param res a resource * @return <code>true</code> if the resource is not yet loaded but is in * the process of loading; <code>false</code>, otherwise * Queries whether the specified resource is currently unloading. * * @param res a resource * @return <code>true</code> if the resource is loaded but is in * the process of unloading; <code>false</code>, otherwise * Queries whether the specified resource is currently unloaded. * * @param res a resource * @return <code>true</code> if the resource has completed unloading and is * not now loading; <code>false</code>, otherwise * Records the specified resource's state as 'loaded'. * * @param res a loaded resource * Records the specified resource's state as 'loading'. * * @param res a loading resource * Records the specified resource's state as 'unloading'. * * @param res an unloading resource * Records the specified resource's state as 'unloaded'. * * @param res an unloaded resource * The default implementation of the transactional editing domain command stack. * * @author Christian W. Damus (cdamus) * {@inheritDoc} * * @since 1.1 * Extends the superclass implementation to first pop the failed command * off of the stack, if it was already appended. * * @since 1.1 * Extends the inherited implementation by invoking it within the context of * an undo transaction (a read/write transaction with the * {@link #getUndoRedoOptions() undo/redo options}). * Extends the inherited implementation to consider the redoability of * {@link ConditionalRedoCommand}s. * Extends the inherited implementation by invoking it within the context * of a redo transaction (a read/write transaction with the * {@link #getUndoRedoOptions() undo/redo options}). * The default implementation of the transactional editing domain. * * Since 1.2, this class implements the {@link Adaptable} interface to adapt * to the following optional API: * * <ul> * <li>{@link TransactionalEditingDomain.DefaultOptions}</li> * <li>{@link TransactionalEditingDomain.Lifecycle} (since 1.3)</li> * <li>{@link Transaction.Option.Registry} (since 1.3)</li> * </ul> * * @author Christian W. Damus (cdamus) * Default implementation of the validator factory * * @since 1.1 * * @author David Cummings (dcummin) * {@inheritDoc} * {@inheritDoc} * Default implementation of a transaction editing domain factory. This * class creates {@link TransactionalEditingDomainImpl}s and provides the mapping of * resource sets to editing domain instances. * * Clients that implement their own factory can plug in to the mapping * of resource sets to editing domains using the static instance's * {@link #mapResourceSet(TransactionalEditingDomain)} and * {@link #unmapResourceSet(TransactionalEditingDomain)} methods by casting the * {@link TransactionalEditingDomain.Factory#INSTANCE} to the * <code>TransactionalEditingDomainImpl.FactoryImpl</code> type. * * * @author Christian W. Damus (cdamus) * An adapter that attaches a weak reference to the editing domain * onto the resource set that it manages. * * @author Christian W. Damus (cdamus) * Adds the specified editing domain to the global reverse mapping * of resource sets. * * @param domain the editing domain to add to the resource set mapping * Removes the specified editing domain from the global reverse mapping * of resource sets. * * @param domain the editing domain to remove from the resource set mapping * Implementation of the global editing domain registry. * * This class is not intended to be used by clients. * * * @author Christian W. Damus (cdamus) * Adds the specified domain into the registry under the given ID. This * method must only be invoked after it has been determined that this * ID can be registered. * * @param id the editing domain ID * @param domain the domain to register * Default implementation of the {@link InternalLifecycle} protocol. * May be subclassed by custom editing domain implementations. * * @author Christian W. Damus (cdamus) * * @since 1.3 * Obtains a copy of my life-cycle listener list as an array, for safe * iteration that allows concurrent updates to the original list. * * @return my life-cycle listeners (as of the time of calling this * method) * Fires the specified life-cycle event to my listeners, if any. * * @param type * one of the life-cycle event * {@linkplain TransactionalEditingDomainEvent#TRANSACTION_STARTING * types} * @param transaction * the transaction that is the subject of the event, or * <code>null</code> if the event pertains to the editing * domain, itself * Initializes my state. * May be overridden by subclasses to create a custom change recorder * implementation. Just creates a change recorder on the specified resource * set and returns it. * * @param rset a resource set in which to record changes * * @return the new change recorder * Obtains an ID suitable for display in debug/trace messages. * * @param domain the editing domain for which to get the debug ID * * @return a debugging ID * Obtains my command stack as the internal interface. * * @return the internal view of my command stack * Obtains an ID suitable for display in debug/trace messages. * * @param tx the transaction for which to get the debug ID * * @return a debugging ID * Obtains a copy of my pre-commit listener list as an array, for safe * iteration that allows concurrent updates to the original list. * * @return my pre-commit listeners (as of the time of calling this method) * Obtains a copy of my aggregate pre-commit listener list as an array, for * safe iteration that allows concurrent updates to the original list. * * @return my aggregate pre-commit listeners (as of the time of calling * this method) * Obtains a copy of my post-commit listener list as an array, for safe * iteration that allows concurrent updates to the original list. * * @return my post-commit listeners (as of the time of calling this method) * Acquires the appropriate locks for the specified transaction. * * @param tx a transaction to be activated or resumed from a yield * * @throws InterruptedException if the current thread is interrupted while * waiting for the lock * Releases the lock currently held by the specified transaction. * * @param tx a transaction * Performs post-commit processing of the specified transaction. This * consists of broadcasting the post-commit events to my resource set * listeners. * * @param tx the transaction that has committed * Sets the factory to use when creating validators for transaction * validation. * * @since 1.1 * * @param validatorFactory the factory to set * Obtains the factory that this transactional editing domain uses * to create validators for transaction validation. * * If the validator factory has yet to be initialized, it is initialized * using the default validator factory. * * * @since 1.1 * * @return the requested validator factory * Obtains my lazily-created lifecycle implementation. * * @return my lifecycle * * @since 1.3 * Creates a new lifecycle implementation. Subclasses may override to * create their own implementation. * * @return a new lifecycle * * @since 1.3 * Obtains my lazily-created transaction option metadata registry. * * @return my option metadata registry * * @since 1.3 * Creates a new transaction option metadata registry. * Subclasses may override to create their own implementation, although it * would hardly seem interesting to do so. * * @return a new option metadata registry * * @since 1.3 * A transaction implementation used by the command stack to wrap the execution * of {@link TriggerCommand}s, to provide them the write access that they need. * This transaction does not propagate its change description to the parent, * because that is handled separately via {@link CommandChangeDescription}s. * * @author Christian W. Damus (cdamus) * Extends the inherited implementation by first clearing my change * description, so that I will not propagate these changes upwards. * Overrides the inherited implementation to simply propagate triggers to * my parent, because it's the transaction that the outside world can see. * A specialized change description that may not be able to apply itself, * especially in the case where it includes non-EMF changes that are not * reversible. * * When a transaction rolls back, the assumption is that all changes that it * performed can be undone, even any non-EMF changes that are captured in its * <code>TransactionChangeDescription</code>. This assumption is necessary because * the semantics of rollback guarantee that rollback cannot fail: rollback * must restore the system to the state it was in before the * transaction started. Thus, any change description (possibly nested in a * composite) that cannot be applied will be ignored and a best effort made to * apply all other changes. * * * However, the same should not hold for undo/redo of the changes performed * by a transaction after it has committed. If the transaction's change * description is stored on some kind of "command stack" as an encapsulation of * an undoable change, then the possibility that a change description cannot * be applied should be respected by disabling undo/redo. * * * @author Christian W. Damus (cdamus) * Queries whether I can {@link ChangeDescription#apply() apply} my changes. * If I can, then it is assumed that I could * {@link ChangeDescription#applyAndReverse() reverse} them also. * * @return <code>true</code> if my changes can be applied; * <code>false</code> otherwise (i.e., they are not invertible) * Queries whether I have no changes. * * @return <code>true</code> if I have no changes (applying me would have * no effect on anything); <code>false</code>, otherwise * An extension of the {@link EditingDomain} API that applies transactional * semantics to reading and writing the contents of an EMF {@link ResourceSet}. * * Editing domains can be created in one of two ways: dynamically, using a * {@link Factory} or statically by registration on the * <code>org.eclipse.emf.transaction.editingDomains</code> extension point. The * latter mechanism is the preferred way to define editing domains that can be * shared with other applications. To create a new editing domain in code, * simply invoke the static factory instance: * * * <PRE> * TransactionalEditingDomain domain = TransactionalEditingDomain.Factory.INSTANCE * .createEditingDomain(); * ResourceSet rset = domain.getResourceSet(); * // or, create our own resource set and initialize the domain with it * rset = new MyResourceSetImpl(); * domain = TransactionalEditingDomain.Factory.INSTANCE.createEditingDomain(rset); * </PRE> * * To share a named editing domain with other applications, the editing domain * registry can be used to obtain domains by ID, creating them if necessary. * Editing domain IDs are configured on an extension point providing the factory * implementation that the registry uses to initialize them: * * * <pre> *  * <extension point="org.eclipse.emf.transaction.editingDomains"> * <editingDomain * id="com.example.MyEditingDomain" * factory="com.example.MyEditingDomainFactory"/> * </extension> * // in code, access the registered editing domain by: * TransactionalEditingDomain myDomain = TransactionalEditingDomain.Registry.INSTANCE.getEditingDomain( * "com.example.MyEditingDomain"); * </pre> * * See the {@link org.eclipse.emf.transaction package documentation} for further * details of editing domain usage. * * * As of the EMF Transaction 1.2 release, editing domains may optionally be * {@link Adaptable} to a variety of optional extension interfaces or "facets." * It is recommended to implement the <tt>Adaptable</tt> interface and support * adaptation to these interfaces to benefit from the services that they offer. * * * As of the EMF Transaction 1.3 release, resource-set listeners may optionally * implement a {@linkplain ResourceSetListener.Internal private} interface to be * notified when they are * {@linkplain #addResourceSetListener(ResourceSetListener) added} to or * {@linkplain #removeResourceSetListener(ResourceSetListener) removed} from an * editing domain. * * * Also since the 1.3 release, the new optional * {@link TransactionalEditingDomain.Lifecycle} interface provides * notifications, from editing domains that support this protocol, of * transaction and editing-domain * {@linkplain TransactionalEditingDomainListener lifecycle changes}. * * * @author Christian W. Damus (cdamus) * * @see TransactionalCommandStack * @see Transaction * @see ResourceSetListener * @see ResourceSetListener.Internal * @see TransactionalEditingDomain.Lifecycle * @see TransactionalEditingDomainListener * Obtains my unique ID. This is the ID under which I am registered in * the {@link Registry} (if I am registered). * * @return my unique identifier * * @see Registry#getEditingDomain(String) * Sets my unique ID. If I am currently registered in the {@link Registry}, * then I am re-registered under this new ID. However, if I am registered * statically on the <code>org.eclipse.emf.transaction.editingDomains</code> * extension point, then my ID cannot be changed. * * @param id my new unique identifier * * @throws IllegalArgumentException if I am a statically registered domain * * @see #getID() * @see Registry#add(String, TransactionalEditingDomain) * Adds a resource set listener to me, to receive notifications of changes * to the resource set when transactions commit. This method has no effect * if the specified listeners is already attached to me. * * @param l a new resource set listener * * @throws IllegalArgumentException if the listener declares both that it * wants only pre-commit events and that it wants only post-commit * events (a logical contradiction) * * @see ResourceSetListener#isPrecommitOnly() * @see ResourceSetListener#isPostcommitOnly() * Removes a resource set listener from me. This method has no effect if * the listener is not currently attached to me. * * @param l a resource set listener to remove * Runs an operation that requires exclusive access to my resource set, * for reading. The specified runnable is executed in a read-only * transaction. If the runnable implements the {@link RunnableWithResult} * interface, then its result is returned after it completes. Moreover, * (and this is a very good reason to implement this extension interface), * if the transaction rolls back on commit, then the <code>RunnableWithResult</code> * is provided with the error status indicating this condition. Even read-only * transactions can roll back when, for example, another thread concurrently * modifies the model (in violation of the transaction protocol), and it is * important to know when corrupted data may have been read. * * Note that this method will block the current thread until * exclusive access to the resource set can be obtained. However, it is * safe to call this method on the Eclipse UI thread because special * precaution is taken to ensure that liveness is maintained (using * mechanisms built into the Job Manager). * * Note: Since the 1.2 release, the * {@link TransactionUtil#runExclusive(TransactionalEditingDomain, RunnableWithResult)} * utility provides type-safe execution of runnables returning results and * should be preferred over this API. * * * @param read a read-only operation to execute * * @return the result of the read operation if it is a * {@link RunnableWithResult} and the transaction did not roll back; * <code>null</code>, otherwise * * @throws InterruptedException if the current thread is interrupted while * waiting for access to the resource set * * @see TransactionUtil#runExclusive(RunnableWithResult) * @see Transaction#commit() * Temporarily yields access to another read-only transaction. The * <code>TransactionalEditingDomain</code> supports any number of pseudo-concurrent * read-only transactions. Transactions that are expected to be * long-running should yield frequently, as a task running in a progress * monitor is expected to check for cancellation frequently. However, there * is a higher cost (in time) associated with yielding, so it should not * be overdone. * * Only read-only transactions may yield, and only the transaction that * is currently active in the editing domain may yield. The yielding * transaction may be nested, but not within a read/write transaction * at any depth. * * * Upon yielding, some other read-only transaction that is attempting to * start or to return from a yield will take control of the editing domain. * Control is never yielded to a read/write transaction (not even to a * read-only transaction nested in a read/write) because this would * introduce dirty reads (transactions reading uncommitted changes). * If there are no other read-only transactions to receive the transfer of * control, then the call returns immediately. Otherwise, control is * transferred in FIFO fashion to waiting transactions. * * Wraps the specified <code>runnable</code> to give it access to the currently * active transaction. This is useful for two or more cooperating threads * to share a transaction (read-only or read-write), executing code in * the a <code>runnable</code> on one thread in the context of another * thread's transaction. * * For example, in an Eclipse UI application, this might be used when a * long-running task in a modal context thread needs to synchronously * execute some operation on the UI thread, which operation needs to read * or write the editing domain. e.g., * * <pre> * Runnable uiBoundAction = // ... * Runnable privileged = domain.createPrivilegedRunnable(uiBoundAction); * Display.syncExec(privileged); * </pre> * * Note that it is critically important that this mechanism only * be used to share a transaction with another thread synchronously. * Or, more generally, during the execution of the privileged runnable, the * thread that originally owned the transaction no longer does, and may not * access the editing domain. Upon completion of the privileged runnable, * the transaction is returned to its original owner. * * * Also, the resulting runnable may only be executed while the currently * active transaction remains active. Any attempt to execute the runnable * after this transaction has committed or while a nested transaction is * active will result in an {@link IllegalStateException}. * * Note: Since the 1.2 release, the * {@link TransactionUtil#createPrivilegedRunnable(TransactionalEditingDomain, RunnableWithResult)} * utility provides type-safe privileged access for runnables returning * results and should be preferred over this API. * * * @param <T> the result type of the {@link RunnableWithResult} if such * is the <tt>read</tt> argument * * @param runnable a runnable to execute in the context of the active * transaction, on any thread * * @return the privileged runnable. If the wrapped <code>runnable</code> * is a {@link RunnableWithResult}, then the privileged runnable will * inherit its result when it completes * * @throws IllegalStateException on an attempt by a thread that does not * own the active transaction to create a privileged runnable. This * prevents "theft" of transactions by malicious code. Note also * that this implies an exception if there is no active transaction at * the time of this call * * @see TransactionUtil#createPrivilegedRunnable(TransactionalEditingDomain, RunnableWithResult) * Disposes of this editing domain and any resources that it has allocated. * Editing domains must be disposed when they are no longer in use, but * only by the client that created them (in case of sharing of editing * domains). * * Note that editing domains registered on the extension point may * not be disposed. * * Interface defining the protocol for creating transactional editing * domains. Non-shared editing domains can be created by accessing the * static factory {@link #INSTANCE}. Shared editing domains (registered * on the <code>org.eclipse.emf.transaction.editingDomains</code> * extension point are obtained via the {@link Registry}. * * @author Christian W. Damus (cdamus) * Static factory instance that can create instances of the default * transactional editing domain implementation. * Creates an editing domain with a default resource set implementation. * * @return the new editing domain * Creates a new transactional editing domain on the specified resource * set. Although it is possible to create multiple editing domains on * the same resource set, this would rarely be useful. * * @param rset the resource set * * @return a new editing domain on the supplied resource set * Obtains the transactional editing domain (if any) that is currently * managing the specified resource set. * * @param rset a resource set * * @return its editing domain, or <code>null</code> if it is not managed * by any <code>TransactionalEditingDomain</code> * An ID-based registry of shareable {@link TransactionalEditingDomain} instances. * Although editing domains can be registered in code, the usual means is * to implement the <code>org.eclipse.emf.transaction.editingDomains</code> * extension point. * * @author Christian W. Damus (cdamus) * The single static registry instance. * Obtains the editing domain having the specified ID. if the specified * domain is registered on the extension point but has not yet been * created, then it is first created (using the designated factory) * and then returned. * * @param id the ID to request * * @return the matching editing domain, or <code>null</code> if it is * not found and it could not be created from the extension point * Registers an editing domain under the specified ID. This will displace * any domain previously registered under this ID. * Note that it is not permitted to replace an editing domain that * was registered statically on the * <code>org.eclipse.emf.transaction.editingDomains</code> extension * point. * * @param id the domain ID to register * @param domain the domain to register. If its current * {@link TransactionalEditingDomain#getID() ID} is not the registered ID, then it * is updated to correspond * * @throws IllegalArgumentException if the specified ID is already registered * statically on the extension point * Removes the editing domain matching the specified ID from the * registry. Note that it is not permitted to remove an ID that * was registered statically on the * <code>org.eclipse.emf.transaction.editingDomains</code> extension * point. * * @param id the domain ID to deregister * * @return the editing domain previously registered under this ID, * or <code>null</code> if none was registered * * @throws IllegalArgumentException if the specified ID was registered * statically on the extension point * * Adapter interface provided by {@link TransactionalEditingDomain}s that * support the notion of default transaction options. This allows clients, * usually when initializing an editing domain, to specify options that * will be applied to any read/write {@link Transaction} for which explicit * values are not provided when they are created. * * There are no default-defaults: by default, an editing domain has no * default transaction options. Default options are only applied to * root-level transactions. Nested transactions are expected to inherit * them (or not) as appropriate to the implementation of the options, * as usual. * * Note that these are applied also to undo/redo transactions and may be * overridden by the options returned by the * {@link InternalTransactionalEditingDomain#getUndoRedoOptions()} method. * Thus, it may be important for an editing domain to use the undo/redo * options to explicitly disable options that may have defaults. * * The {@linkplain TransactionalEditingDomainImpl default editing domain * implementation} provides this adapter interface. * * * @author Christian W. Damus (cdamus) * * @since 1.2 * Obtains a read-only view of the editing domain's default transaction * options. * * @return my read-only map of transaction options * Sets the default transaction options. It is probably best to do this * only when configuring a new editing domain, as inconsistent behaviour * may result from changing the options while editing transactions are * in progress. * * @param options the new options. The options are copied from the map * * Adapter interface provided by {@link TransactionalEditingDomain}s that * support notification of life-cycle events to * {@link TransactionalEditingDomainListener}s. * * * This interface is not intended to be implemented by clients, but by * editing domain providers. * * * @author Christian W. Damus (cdamus) * * @since 1.3 * Adds a listener to be notified of editing domain and transaction * life-cycle events. * * @param l * a listener to add * Removes a lif-cycle event listener from the editing domain. * * @param l * a listener to remove * A convenient superclass for post-commit listeners to process * {@link Notification}s one at a time. This effectively demultiplexes the * list of batched notifications. * * @author Christian W. Damus (cdamus) * Implements the post-commit callback by processing the <code>event</code>'s * notifications one by one, delegating to the {@link #handleNotification} * method. * * @see #handleNotification(TransactionalEditingDomain, Notification) * Implemented by subclasses to respond to each notification in serial order. * * @param domain the editing domain from which the notification originated * @param notification the notification describing a change in the model * * @see #resourceSetChanged(ResourceSetChangeEvent) * I want only post-commit events, not pre-commit events. * Default implementation of a resource-set listener, useful for extending to * implement only the callbacks of interest to the client. * * @author Christian W. Damus (cdamus) * * @see ResourceSetChangeEvent * The default implementation of this method does nothing, returning * no trigger command. * The default implementation of this method does nothing. * By default, assume that we want individual transaction pre-commit. * By default, assume that we do not only want pre-commit events but also * post-commit events. * By default, assume that we do not only want post-commit events but also * pre-commit events. * Queries the transactional editing domain, if any, to which I am * listening. Note the assumption of the most common case in which a * listener is only attached to a single domain. * * @return the editing domain that I listen to, or <code>null</code> if none * @since 1.3 * {@linkplain #getTarget() Remembers} the new editing domain that I am now * listening to, if it is not <code>null</code>. * * @since 1.3 * If the specified domain is the one that I {@linkplain #getTarget() * remembered}, then I forget it because I am no longer listening to it. * * @since 1.3 * Event object describing the nature of changes in a resource set to * {@link ResourceSetListener}s. Note that the event object is only valid * during the scope of the listener call-back invocation; in particular, the * editing domain is free to re-use event objects and/or notification lists * for performance purposes. Therefore, if it is necessary to retain the * event or its list of notifications beyond the scope of the call-back, this * information must be copied by the client. * * This class is not intended to be extended or instantiated by clients. * * * @author Christian W. Damus (cdamus) * * @see ResourceSetListener * Obtains the editing domain whose resource set contents changed. * * @return the editing domain * Obtains the transaction in which resource set changes have occurred. * This is the transaction that is either about to commit or that has * committed. Of particular interest in the transaction's * {@link Transaction#getStatus() status} after it has committed. * * Note that it is not permitted to attempt to commit or roll back * the transaction during the listener call-back. Any attempt to do so will * result in an <code>IllegalStateException</code>. * * * @return the transaction that is committing or committed. This will * never be <code>null</code> * Obtains the list of events (as {@link Notification}s), in the order in * which they occurred, indicating the changes that occurred during the * transaction. * * @return the changes * * @see Notification * An interface for client objects that handle exceptions occurring in the * interaction with an editing domain's command stack. This is useful, for * example, for UIs that want to show a dialog when a command's transaction * is rolled back by validation problems. * * @author Christian W. Damus (cdamus) * * @see RollbackException * Handles the specified exception in some way. * * @param e the exception that occurred. The {@link RollbackException} * is the most interesting exception type that is likely to occur * A filter that determines which {@link Notification}s will be passed to * {@link ResourceSetListener}s. Filters can be combined using simple * boolean operations. * * The default filter for listeners that do not otherwise declare one is * {@link #NOT_TOUCH}. * * * Note that {@link ResourceSetListener}s never receive * {@link Notification#REMOVING_ADAPTER} notifications because these are * intended only to inform an adapter that it is being removed; they are * not broadcast to all adapters of an object. Besides which, resource set * listeners are not adapters. * * * Since the EMF Transaction 1.3 release, clients can implement arbitrary * filter criteria by specializing the {@link NotificationFilter.Custom} class. * * * @author Christian W. Damus (cdamus) * * @see ResourceSetListener * @see Notification As its name implies, this filter matches any notification. * Matches only notifications that are not "touches." * * @see Notification#isTouch() * Matches any notification that can occur during the normal course of * a read-only transaction. These include: * <ul> * <li>proxy resolution</li> * <li>any change to the {@link ResourceSet#getResources() resources} * list of a resource set</li> * <li>any change to the <code>isLoaded</code>, <code>isModified</code>, * <code>URI</code>, <code>errors</code>, <code>warnings</code>, and * <code>resourceSet</code> features of a resource</li> * <li>any change to the {@link Resource#getContents() contents} of * a resource while it is loading or unloading</li> * </ul> * A filter matching "resource loaded" events. * A filter matching "resource unloaded" events. * A custom notification filter, implementing user-defined * {@linkplain NotificationFilter#matches(Notification) selection criteria}. * Custom notification filters are distinguished from the stock * implementations created by the factory methods of the * {@link NotificationFilter} class to ensure that the base class remains * abstract. * * @author Christian W. Damus (cdamus) * * @since 1.3 * Creates a filter matches any notification from a resource of the * specified content type. Because the determination of a resource's * content type is costly, it is cached on the resource via an adapter and * is cleared on any change to the resource's contents or other properties. * * @param contentType the content type identifier to match * * @return the filter * * @throws IllegalArgumentException if the specified content type is not * defined * * @see IContentType * Creates a filter matching any notification from the specified notifier. * * @param notifier a notifier (usually an {@link EObject}, {@link Resource}, * or {@link ResourceSet} * * @return the filter * Creates a filter matching any notification of the specified type. * * @param eventType the notification type (as defined by the * {@link Notification} interface) * * @return the filter * Creates a filter matching any notification from the specified feature. * * @param feature a structural feature meta-object * * @return the filter * Creates a filter matching any notification from the specified feature. * This variant is useful for notifiers that are not modeled via Ecore. * * @param ownerType the notifier type as a Java class or interface * @param featureId the feature's numeric ID * * @return the filter * Creates a filter matching any notification from the specified feature. * This variant is useful for notifiers that are not modeled as * {@link EClass}es. For example, this supports the features of the * {@link Resource} data type. * * @param ownerType the notifier type as an Ecore classifier * @param featureId the feature's numeric ID * * @return the filter * Creates a filter matching notifications from any instance of the * specified type. This variant is useful for notifiers that are not * modeled via Ecore. * * @param type the notifier type as a Java class or interface * * @return the filter * Creates a filter matching notifications from any instance of the * specified type. This variant is useful for notifiers that are * modeled via Ecore. * * @param type the notifier type as an Ecore classifier * * @return the filter * Creates a new filter combining me with another as a boolean conjunction. * The "and" operation short-circuits; the <code>other</code> filter is not * consulted when I (the first filter) do not match. * * @param other another filter (must not be <code>null</code>) * * @return a new "and" filter * Creates a new filter combining me with another as a boolean disjunction. * The "or" operation short-circuits; the <code>other</code> filter is not * consulted when I (the first filter) match. * * @param other another filter (must not be <code>null</code>) * * @return a new "or" filter * Creates a new filter that is the boolean negation of me. * * @return the opposite of me * Determines whether a notification matches my filtering criteria. * Notifications that match are passed to the listener for which I am * filtering. * * @param notification a notification * * @return <code>true</code> if the notification should be passed to my * listener; <code>false</code>, otherwise * Implementation of the filter that matches notifications from changes that are * permitted during read-only transactions. These are only "concrete" changes * (implementation details), not "abstract" (semantically significant) model * changes. * * See the documentation on the {@link NotificationFilter#READ} constant for * details of how notifications are determined to be "read compatible." * * * @author Christian W. Damus (cdamus) * * @see NotificationFilter#READ * Determines whether the specified change to a resource is permitted during * a read-only transaction. * * @param notification indication of a change in a resource * * @return whether the notification is "read compatible" * Checks whether a resource is currently in the process of loading or * unloading. * * @param res a resource * @return <code>true</code> if the resource is currently loading or * unloading; <code>false</code>, otherwise (fully loaded or unloaded) * A partial {@link org.eclipse.emf.common.command.Command} implementation that * records the changes made by a subclass's direct manipulation of objects via * the metamodel's API. This simplifies the programming model for complex * commands (not requiring composition of set/add/remove commands) while * still providing automatic undo/redo support. * * Subclasses are simply required to implement the {@link #doExecute()} method * to make the desired changes to the model. Note that, because changes are * recorded for automatic undo/redo, the concrete command must not make any * changes that cannot be recorded by EMF (unless it does not matter that they * will not be undone). * * * @author Christian W. Damus (cdamus) * Subclasses should override this if they have more preparation to do. * By default, the result is just <code>true</code>. * Implements the execution with automatic recording of undo information. * Delegates the actual model changes to the subclass's implementation of * the {@link #doExecute()} method. * * @see #doExecute() * Will be called prior to {@link RecordingCommand#doExecute()}. * @since 1.4 * Will be called after {@link RecordingCommand#doExecute()}. * @since 1.4 * I can be undone if I successfully recorded the changes that I executed. * Subclasses would not normally need to override this method. * I can be redone if I successfully recorded the changes that I executed. * Subclasses would not normally need to override this method. * Undoes the changes that I recorded. * Subclasses would not normally need to override this method. * * @throws IllegalStateException if I am not {@linkplain #canUndo() undoable} * * @see #canUndo() * Redoes the changes that I recorded. * Subclasses would not normally need to override this method. * * @throws IllegalStateException if I am not {@linkplain #canRedo() redoable} * * @see #canRedo() * Implemented by subclasses to perform the necessary changes in the model. * These changes are applied by direct manipulation of the model objects, * not by executing commands. * Queries whether I am a nested command, not executing as the root command * of the active transaction. * * @return whether I am not the root command being executed in a transaction * Queries whether I am executing in the context of a trigger transaction. * That is to say, whether I am a trigger command. * * @return whether the active transaction is a trigger transaction * Queries whether I am executing in the context of a transaction that is * intended to be undoable. * * @return whether the active transaction is recording undo information * Extends the inherited implementation by disposing my change description, * if any. * A specialization of the EMF {@link Command} API that accounts for conditional * redoable-ness. This interface adds a {@link #canRedo()} operation in * conjunction with the {@link Command#canUndo()}. * * This interface is intended to be implemented by clients. * * * @author Christian W. Damus (cdamus) * Queries whether I can be redone. The result of calling this * operation is undefined until I have been {@link Command#undo() undone}. * Note that it is acceptable for a conditionally redoable command not * to be redoable if it has successfully been undone, or even after * having been successfully redone at least once before. * * @return <code>true</code> if I can be redone; <code>false</code>, * otherwise * A conditionally redoable compound command. * * @author Christian W. Damus (cdamus) * I can redo if none of my composed commands cannot redo. * * @return <code>false</code> if any command that is a * {@link ConditionalRedoCommand} cannot redo; * <code>true</code>, otherwise * I am self-chaining. * Implementation of the filter that matches on resource content type. * * @author Christian W. Damus (cdamus) * Gets the cached content types of the resource that either is * the notifier of the specified notification or that contains the * notifier. * * @param notification a notification from a resource or its * contents * * @return the resource's content types * Gets the cached content types of a resource. If the cache misses. * then we compute the content types and cache them. * * @param res a resource * * @return its cached content types * Computes a resource's content types from its content (if * available on disk) and its file name. * * @param res a resource * * @return its content types * Listener interface for batched notification of changes to a resource set. * Unlike EMF {@link org.eclipse.emf.common.notify.Adapter}s, resource-set * listeners receive notifications at the close of a transaction and, in the * case of the {@link #resourceSetChanged post-commit} call-back, only in * the case that the transaction committed (did not roll back). * * This interface is intended to be implemented by clients. * For convenience, clients can extend the {@link ResourceSetListenerImpl} * class if they need no other superclass. * * * @author Christian W. Damus (cdamus) * * @see ResourceSetListenerImpl * @see ResourceSetChangeEvent * @see NotificationFilter * @see TransactionalEditingDomain#addResourceSetListener(ResourceSetListener) * Provides a filter to select which notifications should be sent to this * listener. If none is provided, the default is the * {@link NotificationFilter#NOT_TOUCH} filter. * * Note that, if a listener's filter does not match any of the * notifications that were received during a transaction, then it is not * invoked at all. Thus, the notification lists received in the * {@link ResourceSetChangeEvent}s will never be empty. * * * Note also that a listener's filter must not change over time, or * unpredictable behaviour will occur. In particular, the editing domain * is free to obtain the filter from the listener only once when the * listener is added and never request it thereafter. Also, it is not * expected the the same filter object's condition can change over time. * * * @return the filter used to select notifications, or <code>null</code> to * obtain the default * Informs the listener that the execution of a command (which may be * implicit) is about to complete. More precisely, that a read/write * transaction is about to commit. * * Listeners implement this method in order to provide "trigger commands", * akin to database triggers in RDBMSes. To follow-up changes that * occurred in the model, to proactively maintain model integrity, the * listener can return a command that makes additional changes. * * * Trigger commands are executed after all listeners have been invoked, * in the same transaction context as the original events (and therefore * validated together with them). Moreover, because these triggers perform * model changes, they cause another round of invocation of these very same * resource set listeners. * * * The command returned by a trigger, if any, should be careful to implement * its {@link Command#canExecute()} method appropriately. In particular, * it is important to check that the conditions observed by the listener * still apply, as other trigger commands may be executed before it that can * make inconsistent changes. * * * Finally, a pre-commit listener has the opportunity to force the current * transaction to roll back instead of completing the commit. This helps * in the implementation of certain kinds of live validation checks that * cannot be implemented using the EMF validation framework. * * * Note that the listener is invoked in a read-only transaction * context. It is safe to read the model, but direct changes are not * permitted (return a command instead). * * * @param event the event object describing the changes that occurred in * the resource set * * @return an optional command to perform additional changes. Can be * <code>null</code> if no changes are required * * @throws RollbackException to force a roll-back of the current transaction * Informs the listener that changes have been committed to the model. * Unlike the {@link #transactionAboutToCommit(ResourceSetChangeEvent)} * call-back, this method has no opportunity to make subsequent changes via * triggers or to roll back the transaction. It has already committed. * This has the advantage, however, of guaranteeing that it is safe to * update the user interface or other dependent components or systems * because the changes are committed. This call-back is not invoked if * the transaction rolls back, as all of its pending changes are reverted. * * Note that the listener is invoked in a read-only transaction * context. It is safe to read the model, but changes are not permitted. * * * @param event the event object describing the changes that occurred in * the resource set * Queries whether I should be invoked only for pre-commit of the root * transaction, with all of the notifications from that transaction and any * nested transactions. Otherwise, I will be invoked for each transaction * individually and only with its own notifications. * * @return <code>true</code> if I should be invoked only for pre-commit of * the root transaction; <code>false</code>, otherwise * Queries whether I am interested only in the pre-commit * ({@link #transactionAboutToCommit(ResourceSetChangeEvent)}) call-back. * This helps the editing domain to optimize the distribution of events. * * Note that this method is queried only once when the listener is * added to the editing domain, so the result should not change over time. * * * @return <code>true</code> if I only am interested in pre-commit events; * <code>false</code>, otherwise * Queries whether I am interested only in the post-commit * ({@link #resourceSetChanged(ResourceSetChangeEvent)}) call-back. * This helps the editing domain to optimize the distribution of events. * * Note that this method is queried only once when the listener is * added to the editing domain, so the result should not change over time. * * * @return <code>true</code> if I only am interested in post-commit events; * <code>false</code>, otherwise * An interface for communication of internal life-cycle events to the * listener. These call-backs do not have anything to do with the state * of the resource set, but rather inform the listeners of changes in its * own state. This interface is optional; listeners should implement it * only if they need the additional notifications. * * @author Christian W. Damus (cdamus) * * @since 1.3 * Informs me that I have been attached to the specified editing domain. * This is particularly useful for listeners that are statically * registered, as it effectively signals the creation of the editing * domain. * * @param domain * an editing domain to which I have been attached. Note that * nothing precludes the addition of a listener to more than * one editing domain * Informs me that I have been detached from the specified editing * domain. This is a good opportunity for me, perhaps, to clean up any * cached data that pertains to this domain. * * @param domain * an editing domain from which I have been detached. Note * that I may very will still be attached to other domains * than this * Exception indicating that a transaction was automatically rolled back on * attempting to commit. The usual cause of this exception is either a * validation failure or some run-time exception during the commit phase. * The {@link #getStatus() status} object provides details suitable for display * in a JFace error dialog or the like. * * This class is intended to be instantiated by clients, particularly in the * {@link ResourceSetListener#transactionAboutToCommit(ResourceSetChangeEvent)} * method. * * * @author Christian W. Damus (cdamus) * * @see Transaction#commit() * @see TransactionalCommandStack#execute(org.eclipse.emf.common.command.Command, java.util.Map) * @see ResourceSetListener#transactionAboutToCommit(ResourceSetChangeEvent) * @see ExceptionHandler * Obtains the status describing the cause of the transaction rollback. * Its severity should be {@link IStatus#ERROR} or greater, otherwise the * transaction should not have rolled back. * * @return the status * Extends the core Java {@link Runnable} interface with the ability to return * a result. Useful for returning results of read operations from the * {@link TransactionalEditingDomain#runExclusive(Runnable)} method. * * Also, because read transactions can roll back on commit if, for example, some * other thread performs a concurrent write that corrupts the data being read, * this interface also provides a means to set a status to indicate success * or failure of the transaction. * * * @param <T> the result type of the runnable * * @author Christian W. Damus (cdamus) * * @see TransactionalEditingDomain#runExclusive(Runnable) * Returns a result computed by my {@link Runnable#run()} method. * * @return my result, or <code>null</code> if none * Sets the commit status after completion of the {@link Runnable#run()} method. * * @param status an OK status if commit succeeds, or an error status * if it fails (in which case the transaction rolled back and the status * provides details in human-readable form) * Queries my commit status. My status is only available after I have * finished running and after the editing domain has attempted to commit * my transaction. * * @return the status of my commit (as set by the {@link #setStatus(IStatus)} method) * A convenient partial implementation of the {@link RunnableWithResult} * interface that implements a settable {@link #setResult(Object) result} * field and commit status. * * @author Christian W. Damus (cdamus) * Sets my result. * * @param result my result * Extension of the basic {@link CommandStack} API providing additional control * over (and feed-back from) the transactions used to execute commands. * * @author Christian W. Damus (cdamus) * Executes the specified command in a read/write transaction. * This method is preferred over the inherited * {@link CommandStack#execute(Command)} method because it provides * feed-back when a command fails to complete. The implementation of this * latter method simply suppresses (but logs) any checked exception that * occurs. * * Note that this method will block the caller until a read/write * transaction can be started (if other transactions are currently active). * * * @param command the command to execute * @param options the options to apply to the command's transaction, or * <code>null</code> to select the defaults * * @throws InterruptedException if the current thread is interrupted while * waiting to start a read/write transaction for the command execution * @throws RollbackException if the changes performed by the command are * rolled back by validation of the transaction * Sets an exception handler. This object will be notified when exceptions * occur, but is not really expected to be able to do anything about them. * Its intended purpose is to support an user feed-back mechanism * appropriate to the environment. * * @param handler the exception handler to set * Obtains my exception handler. * * @return my exception handler, or <code>null</code> if none * * @see #setExceptionHandler(ExceptionHandler) * * A listener interface providing notifications of changes to a transactional * editing domain. This differs from the {@link ResourceSetListener} which * notifies of changes to the resource-set managed by the editing domain. The * events that occur in a transactional editing domain are: * * <ul> * <li>pre-notification of the * {@linkplain #transactionStarting(TransactionalEditingDomainEvent) starting} * of a top-level transaction</li> * <li>{@linkplain #transactionStarted(TransactionalEditingDomainEvent) * successful start} of a top-level transaction</li> * <li>{@linkplain #transactionInterrupted(TransactionalEditingDomainEvent) * interrupted start} of a top-level transaction (thus a non-start)</li> * <li>pre-notification of the * {@linkplain #transactionClosing(TransactionalEditingDomainEvent) closing} of * a top-level transaction</li> * <li>{@linkplain #transactionClosed(TransactionalEditingDomainEvent) * successful or failed close} of a top-level transaction</li> * <li>{@linkplain #editingDomainDisposing(TransactionalEditingDomainEvent) * disposal} of the editing domain</li> * </ul> * * The {@link TransactionalEditingDomainListenerImpl} class provides convenient * empty implementations of the listener methods, suitable for subclassing to * selectively implement these call-backs. * * * @author Christian W. Damus (cdamus) * * @since 1.3 * * @see TransactionalEditingDomain.Lifecycle * @see TransactionalEditingDomainListenerImpl * * * Signals that a transaction has requested activation, but is not yet * started. Note that any number of transactions may be in this state * simultaneously, on different threads, but obviously only one will * actually start. * * * This event is not sent for nested transactions, nor for a transaction's * resumption from the {@linkplain TransactionalEditingDomain#yield() * yielded} state. * * * @param event * indicates the transaction that is about to start * * Signals that a transaction that has requested activation was interrupted * before it could start. Thus, this indicates a failed start. * * * This event is not sent for nested transactions. * * * @param event * indicates the transaction that was interrupted * * Signals that a transaction has been activated. * * * This event is not sent for nested transactions, nor for a transaction's * resumption from the {@linkplain TransactionalEditingDomain#yield() * yielded} state. * * * @param event * indicates the transaction that has started * * Signals that a transaction has finished its work and is about to close. * This may be the beginning of the normal commit sequence of trigger firing * followed by validation (subsequently rolling back, if necessary), or an * explicit roll-back requested by the transaction, itself. * * * This event is not sent for nested transactions, nor for a transaction's * entry into the {@linkplain TransactionalEditingDomain#yield() yielded} * state. * * * @param event * indicates the transaction that is about to close * * Signals that a transaction has closed, either with a successful commit or * with a roll-back. The {@linkplain Transaction#getStatus() status} of the * transaction will indicate which has occurred; an * {@linkplain IStatus#ERROR} indicates roll-back. This event is sent after * all post-commit notifications have gone out to * {@link ResourceSetListener}s. * * * This event is not sent for nested transactions. * * * @param event * indicates the transaction that has closed * * Signals that the transactional editing domain to which the lister is * attached is to be disposed. Disposal result, among other things, in the * removal of the listener from it. * * * @param event * indicates the editing domain that is being disposed. The event * has no * {@linkplain TransactionalEditingDomainEvent#getTransaction() * transaction} * An event object indicating a change in the state of a * {@link TransactionalEditingDomain}, usually in some * {@linkplain transaction #getTransaction()} life-cycle event. * * @author Christian W. Damus (cdamus) * * @since 1.3 * Event {@linkplain #getEventType() type} indicating the * {@linkplain TransactionalEditingDomainListener#transactionStarting(TransactionalEditingDomainEvent) * transaction starting}. * Event {@linkplain #getEventType() type} indicating the * {@linkplain TransactionalEditingDomainListener#transactionInterrupted(TransactionalEditingDomainEvent) * transaction interrupted}. * Event {@linkplain #getEventType() type} indicating the * {@linkplain TransactionalEditingDomainListener#transactionStartied(TransactionalEditingDomainEvent) * transaction started}. * Event {@linkplain #getEventType() type} indicating the * {@linkplain TransactionalEditingDomainListener#transactionClosing(TransactionalEditingDomainEvent) * transaction closing}. * Event {@linkplain #getEventType() type} indicating the * {@linkplain TransactionalEditingDomainListener#transactionClosed(TransactionalEditingDomainEvent) * transaction closed}. * Event {@linkplain #getEventType() type} indicating the * {@linkplain TransactionalEditingDomainListener#editingDomainDisposing(TransactionalEditingDomainEvent) * editing domain disposing}. * Queries the kind of transactional editing event that I signal to * {@link TransactionalEditingDomainListener}s. Each different event type * corresponds to a call-back operation of that interface. * * @return my type * Queries the transaction for which the event signals a change, or * <code>null</code> if the event pertains to the editing domain, itself. * * @return the subject transaction, or <code>null</code> * A default implementation of the {@link TransactionalEditingDomainListener} * interface that does nothing in response to those call-backs, but which is * useful for subclassing to handle just the interesting events. * * @author Christian W. Damus (cdamus) * * @since 1.3 * A convenient superclass for listeners that implement "triggers" to process * {@link Notification}s one at a time, generating a command for each that will * make dependent updates to the model. * * @author Christian W. Damus (cdamus) * Implements the trigger callback by processing the <code>event</code>'s * notifications one by one, delegating to the {@link #trigger} method for each to * generate a command. The commands created by the subclass are chained in * the order that they are received from the subclass. * * @return a composite of the commands returned by the subclass * implementation of the {@link #trigger} method * Implemented by subclasses to provide a trigger command for a single * change in the model. * * @param domain the editing domain * @param notification the notification describing a change in the model * * @return the command, or <code>null</code> if none is required for this * particular notification * I want only ppre-commit events, not post-commit events. * An implementation of a composite undoable operation for composition of * operations which may include {@link AbstractEMFOperation}s. The composite * ensures that all of the nested operations are executed in a single * transaction context. The composite can combine EMF and non-EMF operations * freely, and even include nested <code>CompositeEMFOperation</code>s. * * Although a <code>CompositeEMFOperation</code> provides a single root * transaction context for all of its children, these children open nested * transactions of their own, by default. This can be disabled by turning off * the {@link #isTransactionNestingEnabled() transactionNestingEnabled} property. * This is a hint that child operations should just execute in the transaction * that is already open, unless they require a nested transaction. In * consequence, child operations would not be able to depend on changes being * {@linkplain ResourceSetListener#transactionAboutToCommit triggered} by * previous operations, as triggers will be deferred to the end of the composite * (when it commits). * * * Note that this kind of a composite is different from the * {@link IOperationHistory}'s notion of a {@link TriggeredOperations}, because * the children of a composite are not "triggered" by any primary operation. * Rather, it is assumed that the children are explicitly composed by a client. * The undo contexts of the composite are a union of the undo contexts of its * children. * * * Note: This class cannot be used with the * {@link IOperationHistory#openOperation(ICompositeOperation, int)} API * because it does not implement the <code>ICompositeOperation</code> interface. * This prevents the possibility of open-ended transactions on the operation * history that any listener can contribute additional changes to, on the * same editing domain or a different editing domain. The transaction API * provides a tightly-regulated triggered change mechanism via the * {@link ResourceSetListener} interface. * * * This class is intended to be instantiated by clients and supports a limited * form of subclassing. * * * @author Christian W. Damus (cdamus) * Custom iterator implementation that maintains my undo contexts * correctly when elements are removed. * * @author Christian W. Damus (cdamus) * Custom list-iterator implementation that maintains my undo contexts * correctly, as well as uniqueness of the list contents. * * @author Christian W. Damus (cdamus) * Implements the execution logic by sequential execution of my children. * Non-EMF operations are captured in the transaction's recorded changes * so that they may be correctly rolled back (in sequence) in the event * of rollback, undo, or redo. * Creates a transaction for recording non-EMF changes, using the specified * options. * * @param operation the non-EMF changes to capture in this transaction * @param info the adaptable object provided to the operation when it is * executed * @param options the transaction options * * @return the newly started transaction * * @throws InterruptedException if the current thread was interrupted while * waiting for the transaction to start * I can execute if all of my children can execute. * I can undo if my transaction successfully completed with changes recorded * and my children can all be undone. * I undo by asking my children to undo, in reverse order. * I can redo if my transaction successfully completed with changes recorded * and my children can all be redone. * I undo by asking my children to redo, in forward order. * Removes all of my children and disposes them. * Obtains my nested operations. Note that the return result is mutable and is * identical to my child-operation storage, so subclasses should be careful * of adding or removing contents. This should ordinarily be done only via * the {@link #add(IUndoableOperation)} and {@link #remove(IUndoableOperation)} * methods because these maintain the undo contexts (or, equivalently, using * the iterators). * * @return my list of children * * @see #add(IUndoableOperation) * @see #remove(IUndoableOperation) * @see #iterator() * @see #listIterator(int) * Adds a child operation to me. This should only be done before I am * executed. Has no effect if I already contain this operation as a child. * * @param operation a new child operation * * @throws IllegalStateException if I have already been successfully * executed * Asserts that I have not yet been executed. Changes to my children are * not permitted after I have been executed. * Updates my undo contexts for the addition of a new child operation. * * @param operation a new child operation * Removes a child operation from me. This should only be done before I am * executed. Has no effect if I do not contain this operation as a child. * * Note that, unlike the {@link ICompositeOperation} interface (which * I do not implement), I do not dispose an operation when it is removed * from me. This would not be correct, as I did not create that operation. * * * @param operation a child operation to remove * * @throws IllegalStateException if I have already been successfully * executed * Updates my undo contexts for the removal of a child operation. * * @param operation an erstwhile child operation * Queries whether any of my children has the specified context. * * @param ctx a context * * @return <code>false</code> if none of my children has the specified * context; <code>true</code>, otherwise * Extends the inherited method to toggle my * {@link #setTransactionNestingDisabled(boolean) transaction nesting} * state accordingly. * * @since 1.3 * * @see #isTransactionNestingEnabled() * Queries whether nesting of transactions is enabled, meaning that all * child operations (recursively) execute in their own (nested) transactions. * Nested transactions are enabled by default. * * @return <code>false</code> if child operations execute in a single (flat) * transaction where possible; <code>false</code>, otherwise * * @see #setTransactionNestingEnabled(boolean) * Sets whether nesting of transactions is enabled. Turning this off can * improve performance considerably by avoiding the book-keeping overhead * of large numbers of small transactions, where a composite operation is * a large nested structure. This property is propagated to child * composite operations (recursively). * * Note that this is really only a hint: there are exceptions where * child operation will still create nested transactions. These are: * <ul> * <li>when the child is not an {@link AbstractEMFOperation}. Non-EMF * operations are given special transactions that capture their changes * as change descriptions in the parent transaction</li> * <li>when the child has different * {@link AbstractEMFOperation#getOptions() transaction options} than * the parent composite operation</li> * </ul> * * * @param enable whether to force all child operations to create nested * transactions * * @throws IllegalStateException if I have already been * {@link #execute(IProgressMonitor, IAdaptable) executed}, after which * time transaction nesting cannot be changed * Queries the number of child operations that I contain. * * @return my size * Obtains an iterator to traverse my child operations. * Removing children via this iterator correctly maintains my undo contexts. * * @return an iterator of my children * Obtains an iterator to traverse my child operations in either direction. * Adding and removing children via this iterator correctly maintains my * undo contexts. * * Note that, unlike list iterators generally, this implementation * does not permit the addition of an operation that I already contain * (the composite does not permit duplicates). Moreover, only * {@link IUndoableOperation}s may be added, otherwise * <code>ClassCastException</code>s will result. * * * @return an iterator of my children * Obtains an iterator to traverse my child operations in either direction, * starting from the specified <code>index</code>. * Adding and removing children via this iterator correctly maintains my * undo contexts. * * Note that, unlike list iterators generally, this implementation * does not permit the addition of an operation that I already contain * (the composite does not permit duplicates). Moreover, only * {@link IUndoableOperation}s may be added, otherwise * <code>ClassCastException</code>s will result. * * * @param index the index in my children at which to start iterating * * @return an iterator of my children * An abstract superclass for {@link IUndoableOperation}s that modify EMF * models. The EMF operation provides a read/write transaction context for the * subclass implementation of the execution logic, with undo/redo support "for * free" (via recording of undo information). * * The assumption is that an EMF operation will perform only changes to EMF * models that can be recorded. If concomitant changes to non-EMF models are * also required, then they should be combined with the EMF operation via a * {@link CompositeEMFOperation}, unless ordering of EMF and non-EMF changes * is unimportant. In such cases, it is sufficient to extend the * {@link #doUndo(IProgressMonitor, IAdaptable)} and * {@link #doRedo(IProgressMonitor, IAdaptable)} methods. * * * This class is meant to be extended by clients. * * * @author Christian W. Damus (cdamus) * * @see CompositeEMFOperation * Implements the execution by delegating to the * {@link #doExecute(IProgressMonitor, IAdaptable)} method within a * read/write transaction. * * @see #doExecute(IProgressMonitor, IAdaptable) * Queries whether the specified options differ from the currently active * transaction, if there is one. * * @param options the options to compare against the active transaction * @return <code>false</code> if either there is an active transaction and it * has the same options as specified; <code>true</code>, otherwise * Obtains the options of the currently active transaction, or an empty map * if there is no active transaction. * * @return options currently in effect that would be inherited by a new * transaction that I might create * Creates a suitable aggregate from these statuses. If there are no * statuses to aggregate, then an OK status is returned. If there is a * single status to aggregate, then it is returned. Otherwise, a * multi-status is returned with the provided statuses as children. * * @param statuses the statuses to aggregate. May have zero, one, or more * elements (all must be {@link IStatus}es) * * @return the multi-status * Obtains the change description that I recorded during execution of my * transaction. * * @return my change description, if I executed successfully; * <code>null</code>, otherwise * * Hook for subclasses to learn that the specified <code>transaction</code> * has been successfully committed and, if necessary, to extract information * from it. * * * Note: subclasses should call this super implementation to get some default * behaviours. * * @param transaction a transaction that has committed, which has recorded * our changes * Queries whether I can be undone. I can generally be undone if I was * successfully executed. Subclasses would not usually need to override * this method. * Undoes me by inverting my recorded changes in a transaction. * Hook for subclasses to learn that the specified <code>transaction</code> * has been successfully undone and, if necessary, to extract information * from it. * * @param tx a transaction that has been undone. * Queries whether I can be redone. I can generally be redone if I was * successfully executed. Subclasses would not usually need to override * this method. * Redoes me by replaying my recorded changes in a transaction. * Hook for subclasses to learn that the specified <code>transaction</code> * has been successfully redone and, if necessary, to extract information * from it. * * @param tx a transaction that has been redone. * Obtains my editing domain. * * @return my editing domain * Obtains the transaction options that I use to create my transaction. * * @return my options, or an empty map if none * * Replaces my options with a new set. This may only be done prior to my * initial execution. * * * Note that subclasses may override this method, but if they do so, * then they must call the superclass implementation in order actually to * effect any change to the operation's options. Thus, subclasses may * override to disable this capability or to intercept the <tt>options</tt> * argument and transform its values as required. * * * @param options * my new options * * @throws IllegalStateException * if I have {@linkplain #canSetOptions() already been executed} * * @since 1.3 * * @see #canSetOptions() * Queries whether my options can be changed. That is, whether I have not * yet been executed. * * @return whether my options may be changed * * @since 1.3 * * @see #setOptions(Map) * Creates a transaction, using the specified options, for me to execute * in. * * @param options the transaction options * * @return the newly started transaction * * @throws InterruptedException if the current thread was interrupted while * waiting for the transaction to start * Ensures that the specified transaction is rolled back, first rolling * back a nested transaction (if any). * * @param tx a transaction to roll back * Obtains the transaction in which I execute(d). * * @return my transaction * Implemented by subclasses to perform the model changes. These changes * are applied by manipulation of the EMF metamodel's API, not * by executing commands on the editing domain's command stack. * * @param monitor the progress monitor provided by the operation history. * Will never be <code>null</code> because the * {@link #execute(IProgressMonitor, IAdaptable)} method would substitute * a {@link NullProgressMonitor} in that case * @param info the adaptable provided by the operation history * * @return the status of the execution * * @throws ExecutionException if, for some reason, I fail to complete * the operation * Implements the undo behaviour by inverting my recorded changes. * * Note that subclasses overriding this method must invoke * the super implementation as well. * * * @param monitor the progress monitor provided by the operation history * Will never be <code>null</code> because the * {@link #undo(IProgressMonitor, IAdaptable)} method would substitute * a {@link NullProgressMonitor} in that case * @param info the adaptable provided by the operation history * * @return the status of the undo operation * * @throws ExecutionException on failure to undo * Implements the redo behaviour by replaying my recorded changes. * * Note that subclasses overriding this method must invoke * the super implementation as well. * * * @param monitor the progress monitor provided by the operation history * Will never be <code>null</code> because the * {@link #redo(IProgressMonitor, IAdaptable)} method would substitute * a {@link NullProgressMonitor} in that case * @param info the adaptable provided by the operation history * * @return the status of the redo operation * * @throws ExecutionException on failure to redo * Forgets my transaction and its change description. * Disposes my change description. * * @param force whether to force disposal of the change * Queries whether I reuse an existing read/write transaction when possible. * It is not possible when either there is not any active transaction at the * time of my execution or when the active transaction has different options * from my options. * * @return whether I reuse existing transactions * * @since 1.3 * * @see #setReuseParentTransaction(boolean) * Sets whether I reuse an existing read/write transaction when possible. It * is not possible when either there is not any active transaction at the * time of my execution or when the active transaction has different options * from my options. This can be useful for performance of large nested * operation structures, to eliminate the overhead of creating large numbers * of small transactions with all of the data that they record. * * @param reuseParentTransaction * whether to reuse parent transactions * * @since 1.3 * * @see #isReuseParentTransaction() * * The default implementation of the resource undo-context policy, suitable for * clients to extend/override as required. The default policy is to consider any * resource as affected by an operation if either * * <ol> * <li>A non-touch {@link Notification} is received from a contained object or * from the resource, itself, or</li> * <li>A notification matching (1) is received from a uni-directional * {@link EReference} (i.e., one having no opposite) has an old value or a new * value in the resource * </ol> * * In the first case, above, a subclass can choose to include only changes to a * resource's contents-list and URI as being significant (other resource * properties not affecting the serialization of the resource). * * * The second case, above, is intended for applications that use * {@link ResourceUndoContext}s to manage the Undo menus of their editors. It is * a pessimistic assumption that the referenced resource may either have derived * attributes whose values influenced precursor or successor operations, or that * such operations are influenced by the references incoming to the resource. * Thus, the concern is not so much with the dirty state of the resource as it * is with the integrity of the undo history for the associated editor and the * dependencies between successive operations. Subclasses can disable this case * by overriding the {@link #pessimisticCrossReferences()} method. * * * @author Christian W. Damus (cdamus) * @since 1.3 * * @see #pessimisticCrossReferences() * @see #considerAllResourceChanges() * Queries whether the specified <tt>notification</tt> signals an abstract * change to a resource, which would potentially put that resource into the * operation context. Subclasses may override or extend as needed. * * @param notification * a notification of some concrete change in the resource set * @return whether this change is an abstract change to some resource, for * the purpose of tracking undo context * May be overridden by subclasses to disable pessimistic handling of * cross-resource references. The default implementation returns * <code>true</code> always. * * @return whether to consider changes to directed cross-resource references * as affecting the referenced resource * May be overridden by subclasses to consider changes to any feature of a * resource, not just its contents-list or URI, as affecting it. * * @return <code>true</code> if all changes to a resource are considered as * affecting it for the purposes of undo context; <code>false</code> * if only the contents-list and URI are * Adds to the collection of <tt>resources</tt> any that are affected by the * specified <tt>notification</tt> from a <tt>resource</tt>. * * @param resources * collects the affected resources * @param resource * a resource that sent a notification * @param notification * the notification sent by the resource * Adds to the collection of <tt>resources</tt> any that are affected by the * specified <tt>notification</tt> from an <tt>object</tt>. * * @param resources * collects the affected resources * @param object * a object that sent a notification * @param notification * the notification sent by the object * Adds to the collection of <tt>resources</tt> any that are affected by the * specified <tt>notification</tt> from a <tt>resourceSet</tt>. * * @param resources * collects the affected resources * @param resourceSet * a resource set that sent a notification * @param notification * the notification sent by the resource set * Handles notifications that can potentially represent cross-resource * references. Helper to the * {@link #objectChange(Set, EObject, Notification)} method. * * @param resources * collects the affected resources * @param owner * the owner of the reference that changed * @param notification * a potential cross-resource reference change notification * * A rule determining the resources for which an {@link IUndoableOperation} * should be tagged with {@link ResourceUndoContext}s. In general, these are the * resources that * * <ul> * <li>are modified by the operation, such that they are become dirty, and/or</li> * <li>whose editors should show the operation in their Undo menu</li> * </ul> * * Clients may implement this interface, but it is recommended to extend the * {@link AbstractResourceUndoContextPolicy} class whenever possible. * * * @author Christian W. Damus (cdamus) * @since 1.3 * * @see AbstractResourceUndoContextPolicy * The default undo-context policy used by editing domains for which none is * assigned by the client application. * Determines the resources in the undo context of the specified * <tt>operation</tt>, during which execution the changes indicated by the * given <tt>notifications</tt> occurred. This operation may be called * several times for the same operation, but always with different * notifications. * * @param operation * the operation. It may or may not have finished executing. Must * not be <code>null</code> * @param notifications * a list of notifications of changes caused by the operation * during its execution, in the order in which they occurred. * This may be an empty list, but never <code>null</code> * * @return the resources that are the undo context of this operation, or an * empty list if none. Never ruterns <code>null</code> * An operation that wraps an EMF {@link Command} to execute it in a read/write * transaction on an {@link IOperationHistory}. This class may be created * explicitly by a client of the operation history, or it may be used implicitly * by executing a command on the {@link TransactionalCommandStack}. * * @author Christian W. Damus (cdamus) * Obtains the command that I wrap. * * @return my command * I can execute if my command can execute. * Executes me by executing my command. * I can undo if my command or (if any) trigger command can undo. * Undoes me by undoing my trigger command (if any) and my command. * I can redo if either my wrapped command is a {@link ConditionalRedoCommand} * that can undo, or it is not a conditionally redoable command. * Redoes me by redoing my command and my trigger command (if any). * Extends the inherited implementation to additionally dispose my command * and my trigger command (if any). * Creates a different kind of transaction that knows about this operation. * * @see EMFOperationTransaction * Computes a more user-friendly label for the operation than the label * created by default for EMF's feature-changing commands. * * @param cmd a command * An implementation of the EMF {@link Command} API that wraps an * {@link IUndoableOperation}. It is particularly useful for returning triggers * from a {@link ResourceSetListener} that perform non-EMF changes. An * <code>EMFOperationCommand</code>, when executed, automatically inserts itself * into the change description of the active transaction to support the * inclusion of these non-EMF changes in: * <ul> * <li>transaction rollback (in case of validation failure, etc.)</li> * <li>undo/redo of {@link RecordingCommand}s</li> * </ul> * * @author Christian W. Damus (cdamus) * I can execute if my wrapped operation can execute. * Executes my wrapped operation and inserts it into the active * transaction's change description for rollback and undo/redo support. * * @throws IllegalStateException if I am being executed outside of a * read/write transaction context * Creates a transaction for recording non-EMF changes, using the specified * options. * * @param operation the non-EMF changes to capture in this transaction * @param info the adaptable object provided to the operation when it is * executed * @param options the transaction options * * @return the newly started transaction * * @throws InterruptedException if the current thread was interrupted while * waiting for the transaction to start * I can undo if my wrapped operation can undo. * I undo my wrapped operation. If an adaptable was initially provided to * me and it is still available, then it is passed along to the operation. * * @throws IllegalStateException if I am being undone outside of a * read/write transaction context * I can redo if my wrapped operation can redo. * I redo my wrapped operation. If an adaptable was initially provided to * me and it is still available, then it is passed along to the operation. * * @throws IllegalStateException if I am being redone outside of a * read/write transaction context * Obtains the affected objects from my wrapped operation, if it is an * {@link IAdvancedUndoableOperation}. * My label is my wrapped operation's label. * My description is my wrapped operation's label. * Forgets my operation and the adaptable with which I was initialized, * if any. * Obtains my adaptable, if I was initialized with one and it is still * available. * * @return my adaptable, or <code>null</code> if not available * Obtains the currently active read/write transaction in my editing domain * that is owned by the current thread. * * @return the active transaction, or <code>null</code> if there is no * active transaction or the current thread does not own it or it is * read-only * Obtains the undoable operation that this command is wrapping. * * @return An undoable operation. * An {@link IUndoContext} that tags an EMF operation with a resource affected by it. * Two resource contexts match if and only if they reference the same {@link Resource} * instance. An operation may have any number of distinct resource contexts. * * The determination of which resource is affected by any atomic EMF change is * obvious, except for the case of cross-resource reference changes. When a * cross-resource reference is added or removed, then both the referencing and * referenced resources are considered to be affected, even if the reference is * unidirectional. The assumption is that even without the back-reference, there * is an implicit dependency in that direction. * * * @author Christian W. Damus (cdamus) * I match another <code>context</code> if it is a * <code>ResourceUndoContext</code> representing the same resource as I. * I am equal to other <code>ResourceUndoContexts</code> on the same * resource as mine. * Obtains the resource that I represent. * * @return my resource * Obtains the editing domain that manages my resource. * * @return my editing domain * Analyzes a list of notifications to extract the set of {@link Resource}s * affected by the changes. * * @param notifications * a list of {@link Notification}s indicating changes in a * resource set * * @return the resources affected by the specified notifications. The * resulting set should be treated as unmodifiable * * @deprecated Since the 1.3 release, use the * {@link IResourceUndoContextPolicy#getContextResources(IUndoableOperation, List)} * method of the editing domain's resource undo-context policy, * instead * Extracts the set of EMF {@link Resource}s affected by the specified * operation, from the <code>ResourceUndoContext</code>s attached to it. * * @param operation an undoable operation * * @return the {@link Resource}s that it affects, or an empty set if none. * The resulting set should be treated as unmodifiable * * Factory for creating transactional editing domains that delegate command * execution, undo, and redo to an {@link IOperationHistory}. * * * Since the 1.3 release, the determination of how {@link ResourceUndoContext}s * are attached to undoable operations is * {@linkplain #getResourceUndoContextPolicy() customizable} using the new * {@link IResourceUndoContextPolicy} API. * * * @author Christian W. Damus (cdamus) * The single shared instance of the workbench editing domain factory. * Creates a new editing domain using a default resource set implementation * and the Workbench's shared operation history. * * @return the new editing domain * Creates a new editing domain using the given resource set * and the Workbench's shared operation history. * * @param rset the resource set on which to create the editing domain * * @return the new editing domain * Creates a new editing domain on a default resource set implementation and * the specified operation history. * * @param history the operation history to which I delegate the command stack * * @return the new editing domain * Creates a new editing domain on the given resource set and * the specified operation history. * * @param rset the resource set to use * @param history the operation history to which I delegate the command stack * * @return the new editing domain * Obtains a resource undo-context policy to apply to the editing domain, to * determine how to attach {@link ResourceUndoContext}s to operations in the * associated history. May be overridden by clients to supply a non-default * implementation. * * @return the resource undo-context policy * * @since 1.3 * A specialized transaction implementation that knows the * {@link EMFCommandOperation} that it supports. It is used to communicate * trigger information back to the command operation to support undo/redo. * * @author Christian W. Damus (cdamus) * Obtains the operation that wraps my command. * * @return my operation * Sets the operation that wraps my command. * * @param operation my operation * A transaction encapsulating non-EMF changes (as represented by an * unoable operation). * * @author Christian W. Damus (cdamus) * Customizes the provided options for this transaction. * * @param options The options provided by the call to the constructor that * should be customized. * * @return A new map of options that should be passed to the superclass to * become our official set of options. * Appends my non-EMF change and commits. * Implementation of a transactional command stack that delegates * execution of commands to an {@link IOperationHistory}. * * This is the command stack implementation used by editing domains created by * the {@link WorkspaceEditingDomainFactory}. * * * @author Christian W. Damus (cdamus) * A listener on the editing domain and operation history that tracks * which resources are changed by an operation and attaches the appropriate * {@link ResourceUndoContext} to it when it completes. * * @author Christian W. Damus (cdamus) * Finds resources that have sent unload notifications. * * @param notifications notifications received from a transaction * @return a set of resources that the notifications indicate have been * unloaded, or <code>null</code> if none * Extends the superclass implementation to add/remove listeners on the * editing domain. * Obtains the label to display for the default undo context that I apply * to operations executed through me as {@link Command}s. Subclasses may * override to customize the label. * * @return my default undo context label * * @since 1.2 * Obtains the label to display for the save-point undo context that I apply * to the last operation in my {@linkplain #getDefaultUndoContext() default undo context} * that was executed at the time save was performed (as indicated by invocation * of the {@link #saveIsDone()} method). Subclasses may override to customize the label. * * @return my save-point undo context label * * @since 1.2 * {@inheritDoc} * * @since 1.1 * Queries whether we can undo my default undo context in my operation history. * Undoes my default undo context in my operation history. * Queries whether we can redo my default undo context in my operation history. * Redoes my default undo context in my operation history. * Disposes my default undo context in my operation history. * Gets the command from the most recently executed, done, or redone * operation. * Gets the command from the top of the undo history, if any. * Gets the command from the top of the redo history, if any. * Obtains my resource undo-context policy. * * @return my resource undo-context policy * * @since 1.3 * Sets my resource undo-context policy. * * @param policy * my new policy, or <code>null</code> to restore the default * * @since 1.3 * A specialized transactional command stack that delegates the execution of * commands to an {@link IOperationHistory}. This command stack supports * {@link CommandStack#execute(org.eclipse.emf.common.command.Command) execution} * of {@link Command}s, but supports the following APIs only in terms of the * default undo context of the command stack: * <ul> * <li>{@link CommandStack#execute(Command)}</li> * <li>{@link CommandStack#undo()}</li> * <li>{@link CommandStack#redo()}</li> * <li>{@link CommandStack#flush()}</li> * <li>{@link CommandStack#getMostRecentCommand()}</li> * <li>{@link CommandStack#getUndoCommand()}</li> * <li>{@link CommandStack#getRedoCommand()}</li> * </ul> * All of the above operations map to the effective linear stack of operations * in the history that wrap commands and have the default undo context. Thus, * they will only be consistent with the default command stack semantics if * all commands executed on this command stack's operation history use its * default undo context (which is guaranteed if all commands are executed via * this stack). * * @author Christian W. Damus (cdamus) * * @see #getDefaultUndoContext() * Obtains the operation history to which I delegate command execution. * * @return my operation history * Obtains the default undo context to add to the undoable operations that * I execute on my operation history to wrap {@link Command}s. Moreover, * undo, redo, and flush are context-specific operations * in the operation history, so my undo/redo/flush commands use this context * in delegating to the history. Likewise, the determination of the * most recent command and undo/redo commands depends on this context. * * @return the default undo context for undo/redo/flush invocations * * @see TransactionalCommandStack#execute(Command, java.util.Map) * @see CommandStack#undo() * @see CommandStack#redo() * @see CommandStack#flush() * @see CommandStack#getMostRecentCommand() * @see CommandStack#getUndoCommand() * @see CommandStack#getRedoCommand() * * IUndoableOperation defines an operation that can be executed, undone, and * redone. Operations typically have fully defined parameters. That is, they are * usually created after the user has been queried for any input needed to * define the operation. * * * Operations determine their ability to execute, undo, or redo according to the * current state of the application. They do not make decisions about their * validity based on where they occur in the operation history. That is left to * the particular operation history. * * * @since 3.1 * * Add the specified context to the operation. If a context equal to the * specified context is already present, do not add it again. Note that * determining whether a context is already present is based on equality, * not whether the context matches ({@link IUndoContext#matches(IUndoContext)}) * another context. * * * @param context * the context to be added * * Returns whether the operation can be executed in its current state. * * * * Note: The computation for this method must be fast, as it is called * frequently. If necessary, this method can be optimistic in its * computation (returning true) and later perform more time-consuming * computations during the actual execution of the operation, returning the * appropriate status if the operation cannot actually execute at that time. * * * @return <code>true</code> if the operation can be executed; * <code>false</code> otherwise. * * Returns whether the operation can be undone in its current state. * * * * Note: The computation for this method must be fast, as it is called * frequently. If necessary, this method can be optimistic in its * computation (returning true) and later perform more time-consuming * computations during the actual undo of the operation, returning the * appropriate status if the operation cannot actually be undone at that * time. * * * @return <code>true</code> if the operation can be undone; * <code>false</code> otherwise. * Dispose of the operation. This method is used when the operation is no * longer kept in the history. Implementers of this method typically * unregister any listeners. * * Execute the operation. This method should only be called the first time * that an operation is executed. * * @param monitor * the progress monitor (or <code>null</code>) to use for * reporting progress to the user. * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. * * @return the IStatus of the execution. The status severity should be set * to <code>OK</code> if the operation was successful, and * <code>ERROR</code> if it was not. Any other status is assumed * to represent an incompletion of the execution. * @throws ExecutionException * if an exception occurred during execution. * * Returns the array of contexts that have been assigned to the operation. * * * This method may be called by the operation history from inside a * synchronized block. To avoid deadlock conditions, implementers of this * method must avoid dispatching and waiting on threads that modify the * operation history during this method. * * * @return the array of contexts * Return the label that should be used to show the name of the operation to * the user. This label is typically combined with the command strings shown * to the user in "Undo" and "Redo" user interfaces. * * @return the String label. Should never be <code>null</code>. * * Returns whether the operation has a matching context for the specified * context. * * * This method may be called by the operation history from inside a * synchronized block. To avoid deadlock conditions, implementers of this * method must avoid dispatching and waiting on threads that modify the * operation history during this method. * * * @see IUndoContext#matches(IUndoContext) * * @param context * the context in question * @return <code>true</code> if the context is present, <code>false</code> * if it is not. * Redo the operation. This method should only be called after an operation * has been undone. * * @param monitor * the progress monitor (or <code>null</code>) to use for * reporting progress to the user. * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. * @return the IStatus of the redo. The status severity should be set to * <code>OK</code> if the redo was successful, and * <code>ERROR</code> if it was not. Any other status is assumed * to represent an incompletion of the redo. * @throws ExecutionException * if an exception occurred during redo. * Remove the specified context from the operation. This method has no * effect if the context is not equal to another context in the context * list. Note that determining whether a context is present when removing it * is based on equality, not whether the context matches ({@link * IUndoContext#matches(IUndoContext)}) another context. * * @param context * the context to be removed * Undo the operation. This method should only be called after an operation * has been executed. * * @param monitor * the progress monitor (or <code>null</code>) to use for * reporting progress to the user. * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. * @return the IStatus of the undo. The status severity should be set to * <code>OK</code> if the redo was successful, and * <code>ERROR</code> if it was not. Any other status is assumed * to represent an incompletion of the undo. * @throws ExecutionException * if an exception occurred during undo. * * An undo context is used to "tag" operations as being applicable to a certain * context. The undo context is used to filter the history of operations * available for undo or redo so that only operations appropriate for a given * undo context are shown when the application is presenting that context. * * * The scope of an undo context is defined by the application that is making * undo and redo of operations available. Undo contexts may be related to * application models, or may be associated with UI objects that are providing * undo and redo support. * * * An undo context may be defined as "matching" another context. This allows * applications to provide specialized implementations of an undo context that * will appear in the operation history for their matching context. * * @since 3.1 * Get the label that describes the undo context. * * @return the label for the context. * Return whether the specified context is considered a match for the * receiving context. When a context matches another context, operations * that have the context are considered to also have the matching context. * * @param context * the context to be checked against the receiving context. * * @return <code>true</code> if the receiving context can be considered a * match for the specified context, and <code>false</code> if it * cannot. * * Abstract implementation for an undoable operation. At a minimum, subclasses * should implement behavior for * {@link IUndoableOperation#execute(org.eclipse.core.runtime.IProgressMonitor, org.eclipse.core.runtime.IAdaptable)}, * {@link IUndoableOperation#redo(org.eclipse.core.runtime.IProgressMonitor, org.eclipse.core.runtime.IAdaptable)}, * and * {@link IUndoableOperation#undo(org.eclipse.core.runtime.IProgressMonitor, org.eclipse.core.runtime.IAdaptable)}. * * * @see org.eclipse.core.commands.operations.IUndoableOperation * * @since 3.1 * Set the label of the operation to the specified name. * * @param name * the string to be used for the label. Should never be * <code>null</code>. * The string representation of this operation. Used for debugging purposes * only. This string should not be shown to an end user. * * @return The string representation. * * IOperationHistory tracks a history of operations that can be undone or * redone. Operations are added to the history once they have been initially * executed. Clients may choose whether to have the operations history perform * the initial execution or to simply add an already-executed operation to the * history. * * * Once operations are added to the history, the methods * {@link #canRedo(IUndoContext)} and {@link #canUndo(IUndoContext)} are used to * determine whether there is an operation available for undo and redo in a * given undo context. The context-based protocol implies that there is only one * operation that can be undone or redone at a given time in a given context. * This is typical of a linear undo model, when only the most recently executed * operation is available for undo. When this protocol is used, a linear model * is enforced by the history. * * * It is up to clients to determine how to maintain a history that is invalid or * stale. For example, when the most recent operation for a context cannot be * performed, clients may wish to dispose the history for that context. * * * Additional protocol allows direct undo and redo of a specified operation, * regardless of its position in the history. When a more flexible undo model is * supported, these methods can be implemented to undo and redo directly * specified operations. If an implementer of IOperationHistory does not allow * direct undo and redo, these methods can return a status indicating that it is * not allowed. * * * Listeners ({@link IOperationHistoryListener}) can listen for notifications * about changes in the history (operations added or removed), and for * notification before and after any operation is executed, undone or redone. * Notification of operation execution only occurs when clients direct the * history to execute the operation. If the operation is added after it is * executed, there can be no notification of its execution. * * * {@link IOperationApprover} defines an interface for approving an undo or redo * before it occurs. This is useful for injecting policy-decisions into the undo * model - whether direct undo and redo are supported, or warning the user about * certain kinds of operations. It can also be used when clients maintain state * related to an operation and need to determine whether an undo or redo will * cause any conflicts with their local state. * * * @since 3.1 * An operation is to be opened or closed for execution. (value is 1). * An operation is to be opened for undo. (value is 2). * An operation is to be opened for redo. (value is 3). * An undo context that can be used to refer to the global undo history. * This context is not intended to be assigned to operations. Instead, it is * used for querying the history or performing an undo or redo on the entire * history, regardless of each operation's undo contexts. * An operation info status describing the condition that there is no * available operation for redo. * An operation info status describing the condition that there is no * available operation for undo. * An operation error status describing the condition that the operation * available for execution, undo or redo is not in a valid state for the * action to be performed. * * Add the specified operation to the history without executing it. The * operation should have already been executed by the time it is added to * the history. Listeners will be notified that the operation was added to * the history (<code>OPERATION_ADDED</code>). * * * @param operation * the operation to be added to the history * * Add the specified approver to the list of operation approvers consulted * by the operation history before an undo or redo is attempted. * * * @param approver * the IOperationApprover to be added as an approver.the instance * to remove. Must not be <code>null</code>. If an attempt is * made to register an instance which is already registered with * this instance, this method has no effect. * * @see org.eclipse.core.commands.operations.IOperationApprover * * Add the specified listener to the list of operation history listeners * that are notified about changes in the history or operations that are * executed, undone, or redone. * * * @param listener * the IOperationHistoryListener to be added as a listener. Must * not be <code>null</code>. If an attempt is made to register * an instance which is already registered with this instance, * this method has no effect. * * @see org.eclipse.core.commands.operations.IOperationHistoryListener * @see org.eclipse.core.commands.operations.OperationHistoryEvent * * Close the current operation. If the operation has successfully completed, * send listeners a <code>DONE</code>, <code>UNDONE</code>, or * <code>REDONE</code> notification, depending on the mode. Otherwise send * an <code>OPERATION_NOT_OK</code> notification. Add the operation to the * history if specified and send an <code>OPERATION_ADDED</code> * notification. * * * Any operations that are executed and added after this operation is closed * will no longer be considered part of this operation. * * * This method has no effect if the caller has not previously called * {@link #openOperation}. * * * @param operationOK * <code>true</code> if the operation successfully completed. * Listeners should be notified with <code>DONE</code>, * <code>UNDONE</code>, or <code>REDONE</code>. * <code>false</code> if the operation did not successfully * complete. Listeners should be notified with * <code>OPERATION_NOT_OK</code>. * @param addToHistory * <code>true</code> if the operation should be added to the * history, <code>false</code> if it should not. If the * <code>operationOK</code> parameter is <code>false</code>, * the operation will never be added to the history. * @param mode * the mode the operation was opened in. Can be one of * <code>EXECUTE</code>, <code>UNDO</code>, or * <code>REDO</code>. This determines what notifications are * sent. * * Return whether there is a valid redoable operation available in the given * context. * * * @param context * the context to be checked * @return <code>true</code> if there is a redoable operation, * <code>false</code> otherwise. * * Return whether there is a valid undoable operation available in the given * context * * * @param context * the context to be checked * @return <code>true</code> if there is an undoable operation, * <code>false</code> otherwise. * * Dispose of the specified context in the history. All operations that have * only the given context will be disposed. References to the context in * operations that have more than one context will also be removed. A * history notification for the removal of each operation being disposed * will be sent. * * * @param context * the context to be disposed * @param flushUndo * <code>true</code> if the context should be flushed from the * undo history, <code>false</code> if it should not * @param flushRedo * <code>true</code> if the context should be flushed from the * redo history, <code>false</code> if it should not. * @param flushContext * <code>true</code> if the context is no longer in use and * references to it should be flushed. * * Execute the specified operation and add it to the operations history if * successful. This method is used by clients who wish operation history * listeners to receive notifications before and after the execution of the * operation. Execution of the operation is subject to approval by any * registered {@link IOperationApprover2}. If execution is approved, * listeners will be notified before (<code>ABOUT_TO_EXECUTE</code>) and * after (<code>DONE</code> or <code>OPERATION_NOT_OK</code>). * * * If the operation successfully executes, an additional notification that * the operation has been added to the history (<code>OPERATION_ADDED</code>) * will be sent. * * * @param operation * the operation to be executed and then added to the history * * @param monitor * the progress monitor to be used (or <code>null</code>) * during the operation. * * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. * * @return the IStatus indicating whether the execution succeeded. * * * The severity code in the returned status describes whether the operation * succeeded and whether it was added to the history. <code>OK</code> * severity indicates that the execute operation was successful and that the * operation has been added to the history. Listeners will receive * notifications about the operation's success (<code>DONE</code>) and * about the operation being added to the history (<code>OPERATION_ADDED</code>). * * * <code>CANCEL</code> severity indicates that the user cancelled the * operation and that the operation was not added to the history. * <code>ERROR</code> severity indicates that the operation did not * successfully execute and that it was not added to the history. Any other * severity code is not specifically interpreted by the history, and the * operation will not be added to the history. For all severities other than * <code>OK</code>, listeners will receive the * <code>OPERATION_NOT_OK</code> notification instead of the * <code>DONE</code> notification if the execution was approved and * attempted. * * * @throws ExecutionException * if an exception occurred during execution. * * * Return the limit on the undo and redo history for a particular context. * * * @param context * the context whose limit is requested * * @return the undo and redo history limit for the specified context. * * Get the array of operations in the redo history for a the specified undo * context. The operations are in the order that they were added to the * history, with the most recently undone operation appearing last in the * array. This history is used LIFO (last in, first out) when successive * "Redo" commands are invoked. * * * * @param context * the context for the redo * @return the array of operations in the history * * Get the operation that will next be redone in the given undo context. * * * @param context * the context for the redo * @return the operation to be redone or <code>null</code> if there is no * operation available. There is no guarantee that the returned * operation is valid for redo. * * Get the array of operations in the undo history for the specified undo * context. The operations are in the order that they were added to the * history, with the most recently added operation appearing last in the * array. This history is used LIFO (last in, first out) when successive * "Undo" commands are invoked. * * * @param context * the context for the undo * @return the array of operations in the history * * Open this composite operation and consider it an operation that contains * other related operations. Consider all operations that are subsequently * executed or added to be part of this operation. When an operation is * opened, listeners will immediately receive a notification for the opened * operation. The specific notification depends on the mode in which the * operation is opened (<code>ABOUT_TO_EXECUTE</code>, * <code>ABOUT_TO_UNDO</code>, <code>ABOUT_TO_REDO</code>). * Notifications for any other execute or add while this operation is open * will not occur. Instead, those operations will be added to the current * operation. * * * Note: This method is intended to be used by legacy undo frameworks that * do not expect related undo operations to appear in the same undo history * as the triggering undo operation. When an operation is open, any * subsequent requests to execute, add, undo, or redo another operation will * result in that operation being added to the open operation. Once the * operation is closed, the composite will be considered an atomic * operation. Clients should not modify the composite directly (by adding * and removing children) while it is open. * * * When a composite is open, operations that are added to the history will * be considered part of the open operation instead. Operations that are * executed while a composite is open will first be executed and then added * to the composite. * * * Open operations cannot be nested. If this method is called when a * different operation is open, it is presumed to be an application coding * error and this method will throw an IllegalStateException. * * * @param operation * the composite operation to be considered as the parent for all * subsequent operations. * @param mode * the mode the operation is executing in. Can be one of * <code>EXECUTE</code>, <code>UNDO</code>, or * <code>REDO</code>. This determines what notifications are * sent. * * The specified operation has changed in some way since it was added to the * operation history. Notify listeners with an OPERATION_CHANGED event. * * * @param operation * the operation that has changed. * * * Get the operation that will next be undone in the given undo context. * * * @param context * the context for the undo * @return the operation to be undone or <code>null</code> if there is no * operation available. There is no guarantee that the available * operation is valid for the undo. * * Redo the most recently undone operation in the given context. The redo of * the operation is subject to approval by any registered * {@link IOperationApprover} before it is attempted. * * * @param context * the context to be redone * @param monitor * the progress monitor to be used for the redo, or * <code>null</code> if no progress monitor is provided. * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. * @return the IStatus indicating whether the redo succeeded. * * * The severity code in the returned status describes whether the operation * succeeded and whether it remains in the history. <code>OK</code> * severity indicates that the redo operation was successful and (since * release 3.2), that the operation will be placed in the undo history. * (Prior to 3.2, a successfully redone operation would not be placed on the * undo history if it could not be undone. Since 3.2, this is relaxed, and * all successfully redone operations are placed in the undo history.) * Listeners will receive the <code>REDONE</code> notification. * * * Other severity codes (<code>CANCEL</code>, <code>ERROR</code>, * <code>INFO</code>, etc.) are not specifically interpreted by the * history. The operation will remain in the history and the returned status * is simply passed back to the caller. For all severities other than * <code>OK</code>, listeners will receive the * <code>OPERATION_NOT_OK</code> notification instead of the * <code>REDONE</code> notification if the redo was approved and * attempted. * * * @throws ExecutionException * if an exception occurred during redo. * * * Redo the specified operation. The redo of the operation is subject to * approval by any registered {@link IOperationApprover} before it is * attempted. * * * @param operation * the operation to be redone * @param monitor * the progress monitor to be used for the redo, or code>null</code> * if no progress monitor is provided * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not <code>null</code>, * it should minimally contain an adapter for the * org.eclipse.swt.widgets.Shell.class. * * @return the IStatus indicating whether the redo succeeded. * * * The severity code in the returned status describes whether the operation * succeeded and whether it remains in the history. <code>OK</code> * severity indicates that the redo operation was successful, and (since * release 3.2), that the operation will be placed in the undo history. * (Prior to 3.2, a successfully redone operation would not be placed on the * undo history if it could not be undone. Since 3.2, this is relaxed, and * all successfully redone operations are placed in the undo history.) * Listeners will receive the <code>REDONE</code> notification. * * * Other severity codes (<code>CANCEL</code>, <code>ERROR</code>, * <code>INFO</code>, etc.) are not specifically interpreted by the * history. The operation will remain in the history and the returned status * is simply passed back to the caller. For all severities other than <code>OK</code>, * listeners will receive the <code>OPERATION_NOT_OK</code> notification * instead of the <code>REDONE</code> notification if the redo was * approved and attempted. * * * @throws ExecutionException * if an exception occurred during redo. * * Remove the specified operation approver from the list of operation * approvers that are consulted before an operation is undone or redone. * * * @param approver * the IOperationApprover to be removed. Must not be * <code>null</code>. If an attempt is made to remove an * instance which is not already registered with this instance, * this method has no effect. * * Remove the specified listener from the list of operation history * listeners. * * * @param listener * The IOperationHistoryListener to be removed. Must not be * <code>null</code>. If an attempt is made to remove an * instance which is not already registered with this instance, * this method has no effect. * * Replace the specified operation in the undo or redo history with the * provided list of replacements. This protocol is typically used when a * composite is broken up into its atomic parts. The replacements will be * inserted so that the first replacement will be the first of the * replacements to be undone or redone. Listeners will be notified about the * removal of the replaced element and the addition of each replacement. * * * @param operation * The IUndoableOperation to be replaced * @param replacements * the array of IUndoableOperation to replace the first operation * * Set the limit on the undo and redo history for a particular context. * * * @param context * the context whose limit is being set. * * @param limit * the maximum number of operations that should be kept in the * undo or redo history for the specified context. Must not be * negative. * * Undo the most recently executed operation in the given context. The undo * of the operation is subject to approval by any registered * {@link IOperationApprover} before it is attempted. * * * @param context * the context to be undone * @param monitor * the progress monitor to be used for the undo, or * <code>null</code> if no progress monitor is provided. * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. * * @return the IStatus indicating whether the undo succeeded. * * * The severity code in the returned status describes whether the operation * succeeded and whether it remains in the history. <code>OK</code> * severity indicates that the undo operation was successful, and (since * release 3.2), that the operation will be placed on the redo history. * (Prior to 3.2, a successfully undone operation would not be placed on the * redo history if it could not be redone. Since 3.2, this is relaxed, and * all successfully undone operations are placed in the redo history.) * Listeners will receive the <code>UNDONE</code> notification. * * * Other severity codes (<code>CANCEL</code>, <code>ERROR</code>, * <code>INFO</code>, etc.) are not specifically interpreted by the * history. The operation will remain in the history and the returned status * is simply passed back to the caller. For all severities other than * <code>OK</code>, listeners will receive the * <code>OPERATION_NOT_OK</code> notification instead of the * <code>UNDONE</code> notification if the undo was approved and * attempted. * * * @throws ExecutionException * if an exception occurred during undo. * * Undo the specified operation. The undo of the operation is subject to * approval by any registered {@link IOperationApprover} before it is * attempted. * * * @param operation * the operation to be undone * @param monitor * the progress monitor to be used for the undo, or * <code>null</code> if no progress monitor is provided * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. * * @return the IStatus indicating whether the undo succeeded. * * * The severity code in the returned status describes whether the operation * succeeded and whether it remains in the history. <code>OK</code> * severity indicates that the undo operation was successful, and (since * release 3.2), that the operation will be placed on the redo history. * (Prior to 3.2, a successfully undone operation would not be placed on the * redo history if it could not be redone. Since 3.2, this is relaxed, and * all successfully undone operations are placed in the redo history.) * Listeners will receive the <code>UNDONE</code> notification. * * * Other severity codes (<code>CANCEL</code>, <code>ERROR</code>, * <code>INFO</code>, etc.) are not specifically interpreted by the * history. The operation will remain in the history and the returned status * is simply passed back to the caller. For all severities other than * <code>OK</code>, listeners will receive the * <code>OPERATION_NOT_OK</code> notification instead of the * <code>UNDONE</code> notification if the undo was approved and * attempted. * * * @throws ExecutionException * if an exception occurred during undo. * * This interface is used to listen to notifications from an IOperationHistory. * The supplied OperationHistoryEvent describes the particular notification. * * * Operation history listeners must be prepared to receive notifications from a * background thread. Any UI access occurring inside the implementation must be * properly synchronized using the techniques specified by the client's widget * library. * * * @since 3.1 * Something of note has happened in the IOperationHistory. Listeners should * check the supplied event for details. * * @param event * the OperationHistoryEvent that describes the particular * notification. * * OperationHistoryEvent is used to communicate changes that occur in a * DefaultOperationHistory, including the addition or removal of operations, and * the execution, undo, and redo of operations. * * * Operation history listeners must be prepared to receive notifications from a * background thread. Any UI access occurring inside the implementation must be * properly synchronized using the techniques specified by the client's widget * library. * * * * @since 3.1 * ABOUT_TO_EXECUTE indicates that an operation is about to execute. * Listeners should prepare for the execution as appropriate. Listeners will * receive a DONE notification if the operation is successful, or an * OPERATION_NOT_OK notification if the execution is cancelled or otherwise * fails. This notification is only received for those operations executed * by the operation history. Operations that are added to the history after * execution do not trigger these notifications. * * If the operation successfully executes, clients will also receive a * notification that it has been added to the history. * * (value is 1). * ABOUT_TO_REDO indicates that an operation is about to be redone. * Listeners should prepare for the redo as appropriate. Listeners will * receive a REDONE notification if the operation is successful, or an * OPERATION_NOT_OK notification if the redo is cancelled or otherwise * fails. * * (value is 2). * ABOUT_TO_UNDO indicates that an operation is about to be undone. * Listeners should prepare for the undo as appropriate. Listeners will * receive an UNDONE notification if the operation is successful, or an * OPERATION_NOT_OK notification if the undo is cancelled or otherwise * fails. * * (value is 3). * DONE indicates that an operation has been executed. Listeners can take * appropriate action, such as revealing any relevant state in the UI. This * notification is only received for those operations executed by the * operation history. Operations that are added to the history after * execution do not trigger this notification. * * Clients will also receive a notification that the operation has been * added to the history. * * (value is 4). * OPERATION_ADDED indicates that an operation was added to the history. * Listeners can use this notification to add their undo context to a new * operation as appropriate or otherwise record the operation. * * (value is 5). * OPERATION_CHANGED indicates that an operation has changed in some way * since it was added to the operations history. * * (value is 6). * OPERATION_NOT_OK indicates that an operation was attempted and not * successful. Listeners typically use this when they have prepared for an * execute, undo, or redo, and need to know that the operation did not * successfully complete. For example, listeners that turn redraw off before * an operation is undone would turn redraw on when the operation completes, * or when this notification is received, since there will be no * notification of the completion. * * (value is 7). * OPERATION_REMOVED indicates an operation was removed from the history. * Listeners typically remove any record of the operation that they may have * kept in their own state. The operation has been disposed by the time * listeners receive this notification. * * (value is 8). * REDONE indicates that an operation was redone. Listeners can take * appropriate action, such as revealing any relevant state in the UI. * * (value is 9). * UNDONE indicates that an operation was undone. Listeners can take * appropriate action, such as revealing any relevant state in the UI. * * (value is 10). * Return the type of event that is occurring. * * @return the type code indicating the type of event. * Return the operation history that triggered this event. * * @return the operation history * Return the operation associated with this event. * * @return the operation * Return the status associated with this event. * * @return the status associated with this event. The status may be null. * * @since 3.2 * * An abstract class for detecting violations in a strict linear undo/redo * model. Once a violation is detected, subclasses implement the specific * behavior for indicating whether or not the undo/redo should proceed. * * * @since 3.1 * Return a status indicating whether a linear redo violation is allowable. * A linear redo violation is defined as a request to redo a particular * operation even if it is not the most recently added operation to the redo * history. * * @param operation * the operation for which a linear redo violation has been * detected. * @param context * the undo context in which the linear redo violation exists * @param history * the operation history containing the operation * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. * * @return the IStatus describing whether the redo violation is allowed. The * redo will not proceed if the status severity is not * <code>OK</code>, and the caller requesting the redo will be * returned the status that caused the rejection. Specific status * severities will not be interpreted by the history. * Return a status indicating whether a linear undo violation is allowable. * A linear undo violation is defined as a request to undo a particular * operation even if it is not the most recently added operation to the undo * history. * * @param operation * the operation for which a linear undo violation has been * detected. * @param context * the undo context in which the linear undo violation exists * @param history * the operation history containing the operation * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. * * @return the IStatus describing whether the undo violation is allowed. The * undo will not proceed if the status severity is not * <code>OK</code>, and the caller requesting the undo will be * returned the status that caused the rejection. Specific status * severities will not be interpreted by the history. * * IOperationApprover defines an interface for approving the undo or redo of a * particular operation within an operation history. Operations that are * candidates for undo or redo have already been validated against their current * state and according to the rules of the history. * * * By the time an IOperationApprover is consulted, the undo has already been * requested. Approvers should return an <code>IStatus</code> object with * severity <code>OK</code> if the operation should proceed, and any other * severity if it should not. When an operation is not approved, it is expected * that the object not allowing the operation has already consulted the user if * necessary or otherwise provided any necessary information to the user about * the fact that the operation is not approved. * * * Operation approvers must be prepared to receive the approval messages from a * background thread. Any UI access occurring inside the implementation must be * properly synchronized using the techniques specified by the client's widget * library. * * * @since 3.1 * Return a status indicating whether the specified operation should be * redone. Any status that does not have severity <code>IStatus.OK</code> * will not be approved. Implementers should not assume that the redo will * be performed when the status is <code>OK</code>, since other operation * approvers may veto the redo. * * @param operation * the operation to be redone * @param history * the history redoing the operation * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. Even if UI * information is provided, the implementation of this method * must be prepared for being called from a background thread. * Any UI access must be properly synchronized using the * techniques specified by the client's widget library. * @return the IStatus describing whether the operation is approved. The * redo will not proceed if the status severity is not * <code>OK</code>, and the caller requesting the redo will be * returned the status that caused the rejection. Any other status * severities will not be interpreted by the history. * Return a status indicating whether the specified operation should be * undone. Any status that does not have severity <code>IStatus.OK</code> * will not be approved. Implementers should not assume that the undo will * be performed when the status is <code>OK</code>, since other operation * approvers can veto the undo. * * @param operation * the operation to be undone * @param history * the history undoing the operation * @param info * the IAdaptable (or <code>null</code>) provided by the * caller in order to supply UI information for prompting the * user if necessary. When this parameter is not * <code>null</code>, it should minimally contain an adapter * for the org.eclipse.swt.widgets.Shell.class. Even if UI * information is provided, the implementation of this method * must be prepared for being called from a background thread. * Any UI access must be properly synchronized using the * techniques specified by the client's widget library. * @return the IStatus describing whether the operation is approved. The * undo will not proceed if the status severity is not * <code>OK</code>, and the caller requesting the undo will be * returned the status that caused the rejection. Any other status * severities will not be interpreted by the history. * * A base implementation of IOperationHistory that implements a linear undo and * redo model . The most recently added operation is available for undo, and the * most recently undone operation is available for redo. * * * If the operation eligible for undo is not in a state where it can be undone, * then no undo is available. No other operations are considered. Likewise, if * the operation available for redo cannot be redone, then no redo is available. * * * Implementations for the direct undo and redo of a specified operation are * available. If a strict linear undo is to be enforced, than an * IOperationApprover should be installed that prevents undo and redo of any * operation that is not the most recently undone or redone operation in all of * its undo contexts. * * * The data structures used by the DefaultOperationHistory are synchronized, and * entry points that modify the undo and redo history concurrently are also * synchronized. This means that the DefaultOperationHistory is relatively * "thread-friendly" in its implementation. Outbound notifications or operation * approval requests will occur on the thread that initiated the request. * Clients may use DefaultOperationHistory API from any thread; however, * listeners or operation approvers that receive notifications from the * DefaultOperationHistory must be prepared to receive these notifications from * a background thread. Any UI access occurring inside these notifications must * be properly synchronized using the techniques specified by the client's * widget library. * * * * This implementation is not intended to be subclassed. * * * @see org.eclipse.core.commands.operations.IOperationHistory * @see org.eclipse.core.commands.operations.IOperationApprover * * @since 3.1 * This flag can be set to <code>true</code> if the history should print * information to <code>System.out</code> whenever notifications about * changes to the history occur. This flag should be used for debug purposes * only. * This flag can be set to <code>true</code> if the history should print * information to <code>System.out</code> whenever an unexpected condition * arises. This flag should be used for debug purposes only. * This flag can be set to <code>true</code> if the history should print * information to <code>System.out</code> whenever an undo context is * disposed. This flag should be used for debug purposes only. * This flag can be set to <code>true</code> if the history should print * information to <code>System.out</code> during the open/close sequence. * This flag should be used for debug purposes only. * This flag can be set to <code>true</code> if the history should print * information to <code>System.out</code> whenever an operation is not * approved. This flag should be used for debug purposes only. * the list of {@link IOperationApprover}s * a map of undo limits per context * the list of {@link IOperationHistoryListener}s * the list of operations available for redo, LIFO * the list of operations available for undo, LIFO * a lock that is used to synchronize access between the undo and redo * history * An operation that is "absorbing" all other operations while it is open. * When this is not null, other operations added or executed are added to * this composite. * * a lock that is used to synchronize access to the open composite. * * Add the specified approver to the list of operation approvers consulted * by the operation history before an undo or redo is allowed to proceed. * This method has no effect if the instance being added is already in the * list. * * * Operation approvers must be prepared to receive these the operation * approval messages from a background thread. Any UI access occurring * inside the implementation must be properly synchronized using the * techniques specified by the client's widget library. * * * @param approver * the IOperationApprover to be added as an approver. * * * Add the specified listener to the list of operation history listeners * that are notified about changes in the history or operations that are * executed, undone, or redone. This method has no effect if the instance * being added is already in the list. * * * Operation history listeners must be prepared to receive notifications * from a background thread. Any UI access occurring inside the * implementation must be properly synchronized using the techniques * specified by the client's widget library. * * * @param listener * the IOperationHistoryListener to be added as a listener. * * @see org.eclipse.core.commands.operations.IOperationHistoryListener * @see org.eclipse.core.commands.operations.OperationHistoryEvent * Check the redo limit before adding an operation. In theory the redo limit * should never be reached, because the redo items are transferred from the * undo history, which has the same limit. The redo history is cleared * whenever a new operation is added. We check for completeness since * implementations may change over time. * * Return a boolean indicating whether the redo should proceed. * Check the undo limit before adding an operation. Return a boolean * indicating whether the undo should proceed. * Perform the redo. All validity checks have already occurred. * * @param monitor * @param operation * Perform the undo. All validity checks have already occurred. * * @param monitor * @param operation * An implementation of a command stack. A stack manages the executing, undoing, * and redoing of {@link Command Commands}. Executed commands are pushed onto a * a stack for undoing later. Commands which are undone are pushed onto a redo * stack. Whenever a new command is executed, the Redo stack is flushed. * * A CommandStack contains a dirty property. This property can be used to * determine when persisting changes is required. The stack is dirty whenever * the last executed or redone command is different than the command that was at * the top of the undo stack when {@link #markSaveLocation()} was last called. * Initially, the undo stack is empty, and not dirty. * * @author hudsonr * Constant indicating notification after a command has been executed (value * is 8). * Constant indicating notification after a command has been redone (value * is 16). * Constant indicating notification after a command has been undone (value * is 32). * A bit-mask indicating notification after a command has done something. * Currently this includes after a command has been undone, redone, or * executed. This will include new events should they be introduced in the * future. * * Usage * * <PRE> * if ((commandStackEvent.getDetail() & CommandStack.POST_MASK) != 0) { * // Do something, like: * stopBatchingChanges(); * } * </PRE> * Constant indicating notification prior to executing a command (value is * 1). * Constant indicating notification prior to redoing a command (value is 2). * Constant indicating notification prior to undoing a command (value is 4). * A bit-mask indicating notification before a command makes a change. * Currently this includes before a command has been undone, redone, or * executed. This will include new events should they be introduced in the * future. * * Usage * * <PRE> * if ((commandStackEvent.getDetail() & CommandStack.PRE_MASK) != 0) { * // Do something, like: * startBatchingChanges(); * } * </PRE> * The list of {@link CommandStackListener}s. * * @deprecated This field should not be referenced, use * {@link #notifyListeners()} * Appends the listener to the list of command stack listeners. Multiple * adds result in multiple notifications. * * @since 3.1 * @param listener * the event listener * Appends the listener to the list of command stack listeners. Multiple * adds will result in multiple notifications. * * @param listener * the listener * @return <code>true</code> if it is appropriate to call {@link #redo()}. * @return <code>true</code> if {@link #undo()} can be called * This will <code>dispose()</code> all the commands in both the undo and * redo stack. Both stacks will be empty afterwards. * Executes the specified Command if possible. Prior to executing the * command, a CommandStackEvent for {@link #PRE_EXECUTE} will be fired to * event listeners. Similarly, after attempting to execute the command, an * event for {@link #POST_EXECUTE} will be fired. If the execution of the * command completely normally, stack listeners will receive * {@link CommandStackListener#commandStackChanged(EventObject) * stackChanged} notification. * * If the command is <code>null</code> or cannot be executed, nothing * happens. * * @param command * the Command to execute * @see CommandStackEventListener * Flushes the entire stack and resets the save location to zero. This * method might be called when performing "revert to saved". * @return an array containing all commands in the order they were executed * Peeks at the top of the redo stack. This is useful for describing * to the User what will be redone. The returned <code>Command</code> has a * label describing it. * * @return the top of the redo stack, which may be <code>null</code> * Peeks at the top of the undo stack. This is useful for describing * to the User what will be undone. The returned <code>Command</code> has a * label describing it. * * @return the top of the undo stack, which may be <code>null</code> * Returns the undo limit. The undo limit is the maximum number of atomic * operations that the User can undo. <code>-1</code> is used to indicate no * limit. * * @return the undo limit * Returns true if the stack is dirty. The stack is dirty whenever the last * executed or redone command is different than the command that was at the * top of the undo stack when {@link #markSaveLocation()} was last called. * * @return <code>true</code> if the stack is dirty * Marks the last executed or redone Command as the point at which the * changes were saved. Calculation of {@link #isDirty()} will be based on * this checkpoint. * Sends notification to all {@link CommandStackListener}s. * * @deprecated * Notifies command stack event listeners that the command stack has changed * to the specified state. * * @param command * the command * @param state * the current stack state * @since 3.2 * Calls redo on the Command at the top of the redo stack, and pushes * that Command onto the undo stack. This method should only be * called when {@link #canUndo()} returns <code>true</code>. * Removes the first occurrence of the specified listener. * * @param listener * the listener * Removes the first occurrence of the specified listener. * * @param listener * the listener * Sets the undo limit. The undo limit is the maximum number of atomic * operations that the User can undo. <code>-1</code> is used to indicate no * limit. * * @param undoLimit * the undo limit * Undoes the most recently executed (or redone) Command. The Command is * popped from the undo stack to and pushed onto the redo stack. This method * should only be called when {@link #canUndo()} returns <code>true</code>. * An Abstract implementation of {@link Command}. * * @author hudsonr * @since 2.0 * @return <code>true</code> if the command can be executed * @return <code>true</code> if the command can be undone. This method * should only be called after <code>execute()</code> or * <code>redo()</code> has been called. * Returns a Command that represents the chaining of a specified Command to * this Command. The Command being chained will <code>execute()</code> after * this command has executed, and it will <code>undo()</code> before this * Command is undone. * * @param command * <code>null</code> or the Command being chained * @return a Command representing the union * This is called to indicate that the <code>Command</code> will not be used * again. The Command may be in any state (executed, undone or redone) when * dispose is called. The Command should not be referenced in any way after * it has been disposed. * executes the Command. This method should not be called if the Command is * not executable. * @return an untranslated String used for debug purposes only * @return a String used to describe this command to the User * Re-executes the Command. This method should only be called after * <code>undo()</code> has been called. * Sets the debug label for this command * * @param label * a description used for debugging only * Sets the label used to describe this command to the User. * * @param label * the label * Undoes the changes performed during <code>execute()</code>. This method * should only be called after <code>execute</code> has been called, and * only when <code>canUndo()</code> returns <code>true</code>. * * @see #canUndo() * A CommandStackListener is notified whenever the {@link CommandStack}'s state * has changed. * Called when the {@link CommandStack}'s state has changed. * * @param event * the event * A listener interface for receiving notification before and after commands are * executed, undone, or redone. * * @since 3.1 * Sent when an event occurs on the command stack. * {@link CommandStackEvent#getDetail()} can be used to identify the type of * event which has occurred. * * @since 3.1 * @param event * the event * Instances of this class are sent whenever stack events occur. The type of * event can be determined by calling {@link #getDetail()}, and comparing the * return value to constants defined by {@link CommandStack}. * * Warning: this class is not intended to be subclassed. * * @since 3.1 * Returns <code>null</code> or a Command if a command is relevant to the * current event. * * @since 3.1 * @return <code>null</code> or a command * Returns <code>true</code> if this event is fired prior to the stack * changing. * * @return <code>true</code> if pre-change event * @since 3.2 * Returns <code>true</code> if this event is fired after the stack having * changed. * * @return <code>true</code> if post-change event * @since 3.2 * Returns an integer identifying the type of event which has occurred. * * @since 3.1 * @return the detail of the event * An aggregation of multiple <code>Commands</code>. A * <code>CompoundCommand</code> is executable if all of its contained Commands * are executable, and it has at least one contained Command. The same is true * for undo. When undo is called, the contained Commands are undone in the * reverse order in which they were executed. * * An empty CompoundCommand is not executable. * * A CompoundCommand can be {@link #unwrap() unwrapped}. Unwrapping returns the * simplest equivalent form of the CompoundCommand. So, if a CompoundCommand * contains just one Command, that Command is returned. * Adds the specified command if it is not <code>null</code>. * * @param command * <code>null</code> or a Command * @see org.eclipse.gef.commands.Command#canExecute() * @see org.eclipse.gef.commands.Command#canUndo() * Disposes all contained Commands. * * @see org.eclipse.gef.commands.Command#dispose() * Execute the command.For a compound command this means executing all of * the commands that it contains. * This is useful when implementing * {@link org.eclipse.jface.viewers.ITreeContentProvider#getChildren(Object)} * to display the Command's nested structure. * * @return returns the Commands as an array of Objects. * @return the List of contained Commands * @see org.eclipse.gef.commands.Command#getLabel() * @return <code>true</code> if the CompoundCommand is empty * @see org.eclipse.gef.commands.Command#redo() * @return the number of contained Commands * @see org.eclipse.gef.commands.Command#undo() * Returns the simplest form of this Command that is equivalent. This is * useful for removing unnecessary nesting of Commands. * * @return the simplest form of this Command that is equivalent * A CompoundCommand that performs undo on its contained Commands in the same * order in which they were executed. * @see org.eclipse.gef.commands.Command#getDebugLabel() * Undo the command. For a Preorder compound command this means undoing all * of the commands that it contains. Do it in the same order as applied. * A Command which can never be executed * The singleton instance * @return <code>false</code> * @return <code>false</code> * An instance of this interface provides support for managing a * a shared operations history and an shared undo context at the <code>IWorkbench</code> * level. * * This interface is not intended to be extended or implemented by clients. * * * @since 3.1 * * @see org.eclipse.ui.IWorkbench#getOperationSupport() * @noimplement This interface is not intended to be implemented by clients. * Returns the undo context for workbench-wide operations. * * @return the workbench operation context * Returns the operation history for the workbench. * * @return the workbench operation history * * An operation approver that prompts the user to see if linear undo violations * are permitted. A linear undo violation is detected when an operation being * undone or redone shares an undo context with another operation appearing more * recently in the history. * * * This class may be instantiated by clients. * * * @since 3.1 * * An operation approver that prompts the user to see if a non-local undo should * proceed inside an editor. A non-local undo is detected when an operation * being undone or redone affects elements other than those described by the * editor itself. Clients can optionally specify a class, the preferred * comparison class, that should be used when comparing objects affected by the * editor with objects affected by an undo or redo operation. Comparisons * between the affected objects inside the editor and those described by the * operation will first be done by simply performing an equality check, using * {@link java.lang.Object#equals(java.lang.Object)}. If an object described by * an operation is not equal to one of the objects affected by the editor, and * if it is not an instance of the preferred comparison class, but is an * instance of {@link org.eclipse.core.runtime.IAdaptable}, then the operation * approver will also attempt to retrieve an adapter on that object for the * preferred comparison class and perform a second equality check using the * adapter. * * * This class may be instantiated by clients. * * * * @since 3.1 * * OperationHistoryActionHandler implements common behavior for the undo and * redo actions. It supports filtering of undo or redo on a particular undo * context. If an undo context is not specified, or there has been no history * available for the specified undo context, then the workbench undo context * will be used. * * * OperationHistoryActionHandler provides an adapter in the info parameter of * the IOperationHistory undo and redo methods that is used to get UI info for * prompting the user during operations or operation approval. Adapters are * provided for org.eclipse.ui.IWorkbenchWindow, org.eclipse.swt.widgets.Shell, * org.eclipse.ui.IWorkbenchPart, org.eclipse.core.commands.IUndoContext, and * org.eclipse.runtime.IProgressMonitor. * * * OperationHistoryActionHandler assumes a linear undo/redo model. When the * handler is run, the operation history is asked to perform the most recent * undo/redo for the handler's undo context. The handler can be configured * (using #setPruneHistory(true)) to flush the operation undo or redo history * for the handler's undo context when there is no valid operation on top of the * history. This avoids keeping a stale history of invalid operations. By * default, pruning does not occur and it is assumed that clients of the * particular undo context are pruning the history when necessary. * * * @since 3.1 * @see IPartListener#partActivated(IWorkbenchPart) * @see IPartListener#partBroughtToTop(IWorkbenchPart) * @see IPartListener#partClosed(IWorkbenchPart) * @see IPartListener#partDeactivated(IWorkbenchPart) * @see IPartListener#partOpened(IWorkbenchPart) * The undo and redo subclasses should implement this. * * @return - a boolean indicating enablement state * Set the context shown by the handler. Normally the context is set up when * the action handler is created, but the context can also be changed * dynamically. * * @param context * the context to be used for the undo history * Specify whether the action handler should actively prune the operation * history when invalid operations are encountered. The default value is * <code>false</code>. * * @param prune * <code>true</code> if the history should be pruned by the * handler, and <code>false</code> if it should not. * * Update enabling and labels according to the current status of the * operation history. * * RedoActionHandler provides common behavior for redoing an operation, as well * as labelling and enabling the menu item. This class may be instantiated by * clients. * * * @since 3.1 * * UndoActionHandler provides common behavior for performing an undo, as * well as labelling and enabling the undo menu item. This class may be * instantiated by clients. * * * @since 3.1 * * UndoRedoActionGroup provides standard undo and redo action handlers for a * workbench part site. It supports filtering of undo or redo on a particular * undo context. The undo context can be optionally pruned, which means the * context will be flushed actively whenever an invalid operation is found on * top of its history. This class may be instantiated by clients. * * * @since 3.1 * Access to standard actions provided by the workbench. * * Most of the functionality of this class is provided by static methods and * fields. Example usage: * * <pre> * MenuManager menu = ...; * ActionFactory.IWorkbenchAction closeEditorAction * = ActionFactory.CLOSE.create(window); * menu.add(closeEditorAction); * </pre> * * * Clients may declare other classes that provide additional application-specific * action factories. * * * @since 3.0 * Workbench action (id: "about", commandId: "org.eclipse.ui.help.aboutAction"): Displays the * About dialog. This action maintains its enablement state. * Workbench action (id: "activateEditor", commandId: "org.eclipse.ui.window.activateEditor"): * Activate the most recently used editor. This action maintains its enablement state. * Workbench action (id: "back", commandId: "org.eclipse.ui.navigate.back"): Back. This action * is a {@link RetargetAction} with id "back". This action maintains its enablement state. * Workbench action (id: "backardHistory", commandId: "org.eclipse.ui.navigate.backwardHistory"): * Backward in the navigation history. This action maintains its enablement state. * Workbench action (id: "close", commandId: "org.eclipse.ui.file.close"): Close the active * editor. This action maintains its enablement state. * Workbench action (id: "closeAll", commandId: "org.eclipse.ui.file.closeAll"): Close all open * editors. This action maintains its enablement state. * Workbench action (id: "closeOthers", commandId: "org.eclipse.ui.file.closeOthers"): Close all * editors except the one that is active. This action maintains its enablement state. * * @since 3.2 * Workbench action (id: "closeAllPerspectives", commandId: "org.eclipse.ui.window.closeAllPerspectives"): * Closes all perspectives. This action maintains its enablement state. * Workbench action (id: "closeAllSaved"): Close all open editors except those with unsaved * changes. This action maintains its enablement state. * Workbench action (id: "closePerspective", commandId: "org.eclipse.ui.window.closePerspective"): * Closes the current perspective. This action maintains its enablement state. * Workbench action (id: "intro", commandId: "org.eclipse.ui.help.quickStartAction"): Activate * the introduction extension. This action should not be instantiated if no intro is provided. * Use code like: * * <pre> * if (window.getWorkbench().getIntroManager().hasIntro()) { * introAction= ActionFactory.INTRO.create(window); * register(introAction); * } * </pre> * Workbench action (id: "copy", commandId: "org.eclipse.ui.edit.copy"): Copy. This action is a * {@link RetargetAction} with id "copy". This action maintains its enablement state. * Workbench action (id: "cut", commandId: "org.eclipse.ui.edit.cut"): Cut. This action is a * {@link RetargetAction} with id "cut". This action maintains its enablement state. * Workbench action (id: "delete", commandId: "org.eclipse.ui.edit.delete"): Delete. This action * is a {@link RetargetAction} with id "delete". This action maintains its enablement state. * Workbench action (id: "editActionSets", commandId: "org.eclipse.ui.window.customizePerspective"): * Edit the action sets. This action maintains its enablement state. * Workbench action (id: "export", commandId: "org.eclipse.ui.file.export"): Opens the export * wizard. This action maintains its enablement state. * Workbench action (id: "find", commandId: "org.eclipse.ui.edit.findReplace"): Find. This * action is a {@link RetargetAction} with id "find". This action maintains its enablement * state. * Workbench action (id: "forward", commandId: "org.eclipse.ui.navigate.forward"): Forward. This * action is a {@link RetargetAction} with id "forward". This action maintains its enablement * state. * Workbench action (id: "forwardHistory", commandId: "org.eclipse.ui.navigate.forwardHistory"): * Forward in the navigation history. This action maintains its enablement state. * Workbench action (id: "goInto", commandId: "org.eclipse.ui.navigate.goInto"): Go Into. This * action is a {@link RetargetAction} with id "goInto". This action maintains its enablement * state. * Workbench action (id: "import", commandId: "org.eclipse.ui.file.import"): Opens the import * wizard. This action maintains its enablement state. * Workbench action (id: "lockToolBar"): Lock/unlock the workbench window tool bar. This action * maintains its enablement state. * Workbench action (id: "maximize", commandId: "org.eclipse.ui.window.maximizePart"): * Maximize/restore the active part. This action maintains its enablement state. * Workbench action (id: "minimize", commandId: "org.eclipse.ui.window.minimizePart"): Minimizes * the active part. This action maintains its enablement state. * * @since 3.1 * Workbench action (id: "move", commandId: "org.eclipse.ui.edit.move"): Move. This action is a * {@link RetargetAction} with id "move". This action maintains its enablement state. * Workbench action (id: "new", commandId: "org.eclipse.ui.newWizard"): Opens the new wizard * dialog. This action maintains its enablement state. * Workbench action (id: "newWizardDropDown"): Drop-down action which shows shows the new wizard * drop down, or opens the new wizard dialog when pressed. For use in the toolbar. This action * maintains its enablement state. * * @since 3.1 * Workbench action (id: "next", commandId: "org.eclipse.ui.navigate.next"): Next. This action * is a {@link RetargetAction} with id "next". This action maintains its enablement state. * Workbench action (id: "nextEditor", commandId: "org.eclipse.ui.window.nextEditor"): Next * editor. This action maintains its enablement state. * * <code>NEXT_EDITOR</code> and <code>PREVIOUS_EDITOR</code> form a cycle action pair. For a * given window, use {@link ActionFactory#linkCycleActionPair * ActionFactory.linkCycleActionPair</code>} to connect the two. * * Workbench action (id: "nextPart", commandId: "org.eclipse.ui.window.nextView"): Next part. * This action maintains its enablement state. * * <code>NEXT_PART</code> and <code>PREVIOUS_PART</code> form a cycle action pair. For a given * window, use {@link ActionFactory#linkCycleActionPair * ActionFactory.linkCycleActionPair</code>} to connect the two. * * Workbench action (id: "nextPerspective", commandId: "org.eclipse.ui.window.nextPerspective"): * Next perspective. This action maintains its enablement state. * * <code>NEXT_PERSPECTIVE</code> and <code>PREVIOUS_PERSPECTIVE</code> form a cycle action pair. * For a given window, use {@link ActionFactory#linkCycleActionPair * ActionFactory.linkCycleActionPair</code>} to connect the two. * * Workbench action (id: "openNewWindow", commandId: "org.eclipse.ui.window.newWindow"): Open a * new workbench window. This action maintains its enablement state. * Workbench action (id: "paste", commandId: "org.eclipse.ui.edit.paste"): Paste. This action is * a {@link RetargetAction} with id "paste". This action maintains its enablement state. * Workbench action (id: "preferences", commandId: "org.eclipse.ui.window.preferences"): * Displays the Preferences dialog. This action maintains its enablement state. * Workbench action (id: "previous", commandId: "org.eclipse.ui.navigate.previous"): Previous. * This action is a {@link RetargetAction} with id "previous". This action maintains its * enablement state. * Workbench action (id: "previousEditor", commandId: "org.eclipse.ui.window.previousEditor"): * Previous editor. This action maintains its enablement state. * * <code>NEXT_EDITOR</code> and <code>PREVIOUS_EDITOR</code> form a cycle action pair. For a * given window, use {@link ActionFactory#linkCycleActionPair * ActionFactory.linkCycleActionPair</code>} to connect the two. * * Workbench action (id: "previousPart", commandId: "org.eclipse.ui.window.previousView"): * Previous part. This action maintains its enablement state. * * <code>NEXT_PART</code> and <code>PREVIOUS_PART</code> form a cycle action pair. For a given * window, use {@link ActionFactory#linkCycleActionPair * ActionFactory.linkCycleActionPair</code>} to connect the two. * * Workbench action (id: "previousPerspective", commandId: "org.eclipse.ui.window.previousPerspective"): * Previous perspective. This action maintains its enablement state. * * <code>NEXT_PERSPECTIVE</code> and <code>PREVIOUS_PERSPECTIVE</code> form a cycle action pair. * For a given window, use {@link ActionFactory#linkCycleActionPair * ActionFactory.linkCycleActionPair</code>} to connect the two. * * Workbench action (id: "print", commandId: "org.eclipse.ui.file.print"): Print. This action is * a {@link RetargetAction} with id "print". This action maintains its enablement state. * Workbench action (id: "properties", commandId: "org.eclipse.ui.file.properties"): Properties. * This action is a {@link RetargetAction} with id "properties". This action maintains its * enablement state. * Workbench action (id: "quit", commandId: "org.eclipse.ui.file.exit"): Quit (close the * workbench). This action maintains its enablement state. * Workbench action (id: "redo", commandId: "org.eclipse.ui.edit.redo"): Redo. This action is a * {@link RetargetAction} with id "redo". This action maintains its enablement state. * Workbench action (id: "refresh", commandId: "org.eclipse.ui.file.refresh"): Refresh. This * action is a {@link RetargetAction} with id "refresh". This action maintains its enablement * state. * Workbench action (id: "rename", commandId: "org.eclipse.ui.edit.rename"): Rename. This action * is a {@link RetargetAction} with id "rename". This action maintains its enablement state. * Workbench action (id: "resetPerspective", commandId: "org.eclipse.ui.window.resetPerspective"): * Resets the current perspective. This action maintains its enablement state. * Workbench action (id: "revert", commandId: "org.eclipse.ui.file.revert"): Revert. This action * is a {@link RetargetAction} with id "revert". This action maintains its enablement state. * Workbench action (id: "save", commandId: "org.eclipse.ui.file.save"): Save the active editor. * This action maintains its enablement state. * Workbench action (id: "saveAll", commandId: "org.eclipse.ui.file.saveAll"): Save all open * editors with unsaved changes. This action maintains its enablement state. * Workbench action (id: "saveAs", commandId: "org.eclipse.ui.file.saveAs"): Save As for the * active editor. This action maintains its enablement state. * Workbench action (id: "savePerspective", commandId: "org.eclipse.ui.window.savePerspective"): * Save the current perspective. This action maintains its enablement state. * Workbench action (id: "selectAll", commandId: "org.eclipse.ui.edit.selectAll"): Select All. * This action is a {@link RetargetAction} with id "selectAll". This action maintains its * enablement state. * Workbench action (id: "showEditor"): Show/hide the editor area. This action maintains its * enablement state. * Workbench action (id: "showOpenEditors"): Show a list of open (and recently closed) editors. * This action maintains its enablement state. * Workbench action (id: "showWorkbookEditors"): Shows a list of open editors in the current or * last active workbook. * Workbench action (id: "showQuickAccess"): Shows a list of UI elements like editors, views, * perspectives etc. * * @since 3.3 * Workbench action (id: "showPartPaneMenu"): Show the part pane menu. This action maintains its * enablement state. * Workbench action (id: "showViewMenu", commandId: "org.eclipse.ui.window.showViewMenu"): Show * the view menu. This action maintains its enablement state. * Workbench action (id: "undo", commandId: "org.eclipse.ui.edit.undo"): Undo. This action is a * {@link RetargetAction} with id "undo". This action maintains its enablement state. * Workbench action (id: "up", commandId: "org.eclipse.ui.navigate.up"): Up. This action is a * {@link RetargetAction} with id "up". This action maintains its enablement state. * Workbench action (id: "helpContents", commandId: "org.eclipse.ui.help.helpContents"): Open * the help contents. This action is always enabled. * Workbench action (id: "helpSearch", commandId: "org.eclipse.ui.help.helpSearch"): Open the * help search. This action is always enabled. * * @since 3.1 * Workbench action (id: "dynamicHelp", commandId: "org.eclipse.ui.help.dynamicHelp"): Open the * dynamic help. This action is always enabled. * * @since 3.1 * Workbench action (id: "openPerspectiveDialog", commandId: "org.eclipse.ui.perspectives.showPerspective"): * Open the Open Perspective dialog. This action is always enabled. * * @since 3.1 * Workbench action (id: "newEditor", commandId: "org.eclipse.ui.window.newEditor"): Open a new * editor on the active editor's input. This action maintains its enablement state. * * @since 3.1 * Workbench action (id: "toggleCoolbar"): Toggle the visibility of the coolbar and perspective * switcher. This will only enable visibility of the coolbar and perspective bar if the window * advisor creating the window allowed for their visibility initially. * * @since 3.3 * Id of actions created by this action factory. * Optional ID for this action. * Interface for a workbench action. * Disposes of this action. Once disposed, this action cannot be used. * This operation has no effect if the action has already been * disposed. * Establishes bi-direction connections between the forward and backward * actions of a cycle pair. * * Example usage: * * <pre> * ActionFactory.IWorkbenchAction nextEditorAction = ActionFactory.NEXT_EDITOR * .create(window); * ActionFactory.IWorkbenchAction previousEditorAction = ActionFactory.PREVIOUS_EDITOR * .create(window); * ActionFactory.linkCycleActionPair(nextEditorAction, previousEditorAction); * </pre> * * * * @param next * the action that moves forward * @param previous * the action that moves backward * Creates a new standard action for the given workbench window. The action * has an id as specified by the particular factory. * * Actions automatically register listeners against the workbench window so * that they can keep their enablement state up to date. Ordinarily, the * window's references to these listeners will be dropped automatically * when the window closes. However, if the client needs to get rid of an * action while the window is still open, the client must call * {@link IWorkbenchAction#dispose dispose}to give the action an * opportunity to deregister its listeners and to perform any other * cleanup. * * * @param window * the workbench window * @return the workbench action * Returns the id of this action factory. * * @return the id of actions created by this action factory * Return the command id of this action factory. * * @return the command id of the action created by this action factory. May * be <code>null</code>. * @since 3.5 In GMF defaultContext = EditingDomainUndoContext(editingDomain) Automatically added to operation undoContext = EditingDomainUndoContext(editingDomain) contexts: - EditingDomainUndoContext(editingDomain) added by notifier (who ??) contexts: - ResourceUndoContext(affected uml file) added by the operation - EditingDomainUndoContext(editingDomain) added by notifier (who ??) added contexts: - WorkspaceCommandStackImpl.local – set by the WorkspaceCommandStack - ResourceUndoContext – set when the transaction is commited - EditingDomainUndoContext – set by one notifier (who ?)