Writing an Extension Command

In this section:

Extensions can offer commands through the command handler. Once offered, the command is available to users using any command interface (for example, command prompt console, Telnet command console, scheduler, and so on). An extension command has the following format:

name operand*

where:

name

Identifies the command and the extension. For example, scheduler and bam. As a best practice, try to emulate existing commands where possible.

To add an extension command, your code must extend the following class:

com.ibi.edaqm.XDCommandBase

For example:

public class CmdSchedule extends XDCommandBase implements IXDCommandItem
{
  Your Code}

The command is registered with the system in the register method for the extension, as:

XDCommandHandler.setExtensionCommand("name");

where:

name

Is the same value that you specified for the extension command.

The command received control at its execute method. For example:

void execute(StringTokenizer tokenizer, String inputLine) throws XDException

where:

tokenizer

Can break up the line. The original line is also available in the inputLine parameter.

The XDCommandBase class contains several methods to assist in writing the extension command. The say() and sayerr() methods allow you to communicate with the user. Although the say() method can be used to provide information at any time, the sayerr() method passes an error, which your command should then return. The sayerr() method offers the opportunity to provide an error code.

The following is sample syntax for the sayerr() method:

void sayerr(FailCause fc, int specific, String msg)
FailCause: A value for the failure type
Specific: an integer added to the base value - usually 0
Msg: Explanation

You should use XDCommandBase services only from extension commands that have been properly loaded.

The Failure causes are described in the FailCause enum:

SECURITY

1000

A general security error class.

SYNTAX

2000

A general syntax error (add a specific value).

UNKNOWN

2001

An unknown keyword has been detected.

MISSINGINFO

2002

Information needed for this command is missing.

SYNTAXVALUE

2015

A numeric value is not valid or out of range.

SYNTAXDUPL

2016

Duplicate switch.

SYNTAXXML

2018

A document is not a well formed XML.

SYNTAXURL

2019

A URL is not valid.

RESOURCE

3000

A resource needed for the command is not available.

FILENOTFOUND

3500

A file needed is not found.

SPECIFICATION

5000

Cannot use the command in this situation.

IO

6000

IO error.

These values are meant to avoid random error codes. If your error meets a specific, already enumerated, category, then you must make the specific cause 0. If it simply falls into a category, then you can add a value to make the error more specific. Be careful not to overrun another category.

Note: Additional standard error classes may be created in future releases.

Your code can also take advantage of the following static method to expand a partial token to a full token:

String com.ibi.xdutils.StringUtils.recognizer(String[] candidates, String token)

The array must contain the candidates in ASCII order.

For example, to expand the partial input switch in the following flow command:

private static String[] flowtoks={"-commit","-flat","-map","-output","-xml "};
which = recognizer(flow, which);

This example expands -o to -output.


Top of page

x
Adding Help

You can add help by adding the following lines to your translation file:

cmd.<commandname>=\t\%1 One line explanation of the command
subcmd.name=fuller explanation

The last line responds to the help name.

To explain a subcommand, use the following line:

subcmd.name.subcommand=fuller explanation of subcommand

If you want to hide a subcommand, then do not add this line.

The following is an example of sample syntax that is placed in the com.ibi.commands package.

/**
 * reverse <string> 
 * reverses the string entered on the command line
 */
package com.ibi.commands;
import java.util.StringTokenizer;
import com.ibi.edaqm.XDCommandBase;
import com.ibi.edaqm.XDCommandHandler.FailCause;
public class CmdReverse extends XDCommandBase {
  public void execute(StringTokenizer tokenizer, String inputLine)
         throws Exception
  {
    if (inputLine.trim().length() < 8)  // account for the command name
    {
      sayerr(FailCause.MISSINGINFO,000,"No string to reverse");
      return;
    }
  StringBuilder sb = new StringBuilder(inputLine.substring(8));
  String r = sb.reverse().toString();
  say(r);
  }
}

iWay Software