Using Program Parameters in Java Part-1

Introduction

Every programmer will encounter a situation where a choice must be made between various alternative solutions. Should tabular data be sorted in one way or another? What exactly is the graphical layout of your HTML pages? How often should you poll a queue? Most often you’ll know the path to take based on the requirements specifications, a design manual or some other kind of documentation, but now and then you’ll have to choose without help. Instead of just selecting one solution and hoping the customer will like it when he or she starts using your code, you could make it a “program parameter” or “option”.

This means that the actual choice is given to your program in some way at startup time, for example from a configuration file. Programs like command line utilities, where there’s no GUI and no database, simply take their data as “program parameters”.

In this article we’ll look into the various ways you may enter parameters to a Java program:

  1. Command line parameters
  2. Property files
  3. A combination of 1 and 2
  4. System properties
  5. XML files
  6. Databases

Finally I’ll show how you can hide the implementation–at least to some degree.

Command line parameters

Let’s start with the most basic and simplest way to enter parameters to a Java program: the command line. We all should know that a Java main program takes a String array as its parameter, and it contains the program arguments given to the Java VM. I deliberately used the word “arguments”, since the “parameters” given on the command line are meant for the VM. Entering “java -?” gives the syntax for the Java command:

If you have a fixed list of parameters for your program then you simply add them after the class name, but if you’d like to work with optional parameters, you need some way to identify the different parameters.

It’s common practice to give the parameters descriptive names, and use a hyphen in front of the name of the parameter. The parameter value(s) then follow after the name. This syntax is, for example, used in the Java command shown above.

It might be fun to write a command line parser in Java once and maybe twice, but the third time it gets rather boring. The Jakarta Commons project has a command line parser called CLI (Command Line Interface), which is simple and efficient to use. There are 3 steps involved when using CLI: define, parse, interrogate.

1. Define

CLI uses the word “options” for parameters, and use the Option class and the Options container class for definitions. A quick intro:

An option without arguments:

The first parameter to Option is the name used on the command line. The next parameter is used when CLI types out “usage information”.

An option with one argument:

The “ArgName” is the text used for the argument in the usage information.

If the option is required then add:

An option with one optional argument:

Using this syntax the user may either just enter “- sort” or maybe “-sort descending” or “-sort ascending”.

An option with several arguments:

Let me show you how to use CLI to parse a command line for a program that reads a log file. Let’s assume that the file contains information about activities for the users of some application. The command line syntax to parse is this:

Here’s the code you need to define this syntax:

2. Parse

Next step is parsing the arguments:

The ParseException may be thrown if a required option is missing or an undefined option is found. If CLI throws an Exception then it would be nice to write out the proper syntax of the command. This can be done like this:

  • 3. Interrogate

    The results of the parsing may now be found in the CommandLine object.

    If the rest of the program is coded and then run you will see this printed out:

    The “null” value shows that the “verbose” option does not take any arguments.

    Warning: CLI also stores the results of the parsing in the Option objects, so don’t reuse an object or parse the same object twice.

    Let me finish by mentioning a few useful features in CLI:

  • an option may have both a short name and a long name
  • you may specify arguments without preceding them with specific names (use getArgs to get the arguments from the CommandLine object). The sequence of such arguments is therefore important.
  • you may also specify key-value pairs in java property-style: key=value. An example is given later on in the article.

    Use the JavaDoc to see which other features are available for defining options and handling the parsed results. On the CLI website there’s also a link to some Usage Scenarios, but note that the samples contain a few bugs. The worst is the “Java Property Example” where hasArg() should be replaced with hasArgs().

    Use the Jakarta Commons mailing list to find out more information. There’s no specific mailing list for CLI.

    CLI is an active project at Jakarta Commons. I’ve been told by John Keyes, part of the team developing CLI, that a beta of a new version, CLI2, is slated for availability in late April.

    In the download (see the Resources section at the end of the article) you’ll find a class, TryCLI1, which may be used to write out the contents of an Optionsand a CommandLine instance. It’s useful when experimenting with CLI. See the main method for documentation.