CommandFrameworkDemo.java

/*
 * CommandFrameworkDemo.java
 *
 * Copyright � 1998-2011 Research In Motion Limited
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * Note: For the sake of simplicity, this sample application may not leverage
 * resource bundles and resource strings.  However, it is STRONGLY recommended
 * that application developers make use of the localization features available
 * within the BlackBerry development platform to ensure a seamless application
 * experience across a variety of languages and geographies.  For more information
 * on localizing your application, please refer to the BlackBerry Java Development
 * Environment Development Guide associated with this release.
 */

package com.rim.samples.device.ui.commandframeworkdemo;

import java.util.Hashtable;

import net.rim.device.api.command.AlwaysExecutableCommand;
import net.rim.device.api.command.Command;
import net.rim.device.api.command.CommandHandler;
import net.rim.device.api.command.CommandMetadata;
import net.rim.device.api.command.ReadOnlyCommandMetadata;
import net.rim.device.api.command.registrar.CategoryCollection;
import net.rim.device.api.command.registrar.CommandRegistrarConnection;
import net.rim.device.api.command.registrar.CommandRequest;
import net.rim.device.api.command.registrar.LocalCommandRegistrarConnection;
import net.rim.device.api.command.registrar.RemoteCommandRegistrarConnection;
import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.component.Dialog;

/**
 * A sample application to demonstrate the BlackBerry Smartphone command
 * framework. The application registers various commands with the framework and
 * provides UI elements for which the commands will be added to the context menu
 * or main menu of the application's MainScreen. A command is also registered on
 * startup by the CommandFrameworkDemoRemoteApp application and is retrieved and
 * executed in the constructor of the CommandFrameworkDemo class.
 */
public class CommandFrameworkDemo extends UiApplication {
    static final String EMAIL_ADDR = "emailaddr";

    /**
     * Entry point for application
     * 
     * @param args
     *            Command line arguments (not used)
     */
    public static void main(final String[] args) {
        // Create a new instance of the application and make the currently
        // running thread the application's event dispatch thread.
        final CommandFrameworkDemo app = new CommandFrameworkDemo();
        app.enterEventDispatcher();
    }

    /**
     * Creates a new CommandFrameworkDemo object
     */
    public CommandFrameworkDemo() {
        // Register a ViewContactCommand instance
        registerCommand(new ViewContactCommand(),
                "com.example.contacts.view.emailaddr", new String[] {
                        "app.contacts", "action.view" },
                new String[] { EMAIL_ADDR }, null);

        // Register an AddContactCommand instance
        registerCommand(new AddContactCommand(),
                "com.example.contacts.add.emailaddr", new String[] {
                        "app.contacts", "action.add" },
                new String[] { EMAIL_ADDR }, null);

        // Register a command which will be added to the screen's main menu
        registerCommand(new PopupDialogCommand(), "PopupDialogCommand", null,
                null, null);

        // Execute a command retrieved from RemoteCommandRegistrarConnection
        final CommandRegistrarConnection connection =
                new RemoteCommandRegistrarConnection();
        final CommandRequest request =
                new CommandRequest("CommandFrameworkDemoRemoteAppCommand");
        final Command command = connection.getCommand(request);

        // The Command reference may be null if the
        // CommandFrameworkDemoRemoteApp
        // project has not been loaded.
        if (command != null) {
            command.execute(this);
        }

        // Push a MainScreen onto the display stack
        pushScreen(new CommandFrameworkDemoScreen());
    }

