|
|||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
See:
Description
Class Summary | |
---|---|
AlwaysExecutableCommand | Convenience implementation of CommandHandler whose canExecute() method
always returns true . |
Command | Executes a command. |
CommandHandler | Defines the work that a command performs. |
CommandMetadata | Encapsulates metadata associated with a CommandHandler . |
CommandUtils | Command utilities. |
ExecutionContextEnum | CommandHandler execution contexts. |
NullCommandHandler | Null Object implementation of CommandHandler . |
ReadOnlyCommandMetadata | Read-only version of CommandMetadata . |
Exception Summary | |
---|---|
CommandMetadataException | Represents a command metadata exception. |
CommandRuntimeException | Signals that a command exception has occurred. |
NonExistentAttributeException | Signals that an attempt was made to retrieve a non-existent attribute. |
The Command Framework API provides support for defining functionality that you can use from different parts of your application or from other applications on the device.
This API contains three key components:
Component | Description |
---|---|
Command handler | You use the CommandHandler class to define functionality that you want to make available across your application or across other applications on the device. You create a class that extends the abstract CommandHandler class and define the functionality in the class's execute() method. That functionality is called a command. |
Command metadata | You use the
|
Command | You use the Command class to execute a command. You can think of a Command instance as a proxy to an instance of a class that extends CommandHandler . When Command.execute() is invoked, the call is delegated to the associated CommandHandler instance, passing the current context and transparently passing a read-only version of the associated command metadata for execution. |
To define and use a command:
Create a class that extends the CommandHandler
class. This class contains two methods:
execute(ReadOnlyCommandMetadata metadata, Object context)
, which defines what the command doescanExecute(ReadOnlyCommandMetadata metadata, Object context)
, which determines whether a particular call to execute()
is valid, given a contextReadOnlyCommandMetadata
is a read-only version of CommandMetadata
and is constructed from a CommandMetadata
instance.
The execute()
method in CommandHandler
is abstract, so you must implement it to define your command. The canExecute()
method is concrete. It is defined in CommandHandler
as always returning true
, meaning that the command is always available. You need to implement canExecute()
in your command handler only if your command is valid only in specific contexts.
Here is an example of a class that defines a command handler:
public class HelloWorldPopupDialogCommand extends CommandHandler
{
public void execute(ReadOnlyCommandMetadata metadata, Object object)
{
Dialog dialog = new Dialog( Dialog.D_OK, "Hello World", Dialog.D_OK, null, 100 );
dialog.doModal();
}
} |
HelloWorldPopupDialogCommand
displays a dialog that says "Hello World". Because we want the command to be always available, we did not implement a canExecute()
method.
Next, create a CommandMetadata
instance and set its properties to describe the command. When you construct the CommandMetadata
object, you pass in a string, which represents the identifier of the command the metadata object is associated with. You use this identifier, not the name of the class that extends CommandHandler
, when you execute the command (see below).
Here is an example:
CommandMetadata metadata = new CommandMetadata("HelloWorldPopupDialog");
metadata.setResourceBundleName("HelloWorldDemo");
metadata.set("commandType", "popup"); |
This metadata defines the name of the resource bundle for the command. The last metadata statement defines a command-specific attribute (commandType
) and sets its value.
If you want to make your command available to other applications on the device, you register it using the CommandRegistrarConnection
interface.
The RemoteCommandRegistrarConnection
class implements this interface.
When registering the command, you provide the command handler and the associated CommandMetadata
object, which has the information that is needed to use the command.
Here is an example:
HelloWorldPopupDialogCommand myCommand = new HelloWorldPopupDialogCommand();
CommandRegistrarConnection connection = new RemoteCommandRegistrarConnection();
connection.registerCommand(myCommand, metadata); |
Once registered, the command is available to all applications on the device.
To execute a registered command, first create a CommandRequest
object and obtain the command from the registry. Then, create an instance of the Command
class and invoke its execute()
method, passing in the CommandRequest
object.
Here is an example:
CommandRequest request = new CommandRequest();
request.setCommandId("HelloWorldPopupDialog");
CommandRegistrarConnection connection = new RemoteCommandRegistrarConnection();
Command command = connection.getCommand(request);
command.execute(null); |
This example obtains the command by invoking CommandRequest.setCommandId()
and providing the command's identifier (the identifier of the associated CommandMetadata
object). The Hello World command requires no context object, so null
is provided as the argument in Command.execute()
. The Hello World dialog is displayed.
When you define your command's metadata, you can optionally specify two types of categories for your command:
Type | Description |
---|---|
Command category | Any type of categorization you want for your command. Consumers of commands can query the registry for commands in specified categories. |
Context category | The contexts that are appropriate for your command to execute. Use this category to tell consumers of the command what kinds of context objects can be passed into |
You store the desired category information in the CommandMetadata
object associated with the command by using CommandMetadata.setCommandCategories()
and CommandMetadata.setContextCategories()
. Each of these methods takes a CategoryCollection
as a parameter. A CategoryCollection
is a collection of one or more categories, specified as strings.
You should adopt naming conventions for the categories you create and you will need to document the category names if you want other developers to be able to use your commands. Typically, you use a namespace that is unique to you, such as com.yourcompanyname
, and prepend the namespace when naming your command categories.
Consumers of commands can specify categories to query when defining their CommandRequest
by using CommandRequest.setCommandCategories()
and CommandRequest.setContextCategories()
. If a command has been registered with context categories, the CommandRequest
object must specify context categories to search. By default, a command is returned only if it matches all context categories that were registered for the command. If you want a command to be returned if it matches any registered context category, invoke CommandRequest.setAndContextCategories(false)
.
The command consumer then invokes CommandRegistrarConnection.getCommands(CommandRequest request)
, which returns an array of commands that match the categories that are specified in the CommandRequest
. When one of the returned commands is executed by using Command.execute(Context object)
, the command handler's canExecute()
method determines whether the requester has provided the necessary type of context for the command to execute.
If you are defining commands in an application that are only for use in that application, you don't need to register the command. For example, you could create a CommandHandler
, wrap it in a Command
instance, then populate the Command
instance in a ButtonField
.
|
|||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal