apps

Class ClientApplication

java.lang.Object

apps.Application

apps.ClientApplication

Direct Known Subclasses:

ChangeDirectoryDummy, Get, List, MakeDirectory, Parse, PrintWorkingDirectory, Put, Remove, Touch

abstract class ClientApplication
extends Application

Base class of client applications.

This base class provides its own run method. Particular applications are implemented by overriding the coreLogic method of this class. The run method in this class wraps the main application logic in a try...catch statement. The application logic need not concern itself with error codes or printing error messages. If the coreLogic method throws an exception, an error message is printed to standard error, and the exit code is non-zero.

This class also provides an exception aggregation mechanism. If an application repeats certain work on each of several arguments, instead of the first exception terminating the whole program, it is possible to accumulate exceptions from each argument, and display all of them only after all arguments have been processed. This is done using the report methods. An application which wishes to process multiple arguments in this way should call report with no arguments after each argument that is processed successfully, and report with the exception as an argument after each argument that causes a failure during processing.

Calling fatal during processing causes the application to quit at the next call to report. Fatal errors are those in which resources which must be released to continue running the application safely cannot be released.

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.LinkedList<ApplicationFailure>	failures Aggregated list of application error messages.
private java.lang.String	fatal_error_message Fatal error message, if a fatal error has occurred.

Fields inherited from class apps.Application

EXIT_FAILURE, EXIT_SUCCESS

Constructor Summary

Constructors

Constructor and Description
ClientApplication()

Method Summary

Modifier and Type	Method and Description
protected abstract void	coreLogic(java.lang.String[] arguments) Called to execute the main body of the application.
protected void	fatal(java.lang.String message) Indicates that a fatal error has occurred.
private void	printErrorsAndExit() Prints all errors and terminates the process.
protected void	report() Reports that an argument has been processed successfully, for an application that processes multiple arguments.
protected void	report(ApplicationFailure failure) Reports that an argument has been processed, but the processing has caused a failure.
void	run(java.lang.String[] arguments) Wraps coreLogic in an exception handler.

Methods inherited from class java.lang.Object

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

Field Detail

fatal_error_message

private java.lang.String fatal_error_message

Fatal error message, if a fatal error has occurred.

failures

private java.util.LinkedList<ApplicationFailure> failures

Aggregated list of application error messages.

Constructor Detail

ClientApplication

ClientApplication()

Method Detail

coreLogic

protected abstract void coreLogic(java.lang.String[] arguments)
                           throws ApplicationFailure

Called to execute the main body of the application.

Parameters:

arguments - Command line arguments passed to the application.

Throws:

ApplicationFailure - When an error occurs. If this exception is thrown, its message string is printed to the standard error stream, and the application's exit status is non-zero.

java.lang.Throwable - If the application failed to handle an error by responding to it, or by translating it to ApplicationFailure.

run

public void run(java.lang.String[] arguments)

Wraps coreLogic in an exception handler.

Specified by:

run in class Application

Parameters:

arguments - Command line arguments.

report

protected void report()

Reports that an argument has been processed successfully, for an application that processes multiple arguments.

The primary purpose of this method is to act as a checkpoint. Fatal errors are sometimes the result of code that is run in finally blocks. Such code typically avoids raising exceptions when it fails, in order to avoid masking a primary exception. Thus, fatal errors are signalled instead by calling the fatal method. A method which called fatal, but had no other errors, will appear to have returned successfully. report must be called after such a method is run to ensure that the fatal error causes termination of the program.

report

protected void report(ApplicationFailure failure)

Reports that an argument has been processed, but the processing has caused a failure.

The failure is added to a list of application errors, and will be printed on application exit. If a fatal error has been signalled, the application exits immediately.

Parameters:

failure - Application failure.

printErrorsAndExit

private void printErrorsAndExit()

Prints all errors and terminates the process.

The exit status is zero if there are no errors, and non-zero otherwise.

fatal

protected void fatal(java.lang.String message)

Indicates that a fatal error has occurred.

Parameters:

message - Description of the error.