    /**
     * Registers a command with LocalCommandRegistrarConnection
     * 
     * @param handler
     *            A CommandHandler implementation
     * @param id
     *            ID used to construct a CommandMetadata object
     * @param commandCategories
     *            String array containing command categories
     * @param contextCategories
     *            String array containing context categories
     * @param classname
     *            Classname of CommandHandler implementation to register, should
     *            be null if <code>handler</code> parameter is not null
     */
    private static void registerCommand(final CommandHandler handler,
            final String id, final String[] commandCategories,
            final String[] contextCategories, final String classname) {
        // Initialize CommandMetadata
        final CommandMetadata metadata = new CommandMetadata(id);
        metadata.setCommandCategories(new CategoryCollection(commandCategories));
        metadata.setContextCategories(new CategoryCollection(contextCategories));
        if (classname != null) {
            metadata.setClassname(classname);
        }

        // Register the CommandHandler and CommandMetadata with
        // LocalCommandRegistrarConnection
        final LocalCommandRegistrarConnection connection =
                new LocalCommandRegistrarConnection();
        connection.registerCommand(handler, metadata);
    }

    /**
     * Helper to stub in Contacts application functionality
     * 
     * @param emailaddr
     *            Email address for which to query contact
     * @return True if a contact exists with given email address, otherwise
     *         false
     */
    public static boolean queryContactExists(final String emailaddr) {
        // Entry exists in Contacts application with email address
        // jgraham@rim.com
        return "jgraham@rim.com".equals(emailaddr);
    }

    /**
     * Retrieves a value from provided context object for a given key
     * 
     * @param contextObject
     *            Context object from which to retrieve a value
     * @param key
     *            Key for which to retrieve a value
     * @return The value associated with given key
     */
    public static String getFromContextObject(final Object contextObject,
            final String key) {
        String str = null;

        if (contextObject instanceof Hashtable) {
            final Object object = ((Hashtable) contextObject).get(key);
            if (object != null) {
                str = object.toString();
            }
        }

        return str;
    }

    /**
     * A CommandHandler implementation for viewing an existing contact in the
     * Contacts application.
     */
    private static class ViewContactCommand extends CommandHandler {
        /**
         * @see CommandHandler#canExecute(ReadOnlyCommandMetadata, Object)
         */
        public boolean canExecute(final ReadOnlyCommandMetadata metadata,
                final Object context) {
            // Return true if the email address contained in the context object
            // exists in the Contacts application
            return queryContactExists(getFromContextObject(context, EMAIL_ADDR));
        }

        /**
         * @see CommandHandler#canExecute(ReadOnlyCommandMetadata, Object)
         */
        public void execute(final ReadOnlyCommandMetadata metadata,
                final Object context) {
            // Excecute an action on the contact
            final String msg =
                    "Viewing " + getFromContextObject(context, EMAIL_ADDR)
                            + " in Contacts application";
            Dialog.alert(msg);
        }
    }

    /**
     * A CommandHandler implementation which will be executed unconditionally
     */
    private static class PopupDialogCommand extends AlwaysExecutableCommand {
        public void execute(final ReadOnlyCommandMetadata metadata,
                final Object context) {
            // This command merely demonstrates the adding of a command to the
            // screen's menu directly.
            final Dialog dialog =
                    new Dialog(Dialog.D_OK, "Popped up dialog", Dialog.D_OK,
                            null, 100);
            dialog.doModal();
        }
    }

    /**
     * A CommandHandler implementation for adding an email address as a new
     * contact in the Contacts application.
     */
    private static class AddContactCommand extends CommandHandler {
        /**
         * @see CommandHandler#canExecute(ReadOnlyCommandMetadata, Object)
         */
        public boolean canExecute(final ReadOnlyCommandMetadata metadata,
                final Object context) {
            // Return false if a contact already exists with the email address
            // in question.
            return !queryContactExists(getFromContextObject(context, EMAIL_ADDR));
        }

        /**
         * @see CommandHandler#execute(ReadOnlyCommandMetadata, Object)
         */
        public void execute(final ReadOnlyCommandMetadata metadata,
                final Object context) {
            final String emailAddress =
                    getFromContextObject(context, EMAIL_ADDR);
            final String msg =
                    "Adding " + emailAddress + " to Contacts application";
            Dialog.alert(msg);
        }
    }
}