org.eclipse.core.commands
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
INDEX_PARAMETER_ID
public static final int INDEX_PARAMETER_ID
-
Deprecated. no longer used
- The index of the parameter id in the parameter values.
-
See Also:
-
Constant Field Values
INDEX_PARAMETER_NAME
public static final int INDEX_PARAMETER_NAME
-
Deprecated. no longer used
- The index of the human-readable name of the parameter itself, in the
parameter values.
-
See Also:
-
Constant Field Values
INDEX_PARAMETER_VALUE_NAME
public static final int INDEX_PARAMETER_VALUE_NAME
-
Deprecated. no longer used
- The index of the human-readable name of the value of the parameter for
this command.
-
See Also:
-
Constant Field Values
INDEX_PARAMETER_VALUE_VALUE
public static final int INDEX_PARAMETER_VALUE_VALUE
-
Deprecated. no longer used
- The index of the value of the parameter that the command can understand.
-
See Also:
-
Constant Field Values
ParameterizedCommand
public ParameterizedCommand(
Command command,
Parameterization[] parameterizations)
- Constructs a new instance of
ParameterizedCommand with
specific values for zero or more of its parameters.
-
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.
generateCombinations
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.
-
-
-
Parameters:
-
command - The command for which the parameter combinations should be
generated; must not be null.
-
Returns:
- A collection of
ParameterizedCommand instances
representing all of the possible combinations. This value is
never empty and it is never null.
-
Throws:
-
NotDefinedException
- If the command is not defined.
generateCommand
public static final
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 be null. -
parameters - A map of String parameter ids to objects. May be
null.
-
Returns:
- the parameterized command, or
null if it could not
be generated -
Since:
- 3.4
compareTo
public final int compareTo(
Object object)
-
-
Specified by:
-
compareTo
in interface
Comparable
-
equals
public final boolean equals(
Object object)
-
-
Overrides:
-
equals
in class
Object
-
execute
public final
Object execute(
Object trigger,
Object applicationContext)
throws
ExecutionException,
NotHandledException
-
Deprecated. Please use
executeWithChecks(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 use
executeWithChecks(Object, Object).
-
-
-
Parameters:
-
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.
-
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 final
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 be
null. -
applicationContext - The state of the application at the time the execution was
triggered; may be null.
-
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 final
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 final
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 final
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.
getParameterMap
public final
Map getParameterMap()
- Returns the parameter map, as can be used to construct an
ExecutionEvent.
-
-
-
Returns:
- The map of parameter ids (
String) to parameter
values (String). This map is never
null, but may be empty.
hashCode
public final int hashCode()
-
-
Overrides:
-
hashCode
in class
Object
-
serialize
public final
String serialize()
- Returns a
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)
-
-
-
Returns:
- A string containing the escaped command id, parameter ids and
parameter values; never
null. -
Since:
- 3.2
-
See Also:
-
CommandManager.deserialize(String)
toString
public final
String toString()
-
-
Overrides:
-
toString
in class
Object
-
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
