com.ccg.util
Class CommandLineUtility

java.lang.Object
  com.ccg.util.Convert
      com.ccg.util.TagLookup
          com.ccg.util.CommandLineUtility

All Implemented Interfaces:

Lookup, Runnable

public abstract class CommandLineUtility
extends TagLookup
implements Runnable

Simplification of the process of creating command line utilities. It seemed like everytime I wanted to create a command line utility, I was copying and pasting a lot of code. I created this class to standardize the process and will hope to expand on it in the future. It does the following setup for your command line applications:

• Provides methods to access command line arguments.
• Provides methods to get input/output (which can be redirected via command line arguments).
• Initializes the logging environment so that your code can include debug/log messages easily.

The following command line options are recognized/resevered by this application:

-in SOURCE

Optional method to allow the user to specify a source input (instead of using System.in - which is the default). You can specify the name of a existing file/URL or "-"/"in" for System.in (which is the default).

-out SOURCE

Optional method to allow the user to specify a output (instead of using System.out - which is the default). You can specify the name of a file which does not exist, "-" or "out" for System.out, or "err" for System.err.

-debug [LEVEL]

This option will automatically set the logger to the DEBUG level for output. In addition, if the optional debug LEVEL (as a number from 0-9) is specified, it will also set the debug verbosity level to the level specified or the default value of 3 if not specified.

-log_level LEVEL

Specify the log level (similar to setLevel(int). The LEVEL must be one of the following "always", "error", "info", "warning", or "debug". This option is only checked if -debug [LEVEL] is not set.

-help

Reserved for future use. Will probably support options like: "version", "gui", etc.

-pipe

Reseverd for implementing future code which allows one to "pipe" (ala Unix) output from one utility to another without leaving the JVM (reduces startup time).

-args URL

Sometimes the command line options can become overwelming. This option allows one to indicate that additional parameters can be read from the FILE/URL specified. This property file (if found) will allow one to specify options to the program without having to continually type them on the command line. The entries will be of the standard Java property file. For example, "-debug 8" could be specified on the command line, or "debug=8" could be specified in the property file. If a value is specified in both locations, the value found on the command line will take precedence. You don't have to specify a full URL, you can specify a file name as well.

Here's how one would write "Hello World" using this class (note that debug output is only displayed

import com.ccg.util.Debug;
import java.io.PrintWriter;

class HelloWorld extends com.ccg.util.CommandLineUtility {

  HelloWorld(String[] args) { super(args) }

  public void run() {
    try {
                                // sample debug ouput (see if -debug 9 set)
      if (Debug.isEnabledFor(9)) Debug.out("Hello World is starting");

                                // get output
      PrintWriter pw = getPrintWriter();
                                // display hello world unless -text STR
                                // specified on command line
      pw.println(getString("text","Hello world."));
      pw.flush();               // flush the output
    } catch (Exception e) { e.printStackTrace(); }
  }

                                // create and run the object
  static public void main(String[] args) {
    (new HelloWorld(args)).run();
  }
}

 

Since:

1.0

Version:

$Revision: 1.1.1.1 $

Author:

$Author: pkb $

See Also:

CommandLine

Constructor Summary

CommandLineUtility()
Construct the object without a command line (no initialization).

CommandLineUtility(Lookup l, String tag)
Initializes the command line utility This constructor should be the first thing your class invokes it performs the following basic initialization steps: Sets the argument array as its command line options Initializes the logging device used for Log and Debug messages.

CommandLineUtility(String[] args)
Initializes the command line utility This constructor should be the first thing your class invokes from its main() method.

Method Summary

File[]	getFiles(String[] matches) Get a set of files matching a specific set of criterea.
InputStream	getInputStream() Get the InputStream which should be processed.
LineNumberReader	getLineNumberReader() Get the LineNumberReader which should be processed.
OutputStream	getOutputStream() Get the OutputStream to use for outpu.
PrintWriter	getPrintWriter() Get the PrintWriter to use for output.
String[]	getStrings() Get all non-switch related strings from command line.
abstract void	run() The method which does the work.
void	setInputStream(InputStream is) Set the InputStream to read data from.
void	setOutputStream(OutputStream os) Set the OutputStream to read data from.

Methods inherited from class com.ccg.util.TagLookup

get, getBoolean, getChoice, getColor, getDate, getDate, getFont, getIndexedList, getInputStream, getLocale, getLookup, getNumber, getNumber, getOutputStream, getString, getString, getStrings, getTag, getTimeSpan, getTimeSpan, setLookup, setTag

Methods inherited from class com.ccg.util.Convert

choiceValue, getDateFormat, getNumberFormat, setDateFormat, setNumberFormat, toBoolean, toColor, toDate, toFont, toInputStream, toLocale, toNumber, toOutputStream, toString, toTimeSpan

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CommandLineUtility

public CommandLineUtility()

Construct the object without a command line (no initialization).

If you are designing an bean style object that can be run outside of the command line environment as well as from the command line, then you can use this constructor - it does the minimal amount of initialization (it doesn't initialized the debug level).

Since:

1.0

See Also:

CommandLineUtility(String[])

CommandLineUtility

public CommandLineUtility(Lookup l,
                          String tag)

Initializes the command line utility This constructor should be the first thing your class invokes it performs the following basic initialization steps:

• Sets the argument array as its command line options
• Initializes the logging device used for Log and Debug messages.
• Installs a default date parse which assumes dates are specified in a ISO standard form (not localized - the "yyyy-MM-dd HH:mm:ss" form).
• It checks to see if the "-args URL" option is specified. If so, it will load additional arguments from the property file specified.

Parameters:

args - Command line arguments (just like the static main(String[]) method receives).

Since:

1.0

See Also:

run()

CommandLineUtility

public CommandLineUtility(String[] args)

Initializes the command line utility This constructor should be the first thing your class invokes from its main() method. It performs the following basic initialization steps:

• Sets the argument array as its command line options
• Initializes the logging device used for Log and Debug messages.
• Installs a default date parse which assumes dates are specified in a ISO standard form (not localized - the "yyyy-MM-dd HH:mm:ss" form).

Refer to the other constructor to see some of the other functionality which occurs.

Parameters:

args - Command line arguments (just like the static main(String[]) method receives).

Since:

1.0

See Also:

run()

Method Detail

run

public abstract void run()

The method which does the work. This is the method which must be implemented by all descended classes. This is where your application will do most of its work.

Specified by:

run in interface Runnable

Since:

1.0

See Also:

CommandLineUtility

getInputStream

public InputStream getInputStream()
                           throws IOException

Get the InputStream which should be processed. This method returns the current InputStream object associated with the object. If a one is not yet associated with the class, then System.in will be returned unless the "-in SOURCE" command line option is specified. If the "-in SOURCE" command line option is specified, then the getInputString("in",System.in,false) will be used to set the input stream associated with the object.

It should be noted that you may call this routine multiple times. All subsequent calls will return the same value as the first call (unless the setInputStream(java.io.InputStream) method is invoked).

Returns:

A InputStream object to read the input from - does not return null.

Throws:

IOException - If "-in SOURCE" was specified and could not be converted to a InputStream.

Since:

1.0

See Also:

setInputStream(java.io.InputStream), getLineNumberReader()

getStrings

public String[] getStrings()

Get all non-switch related strings from command line. This method does its best to return all of the strings from the command line which are NOT related to switches. For example, if you had a command line like:

java MyProg f1.txt -debug 9 f2.txt

Then this method would return string array with two elements whose values were "f1.txt" and "f2.txt". This method currently does its best estimation, however binary switches will cause it problems if they are not followed explicitly by "true"/"false". For example, suppose your utility supported a "-html" switch to enable HTML output. If the command line looked like:

java MyProg -html f1.txt -debug 9 f2.txt

To use this method (currently) with this type of situation, the boolean flag switches should be at the end of the list of parameters, OR you should explicitly specify "true/false" on command line. The following two lines demonstrate:

 java MyProg f1.txt -debug 9 f2.txt -html

 java MyProg -html true f1.txt -debug 9 f2.txt
 

In the future (when I get around to writing command line verification routines), this limitation may be removed.

IMPORTANT: This method only returns useful information if the CommandLineUtility(String[]) method was used to construct the object. If another constructor was used, this method will always return a zero length array.

Returns:

Array of strings from the command line which are the best guess at what is left after all of the command line switches are removed. Never returns null - but may return a zero length array.

Since:

1.0

See Also:

getFiles(java.lang.String[])

getFiles

public File[] getFiles(String[] matches)

Get a set of files matching a specific set of criterea. This method is handy for command line utilities which are intended to work on a set of files as opposed to (or in addition to) acting as a filter.

Parameters:

matches - A array of strings which specify a set of file names (with or without wild cards). You may pass null (the preferred method) in which case all of the remaining command line arguments (see getString()) will be used.

Returns:

An array of File objects which "matched" your requirements. Never returns null, but may return a zero length array.

Since:

1.0

See Also:

FilenameFilterWild

getLineNumberReader

public LineNumberReader getLineNumberReader()
                                     throws IOException

Get the LineNumberReader which should be processed. This method returns the current LineNumberReader object associated with the object. If a one is not yet associated with the class, then one will be created from the InputStream returned by getInputStream() method and then associated with the object. Applicactions which want to work with Reader objects instead of streams should use this method instead of getInputStream().

It should be noted that you may call this routine multiple times. All subsequent calls will return the same value as the first call (unless the setInputStream(java.io.InputStream) method is invoked).

Returns:

A LineNumberReader object to read the input from - does not return null.

Throws:

IOException - If "-in SOURCE" was specified and could not be converted to a InputStream which would then be converted to a LineNumberReader.

Since:

1.0

See Also:

setInputStream(java.io.InputStream), getInputStream()

setInputStream

public void setInputStream(InputStream is)

Set the InputStream to read data from. Most applications will not need to use this method. However, if one wanted to change the input stream to their own specific source, they could use this method to do so. Typically one would do this "prior" to invoking getInputStream(). Invoking this method also affects the getLineNumberReader() in that the reader produced will be based on the stream passed to this method.

The most effective use of this method would be for the purpose of attaching a PipedInputStream to the object for the purpose of "chaining" the output of one command line utility into another without using the operating system. This will be done once the "-pipe" command line option is implemented.

Parameters:

s - New InputStream to use for the reading of data. You can pass null, but it has no affect on the object (null is ignored).

Since:

1.0

See Also:

getInputStream(), getLineNumberReader()

getOutputStream

public OutputStream getOutputStream()
                             throws IOException

Get the OutputStream to use for outpu. This method returns the current OutputStream object associated with the object. If a one is not yet associated with the class, then System.out will be returned unless the "-out SOURCE" command line option is specified. If the "-out SOURCE" command line option is specified, then the getOutputString("out",System.out,true,true,false) will be used to set the Output stream associated with the object.

It should be noted that you may call this routine multiple times. All subsequent calls will return the same value as the first call (unless the setOutputStream(java.io.OutputStream) method is invoked).

Returns:

A OutputStream object to write the output to - does not return null.

Throws:

IOException - If "-out SOURCE" was specified and could not be converted to a OutputStream.

Since:

1.0

See Also:

setOutputStream(java.io.OutputStream), getPrintWriter()

getPrintWriter

public PrintWriter getPrintWriter()
                           throws IOException

Get the PrintWriter to use for output. This method returns the current PrintWriter object associated with the object. If a one is not yet associated with the class, then one will be created from the OutputStream returned by getOutputStream() method and then associated with the object. Applications which want to work with Writer objects instead of streams should use this method instead of getOutputStream().

It should be noted that you may call this routine multiple times. All subsequent calls will return the same value as the first call (unless the setOutputStream(java.io.OutputStream) method is invoked).

Returns:

A PrintWriter object to write the output to - does not return null.

Throws:

IOException - If "-out SOURCE" was specified and could not be converted to a OutputStream which would then be converted to a PrintWriter.

Since:

1.0

See Also:

setOutputStream(java.io.OutputStream), getOutputStream()

setOutputStream

public void setOutputStream(OutputStream os)

Set the OutputStream to read data from. Most applications will not need to use this method. However, if one wanted to change the output stream to their own specific destination, they could use this method to do so. Typically one would do this "prior" to invoking getOutputStream(). Invoking this method also affects the getPrintWriter() in that the writer produced will be based on the stream passed to this method.

The most effective use of this method would be for the purpose of attaching a PipedOutputStream to the object for the purpose of "chaining" the output of one command line utility into another without using the operating system. This will be done once the "-pipe" command line option is implemented.

Parameters:

s - New OutputStream to use for the reading of data. You can pass null, but it has no affect on the object (null is ignored).

Since:

1.0

See Also:

getOutputStream(), getPrintWriter()