Package nzilbb.util

Class CommandLineProgram

  • Direct Known Subclasses:
    Annotate, Deserialize, Info, StandAloneWebApp, Transcribe, Transform
    public class CommandLineProgram
extends Object
    Base class that standardizes various common functions for utilitiy applications - whether they be run as full applications from the command line or via JNLP or as applets within a browser.

    To implement a self-documenting, self-configuring application, simply extend this class, annotate any setXXX() methods with a Switch annotation, and call processArguments(String argv[]) from the derived class's public static void main(String argv[])

    To provide further information, you may use the ProgramDescription annotation on the derived class itself.

    Doing this has the following effect:

    • If the application is run from the command line with the -usage flag then a list of switches (one for each @Switch annotated setter) is listed to stderr, along with description information annotated with ProgramDescription
    • If the application is run from the command line with switches that correspond to @Switch annotated setters, then the setter will be called with the given value - e.g. if --myswitch=myvalue is called, then the equivalent of myObject.setMyswitch("myvalue") is executed
    • If the application is run from the command line and any switches that are marked as compulsory are not set, then execution is halted with an error message and the usage information written to stderr
    • If the application is run from the command line with arguments that don't start with '--' then these are added to a arguments
    • When the application is run, if it finds a .properties file that matches the main class name, it is used to call @Switch annotated setter corresponding to the properties defined in the file. Arguments can also be specified by defining properties called arg[0], arg[1], etc.

    e.g. 

     import nzilbb.util.CommandLineProgram;
 import nzilbb.util.ProgramDescription;
 import nzilbb.util.Switch;
 
 @ProgramDescription(value="A very useful utility",arguments="extra-arg-1 extra-arg-2")
 public class Useful extends CommandLineProgram
 {
    public static void main(String argv[])
    {
       Useful application = new Useful();
       if (application.processArguments(argv))
       {
          application.start();
       }
    }
 
    @Switch(value="This is a compulsory string switch that fulfils some purpose",compulsory=true)
    public void setSomeString(String s) {...}
 
    @Switch("This is an optional boolean switch")
    public void setSomeBoolean(Boolean b) {...}
 
    public void start()
    {
       for (String sArgument: arguments)
       {
         ...
       }
    }
 }

    This could then be invoked as:
    java Useful --SomeString=Hello --SomeBoolean sundryArg1 sundryArg2

    Author:
    Robert Fromont robert@fromont.net.nz

    • Constructor Detail

      • CommandLineProgram

        public CommandLineProgram()
        Constructor

    • Method Detail

      • getUsage

        public Boolean getUsage()
        Getter for usage: Whether or not to display usage information
        Returns:
        Whether or not to display usage information

      • setUsage

        @Switch("Whether or not to display usage information")
public CommandLineProgram setUsage​(Boolean bNewUsage)
        Setter for usage: Whether or not to display usage information
        Parameters:
        bNewUsage - Whether or not to display usage information

      • getV

        public String getV()
        Getter for v: Version information.
        Returns:
        Version information.

      • setV

        public CommandLineProgram setV​(String newV)
        Setter for v: Version information.
        Parameters:
        newV - Version information.

      • getVersion

        public Boolean getVersion()
        Getter for version: Print version information.
        Returns:
        Print version information.

      • setVersion

        @Switch("Print version information.")
public CommandLineProgram setVersion​(Boolean newVersion)
        Setter for version: Print version information.
        Parameters:
        newVersion - Print version information.

      • processArguments

        public boolean processArguments​(String[] argv)
        Main entrypoint if run as an application - this should be called by the public static void main(String argv[]) of the derived class.
        Parameters:
        argv - Command-line arguments.
        Returns:
        true if all obligatory arguments were present, false otherwise

      • interpretPropertiesParameters

        public void interpretPropertiesParameters()
        This method looks for a .properties file matching the class name, and if it finds one, uses it to set bean attributes and arguments appropiately. Arguments are interpreted is being the values of Properties named arg[0], arg[1], etc.

      • message

        public void message​(String message)
        Display a message
        Parameters:
        message - The message to display.

      • error

        public void error​(String message)
        Show error message
        Parameters:
        message - The error message.

      • error

        public void error​(Throwable t)
        Show error message
        Parameters:
        t - The error.

      • warning

        public void warning​(String message)
        Show warning message
        Parameters:
        message - The warning message.

      • warning

        public void warning​(Throwable t)
        Show warning message
        Parameters:
        t - The error.