oracle.ide.controller

Class CommandProcessor

java.lang.Object

oracle.ide.controller.CommandProcessor

All Implemented Interfaces:

Observer

public final class CommandProcessor
extends java.lang.Object
implements Observer

The CommandProcessor singleton class is responsible for managing the execution of the IDE commands and managing the undo stack.

In general, all controller implementations should use the IDE command processor to execute the commands that controller handles. For example, the Navigator controller uses the IdeCommandProcessor) to handle its commands.

Since Command implementations may involve Swing interaction, all operations upon CommandProcessor must be made using the event thread. NEW BEHAVAIOR: Support for invoking single commands or batch commands that interrupt a transaction in progress has been added. NOTE: Since the API doesn't currently return some sort of transaction object, transactions are assumed to be on the same thread (a future version of CommandProcessor will correct this). The current version assumes any request that is received while a transaction is active that is not on the current transactions thread will be blocked until the current transaction is completed, at which point it will proceed (previous behavior was to generate exception feedback and set the undo stack size to 0). If a command in a transaction throws an exception, then the transaction is aborted. Additionally if a transaction is interrupted the interrupting command will wait for 60 seconds and then abort the transaction. Since transaction aren't typically expected to be interrupted this shouldn't affect existing behaviour. All transactions should be in try/finally blocks with the endTrans() in the finally statement.

See Also:

Command, Controller, Ide

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CommandProcessor.InfiniteLoopException

Method Summary

Methods

Modifier and Type	Method and Description
void	abortTrans() Abort a multi Command batch operation, calling undo on any Command instances already invoked as part of the current batch operation.
void	beginTrans(java.lang.String label) Begin a multi Command batch operation.
boolean	canRedo(Context context) Check if the last Command associated with the Node of the given Context can be redone.
boolean	canUndo(Context context) Check if the last Command associated with the Node of the given Context can be undone.
static Command	createCommand(java.lang.String cmd, Context context) Deprecated. use createCommandFromMeta(MetaClass,Context)
static Command	createCommandFromAction(IdeAction action, Context context) Creates a command for the action May return null if the action is not found or the action does not contain a MetaClass for the command.
static Command	createCommandFromAction(int actionId, Context context) Creates a command for the action looked up by the specified actionId May return null if the action is not found or the action does not contain a MetaClass for the command.
static Command	createCommandFromAction(java.lang.String commandString, Context context) Creates a command for the action looked up by the specified command string May return null if the action is not found or the action does not contain a MetaClass for the command.
static Command	createCommandFromClass(java.lang.Class clazz, Context context)
static Command	createCommandFromMeta(MetaClass commandMeta, Context context)
void	endTrans() Commit a multi Command batch operation.
void	flush(Node node) Flush the undo stack associated with the specified Node.
void	flush(Node[] objects) Flush the undo stack of all the specified objects.
void	flush(java.lang.Object object) Flush the undo stack associated with the specified Node.
void	flush(java.lang.Object[] objects) Flush the undo stack of all the specified objects.
Command	getCommand(Context context)
static CommandProcessor	getInstance() This is a singleton class.
java.lang.String	getRedoLabel(Context context) Get the name of the last redoable Command associated with the Node of the given Context.
java.lang.String	getUndoLabel(Context context) Get the name of the last undoable Command associated with the Node of the given Context.
int	invoke(Command cmd) Executes the actions associated with a specific command.
java.util.concurrent.Future<java.lang.Integer>	invokeAsync(Command cmd) Deprecated. - will be removing this shortly, the CommandProcessor should only be called from a Controller, to achieve asynch commands use an AsynchronousController
java.util.concurrent.Future<java.lang.Integer>	invokeAsync(Command cmd, boolean runOnEventDispatchThread) Deprecated. - will be removing this shortly, the CommandProcessor should only be called from a Controller, to achieve asynch commands use an AsynchronousController
boolean	isTransactionActive()
int	redo(Context context) Redo the last Command associated with the Node of the given Context.
int	undo(Context context) Undo the last Command associated with the Node of the given Context.
void	update(java.lang.Object observed, UpdateMessage change) Respond to applicable UpdateMessages.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static CommandProcessor getInstance()

This is a singleton class. Use this methods to get at the only instance of this class. The getInstance method creates the instance if it has not yet been created.

Returns:

the only instance of the CommandProcessor

invokeAsync

public final java.util.concurrent.Future<java.lang.Integer> invokeAsync(Command cmd,
                                                         boolean runOnEventDispatchThread)
                                                                 throws java.lang.IllegalStateException,
                                                                        java.lang.Exception

Deprecated. - will be removing this shortly, the CommandProcessor should only be called from a Controller, to achieve asynch commands use an AsynchronousController

invokeAsync runs cmd in a background thread while returning a Future immediately. The Future can be queried at any time for the result, but if the background thread is not completed will block until the background thread completes. If runWithSwingWorker is true AND the calling thread is running on the Event dispatch thread then a deadlock will occur if the Future.get is called before the background thread begins. If Future.get(...) is called before the Future.isDone == true, get(...) will throw an IllegalStateException to avoid deadlock.

Parameters:

cmd -

runOnEventDispatchThread -

Returns:

Throws:

java.lang.Exception

java.lang.IllegalStateException

invokeAsync

public final java.util.concurrent.Future<java.lang.Integer> invokeAsync(Command cmd)
                                                                 throws java.lang.Exception

Deprecated. - will be removing this shortly, the CommandProcessor should only be called from a Controller, to achieve asynch commands use an AsynchronousController

invokeAsync runs cmd in a background thread while returning a Future immediately. The Future can be queried at any time for the result, but if the background thread is still running will block until the background thread completes.

