Would you like to tell us how we are doing?

You bet No thanks

Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Command Framework API

You can use the Command Framework API in the net.rim.device.api.command package to define functionality that you can use in different locations in your application or in other applications on the BlackBerry device.

The Command Framework API contains command handlers, command metadata, and commands.

Component

Description

Command handler

You use the CommandHandler class to define functionality that you want to make available in your application or in 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's metadata 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 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 that is used by the command. You can also define metadata items that are specific to a particular command.

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 Command Framework API provides two registries that you can use to store your commands:

  • You can use the local registry to store commands for use in your application by using the LocalCommandRegistrarConnection class.
  • You can use the global registry to store commands for use in other applications on the device by using the RemoteCommandRegistrarConnection class.

The Command Framework Demo and Command Framework Demo Remote App sample applications are included in the BlackBerry Java SDK. These sample applications demonstrate how to define and use commands in a single application and how to define commands in one application and use them in other applications.

Use a command with one UI component

You can define a command for use with one UI component in your BlackBerry device application. Using this approach, you don't need to define metadata for the command. The core UI components for BlackBerry device applications that support commands include menu items, buttons, pop-up menu items, and toolbars.

  1. Import the required classes and interfaces.

    import net.rim.device.api.command.*;
    import net.rim.device.api.ui.*;
    import net.rim.device.api.ui.container.*;
  2. Create a command handler by creating a class that extends the abstract CommandHandler class. In execute(), define the functionality that you want to associate with the UI component. To specify whether a command is executable for a given context object, you can implement a canExecute() method in your command handler. If you don't implement canExecute(), your command is always executable.

    // this command is always executable
    class DialogCommandHandler extends CommandHandler
    {
       public void execute(ReadOnlyCommandMetadata metadata, Object context)
       {
          Dialog.alert("Executing command for " + context.toString());
       }
    }
  3. Create the UI component.

    MenuItem myItem = new MenuItem(new StringProvider("My Menu Item"), 
       0x230000, 0);
    
  4. For a menu item or button, you can optionally set the context for the command using the UI component's setCommandContext() method. For some commands, a context might be needed to determine what the command should do. If you don't set a context, the menu item object or button object is the context.

    myItem.setCommandContext(new Object()
    {
       public String toString()
       {
          return "My MenuItem Object"; 
       }          
    });
  5. Invoke setCommand() to specify the command for the UI component and provide the command handler as the method's argument.

    myItem.setCommand(new Command(new DialogCommandHandler()));
  6. Add the component to your screen.

    addMenuItem(myItem);

The command is executed when a BlackBerry device user performs an action on the UI component (for example, when the user clicks a menu item).

Code samples

For examples of this approach to defining and using commands, see the API reference for MenuItem and ButtonField.

Use a command in one or more applications

You can store a command in a local registry for use in your application or store a command in a global registry for use in any application on the BlackBerry device.

  1. Import the required classes and interfaces.

    import net.rim.device.api.command.*;
    import net.rim.device.api.command.registrar.*;
    import net.rim.device.api.ui.*;
    import net.rim.device.api.ui.container.*;
  2. Create a command handler by creating a class that extends the abstract CommandHandler class. In execute(), define the functionality that you want to make available. To specify whether a command is executable for a given context object, you can optionally implement canExecute() in your command handler. If you don't implement canExecute(), your command is always executable.

    private static class ViewContactCommand extends CommandHandler
    {
       public void execute(ReadOnlyCommandMetadata metadata, Object context)
       {              
          // Invoke the Contacts application to view a contact here
       }        
    
       public boolean canExecute(ReadOnlyCommandMetadata metadata, Object context)
       {
          // Return true if the command can be executed 
          // with the passed-in context object.
       }
    }
  3. Define the command's metadata.

    String id = "com.example.contacts.view.emailaddr";
    
    CommandMetadata metadata = new CommandMeta(id);
  4. If applications that use the command must create instances of the command, store the command's class name in the metadata.

    metadata.setClassname(ViewContactCommand.class.getName());  

    Applications can create instances of third-party commands dynamically only if the commands are stored in the local registry.

  5. Optionally, define command categories and context categories for the command. Applications that use the command use the categories to find commands in a registry and to determine whether a command is executable.

    • Command: specifies a type of categorization you want for your command. Applications that use commands can query a registry for commands in specified categories.
    • Context: specifies the contexts that are appropriate for your command to execute within. You can use this category to tell applications that use the command what kinds of context objects can be passed to CommandHandler.Execute().
    String[] myCommandCategories = {"app.contacts", "action.view"};
    metadata.setCommandCategories(new CategoryCollection(myCommandCategories));
    
    String[] myContextCategories = {emailaddr};
    metadata.setContextCategories(new CategoryCollection(myContextCategories));
  6. Register the command. If you want your command to be available only in your application, use a LocalCommandRegistrarConnection object. The local registry is available only in the current process.

    LocalCommandRegistrarConnection connection =
       new LocalCommandRegistrarConnection();
    connection.registerCommand(new ViewContactCommand(), metadata);

    For applications to create instances of the command dynamically, you must register the command only with the metadata by invoking registerCommand(CommandMetadata)). Otherwise, the registered CommandHandler is used.

    If you want your command to be available in any application, use a RemoteCommandRegistrarConnection object. The global registry is available to all processes that are running on the device.

    RemoteCommandRegistrarConnection connection =
       new RemoteCommandRegistrarConnection();
    connection.registerCommand(new ViewContactCommand(), metadata);
  7. From another location in your application (for local commands) or from any application on the device (for global commands), retrieve and use the command.

    Create a CommandRequest object and populate it with information about the command that you want to retrieve from the registry.

    CommandRequest request = new CommandRequest();
    
    String[] myCommandCategories = {"app.contacts", "action.view"};
    request.setCommandCategories(new CategoryCollection(myCommandCategories));
    ...

    Retrieve the command from the registry.

    // using the local registry
    LocalCommandRegistrarConnection connection = 
       new LocalCommandRegistrarConnection();
    Command command = connection.getCommand(request);
    
    // using the global registry
    RemoteCommandRegistrarConnection connection = 
       new RemoteCommandRegistrarConnection();
    Command command = connection.getCommand(request);
    

    Use the command. The following example executes the command, depending on the context.

    command.execute(context); // context is the context object

Code samples

Two sample applications that use the Command Framework API are included in the BlackBerry Java SDK:

  • Command Framework Demo Remote App demonstrates how to create a command and store it in the global registry for use in other applications.
  • Command Framework Demo demonstrates how to create commands, store them in the local registry, and add them as menu items in the pop-up menus for the fields, depending on the content of the fields. This sample application also executes a command that is stored in the global registry by Command Framework Demo Remote App.