Package net.rim.device.api.command

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.

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.

Package net.rim.device.api.command Description

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.

• Overview
• The basic process
• Using command categories and context categories
• Using commands without using the registry

Overview

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 CommandMetadata class to define metadata that describes a command. Each command requires metadata, which is encapsulated in a CommandMetadata object. The only required piece of metadata for a command is the command's ID, which is provided when the CommandMetadata object is constructed and is stored in the object's COMMAND_ID field. CommandMetadata also provides other fields for you to use to describe the command, such as RESOURCE_BUNDLE_NAME, to which you can assign the name of the resource bundle used by the command. You can also define command-specific metadata items.
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.

The basic process

To define and use a command:

1. Define a command handler.
2. Define the command's metadata.
3. Optionally, register the command.
4. Execute the command.

Defining a command handler

Create a class that extends the CommandHandler class. This class contains two methods:

• execute(ReadOnlyCommandMetadata metadata, Object context), which defines what the command does
• canExecute(ReadOnlyCommandMetadata metadata, Object context), which determines whether a particular call to execute() is valid, given a context

ReadOnlyCommandMetadata 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.

Defining the command's metadata

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.

Registering the command

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.

Executing the command

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.

Using command categories and context categories

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 CommandHandler.canExecute().

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.

Using commands without using the registry

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.