de.frame4j.util

Class AppBase

java.lang.Object

de.frame4j.util.AppBase

All Implemented Interfaces:

ComVar

@MinDoc(copyright="Copyright 2004 - 2009, 2015  A. Weinert",
        author="Albrecht Weinert",
        version="V.38",
        lastModified="16.04.2021",
        usage="Hold a singleton object",
        purpose="Basic services for applications")
public final class AppBase
extends Object
implements ComVar

Basic common services for Java applications.

An object of this class is / should be a singleton within a JVM shared by all applications etc. running. It provides a substantial part of Frame4J's powerful infrastructure as well as some services.

Java applications extending App automatically have a common AppBase object. It provides, also by an associated AppIO object, the following services and utilities:

• a PrintWriter (AppIO.out) for normal output,
• a PrintWriter (AppIO.err) for error messages
• a PrintWriter (AppIO.log) with optional branching to normal output and a file,
• a BufferedReader (AppIO.in) for normal input,
• the handling of ever recurring I/O tasks,
• shutdown and start of applications,
• some time-keeping support and

© Copyright 2002 - 2003 Albrecht Weinert

See Also:

AppIO, TeeWriter, App

Nested Class Summary

Nested classes/interfaces inherited from interface de.frame4j.util.ComVar

ComVar.Impl

Field Summary

Fields

Modifier and Type	Field and Description
boolean	askGraf Graphical question on files instead of console question.
Object	baseApp The generating application object / the "mother" application.
AppIO	baseAppIO The one common AppIO object.
boolean	isBaseApp The generating application object is of type App.
int	killJVMdelay Delay before stopping JVM in ms.

Fields inherited from interface de.frame4j.util.ComVar

AUTHOR, BLANK_STRING, cons, CONSOL_ENCODING, COPYRIGHT, D, D_NaN, D_NegInf, D_PosInf, EMPTY_INT_A, EMPTY_STRING, FILE_ENCODING, FRW_CLLD, FS, FSS, H, hasCons, HOST_IP, HOST_IPv4, HOST_NAME, INIT_ERROR, JAR_ENCODING, JH, JOB_DONE_OK, JRL, LOG_OUT_ERROR, M, MAIN_THREAD_EXC, NO_BYTES, NO_CLASSES, NO_DOUBLES, NO_OBJECTS, NO_PARS_ERROR, NO_STRINGS, NOT_WINDOWS, ON_PI, ONE_DAY, ONE_HOUR, ONE_LEAP_YEAR, ONE_MINUTE, ONE_SECOND, ONE_WEEK, ONE_YEAR, OS, PROG_NAME, PROG_SHORT, PS, RUNTIME, S, SHY, UD, UL, UL_UR_da, UR

Method Summary

Modifier and Type	Method and Description
void	errorExit(Object theApp, int errNum, String errText) Error exit.
static void	exit(Exception excp, int errNum) Static Exit — helper method.
static AppBase	getAppBase() The one /singleton) AppBase object.
static AppBase	getAppBase(Object baseApp, int outBuffLen, int logBuffLen, String codePage) Fetching or making the one AppBase object.
static AppBase	getAppBase(Object baseApp, String codePage) Fetching or making the one AppBase object.
AppIO	getAppIO(Object theApp, int outBuffLen, int logBuffLen, String codePage) Fetching or making the one fitting AppIO object.
static boolean	isCommonRun() Common flag: the applications shall / might run on.
void	normalExit(Object theApp, int returnCode) Normal exit.
static Instant	setActTime() Update the commonly used actual (platform based) Time.
static boolean	sleep(long millis) Delay the applications running by waiting.
static int	start(App app, String[] args) Comfortable start of an application extending App.

Methods inherited from class java.lang.Object

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

Field Detail

baseApp

public final Object baseApp

The generating application object / the "mother" application.

Normally this will be of type / inheritor of de.frame4j.util.App, which is then signalled by isBaseApp being true.

baseApp is the first requester for which this singleton / common infrastructure object was made.

See Also:

getAppBase(Object, int, int, String), getAppBase(Object, String), getAppBase(), isBaseApp

baseAppIO

public final AppIO baseAppIO

The one common AppIO object.

isBaseApp

public final boolean isBaseApp

The generating application object is of type App.

See Also:

App, baseApp

killJVMdelay

public volatile int killJVMdelay

Delay before stopping JVM in ms.

This is the grace period between the mother application's errorExit() or normalExit() and the killing of the JVM.

Allowed values are in the range of 50 to 35000 (0,05 .. 35 s), otherwise there's no such grace period.

Hint: The waiting time is done in a so called shutdown hook which in turn resets the run flags (which normally is already done). This proceeding may give the usable grace period even in cases of external control-C or platform shutdown.

default: 64

See Also:

isCommonRun()

askGraf

public volatile boolean askGraf

Graphical question on files instead of console question.

Is askGraf true questions about how to deal with existing files will be asked in a little window, otherwise on the console.

