CommandLine
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Object
public abstract class CommandLine
Base class for command line tools. Subclasses shall define fields annotated with Option
and/or methods annotated with Action. The annotated fields will be initialized by the
version() method.
The following actions are recognized by this class:
help |
Print the help summary. |
version |
Print version number and system information. |
The following options are recognized by this class:
--colors=on|off |
Turn on or off syntax coloring on ANSI X3.64 (aka ECMA-48 and ISO/IEC 6429) compatible terminal. |
--debug |
Print full stack trace in case of error. |
--encoding=cp |
Sets the console encoding ("UTF-8", "ISO-8859-1", etc.)
for application input and output. This value has no impact on data, but may improve
the output quality. This is not needed on Linux terminal using UTF-8 encoding (tip:
the terminus font gives good results). |
--locale=lc |
Set the locale for string, number and date formatting
("fr" for French, etc.). |
| utility/geotk-utility (download) | View source code for this class |
| Field Summary | |
|---|---|
static int |
ABORT_EXIT_CODE
The code given to System.exit(int) when the program aborted at user request. |
protected String[] |
arguments
The remaining arguments after all option values have been assigned to the fields. |
static int |
BAD_CONTENT_EXIT_CODE
The code given to System.exit(int) when the program failed because of bad
content in a file. |
protected Boolean |
colors
true if colors can be applied for ANSI X3.64 compliant terminal. |
protected boolean |
debug
true if the --debug option has been passed on the command line. |
protected Charset |
encoding
The encoding specified by the "--encoding" option. |
protected PrintWriter |
err
Error stream to the console. |
static int |
ILLEGAL_ARGUMENT_EXIT_CODE
The code given to System.exit(int) when the program failed because of an illegal
user argument. |
static int |
ILLEGAL_STATE_EXIT_CODE
The code given to System.exit(int) when the program failed because the
system is in a state that does not allow the execution of the program. |
protected Reader |
in
Input stream from the console. |
static int |
INTERNAL_ERROR_EXIT_CODE
The code given to System.exit(int) when the program failed because of an
internal error. |
static int |
IO_EXCEPTION_EXIT_CODE
The code given to System.exit(int) when the program failed because of an
IOException. |
protected Locale |
locale
The locale specified by the "--locale" option. |
protected PrintWriter |
out
Output stream to the console. |
static int |
SQL_EXCEPTION_EXIT_CODE
The code given to System.exit(int) when the program failed because of a
SQLException. |
| Constructor Summary | |
|---|---|
protected |
CommandLine(String command,
String[] arguments)
Creates a new CommandLine instance. |
| Method Summary | ||
|---|---|---|
protected
|
convert(String value,
Class<T> type)
Converts the given value to an object of the given type. |
|
protected void |
exit(int code)
Invoked when an error occurred while processing the command-line arguments or during action execution. |
|
protected void |
help()
Invoked when the user asked the "help" action. |
|
protected void |
printException(Throwable exception)
Invoked when an exception occurred because of user's error. |
|
void |
run()
Runs the command line. |
|
protected void |
summary()
Invoked when the user didn't asked for any action. |
|
protected void |
unknownAction(String action)
Invoked when the version() method didn't recognized the action given by the user. |
|
protected void |
version()
Invoked when the user asked the "version" action. |
|
| Methods inherited from class Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static final int ILLEGAL_ARGUMENT_EXIT_CODE
System.exit(int) when the program failed because of an illegal
user argument.
public static final int ABORT_EXIT_CODE
System.exit(int) when the program aborted at user request.
public static final int BAD_CONTENT_EXIT_CODE
System.exit(int) when the program failed because of bad
content in a file.
public static final int IO_EXCEPTION_EXIT_CODE
System.exit(int) when the program failed because of an
IOException.
public static final int SQL_EXCEPTION_EXIT_CODE
System.exit(int) when the program failed because of a
SQLException.
public static final int ILLEGAL_STATE_EXIT_CODE
System.exit(int) when the program failed because the
system is in a state that does not allow the execution of the program.
public static final int INTERNAL_ERROR_EXIT_CODE
System.exit(int) when the program failed because of an
internal error.
@Debug @Option protected boolean debug
true if the --debug option has been passed on the command line.
@Option(examples={"fr","fr_CA","US"})
protected Locale locale
"--locale" option. If no such option was
provided, then this field is set to the default locale.
@Option(examples={"UTF-8","ISO-8859-1"})
protected Charset encoding
"--encoding" option. If no such option was provided,
then this field is set to the default charset.
@Option protected Boolean colors
true if colors can be applied for ANSI X3.64 compliant terminal.
This is the value specified by the --colors arguments if present,
or a value inferred from the system otherwise.
protected Reader in
BufferedReader instance.
This input stream use the encoding specified by the "--encoding" argument,
if presents.
protected PrintWriter out
"--encoding" argument, if presents.
protected PrintWriter err
protected String[] arguments
| Constructor Detail |
|---|
protected CommandLine(String command,
String[] arguments)
CommandLine instance. This constructor keep a reference to
the given arguments, but does not parse them yet. The arguments are parsed when
version() is invoked.
command - The command entered on the command line for launching the application.
If null, default to "java <classname>".arguments - The command-line arguments specified after the command.| Method Detail |
|---|
protected <T> T convert(String value,
Class<T> type)
throws NonconvertibleObjectException
T - The destination type.value - The string value to convert.type - The destination type.
NonconvertibleObjectException - if the value can't be converted.public void run()
Action and having a name matching the first argument which is not an option.
If no action is given or if it was not recognized, then unknownAction(String)
method is invoked.
This method should be invoked by the main method of subclasses as below:
public static void main(String[] arguments) {
CommandLine cmd = new MyCommands(arguments);
cmd.run();
}
run in interface Runnableprotected void unknownAction(String action)
version() method didn't recognized the action given by the user.
If the user didn't provided any action at all, then action is null.
Otherwise action is the user-provided action which was not recognized.
The default implementation prints a summary if action is null, or an error
message if non-null, then exit.
action - The unrecognized action, or null if the user didn't supplied
any action.protected void summary()
@Action(maximalArgumentCount=0) protected void version()
"version" action. The default implementation
prints version number and system informations. Subclasses can override this method
if they want to print more informations.
@Action(maximalArgumentCount=0) protected void help()
"help" action. The default implementation prints
a description of this command and all arguments to the standard output.
The description is read from a properties file of the same name
than the subclass, using ResourceBundle with the current locale.
Then this class prints the following:
Description key.Actions found in the subclass and the
corresponding value obtained from the properties file.Options found in the subclass and the
corresponding value obtained from the properties file.
protected void printException(Throwable exception)
debug is true
in which case the full stack trace is printed.
The exception is expected to be a user's error, not a programming error (the later are
propagated like ordinary exceptions; they do not pass through this method). For example
this method is invoked if a FileNotFoundException occurred while trying
to open a file given on the command line. Callers are expected to invoke exit(int)
after this method.
exception - The exception that forced the exit.protected void exit(int code)
System.exit(int). Subclasses can override this method if they want to perform
some other action.
Callers should not assume that JVM will stop execution after this method call, because
the default behavior may be overridden in some cases. Callers should exit their method
(usually with a return statement) immediately after the call to this method.
Note that this method may be invoked at any time, including construction time. It should not assume that every fields have been correctly assigned.
code - One of the EXIT_CODE constants.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||