Parameters:

cmd -

Returns:

Throws:

java.lang.Exception

invoke

public final int invoke(Command cmd)
                 throws java.lang.Exception

Executes the actions associated with a specific command. A Controller uses this method to tell the CommandProcessor that a command should be executed.

Parameters:

cmd - the command to execute.

Throws:

java.lang.Exception

undo

public final int undo(Context context)
               throws java.lang.Exception

Undo the last Command associated with the Node of the given Context. If the Node of the given Context is null, then Command.CANCEL will be returned. If the given Context itself is null, then an attempt will be made to undo the last global Command.

Parameters:

context - a Context describing a Node, else null.

Returns:

oracle.ide.addin.Command.OK on success, oracle.ide.addin.Command on failure.

Throws:

java.lang.Exception

redo

public final int redo(Context context)
               throws java.lang.Exception

Redo the last Command associated with the Node of the given Context. If the Node of the given Context is null, then Command.CANCEL will be returned. If the given Context itself is null, then an attempt will be made to redo the last global Command.

Parameters:

context - a Context describing a Node, else null.

Returns:

oracle.ide.addin.Command.OK on success, oracle.ide.addin.Command on failure.

Throws:

java.lang.Exception

canUndo

public boolean canUndo(Context context)

Check if the last Command associated with the Node of the given Context can be undone. If the Node of the given Context is null, then false will be returned. If the given Context itself is null, then a check will be done to see if the last global Command can be undone.

Parameters:

context - a Context describing a Node, else null.

Returns:

true if the last applicable Command can be undone.

getUndoLabel

public java.lang.String getUndoLabel(Context context)

Get the name of the last undoable Command associated with the Node of the given Context. If the Node of the given Context is null, then null will be returned. If the given Context itself is null, then the name of the last undoable global Command will be returned.

Parameters:

context - a Context describing a Node, else null.

Returns:

The name of the last applicable Command available for undo.

getCommand

public Command getCommand(Context context)

Returns:

The Command that is to be undone

canRedo

public boolean canRedo(Context context)

Check if the last Command associated with the Node of the given Context can be redone. If the Node of the given Context is null, then false will be returned. If the given Context itself is null, then a check will be done to see if the last global Command can be redone.

Parameters:

context - a Context describing a Node, else null.

Returns:

true if the last applicable Command can be redone.

getRedoLabel

public java.lang.String getRedoLabel(Context context)

Get the name of the last redoable Command associated with the Node of the given Context. If the Node of the given Context is null, then null will be returned. If the given Context itself is null, then the name of the last redoable global Command will be returned.

Parameters:

context - a Context describing a Node, else null.

Returns:

The name of the last applicable Command available for redo.

flush

public void flush(java.lang.Object object)

Flush the undo stack associated with the specified Node.

flush

public void flush(Node node)

Flush the undo stack associated with the specified Node.

flush

public void flush(java.lang.Object[] objects)

Flush the undo stack of all the specified objects.

flush

public void flush(Node[] objects)

Flush the undo stack of all the specified objects.

beginTrans

public void beginTrans(java.lang.String label)

Begin a multi Command batch operation. All calls to invoke occuring between a preceding call to beginTrans and a succeding call to endTrans will be treated as parts of a single undoable operation if they are on the same thread. beginTrans should also be called in a try block of a try/finally statment with endTrans in the finally block.

Parameters:

label - summary label for use in undo/redo menu item.

endTrans

public void endTrans()

Commit a multi Command batch operation. All calls to invoke occuring between a preceding call to beginTrans and a succeding call to endTrans will be treated as parts of a single undoable operation if they are on the same thread.

abortTrans

public void abortTrans()

Abort a multi Command batch operation, calling undo on any Command instances already invoked as part of the current batch operation.

isTransactionActive

public boolean isTransactionActive()

update

public void update(java.lang.Object observed,
          UpdateMessage change)

Respond to applicable UpdateMessages.

Specified by:

update in interface Observer

Parameters:

observed - the subject whose state has changed.

change - what has changed.

createCommand

@Deprecated
public static Command createCommand(java.lang.String cmd,
                               Context context)

Deprecated. use createCommandFromMeta(MetaClass,Context)

Creates and instance of the specified command. The data specified is maintained by the newly created command. Returns null if command instance cannot be created. This method is deprecated for it assumes that the classloader of the class passed in is known. In a multiple classloader environment it is not known, so it will have to be passed is as a param.

Parameters:

cmd - the class name of the command, i.e., oracle.jdeveloper.cmd.CutCommand

context - the context to be associated with the command. This object is stored within the command an can be accessed later.

Returns:

the newly created command.

createCommandFromMeta

public static Command createCommandFromMeta(MetaClass commandMeta,
                            Context context)

createCommandFromAction

public static Command createCommandFromAction(int actionId,
                              Context context)

Creates a command for the action looked up by the specified actionId May return null if the action is not found or the action does not contain a MetaClass for the command.

Parameters:

actionId -

context -

Returns:

the command or null

createCommandFromAction

public static Command createCommandFromAction(java.lang.String commandString,
                              Context context)

Creates a command for the action looked up by the specified command string May return null if the action is not found or the action does not contain a MetaClass for the command.

Parameters:

commandString -

context -

Returns:

the command or null

createCommandFromAction

public static Command createCommandFromAction(IdeAction action,
                              Context context)

Creates a command for the action May return null if the action is not found or the action does not contain a MetaClass for the command.

Parameters:

action -

context -

Returns:

the command or null

createCommandFromClass

public static Command createCommandFromClass(java.lang.Class clazz,
                             Context context)