commandgroupadapter.java

来自「OSGI这是一个中间件,与UPNP齐名,是用于移植到嵌入式平台之上」· Java 代码 · 共 508 行 · 第 1/2 页

/*
 * Copyright (c) 2003, KNOPFLERFISH project
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following
 * conditions are met:
 *
 * - Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * - Redistributions in binary form must reproduce the above
 *   copyright notice, this list of conditions and the following
 *   disclaimer in the documentation and/or other materials
 *   provided with the distribution.
 *
 * - Neither the name of the KNOPFLERFISH project nor the names of its
 *   contributors may be used to endorse or promote products derived
 *   from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package org.knopflerfish.service.console;

import java.io.PrintWriter;
import java.io.Reader;
import java.lang.reflect.Field;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.util.ArrayList;
import java.util.Dictionary;
import java.util.Hashtable;

/**
 * Adapter class for CommandGroup. Simplifies the creations of command groups.
 * It takes away the work of parsing command lines and generates help text. It
 * uses reflection to check which commands you have created.
 * <p>
 * To create your own command group you extend this class and add two variables
 * and a method.
 * <dl>
 * <dt><code>USAGE_{NAME}</code></dt>
 * <dd> A static String (NAME must be capital letters) that describes the
 * command line options of the command. The following is valid usage string
 * (only space can be used as whitespace):
 * 
 * <pre>
 *      usage : [ flags ] [ args [ '...' ]]
 *      flags : flag [ flags ]
 *      flags : oflag [ flags ]
 *      flag  : flag '|' flag
 *      flag  : '-'FLAGNAME [ '#'[TEXT['#']] ]
 *      oflag : '[' flag ']'
 *      args  : '&lt;' ARGNAME '&gt;'
 *      args  : '[' args ']'
 * </pre>
 * 
 * Note: The flag "-help" is automatically added and handled by
 * CommandGroupAdapter. </dd>
 * <dt><code>HELP_{NAME}</code></dt>
 * <dd> A static String array (NAME must be capital letters) that gives the help
 * text for the command. Each element is printed on its own line. The first
 * element should be a short description of the command as it is used to
 * describe the command when we generate the help text for the command group.
 * </dd>
 * <dt><code>int cmd{Name}(Dictionary, Reader, PrintWriter, Session)</code></dt>
 * <dd> A method (the first letter in the command name must be capital, and the
 * rest must be lowercase) that is called when the CommandGroupAdapter has
 * matched the command and decode the command flags. The Dictionary contains the
 * parsed commands arguments. If a flag is present the key "-FLAGNAME" is
 * present and any value as the object (type String) connected to the key. The
 * same goes for "ARGNAME". If the usage string ends with "...", then the last
 * ARGNAME key is connected with a String array object that contains all the
 * remaining arguments on the command line. The method parameters Reader,
 * PrintWriter and Session are the same as for the <tt>execute</tt> method.
 * The method should return a 0 if the command executed okey. </dd>
 * </dl>
 * <p>
 * The object must then be registered under the class name <br>
 * <code>org.knopflerfish.service.console.CommandGroup</code> with the
 * property "groupName" set to the command group name.
 * <p>
 * Example:
 * 
 * <pre>
 * package com.apa;
 * 
 * import java.io.*;
 * import java.util.*;
 * 
 * import org.knopflerfish.service.console.*;
 * 
 * public class MyCommandGroup extends CommandGroupAdapter {
 * 
 *     MyCommandGroup() {
 *         super(&quot;echocommands&quot;, &quot;Echo commands&quot;);
 *     }
 * 
 *     public final static String USAGE_ECHO = &quot;[-n] &lt;text&gt; ...&quot;;
 * 
 *     public final static String[] HELP_ECHO = new String[] {
 *             &quot;Echo command arguments&quot;, &quot;-n     Don't add newline at end&quot;,
 *             &quot;&lt;text&gt; Text to echo&quot; };
 * 
 *     public int cmdEcho(Dictionary opts, Reader in, PrintWriter out,
 *             Session session) {
 *         String[] t = (String[]) opts.get(&quot;text&quot;);
 *         for (int i = 0; i &lt; t.length; i++) {
 *             out.print(t[i]);
 *         }
 *         if (opts.get(&quot;-n&quot;) == null) {
 *             out.println();
 *         }
 *         return 0;
 *     }
 * }
 * </pre>
 * 
 * @author Gatespace AB
 * @version $Revision: 1.1.1.1 $
 */