default: false

Method Detail

isCommonRun

public static boolean isCommonRun()

Common flag: the applications shall / might run on.

This flag remains true, as long as there is a (mother) application baseApp that is running (or shall do so).

If set to false (e.g. by mother application's errorExit() or normalExit()), this has to be used by all running threads and plug-ins as a "stop ASAP!" signal.

In the spirit of this contract calling one of those exit methods may lead to this flag and the mother application's (baseApp) runFlag being reciprocative reset.

Between resetting this flag and killing the JVM a grace period of killJVMdelay milliseconds will interleave, to allow all threads applications and plug-ins to end well-behaved.

Returns:

the current state of the common run flag

See Also:

App.isRunFlag()

errorExit

public void errorExit(Object theApp,
                      int errNum,
                      String errText)

Error exit.

The flag commonRun will be reset (to false) at once.

If the parameter theApp is of type App the following will be done:

• theApp's runFlag will be reset to false.
  If errNum is not 0 or errText not empty, a multi-line report will be generated (by errMeld()) and output on log.
• If errNum is >= App.INIT_ERROR the text getUsage() will be output to baseAppIO.log.

If the parameter theApp is the base or mother application the following will be done:

• Is killJVMdelay in the allowed range (0,1 .. 30 s), the caller (the calling thread) will be delayed by this grace period.
• Afterwards the caller and all (i.e. the JVM) will be killed by System.exit(errNum). If errNum < 0 and not ComVar.NOT_WINDOWS (i.e. probably Windows), System.exit(-errNum) is used, as negative process return codes are immoral there.

This means this method, if called by the mother application baseApp or if called on commonRun already false, will not return to the caller. In this sense it's like calling System.exit(), that no other framework based software ever shall do (!).

In the other cases this method returns normally, but the application code should have done all its clean up anyway before.

Parameters:

theApp - the calling application (may be null).

errNum - !=0 : error (or special case) code

errText - supplemental (error) text

normalExit

public void normalExit(Object theApp,
                       int returnCode)

Normal exit.

If the application to end is the base or mother application the returnCode will be the common JVM process return value for all applications or plug-ins. This value can be processed as process (java.exe) exit code for the platform. In the case of DOS-Win32 the rules are:
0 = O.K.
>0 = special case or error (the higher the worse)

In scripts (batch or command files) this value can be evaluated by "IF ERRORLEVEL n". Negative return codes used sometimes by Unix applications should be avoided for sake of platform independence. So some framework exit methods (including this one) suppress negative return codes; see errorExit(Object, int, String).

Parameters:

theApp - the calling application (may be null).

returnCode - !=0 : error or special case code

exit

public static void exit(Exception excp,
                        int errNum)

Static Exit — helper method.

This method is the framework's substitute for System.exit() and the like. No Frame4J based / Frame4J using software should ever use murder methods ( System.exit() and consorts) directly.

If (still) in a static context, e.g. in the main(String[] ) or in static initialiser's exception handling, this is the method of choice.

In all other cases the App's or the AppBase object's exit methods are to be used.

On one hand this method supports the handling of an Exception comfortably. On the other hand another (mother) application(s) that may be already running under the framework will be saved from the disastrous effects of System.exit().

To repeat it clearly: No code using this framework Frame4J must call System.exit() and the like under whatever circumstances. Period.

For the output described in the following BaseAppIO.log is used, if that is available and else System.err:

• If the Exception excp exists and errNum is not 0, the text
  " *** classname Error errNum XXX"
  is output.
  
• For a given Exception excp the call stack is output in the case of a RunTimeException but no IllegalArgumentException. (If this condition holds, there's often a programming error where the call stack is helpful.)
• For another given Exception excp only the message text is output. If that is empty, the stack trace is output.
• If the above mentioned other running (mother) applications do not exist and run, an errNum != 0 will be forwarded by (something like) System.exit(errNum). If the platform is not Windows a negative number will be forwarded as is, otherwise the absolute value is taken.
  With other applications or plug-ins still running this method returns normally to the caller, that should then end its thread by leaving static main(), run(), doIt() or whatever the type's starting or working method may be be.
  In such cases (return to the caller) the report text (part)
  " *** className Error errNum XXX"
  will be replaced by
  " *** className Error errNum ***".

Hint: Very clever JIT-Compilers and certain optimisations may reduce the information contained in the generated report texts.

Parameters:

excp - the given exception (or null).

errNum - >0 : the error number

getAppBase

public static final AppBase getAppBase()

The one /singleton) AppBase object.

This method returns the (maximal one singleton) AppBase object, if it was already constructed elsewhere.

Otherwise null is returned.

Returns:

the single AppBase

See Also:

getAppBase(Object, String), getAppBase(Object, int, int, String)

getAppBase

public static AppBase getAppBase(Object baseApp,
                                 String codePage)
                          throws IllegalArgumentException

Fetching or making the one AppBase object.

This method returns the (singleton) AppBase object unchanged, if it was already constructed elsewhere. In this case the caller's parameters are all irrelevant.

Otherwise the object will be constructed according to the parameters and returned. Illegal parameter values are punished by an IllegalArgumentException.

Parameters:

baseApp - The (first) using application; it will be normally of type App, must not be null

codePage - The code page for in, out and err (oder null)

Returns:

the single AppBase

Throws:

IllegalArgumentException - if any used parameter values are illegal

See Also:

getAppIO(Object, int, int, String)

getAppBase

public static AppBase getAppBase(Object baseApp,
                                 int outBuffLen,
                                 int logBuffLen,
                                 String codePage)
                          throws IllegalArgumentException

Fetching or making the one AppBase object.

This method returns the (singleton) AppBase object unchanged, if it was already constructed elsewhere. In this case the caller's parameters are all irrelevant.

Otherwise the object will be constructed according to the parameters and returned. Illegal parameter values are punished by an IllegalArgumentException.

Parameters:

baseApp - The (first) using application; it will be normally of type App, must not be null

outBuffLen - the out TeeWriter's buffer size, 1024 to 400000 characters, default 20K

logBuffLen - the log TeeWriter's buffer size, 1024 to 400000 characters, default 10K

codePage - encoding for console I/O, null will act as CONSOL_ENCODING, "defaultEncoding" or specifying unimplemented encodings will default to the system's file encoding (ComVar.FILE_ENCODING)

Returns:

the single AppBase

Throws:

IllegalArgumentException - if any used parameter values are illegal

getAppIO

public AppIO getAppIO(Object theApp,
                      int outBuffLen,
                      int logBuffLen,
                      String codePage)
               throws IllegalArgumentException

Fetching or making the one fitting AppIO object.

This method returns an AppIO object fitting for a given application. Applications of type App this method is used accordingly in App's constructors (as the one AppIO object associated with an App is final).

If theApp is null, an Exception will occur.

If theApp is the one base (or mother) application of this (also singleton) AppBase object, the already made AppIO object will be returned. All other parameters are then irrelevant.

If theApp is of type App, the already associated AppIO object is returned, if it is already made. (This will be so for all calls outside / after App constructors). All other parameters are then irrelevant.

If no already made and associated AppIO object can be determined, one is made according to the parameters. The free outputs of the log and out TeeWriters will be forwarded / connected to log and out of this AppBase object's AppIO object.

Parameters:

theApp - The using application; it will be normally of type App, must not be null

outBuffLen - the out TeeWriter's buffer size, 1024 to 400000 characters, default 20K

logBuffLen - the log TeeWriter's buffer size, 1024 to 400000 characters, default 10K

codePage - encoding for console I/O, null will act as CONSOL_ENCODING, "defaultEncoding" or specifying unimplemented encodings will default to the system's file encoding (ComVar.FILE_ENCODING)

Returns:

a fitting AppIO

Throws:

IllegalArgumentException - if any used parameter values are illegal

setActTime

public static final Instant setActTime()

Update the commonly used actual (platform based) Time.

The commonly used (actual) time (stamp) will be updated to platform time and fetched.

Returns:

the updated time

sleep

public static boolean sleep(long millis)

Delay the applications running by waiting.

This method's effect is essentially that of the method Thread.sleep(long) (used).

This method throws no exception. Interrupted wait sleep is instead signalled via the return value.

The waiting / sleeping time is given in ms (milliseconds). The resolution may on some operating systems more coarse.
To use longer times one may use the constant values of the interface de.frame4j.util.ComVar.

Parameters:

millis - (>0 !) the delay / sleep in ms

Returns:

true if the sleep was complete; false on interrupt (wake up)

See Also:

AppHelper.sleep()

start

public static final int start(App app,
                              String[] args)

Comfortable start of an application extending App.

This method starts an App object. It may of course be used from an application extending App itself. The started Application's main thread (doIt()) does run in the thread of this method's caller.

The return value is ComVar.NO_PARS_ERROR, if app or args is null. It is ComVar.INIT_ERROR on errors while evaluating .properties files or the arguments supplied.
Otherwise this methods return value is that of the started App's method app.doIt().

app.App.verbose and app.App.help will be set according to the " mother application" baseApp. Besides that this methods effect is mostly that of:
app.go(args, false, null);.

Hint: Some applications extending App are written in a way that they require (default) initialising their object variables by constructor or initialisers. This is of course perfectly in order. But if that is so, the same object app may not be started multiple times by this method. In that case do not
App app = new myApp();
AppBase.start(app, args1);
AppBase.start(app, args2);
but do
AppBase.start(new myApp(), args1);
AppBase.start(new myApp(), args2);

Parameters:

app - the application to start

args - start parameter

Returns:

ComVar.INIT_ERROR etc.: start error, 0: OK (return by doIt())

See Also:

App.go(String[], String, CharSequence)