public final class Command extends NamedHandleObject implements Comparable
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.
Modifier and Type | Field and Description |
---|---|
static boolean |
DEBUG_COMMAND_EXECUTION
This flag can be set to
true if commands should print
information to System.out when executing. |
static boolean |
DEBUG_HANDLERS
This flag can be set to
true if commands should print
information to System.out when changing handlers. |
static String |
DEBUG_HANDLERS_COMMAND_ID
This flag can be set to a particular command identifier if only that
command should print information to
System.out when
changing handlers. |
description, name
defined, id, string
Modifier and Type | Method and Description |
---|---|
void |
addCommandListener(ICommandListener commandListener)
Adds a listener to this command that will be notified when this command's
state changes.
|
void |
addExecutionListener(IExecutionListener executionListener)
Adds a listener to this command that will be notified when this command
is about to execute.
|
void |
addState(String id,
State state)
Adds a state to this command.
|
int |
compareTo(Object object)
Compares this command with another command by comparing each of its
non-transient attributes.
|
void |
define(String name,
String description,
Category category)
Defines this command by giving it a name, and possibly a description as
well.
|
void |
define(String name,
String description,
Category category,
IParameter[] parameters)
Defines this command by giving it a name, and possibly a description as
well.
|
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.
|
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.
|
Object |
execute(ExecutionEvent event)
Deprecated.
Please use
executeWithChecks(ExecutionEvent)
instead. |
Object |
executeWithChecks(ExecutionEvent event)
Executes this command by delegating to the current handler, if any.
|
Category |
getCategory()
Returns the category for this command.
|
String |
getDescription()
Returns the description for this handle.
|
IHandler |
getHandler()
Returns the current handler for this command.
|
String |
getName()
Returns the name for this handle.
|
IParameter |
getParameter(String parameterId)
Returns the parameter with the provided id or
null if this
command does not have a parameter with the id. |
IParameter[] |
getParameters()
Returns the parameters for this command.
|
ParameterType |
getParameterType(String parameterId)
Returns the
ParameterType for the parameter with the provided id
or null if this command does not have a parameter type
with the id. |
ParameterType |
getReturnType()
Returns the
ParameterType for the return value of this command or
null if this command does not declare a return value
parameter type. |
State |
getState(String stateId)
Gets the state with the given id.
|
String[] |
getStateIds()
Gets the identifiers for all of the state associated with this object.
|
boolean |
isEnabled()
Returns whether this command has a handler, and whether this handler is
also handled and enabled.
|
boolean |
isHandled()
Returns whether this command has a handler, and whether this handler is
also handled.
|
void |
removeCommandListener(ICommandListener commandListener)
Removes a listener from this command.
|
void |
removeExecutionListener(IExecutionListener executionListener)
Removes a listener from this command.
|
void |
removeState(String stateId)
Removes a state from this command.
|
void |
setEnabled(Object evaluationContext)
Called be the framework to allow the handler to update its enabled state.
|
boolean |
setHandler(IHandler handler)
Changes the handler for this command.
|
String |
toString()
The string representation of this command -- for debugging purposes only.
|
void |
undefine()
Makes this command become undefined.
|
equals, getId, hashCode, isDefined
addListenerObject, clearListeners, getListeners, isListenerAttached, removeListenerObject
public static boolean DEBUG_COMMAND_EXECUTION
true
if commands should print
information to System.out
when executing.public static boolean DEBUG_HANDLERS
true
if commands should print
information to System.out
when changing handlers.public static String DEBUG_HANDLERS_COMMAND_ID
System.out
when
changing handlers.public final void addCommandListener(ICommandListener commandListener)
commandListener
- The listener to be added; must not be null
.public final void addExecutionListener(IExecutionListener executionListener)
executionListener
- The listener to be added; must not be null
.public void addState(String id, State state)
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 State
cannot be registered with multiple
commands. Each command requires its own unique instance.
addState
in interface IObjectWithState
id
- The identifier of the state to add; must not be
null
.state
- The state to add; must not be null
.public final int compareTo(Object object)
compareTo
in interface Comparable
object
- The object with which to compare; must be an instance of
Command
.public final void define(String name, String description, Category category)
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.
name
- The name of this command; must not be null
.description
- The description for this command; may be null
.category
- The category for this command; must not be null
.public final void define(String name, String description, Category category, IParameter[] parameters)
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.
name
- The name of this command; must not be null
.description
- The description for this command; may be null
.category
- The category for this command; must not be null
.parameters
- The parameters understood by this command. This value may be
either null
or empty if the command does not
accept parameters.public final 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.
name
- The name of this command; must not be null
.description
- The description for this command; may be null
.category
- The category for this command; must not be null
.parameters
- The parameters understood by this command. This value may be
either null
or empty if the command does not
accept parameters.returnType
- The type of value returned by this command. This value may be
null
if the command does not declare a return
type.public final 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.
name
- The name of this command; must not be null
.description
- The description for this command; may be null
.category
- The category for this command; must not be null
.parameters
- The parameters understood by this command. This value may be
either null
or empty if the command does not
accept parameters.returnType
- The type of value returned by this command. This value may be
null
if the command does not declare a return
type.helpContextId
- The identifier of the help context to associate with this
command; may be null
if this command does not
have any help associated with it.public final Object execute(ExecutionEvent event) throws ExecutionException, NotHandledException
executeWithChecks(ExecutionEvent)
instead.executeWithChecks(ExecutionEvent)
.event
- An event containing all the information about the current
state of the application; must not be null
.null
. This
result will be available to the client executing the command, and
execution listeners.ExecutionException
- If the handler has problems executing this command.NotHandledException
- If there is no handler.public final Object executeWithChecks(ExecutionEvent event) throws ExecutionException, NotDefinedException, NotEnabledException, NotHandledException
event
- An event containing all the information about the current
state of the application; must not be null
.null
. This
result will be available to the client executing the command, and
execution listeners.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.public final Category getCategory() throws NotDefinedException
null
.NotDefinedException
- If the handle is not currently defined.public final IHandler getHandler()
This value can change at any time and should never be cached.
null
.public final IParameter getParameter(String parameterId) throws NotDefinedException
null
if this
command does not have a parameter with the id.parameterId
- The id of the parameter to retrieve.null
if this
command does not have a parameter with the id.NotDefinedException
- If the handle is not currently defined.public final IParameter[] getParameters() throws NotDefinedException
null
, if the command has no parameters.NotDefinedException
- If the handle is not currently defined.public final ParameterType getParameterType(String parameterId) throws NotDefinedException
ParameterType
for the parameter with the provided id
or null
if this command does not have a parameter type
with the id.parameterId
- The id of the parameter to retrieve the ParameterType
of.ParameterType
for the parameter with the provided id
or null
if this command does not have a parameter
type with the provided id.NotDefinedException
- If the handle is not currently defined.public final ParameterType getReturnType() throws NotDefinedException
ParameterType
for the return value of this command or
null
if this command does not declare a return value
parameter type.ParameterType
for the return value of this command or
null
if this command does not declare a return
value parameter type.NotDefinedException
- If the handle is not currently defined.public final boolean isEnabled()
true
if the command is handled; false
otherwise.public void setEnabled(Object evaluationContext)
evaluationContext
- the state to evaluate against. May be null
which indicates that the handler can query whatever model that
is necessary. This context must not be cached.public final boolean isHandled()
true
if the command is handled; false
otherwise.public final void removeCommandListener(ICommandListener commandListener)
commandListener
- The listener to be removed; must not be null
.public final void removeExecutionListener(IExecutionListener executionListener)
executionListener
- The listener to be removed; must not be null
.public void removeState(String stateId)
Removes a state from this command. This will remove the state from the
active handler, if the active handler is an instance of
IObjectWithState
.
removeState
in interface IObjectWithState
stateId
- The identifier of the state to remove; must not be
null
.public final boolean setHandler(IHandler handler)
handler
.
If debugging is turned on, then this will also print information about
the change to System.out
.handler
- The new handler; may be null
if none.true
if the handler changed; false
otherwise.public final String toString()
toString
in class HandleObject
null
.public final void undefine()
null
. This also removes all
state and disposes of it. Notification is sent to all listeners.undefine
in class HandleObject
public final String getDescription() throws NotDefinedException
NamedHandleObject
getDescription
in class NamedHandleObject
null
if there is no
description.NotDefinedException
- If the handle is not currently defined.public final String getName() throws NotDefinedException
NamedHandleObject
getName
in class NamedHandleObject
null
.NotDefinedException
- If the handle is not currently defined.public final State getState(String stateId)
IObjectWithState
getState
in interface IObjectWithState
stateId
- The identifier of the state to retrieve; must not be
null
.null
if there is no state with
the given id.public final String[] getStateIds()
IObjectWithState
getStateIds
in interface IObjectWithState
null
.
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.