com.unboundid.util
Class CommandLineTool

java.lang.Object
  extended by com.unboundid.util.CommandLineTool
Direct Known Subclasses:
GenerateSchemaFromSource, InMemoryDirectoryServerTool, LDAPCommandLineTool, MultiServerLDAPCommandLineTool

@Extensible
@ThreadSafety(level=INTERFACE_NOT_THREADSAFE)
public abstract class CommandLineTool
extends java.lang.Object

This class provides a framework for developing command-line tools that use the argument parser provided as part of the UnboundID LDAP SDK for Java. This tool adds a "-H" or "--help" option, which can be used to display usage information for the program, and may also add a "-V" or "--version" option, which can display the tool version.

Subclasses should include their own main method that creates an instance of a CommandLineTool and should invoke the runTool(java.lang.String...) method with the provided arguments. For example:

   public class ExampleCommandLineTool
          extends CommandLineTool
   {
     public static void main(String[] args)
     {
       ExampleCommandLineTool tool = new ExampleCommandLineTool();
       ResultCode resultCode = tool.runTool(args);
       if (resultCode != ResultCode.SUCCESS)
       {
         System.exit(resultCode.intValue());
       }
     |

     public ExampleCommandLineTool()
     {
       super(System.out, System.err);
     }

     // The rest of the tool implementation goes here.
     ...
   }
 
.

Note that in general, methods in this class are not threadsafe. However, the out(Object...) and err(Object...) methods may be invoked concurrently by any number of threads.


Constructor Summary
CommandLineTool(java.io.OutputStream outStream, java.io.OutputStream errStream)
          Creates a new instance of this command-line tool with the provided information.
 
Method Summary
abstract  void addToolArguments(ArgumentParser parser)
          Adds the command-line arguments supported for use with this tool to the provided argument parser.
 ArgumentParser createArgumentParser()
          Creates a parser that can be used to to parse arguments accepted by this tool.
 void doExtendedArgumentValidation()
          Performs any necessary processing that should be done to ensure that the provided set of command-line arguments were valid.
protected  void doShutdownHookProcessing(ResultCode resultCode)
          Performs any processing that may be needed when the JVM is shutting down, whether because tool processing has completed or because it has been interrupted (e.g., by a kill or break signal).
abstract  ResultCode doToolProcessing()
          Performs the core set of processing for this tool.
 void err(java.lang.Object... msg)
          Writes the provided message to the standard error stream for this tool.
 java.io.PrintStream getErr()
          Retrieves the print writer that will be used for standard error.
 java.util.LinkedHashMap<java.lang.String[],java.lang.String> getExampleUsages()
          Retrieves a set of information that may be used to generate example usage information.
 int getMaxTrailingArguments()
          Retrieves the maximum number of unnamed trailing arguments that may be provided for this tool.
 java.io.PrintStream getOut()
          Retrieves the print writer that will be used for standard output.
abstract  java.lang.String getToolDescription()
          Retrieves a human-readable description for this tool.
abstract  java.lang.String getToolName()
          Retrieves the name of this tool.
 java.lang.String getToolVersion()
          Retrieves a version string for this tool, if available.
 java.lang.String getTrailingArgumentsPlaceholder()
          Retrieves a placeholder string that should be used for trailing arguments in the usage information for this tool.
 void out(java.lang.Object... msg)
          Writes the provided message to the standard output stream for this tool.
protected  boolean registerShutdownHook()
          Indicates whether this tool should register a shutdown hook with the JVM.
 ResultCode runTool(java.lang.String... args)
          Performs all processing for this command-line tool.
 void wrapErr(int indent, int wrapColumn, java.lang.Object... msg)
          Writes the provided message to the standard error stream for this tool, optionally wrapping and/or indenting the text in the process.
 void wrapOut(int indent, int wrapColumn, java.lang.Object... msg)
          Writes the provided message to the standard output stream for this tool, optionally wrapping and/or indenting the text in the process.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CommandLineTool

public CommandLineTool(java.io.OutputStream outStream,
                       java.io.OutputStream errStream)
Creates a new instance of this command-line tool with the provided information.

Parameters:
outStream - The output stream to use for standard output. It may be System.out for the JVM's default standard output stream, null if no output should be generated, or a custom output stream if the output should be sent to an alternate location.
errStream - The output stream to use for standard error. It may be System.err for the JVM's default standard error stream, null if no output should be generated, or a custom output stream if the output should be sent to an alternate location.
Method Detail

runTool

public final ResultCode runTool(java.lang.String... args)
Performs all processing for this command-line tool. This includes:

Parameters:
args - The command-line arguments provided to this program.
Returns:
The result of processing this tool. It should be ResultCode.SUCCESS if the tool completed its work successfully, or some other result if a problem occurred.

getToolName

public abstract java.lang.String getToolName()
Retrieves the name of this tool. It should be the name of the command used to invoke this tool.

Returns:
The name for this tool.

getToolDescription

public abstract java.lang.String getToolDescription()
Retrieves a human-readable description for this tool.

Returns:
A human-readable description for this tool.

getToolVersion

public java.lang.String getToolVersion()
Retrieves a version string for this tool, if available.

Returns:
A version string for this tool, or null if none is available.

getMaxTrailingArguments

public int getMaxTrailingArguments()
Retrieves the maximum number of unnamed trailing arguments that may be provided for this tool. If a tool supports trailing arguments, then it must override this method to return a nonzero value, and must also override the getTrailingArgumentsPlaceholder() method to return a non-null value.

Returns:
The maximum number of unnamed trailing arguments that may be provided for this tool. A value of zero indicates that trailing arguments are not allowed. A negative value indicates that there should be no limit on the number of trailing arguments.

getTrailingArgumentsPlaceholder

public java.lang.String getTrailingArgumentsPlaceholder()
Retrieves a placeholder string that should be used for trailing arguments in the usage information for this tool.

Returns:
A placeholder string that should be used for trailing arguments in the usage information for this tool, or null if trailing arguments are not supported.

createArgumentParser

public final ArgumentParser createArgumentParser()
                                          throws ArgumentException
Creates a parser that can be used to to parse arguments accepted by this tool.

Returns:
ArgumentParser that can be used to parse arguments for this tool.
Throws:
ArgumentException - If there was a problem initializing the parser for this tool.

addToolArguments

public abstract void addToolArguments(ArgumentParser parser)
                               throws ArgumentException
Adds the command-line arguments supported for use with this tool to the provided argument parser. The tool may need to retain references to the arguments (and/or the argument parser, if trailing arguments are allowed) to it in order to obtain their values for use in later processing.

Parameters:
parser - The argument parser to which the arguments are to be added.
Throws:
ArgumentException - If a problem occurs while adding any of the tool-specific arguments to the provided argument parser.

doExtendedArgumentValidation

public void doExtendedArgumentValidation()
                                  throws ArgumentException
Performs any necessary processing that should be done to ensure that the provided set of command-line arguments were valid. This method will be called after the basic argument parsing has been performed and immediately before the doToolProcessing() method is invoked.

Throws:
ArgumentException - If there was a problem with the command-line arguments provided to this program.

doToolProcessing

public abstract ResultCode doToolProcessing()
Performs the core set of processing for this tool.

Returns:
A result code that indicates whether the processing completed successfully.

registerShutdownHook

protected boolean registerShutdownHook()
Indicates whether this tool should register a shutdown hook with the JVM. Shutdown hooks allow for a best-effort attempt to perform a specified set of processing when the JVM is shutting down under various conditions, including: Shutdown hooks may not be invoked if the process is forcefully killed (e.g., using "kill -9", or the System.halt() or Runtime.halt() methods).

If this method is overridden to return true, then the doShutdownHookProcessing(ResultCode) method should also be overridden to contain the logic that will be invoked when the JVM is shutting down in a manner that calls shutdown hooks.

Returns:
true if this tool should register a shutdown hook, or false if not.

doShutdownHookProcessing

protected void doShutdownHookProcessing(ResultCode resultCode)
Performs any processing that may be needed when the JVM is shutting down, whether because tool processing has completed or because it has been interrupted (e.g., by a kill or break signal).

Note that because shutdown hooks run at a delicate time in the life of the JVM, they should complete quickly and minimize access to external resources. See the documentation for the java.lang.Runtime.addShutdownHook method for recommendations and restrictions about writing shutdown hooks.

Parameters:
resultCode - The result code returned by the tool. It may be null if the tool was interrupted before it completed processing.

getExampleUsages

@ThreadSafety(level=METHOD_THREADSAFE)
public java.util.LinkedHashMap<java.lang.String[],java.lang.String> getExampleUsages()
Retrieves a set of information that may be used to generate example usage information. Each element in the returned map should consist of a map between an example set of arguments and a string that describes the behavior of the tool when invoked with that set of arguments.

Returns:
A set of information that may be used to generate example usage information. It may be null or empty if no example usage information is available.

getOut

public final java.io.PrintStream getOut()
Retrieves the print writer that will be used for standard output.

Returns:
The print writer that will be used for standard output.

out

@ThreadSafety(level=METHOD_THREADSAFE)
public final void out(java.lang.Object... msg)
Writes the provided message to the standard output stream for this tool.

This method is completely threadsafe and my be invoked concurrently by any number of threads.

Parameters:
msg - The message components that will be written to the standard output stream. They will be concatenated together on the same line, and that line will be followed by an end-of-line sequence.

wrapOut

@ThreadSafety(level=METHOD_THREADSAFE)
public final void wrapOut(int indent,
                                                             int wrapColumn,
                                                             java.lang.Object... msg)
Writes the provided message to the standard output stream for this tool, optionally wrapping and/or indenting the text in the process.

This method is completely threadsafe and my be invoked concurrently by any number of threads.

Parameters:
indent - The number of spaces each line should be indented. A value less than or equal to zero indicates that no indent should be used.
wrapColumn - The column at which to wrap long lines. A value less than or equal to two indicates that no wrapping should be performed. If both an indent and a wrap column are to be used, then the wrap column must be greater than the indent.
msg - The message components that will be written to the standard output stream. They will be concatenated together on the same line, and that line will be followed by an end-of-line sequence.

getErr

public final java.io.PrintStream getErr()
Retrieves the print writer that will be used for standard error.

Returns:
The print writer that will be used for standard error.

err

@ThreadSafety(level=METHOD_THREADSAFE)
public final void err(java.lang.Object... msg)
Writes the provided message to the standard error stream for this tool.

This method is completely threadsafe and my be invoked concurrently by any number of threads.

Parameters:
msg - The message components that will be written to the standard error stream. They will be concatenated together on the same line, and that line will be followed by an end-of-line sequence.

wrapErr

@ThreadSafety(level=METHOD_THREADSAFE)
public final void wrapErr(int indent,
                                                             int wrapColumn,
                                                             java.lang.Object... msg)
Writes the provided message to the standard error stream for this tool, optionally wrapping and/or indenting the text in the process.

This method is completely threadsafe and my be invoked concurrently by any number of threads.

Parameters:
indent - The number of spaces each line should be indented. A value less than or equal to zero indicates that no indent should be used.
wrapColumn - The column at which to wrap long lines. A value less than or equal to two indicates that no wrapping should be performed. If both an indent and a wrap column are to be used, then the wrap column must be greater than the indent.
msg - The message components that will be written to the standard output stream. They will be concatenated together on the same line, and that line will be followed by an end-of-line sequence.