public abstract class CommandGroupAdapter implements CommandGroup {

    /**
     * Full class name of CommandGroup interface.
     */
    public final static String COMMAND_GROUP = org.knopflerfish.service.console.CommandGroup.class
            .getName();

    String groupName;

    String shortHelp;

    /**
     * Constructs a command group. This should be called via super() if you
     * extend this class.
     * 
     * @param groupName
     *            the name for this command group
     * @param shortHelp
     *            one line description of this command group
     */
    public CommandGroupAdapter(String groupName, String shortHelp) {
        this.groupName = groupName;
        this.shortHelp = shortHelp;
    }

    /**
     * Returns the command group name. This methods returns the group name
     * registered via the constructor.
     * 
     * @return Group name.
     */
    public String getGroupName() {
        return groupName;
    }

    /**
     * Returns short command group help. Returns the short help message
     * registered via the constructor.
     * 
     * @return short command group help.
     */
    public String getShortHelp() {
        return shortHelp;
    }

    /**
     * Returns long command group help. This is built using the
     * <code>HELP_{CMD}</code> and <code>USAGE_{CMD}</code> variables of the
     * sub-class.
     * 
     * @return long command group help.
     */
    public String getLongHelp() {
        StringBuffer res = new StringBuffer();
        res.append("Available " + groupName + " commands:\n");
        Field[] f = getClass().getFields();
        for (int i = 0; i < f.length; i++) {
            String name = f[i].getName();
            if (name.startsWith("HELP_")) {
                try {
                    name = name.substring(5).toLowerCase();
                    DynamicCmd cmd = new DynamicCmd(this, name);
                    res.append("  " + name + " [-help] " + cmd.usage + " - "
                            + cmd.help[0] + "\n");
                } catch (Exception ignore) {
                }
            }
        }
        return res.toString();
    }

    /**
     * Executes a command in the command group. This parses the command line,
     * matches it with commands from the sub-class, check the
     * <code>USAGE_{CMD}</code> string of that command and calls its
     * <code>cmd{Cmd}</code> method of the sub-class.
     * 
     * @param args
     *            argument list passed to the command
     * @param out
     *            output device to print result
     * @param in
     *            input for command
     * @param session
     *            a handle to command session or null if single command
     * @return status from execution, 0 means okey
     */
    public int execute(String[] args, Reader in, PrintWriter out,
            Session session) {
        if (args.length == 0 || args[0] == null || args[0].length() == 0) {
            return -1;
        }
        DynamicCmd cmd;
        try {
            cmd = new DynamicCmd(this, args[0]);
        } catch (Exception e) {
            out.println(e.getMessage());
            return -2;
        }
        for (int i = 0; i < args.length; i++) {
            if ("-help".equals(args[i])) {
                out.println("Usage: " + args[0] + " [-help] " + cmd.usage);
                for (int j = 0; j < cmd.help.length; j++) {
                    out.println("  " + cmd.help[j]);
                }
                return 0;
            }
        }
        try {
            Integer res = (Integer) cmd.cmd.invoke(this, new Object[] {
                    getOpt(args, cmd.usage), in, out, session });
            return res.intValue();
        } catch (IllegalAccessException e) {
            out.println("Command failed: " + e.getMessage());
            return -1;
        } catch (InvocationTargetException e) {
            out.println("Command execution failed, stack trace follows:");
            e.getTargetException().printStackTrace(out);
            return -1;