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());  
    Note: 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.

    Category type

    Description

    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.
    1. 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);
      Note: 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.
    2. 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.
    1. 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));
      ...
    2. 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);
      
    3. 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.

Was this information helpful? Send us your comments.