Class Command
- All Implemented Interfaces:
Comparable,IIdentifiable,IObjectWithState
A command is an abstract representation for some semantic behaviour. It is not the actual implementation of this behaviour, nor is it the visual appearance of this behaviour in the user interface. Instead, it is a bridge between the two.
The concept of a command is based on the command design pattern. The notable
difference is how the command delegates responsibility for execution. Rather
than allowing concrete subclasses, it uses a handler mechanism (see the
handlers extension point). This provides another level of
indirection.
A command will exist in two states: defined and undefined. A command is
defined if it is declared in the XML of a resolved plug-in. If the plug-in is
unloaded or the command is simply not declared, then it is undefined. Trying
to reference an undefined command will succeed, but trying to access any of
its functionality will fail with a NotDefinedException. If
you need to know when a command changes from defined to undefined (or vice
versa), then attach a command listener.
Commands are mutable and will change as their definition changes.
- Since:
- 3.1
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic booleanThis flag can be set totrueif commands should print information toSystem.outwhen executing.static booleanThis flag can be set totrueif commands should print information toSystem.outwhen changing handlers.static StringThis flag can be set to a particular command identifier if only that command should print information toSystem.outwhen changing handlers.Fields inherited from class org.eclipse.core.commands.common.NamedHandleObject
description, nameFields inherited from class org.eclipse.core.commands.common.HandleObject
defined, id, string -
Method Summary
Modifier and TypeMethodDescriptionvoidaddCommandListener(ICommandListener commandListener) Adds a listener to this command that will be notified when this command's state changes.voidaddExecutionListener(IExecutionListener executionListener) Adds a listener to this command that will be notified when this command is about to execute.voidAdds a state to this command.intCompares this command with another command by comparing each of its non-transient attributes.voidDefines this command by giving it a name, and possibly a description as well.voiddefine(String name, String description, Category category, IParameter[] parameters) Defines this command by giving it a name, and possibly a description as well.voiddefine(String name, String description, Category category, IParameter[] parameters, ParameterType returnType) Defines this command by giving it a name, and possibly a description as well.voiddefine(String name, String description, Category category, IParameter[] parameters, ParameterType returnType, String helpContextId) Defines this command by giving it a name, and possibly a description as well.execute(ExecutionEvent event) Deprecated.executeWithChecks(ExecutionEvent event) Executes this command by delegating to the current handler, if any.Returns the category for this command.final StringReturns the description for this handle.Returns the current handler for this command.final StringgetName()Returns the name for this handle.getParameter(String parameterId) Returns the parameter with the provided id ornullif this command does not have a parameter with the id.Returns the parameters for this command.getParameterType(String parameterId) Returns theParameterTypefor the parameter with the provided id ornullif this command does not have a parameter type with the id.Returns theParameterTypefor the return value of this command ornullif this command does not declare a return value parameter type.final StateGets the state with the given id.final String[]Gets the identifiers for all of the state associated with this object.booleanReturns whether this command has a handler, and whether this handler is also handled and enabled.booleanReturns whether this command has a handler, and whether this handler is also handled.voidremoveCommandListener(ICommandListener commandListener) Removes a listener from this command.voidremoveExecutionListener(IExecutionListener executionListener) Removes a listener from this command.voidremoveState(String stateId) Removes a state from this command.voidsetEnabled(Object evaluationContext) Called be the framework to allow the handler to update its enabled state.booleansetHandler(IHandler handler) Changes the handler for this command.toString()The string representation of this command -- for debugging purposes only.voidundefine()Makes this command become undefined.Methods inherited from class org.eclipse.core.commands.common.HandleObject
equals, getId, hashCode, isDefinedMethods inherited from class org.eclipse.core.commands.common.EventManager
addListenerObject, clearListeners, getListeners, isListenerAttached, removeListenerObject
-
Field Details
-
DEBUG_COMMAND_EXECUTION
public static boolean DEBUG_COMMAND_EXECUTIONThis flag can be set totrueif commands should print information toSystem.outwhen executing. -
DEBUG_HANDLERS
public static boolean DEBUG_HANDLERSThis flag can be set totrueif commands should print information toSystem.outwhen changing handlers. -
DEBUG_HANDLERS_COMMAND_ID
This flag can be set to a particular command identifier if only that command should print information toSystem.outwhen changing handlers.
-
-
Method Details
-
addCommandListener
Adds a listener to this command that will be notified when this command's state changes.- Parameters:
commandListener- The listener to be added; must not benull.
-
addExecutionListener
Adds a listener to this command that will be notified when this command is about to execute.- Parameters:
executionListener- The listener to be added; must not benull.
-
addState
Adds a state to this command. This will add this state to the active handler, if the active handler is an instance of
IObjectWithState.A single instance of
Statecannot be registered with multiple commands. Each command requires its own unique instance.- Specified by:
addStatein interfaceIObjectWithState- Parameters:
id- The identifier of the state to add; must not benull.state- The state to add; must not benull.- Since:
- 3.2
- See Also:
-
compareTo
Compares this command with another command by comparing each of its non-transient attributes.- Specified by:
compareToin interfaceComparable- Parameters:
object- The object with which to compare; must be an instance ofCommand.- Returns:
- A negative integer, zero or a postivie integer, if the object is greater than, equal to or less than this command.
-
define
Defines this command by giving it a name, and possibly a description as well. The defined property automatically becomes
true.Notification is sent to all listeners that something has changed.
- Parameters:
name- The name of this command; must not benull.description- The description for this command; may benull.category- The category for this command; must not benull.- Since:
- 3.2
-
define
Defines this command by giving it a name, and possibly a description as well. The defined property automatically becomes
true.Notification is sent to all listeners that something has changed.
- Parameters:
name- The name of this command; must not benull.description- The description for this command; may benull.category- The category for this command; must not benull.parameters- The parameters understood by this command. This value may be eithernullor empty if the command does not accept parameters.
-
define
public void define(String name, String description, Category category, IParameter[] parameters, ParameterType returnType) Defines this command by giving it a name, and possibly a description as well. The defined property automatically becomes
true.Notification is sent to all listeners that something has changed.
- Parameters:
name- The name of this command; must not benull.description- The description for this command; may benull.category- The category for this command; must not benull.parameters- The parameters understood by this command. This value may be eithernullor empty if the command does not accept parameters.returnType- The type of value returned by this command. This value may benullif the command does not declare a return type.- Since:
- 3.2
-
define
public void define(String name, String description, Category category, IParameter[] parameters, ParameterType returnType, String helpContextId) Defines this command by giving it a name, and possibly a description as well. The defined property automatically becomes
true.Notification is sent to all listeners that something has changed.
- Parameters:
name- The name of this command; must not benull.description- The description for this command; may benull.category- The category for this command; must not benull.parameters- The parameters understood by this command. This value may be eithernullor empty if the command does not accept parameters.returnType- The type of value returned by this command. This value may benullif the command does not declare a return type.helpContextId- The identifier of the help context to associate with this command; may benullif this command does not have any help associated with it.- Since:
- 3.2
-
execute
@Deprecated public Object execute(ExecutionEvent event) throws ExecutionException, NotHandledException Deprecated.Please useexecuteWithChecks(ExecutionEvent)instead.Executes this command by delegating to the current handler, if any. If the debugging flag is set, then this method prints information about which handler is selected for performing this command. This method will succeed regardless of whether the command is enabled or defined. It is generally preferred to callexecuteWithChecks(ExecutionEvent).- Parameters:
event- An event containing all the information about the current state of the application; must not benull.- Returns:
- The result of the execution; may be
null. This result will be available to the client executing the command, and execution listeners. - Throws:
ExecutionException- If the handler has problems executing this command.NotHandledException- If there is no handler.
-
executeWithChecks
public Object executeWithChecks(ExecutionEvent event) throws ExecutionException, NotDefinedException, NotEnabledException, NotHandledException Executes this command by delegating to the current handler, if any. If the debugging flag is set, then this method prints information about which handler is selected for performing this command. This does checks to see if the command is enabled and defined. If it is not both enabled and defined, then the execution listeners will be notified and an exception thrown.- Parameters:
event- An event containing all the information about the current state of the application; must not benull.- Returns:
- The result of the execution; may be
null. This result will be available to the client executing the command, and execution listeners. - Throws:
ExecutionException- If the handler has problems executing this command.NotDefinedException- If the command you are trying to execute is not defined.NotEnabledException- If the command you are trying to execute is not enabled.NotHandledException- If there is no handler.- Since:
- 3.2
-
getCategory
Returns the category for this command.- Returns:
- The category for this command; never
null. - Throws:
NotDefinedException- If the handle is not currently defined.
-
getHandler
Returns the current handler for this command. This is used by the command manager for determining the appropriate help context identifiers and by the command service to allow handlers to update elements.This value can change at any time and should never be cached.
- Returns:
- The current handler for this command; may be
null. - Since:
- 3.3
-
getParameter
Returns the parameter with the provided id ornullif this command does not have a parameter with the id.- Parameters:
parameterId- The id of the parameter to retrieve.- Returns:
- The parameter with the provided id or
nullif this command does not have a parameter with the id. - Throws:
NotDefinedException- If the handle is not currently defined.- Since:
- 3.2
-
getParameters
Returns the parameters for this command. This call triggers provides a copy of the array, so excessive calls to this method should be avoided.- Returns:
- The parameters for this command. This value might be
null, if the command has no parameters. - Throws:
NotDefinedException- If the handle is not currently defined.
-
getParameterType
Returns theParameterTypefor the parameter with the provided id ornullif this command does not have a parameter type with the id.- Parameters:
parameterId- The id of the parameter to retrieve theParameterTypeof.- Returns:
- The
ParameterTypefor the parameter with the provided id ornullif this command does not have a parameter type with the provided id. - Throws:
NotDefinedException- If the handle is not currently defined.- Since:
- 3.2
-
getReturnType
Returns theParameterTypefor the return value of this command ornullif this command does not declare a return value parameter type.- Returns:
- The
ParameterTypefor the return value of this command ornullif this command does not declare a return value parameter type. - Throws:
NotDefinedException- If the handle is not currently defined.- Since:
- 3.2
-
isEnabled
public boolean isEnabled()Returns whether this command has a handler, and whether this handler is also handled and enabled.- Returns:
trueif the command is handled;falseotherwise.
-
setEnabled
Called be the framework to allow the handler to update its enabled state.- Parameters:
evaluationContext- the state to evaluate against. May benullwhich indicates that the handler can query whatever model that is necessary. This context must not be cached.- Since:
- 3.4
-
isHandled
public boolean isHandled()Returns whether this command has a handler, and whether this handler is also handled.- Returns:
trueif the command is handled;falseotherwise.
-
removeCommandListener
Removes a listener from this command.- Parameters:
commandListener- The listener to be removed; must not benull.
-
removeExecutionListener
Removes a listener from this command.- Parameters:
executionListener- The listener to be removed; must not benull.
-
removeState
Removes a state from this command. This will remove the state from the active handler, if the active handler is an instance of
IObjectWithState.- Specified by:
removeStatein interfaceIObjectWithState- Parameters:
stateId- The identifier of the state to remove; must not benull.- Since:
- 3.2
-
setHandler
Changes the handler for this command. This will remove all the state from the currently active handler (if any), and add it tohandler. If debugging is turned on, then this will also print information about the change toSystem.out.- Parameters:
handler- The new handler; may benullif none.- Returns:
trueif the handler changed;falseotherwise.
-
toString
The string representation of this command -- for debugging purposes only. This string should not be shown to an end user.- Specified by:
toStringin classHandleObject- Returns:
- The string representation; never
null.
-
undefine
public void undefine()Makes this command become undefined. This has the side effect of changing the name and description tonull. This also removes all state and disposes of it. Notification is sent to all listeners.- Specified by:
undefinein classHandleObject
-
getDescription
Description copied from class:NamedHandleObjectReturns the description for this handle.- Overrides:
getDescriptionin classNamedHandleObject- Returns:
- The description; may be
nullif there is no description. - Throws:
NotDefinedException- If the handle is not currently defined.
-
getName
Description copied from class:NamedHandleObjectReturns the name for this handle.- Overrides:
getNamein classNamedHandleObject- Returns:
- The name for this handle; never
null. - Throws:
NotDefinedException- If the handle is not currently defined.
-
getState
Description copied from interface:IObjectWithStateGets the state with the given id.- Specified by:
getStatein interfaceIObjectWithState- Parameters:
stateId- The identifier of the state to retrieve; must not benull.- Returns:
- The state; may be
nullif there is no state with the given id.
-
getStateIds
Description copied from interface:IObjectWithStateGets the identifiers for all of the state associated with this object.- Specified by:
getStateIdsin interfaceIObjectWithState- Returns:
- All of the state identifiers; may be empty, but never
null.
-
executeWithChecks(ExecutionEvent)instead.