Knopflerfish OSGi 5.2.0

org.knopflerfish.service.console
Class CommandGroupAdapter

java.lang.Object
  extended by org.knopflerfish.service.console.CommandGroupAdapter
All Implemented Interfaces:
CommandGroup

public abstract class CommandGroupAdapter
extends java.lang.Object
implements CommandGroup

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.

To create your own command group you extend this class and add two variables and a method.

USAGE_{NAME}
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):
      usage : [ flags ] [ args [ '...' ]]
      flags : flag [ flags ]
      flags : oflag [ flags ]
      flag  : flag '|' flag
      flag  : '-'FLAGNAME [ '#'[TEXT['#']] ]
      oflag : '[' flag ']'
      args  : '<' ARGNAME '>'
      args  : '[' args ']'
 
Note: The flag "-help" is automatically added and handled by CommandGroupAdapter.
HELP_{NAME}
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.
int cmd{Name}(Dictionary, Reader, PrintWriter, Session)
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 execute method. The method should return a 0 if the command executed okey.

The object must then be registered under the class name
org.knopflerfish.service.console.CommandGroup with the property "groupName" set to the command group name.

Example:

 package com.apa;
 
 import java.io.*;
 import java.util.*;
 
 import org.knopflerfish.service.console.*;
 
 public class MyCommandGroup extends CommandGroupAdapter {
 
     MyCommandGroup() {
         super("echocommands", "Echo commands");
     }
 
     public final static String USAGE_ECHO = "[-n] <text> ...";
 
     public final static String[] HELP_ECHO = new String[] {
             "Echo command arguments", "-n     Don't add newline at end",
             "<text> Text to echo" };
 
     public int cmdEcho(Dictionary opts, Reader in, PrintWriter out,
             Session session) {
         String[] t = (String[]) opts.get("text");
         for (int i = 0; i < t.length; i++) {
             out.print(t[i]);
         }
         if (opts.get("-n") == null) {
             out.println();
         }
         return 0;
     }
 }
 

Author:
Gatespace AB

Nested Class Summary
static class CommandGroupAdapter.DynamicCmd
           
 
Field Summary
static java.lang.String COMMAND_GROUP
          Full class name of CommandGroup interface.
 
Fields inherited from interface org.knopflerfish.service.console.CommandGroup
GROUP_NAME
 
Constructor Summary
CommandGroupAdapter(java.lang.String groupName, java.lang.String shortHelp)
          Constructs a command group.
 
Method Summary
 int execute(java.lang.String[] args, java.io.Reader in, java.io.PrintWriter out, Session session)
          Executes a command in the command group.
 java.util.Map<java.lang.String,java.lang.String> getCommandNames()
           
 java.lang.String getGroupName()
          Returns the command group name.
 java.lang.String getLongHelp()
          Returns long command group help.
 java.util.Dictionary<java.lang.String,java.lang.Object> getOpt(java.lang.String[] args, java.lang.String usage)
          Method to do argument parsing.
 java.lang.String getShortHelp()
          Returns short command group help.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COMMAND_GROUP

public static final java.lang.String COMMAND_GROUP
Full class name of CommandGroup interface.

Constructor Detail

CommandGroupAdapter

public CommandGroupAdapter(java.lang.String groupName,
                           java.lang.String shortHelp)
Constructs a command group. This should be called via super() if you extend this class.

Parameters:
groupName - the name for this command group
shortHelp - one line description of this command group
Method Detail

getGroupName

public java.lang.String getGroupName()
Returns the command group name. This methods returns the group name registered via the constructor.

Specified by:
getGroupName in interface CommandGroup
Returns:
Group name.

getShortHelp

public java.lang.String getShortHelp()
Returns short command group help. Returns the short help message registered via the constructor.

Specified by:
getShortHelp in interface CommandGroup
Returns:
short command group help.

getLongHelp

public java.lang.String getLongHelp()
Returns long command group help. This is built using the HELP_{CMD} and USAGE_{CMD} variables of the sub-class.

Specified by:
getLongHelp in interface CommandGroup
Returns:
long command group help.

execute

public int execute(java.lang.String[] args,
                   java.io.Reader in,
                   java.io.PrintWriter out,
                   Session session)
Executes a command in the command group. This parses the command line, matches it with commands from the sub-class, check the USAGE_{CMD} string of that command and calls its cmd{Cmd} method of the sub-class.

Specified by:
execute in interface CommandGroup
Parameters:
args - argument list passed to the command
out - output device to print result
in - input for command
session - a handle to command session or null if single command
Returns:
status from execution, 0 means okey

getOpt

public java.util.Dictionary<java.lang.String,java.lang.Object> getOpt(java.lang.String[] args,
                                                                      java.lang.String usage)
                                                               throws java.lang.Exception
Method to do argument parsing. See parsed syntax in class CommandGroupAdapter description.

Parameters:
args - argument list passed to the command
usage - usage string
Returns:
Dictionary with parsed arguments
Throws:
java.lang.Exception - Thrown if it fails to parse args or usage

getCommandNames

public java.util.Map<java.lang.String,java.lang.String> getCommandNames()

Knopflerfish OSGi 5.2.0