public final class ParameterizedCommand extends Object implements Comparable
A command that has had one or more of its parameters specified. This class serves as a utility class for developers that need to manipulate commands with parameters. It handles the behaviour of generating a parameter map and a human-readable name.
Modifier and Type | Field and Description |
---|---|
static int |
INDEX_PARAMETER_ID
Deprecated.
no longer used
|
static int |
INDEX_PARAMETER_NAME
Deprecated.
no longer used
|
static int |
INDEX_PARAMETER_VALUE_NAME
Deprecated.
no longer used
|
static int |
INDEX_PARAMETER_VALUE_VALUE
Deprecated.
no longer used
|
Constructor and Description |
---|
ParameterizedCommand(Command command,
Parameterization[] parameterizations)
Constructs a new instance of
ParameterizedCommand with
specific values for zero or more of its parameters. |
Modifier and Type | Method and Description |
---|---|
int |
compareTo(Object object) |
boolean |
equals(Object object) |
Object |
execute(Object trigger,
Object applicationContext)
Deprecated.
Please use
executeWithChecks(Object, Object)
instead. |
Object |
executeWithChecks(Object trigger,
Object applicationContext)
Executes this command with its parameters.
|
static Collection |
generateCombinations(Command command)
Generates all the possible combinations of command parameterizations for
the given command.
|
static ParameterizedCommand |
generateCommand(Command command,
Map parameters)
Take a command and a map of parameter IDs to values, and generate the
appropriate parameterized command.
|
Command |
getCommand()
Returns the base command.
|
String |
getId()
Returns the command's base identifier.
|
String |
getName()
Returns a human-readable representation of this command with all of its
parameterizations.
|
Map |
getParameterMap()
Returns the parameter map, as can be used to construct an
ExecutionEvent . |
int |
hashCode() |
String |
serialize()
Returns a
String containing the command id, parameter ids and
parameter values for this ParameterizedCommand . |
String |
toString() |
public static final int INDEX_PARAMETER_ID
public static final int INDEX_PARAMETER_NAME
public static final int INDEX_PARAMETER_VALUE_NAME
public static final int INDEX_PARAMETER_VALUE_VALUE
public ParameterizedCommand(Command command, Parameterization[] parameterizations)
ParameterizedCommand
with
specific values for zero or more of its parameters.command
- The command that is parameterized; must not be
null
.parameterizations
- An array of parameterizations binding parameters to values for
the command. This value may be null
.public static final Collection generateCombinations(Command command) throws NotDefinedException
Generates all the possible combinations of command parameterizations for the given command. If the command has no parameters, then this is simply a parameterized version of that command. If a parameter is optional, both the included and not included cases are considered.
If one of the parameters cannot be loaded due to a
ParameterValuesException
, then it is simply ignored.
command
- The command for which the parameter combinations should be
generated; must not be null
.ParameterizedCommand
instances
representing all of the possible combinations. This value is
never empty and it is never null
.NotDefinedException
- If the command is not defined.public static final ParameterizedCommand generateCommand(Command command, Map parameters)
command
- The command object. Must not be null
.parameters
- A map of String parameter ids to objects. May be
null
.null
if it could not
be generatedpublic final int compareTo(Object object)
compareTo
in interface Comparable
public final Object execute(Object trigger, Object applicationContext) throws ExecutionException, NotHandledException
executeWithChecks(Object, Object)
instead.executeWithChecks(Object, Object)
.trigger
- The object that triggered the execution; may be
null
.applicationContext
- The state of the application at the time the execution was
triggered; may be null
.null
.ExecutionException
- If the handler has problems executing this command.NotHandledException
- If there is no handler.public final Object executeWithChecks(Object trigger, Object applicationContext) throws ExecutionException, NotDefinedException, NotEnabledException, NotHandledException
trigger
- The object that triggered the execution; may be
null
.applicationContext
- The state of the application at the time the execution was
triggered; may be null
.null
.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 Command getCommand()
null
, but may be undefined.public final String getId()
null
.public final String getName() throws NotDefinedException
null
.NotDefinedException
- If the underlying command is not defined.public final Map getParameterMap()
ExecutionEvent
.String
) to parameter
values (String
). This map is never
null
, but may be empty.public final String serialize()
String
containing the command id, parameter ids and
parameter values for this ParameterizedCommand
. The returned
String
can be stored by a client and later used to reconstruct an
equivalent ParameterizedCommand
using the
CommandManager.deserialize(String)
method.
The syntax of the returned String
is as follows:
serialization = commandId [ '(' parameters ')' ]
parameters = parameter [ ',' parameters ]
parameter = parameterId [ '=' parameterValue ]
In the syntax above, sections inside square-brackets are optional. The
characters in single quotes ((
, )
,
,
and =
) indicate literal characters.
commandId
represents the command id encoded with
separator characters escaped. parameterId
and
parameterValue
represent the parameter ids and
values encoded with separator characters escaped. The separator
characters (
, )
, ,
and
=
are escaped by prepending a %
. This
requires %
to be escaped, which is also done by prepending
a %
.
The order of the parameters is not defined (and not important). A missing
parameterValue
indicates that the value of the
parameter is null
.
For example, the string shown below represents a serialized parameterized command that can be used to show the Resource perspective:
org.eclipse.ui.perspectives.showPerspective(org.eclipse.ui.perspectives.showPerspective.perspectiveId=org.eclipse.ui.resourcePerspective)
This example shows the more general form with multiple parameters,
null
value parameters, and escaped =
in the
third parameter value.
command.id(param1.id=value1,param2.id,param3.id=esc%=val3)
null
.CommandManager.deserialize(String)
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.