public final class CommandManager extends HandleObjectManager implements ICategoryListener, ICommandListener, IParameterTypeListener
A central repository for commands -- both in the defined and undefined states. Commands can be created and retrieved using this manager. It is possible to listen to changes in the collection of commands by attaching a listener to the manager.
getCommand(String)
Modifier and Type | Field and Description |
---|---|
static String |
AUTOGENERATED_CATEGORY_ID
The identifier of the category in which all auto-generated commands will
appear.
|
definedHandleObjects, handleObjectsById
Constructor and Description |
---|
CommandManager() |
Modifier and Type | Method and Description |
---|---|
void |
addCommandManagerListener(ICommandManagerListener listener)
Adds a listener to this command manager.
|
void |
addExecutionListener(IExecutionListener listener)
Adds an execution listener to this manager.
|
void |
categoryChanged(CategoryEvent categoryEvent)
Notifies that one or more properties of an instance of
Category have changed. |
void |
commandChanged(CommandEvent commandEvent)
Notifies that one or more properties of an instance of
Command have changed. |
void |
defineUncategorizedCategory(String name,
String description)
Sets the name and description of the category for uncategorized commands.
|
ParameterizedCommand |
deserialize(String serializedParameterizedCommand)
Returns a
ParameterizedCommand with a command and
parameterizations as specified in the provided
serializedParameterizedCommand string. |
void |
fireNotDefined(String commandId,
NotDefinedException exception)
Fires the
notDefined event for
executionListeners . |
void |
fireNotEnabled(String commandId,
NotEnabledException exception)
Fires the
notEnabled event for
executionListeners . |
void |
firePostExecuteFailure(String commandId,
ExecutionException exception)
Fires the
postExecuteFailure event for
executionListeners . |
void |
firePostExecuteSuccess(String commandId,
Object returnValue)
Fires the
postExecuteSuccess event for
executionListeners . |
void |
firePreExecute(String commandId,
ExecutionEvent event)
Fires the
preExecute event for
executionListeners . |
Command[] |
getAllCommands()
Returns all of the commands known by this manager -- defined and
undefined.
|
Category |
getCategory(String categoryId)
Gets the category with the given identifier.
|
Command |
getCommand(String commandId)
Gets the command with the given identifier.
|
Category[] |
getDefinedCategories()
Returns the categories that are defined.
|
Set |
getDefinedCategoryIds()
Returns the set of identifiers for those category that are defined.
|
Set |
getDefinedCommandIds()
Returns the set of identifiers for those commands that are defined.
|
Command[] |
getDefinedCommands()
Returns the commands that are defined.
|
Set |
getDefinedParameterTypeIds()
Returns the set of identifiers for those parameter types that are
defined.
|
ParameterType[] |
getDefinedParameterTypes()
Returns the command parameter types that are defined.
|
String |
getHelpContextId(Command command)
Gets the help context identifier for a particular command.
|
ParameterType |
getParameterType(String parameterTypeId)
Gets the command
ParameterType with the given identifier. |
void |
parameterTypeChanged(ParameterTypeEvent parameterTypeEvent)
Notifies that one or more properties of an instance of
ParameterType have changed. |
void |
removeCommandManagerListener(ICommandManagerListener listener)
Removes a listener from this command manager.
|
void |
removeExecutionListener(IExecutionListener listener)
Removes an execution listener from this command manager.
|
void |
setHandlersByCommandId(Map handlersByCommandId)
Block updates all of the handlers for all of the commands.
|
void |
setHelpContextId(IHandler handler,
String helpContextId)
Sets the help context identifier to associate with a particular handler.
|
checkId, getDefinedHandleObjectIds
addListenerObject, clearListeners, getListeners, isListenerAttached, removeListenerObject
public static final String AUTOGENERATED_CATEGORY_ID
null
.public final void addCommandManagerListener(ICommandManagerListener listener)
listener
- The listener to attach; must not be null
.public final void addExecutionListener(IExecutionListener listener)
listener
- The listener to attach; must not be null
.public final void categoryChanged(CategoryEvent categoryEvent)
ICategoryListener
Category
have changed. Specific details are described in
the CategoryEvent
.categoryChanged
in interface ICategoryListener
categoryEvent
- the category event. Guaranteed not to be null
.public final void commandChanged(CommandEvent commandEvent)
ICommandListener
Command
have changed. Specific details are described in
the CommandEvent
.commandChanged
in interface ICommandListener
commandEvent
- the command event. Guaranteed not to be null
.public final void defineUncategorizedCategory(String name, String description)
getCategory(String)
is called with null
.name
- The name of the category for uncategorized commands; must not
be null
.description
- The description of the category for uncategorized commands;
may be null
.public final ParameterizedCommand deserialize(String serializedParameterizedCommand) throws NotDefinedException, SerializationException
Returns a ParameterizedCommand
with a command and
parameterizations as specified in the provided
serializedParameterizedCommand
string. The
serializedParameterizedCommand
must use the format
returned by ParameterizedCommand.serialize()
and described in the
Javadoc for that method.
If a parameter id encoded in the
serializedParameterizedCommand
does not exist in the
encoded command, that parameter id and value are ignored. A given
parameter id should not be used more than once in
serializedParameterizedCommand
. This will not result in
an exception, but in this case the value of the parameter when the
command is executed is unspecified.
This method will never return null
, however it may throw
an exception if there is a problem processing the serialization string or
the encoded command is undefined.
serializedParameterizedCommand
- a string representing a command id and parameter ids and
values; must not be null
ParameterizedCommand
with the command and
parameterizations encoded in the
serializedParameterizedCommand
; never
null
.NotDefinedException
- if the command indicated in
serializedParameterizedCommand
is not definedSerializationException
- if there is an error deserializing
serializedParameterizedCommand
ParameterizedCommand.serialize()
public final Command[] getAllCommands()
null
.public final Category getCategory(String categoryId)
categoryId
- The identifier to find; must not be null
. If
the category is null
, then a category suitable
for uncategorized items is defined and returned.null
, but it might be undefined.Category
public final Command getCommand(String commandId)
commandId
- The identifier to find; must not be null
and
must not be zero-length.null
, but it might be undefined.Command
public final Category[] getDefinedCategories()
null
.public final Set getDefinedCategoryIds()
null
.public final Set getDefinedCommandIds()
null
.public final Command[] getDefinedCommands()
null
.public final Set getDefinedParameterTypeIds()
null
.public final ParameterType[] getDefinedParameterTypes()
null
.public final String getHelpContextId(Command command) throws NotDefinedException
null
is returned.command
- The command for which the help context should be retrieved;
must not be null
.null
.NotDefinedException
- If the given command is not defined.public final ParameterType getParameterType(String parameterTypeId)
ParameterType
with the given identifier. If no
such command parameter type currently exists, then the command parameter
type will be created (but will be undefined).parameterTypeId
- The identifier to find; must not be null
and
must not be zero-length.ParameterType
with the given identifier; this value
will never be null
, but it might be undefined.public final void parameterTypeChanged(ParameterTypeEvent parameterTypeEvent)
ParameterType
have changed. Specific details are described in the
ParameterTypeEvent
.parameterTypeChanged
in interface IParameterTypeListener
parameterTypeEvent
- the event. Guaranteed not to be null
.public final void removeCommandManagerListener(ICommandManagerListener listener)
listener
- The listener to be removed; must not be null
.public final void removeExecutionListener(IExecutionListener listener)
listener
- The listener to be removed; must not be null
.public final void setHandlersByCommandId(Map handlersByCommandId)
null
or the command id does not exist in the map, then
the command becomes unhandled. Otherwise, the handler is set to the
corresponding value in the map.handlersByCommandId
- A map of command identifiers (String
) to
handlers (IHandler
). This map may be
null
if all handlers should be cleared.
Similarly, if the map is empty, then all commands will become
unhandled.public final void setHelpContextId(IHandler handler, String helpContextId)
handler
- The handler with which to register a help context identifier;
must not be null
.helpContextId
- The help context identifier to register; may be
null
if the help context identifier should be
removed.public void fireNotEnabled(String commandId, NotEnabledException exception)
notEnabled
event for
executionListeners
.
Note: This supports bridging actions to the command framework, and should not be used outside the framework.
commandId
- The command id of the command about to execute, never
null
.exception
- The exception, never null
.public void fireNotDefined(String commandId, NotDefinedException exception)
notDefined
event for
executionListeners
.
Note: This supports bridging actions to the command framework, and should not be used outside the framework.
commandId
- The command id of the command about to execute, never
null
.exception
- The exception, never null
.public void firePreExecute(String commandId, ExecutionEvent event)
preExecute
event for
executionListeners
.
Note: This supports bridging actions to the command framework, and should not be used outside the framework.
commandId
- The command id of the command about to execute, never
null
.event
- The event that triggered the command, may be null
.public void firePostExecuteSuccess(String commandId, Object returnValue)
postExecuteSuccess
event for
executionListeners
.
Note: This supports bridging actions to the command framework, and should not be used outside the framework.
commandId
- The command id of the command executed, never
null
.returnValue
- The value returned from the command, may be null
.public void firePostExecuteFailure(String commandId, ExecutionException exception)
postExecuteFailure
event for
executionListeners
.
Note: This supports bridging actions to the command framework, and should not be used outside the framework.
commandId
- The command id of the command executed, never
null
.exception
- The exception, never null
.
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.