Class ParameterizedCommand
- java.lang.Object
-
- org.eclipse.core.commands.ParameterizedCommand
-
- All Implemented Interfaces:
Comparable
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.
- Since:
- 3.1
-
-
Field Summary
Fields Modifier and Type Field Description static int
INDEX_PARAMETER_ID
Deprecated.no longer usedstatic int
INDEX_PARAMETER_NAME
Deprecated.no longer usedstatic int
INDEX_PARAMETER_VALUE_NAME
Deprecated.no longer usedstatic int
INDEX_PARAMETER_VALUE_VALUE
Deprecated.no longer used
-
Constructor Summary
Constructors Constructor Description ParameterizedCommand(Command command, Parameterization[] parameterizations)
Constructs a new instance ofParameterizedCommand
with specific values for zero or more of its parameters.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description int
compareTo(Object object)
boolean
equals(Object object)
Object
execute(Object trigger, Object applicationContext)
Deprecated.Please useexecuteWithChecks(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.String
getName(String baseName)
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 anExecutionEvent
.int
hashCode()
String
serialize()
Returns aString
containing the command id, parameter ids and parameter values for thisParameterizedCommand
.String
toString()
-
-
-
Field Detail
-
INDEX_PARAMETER_ID
@Deprecated public static final int INDEX_PARAMETER_ID
Deprecated.no longer usedThe index of the parameter id in the parameter values.- See Also:
- Constant Field Values
-
INDEX_PARAMETER_NAME
@Deprecated public static final int INDEX_PARAMETER_NAME
Deprecated.no longer usedThe index of the human-readable name of the parameter itself, in the parameter values.- See Also:
- Constant Field Values
-
INDEX_PARAMETER_VALUE_NAME
@Deprecated public static final int INDEX_PARAMETER_VALUE_NAME
Deprecated.no longer usedThe index of the human-readable name of the value of the parameter for this command.- See Also:
- Constant Field Values
-
INDEX_PARAMETER_VALUE_VALUE
@Deprecated public static final int INDEX_PARAMETER_VALUE_VALUE
Deprecated.no longer usedThe index of the value of the parameter that the command can understand.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
ParameterizedCommand
public ParameterizedCommand(Command command, Parameterization[] parameterizations)
Constructs a new instance ofParameterizedCommand
with specific values for zero or more of its parameters.- Parameters:
command
- The command that is parameterized; must not benull
.parameterizations
- An array of parameterizations binding parameters to values for the command. This value may benull
.
-
-
Method Detail
-
generateCombinations
public static 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.- Parameters:
command
- The command for which the parameter combinations should be generated; must not benull
.- Returns:
- A collection of
ParameterizedCommand
instances representing all of the possible combinations. This value is never empty and it is nevernull
. - Throws:
NotDefinedException
- If the command is not defined.
-
generateCommand
public static ParameterizedCommand generateCommand(Command command, Map parameters)
Take a command and a map of parameter IDs to values, and generate the appropriate parameterized command.- Parameters:
command
- The command object. Must not benull
.parameters
- A map of String parameter ids to objects. May benull
.- Returns:
- the parameterized command, or
null
if it could not be generated - Since:
- 3.4
-
compareTo
public int compareTo(Object object)
- Specified by:
compareTo
in interfaceComparable
-
execute
@Deprecated public Object execute(Object trigger, Object applicationContext) throws ExecutionException, NotHandledException
Deprecated.Please useexecuteWithChecks(Object, Object)
instead.Executes this command with its parameters. This method will succeed regardless of whether the command is enabled or defined. It is preferrable to useexecuteWithChecks(Object, Object)
.- Parameters:
trigger
- The object that triggered the execution; may benull
.applicationContext
- The state of the application at the time the execution was triggered; may benull
.- Returns:
- The result of the execution; may be
null
. - Throws:
ExecutionException
- If the handler has problems executing this command.NotHandledException
- If there is no handler.
-
executeWithChecks
public Object executeWithChecks(Object trigger, Object applicationContext) throws ExecutionException, NotDefinedException, NotEnabledException, NotHandledException
Executes this command with its parameters. This does extra checking 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:
trigger
- The object that triggered the execution; may benull
.applicationContext
- The state of the application at the time the execution was triggered; may benull
.- Returns:
- The result of the execution; may be
null
. - 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
-
getCommand
public Command getCommand()
Returns the base command. It is possible for more than one parameterized command to have the same identifier.- Returns:
- The command; never
null
, but may be undefined.
-
getId
public String getId()
Returns the command's base identifier. It is possible for more than one parameterized command to have the same identifier.- Returns:
- The command id; never
null
.
-
getName
public String getName() throws NotDefinedException
Returns a human-readable representation of this command with all of its parameterizations.- Returns:
- The human-readable representation of this parameterized command;
never
null
. - Throws:
NotDefinedException
- If the underlying command is not defined.
-
getName
public String getName(String baseName) throws NotDefinedException
Returns a human-readable representation of this command with all of its parameterizations.- Parameters:
baseName
- The base name of the command that should be used to create the parameterized command representation.- Returns:
- The human-readable representation of this parameterized command;
never
null
. - Throws:
NotDefinedException
- If the underlying command is not defined.- Since:
- 3.8
-
getParameterMap
public Map getParameterMap()
Returns the parameter map, as can be used to construct anExecutionEvent
.- Returns:
- The map of parameter ids (
String
) to parameter values (String
). This map is nevernull
, but may be empty.
-
serialize
public String serialize()
Returns aString
containing the command id, parameter ids and parameter values for thisParameterizedCommand
. The returnedString
can be stored by a client and later used to reconstruct an equivalentParameterizedCommand
using theCommandManager.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
andparameterValue
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 isnull
.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)
- Returns:
- A string containing the escaped command id, parameter ids and
parameter values; never
null
. - Since:
- 3.2
- See Also:
CommandManager.deserialize(String)
-
-