App ( Frame4J -- the Java framework de.frame4j... )

java.lang.Object
- de.frame4j.util.App

All Implemented Interfaces:

AttrSettable, TextHelper.MessageComponents, AppMBean, ComVar, UIInfo, ActionListener, EventListener

Direct Known Subclasses:

AskAlert, BlinkOnPi, Del, Era, FS, FuR, HelloFrame4J, MakeDigest, PKextr, SAXdemo, SendMail, SVNkeys, SVNkeysFilter, TestOnPi, UCopy, Update, XMLio
```
@MinDoc(copyright="Copyright 1997 - 2016, 2021 A. Weinert",
        author="Albrecht Weinert",
        version="V.65",
        lastModified="3.06.2024",
        usage="start as Java application",
        purpose="Base class for powerful, robust and comfortable applications")
public abstract class App
extends Object
implements ActionListener, AppMBean, ComVar, UIInfo, TextHelper.MessageComponents, AttrSettable
```
The parent for Frame4J based Java applications.

A Java application written as an App inheritor gets a powerful infrastructure and wide range of often needed abilities otherwise to be programmed again and again. App by itself supports no Graphics or GUIs, but is suitable for graphical applications.

With App and the framework Frame4J implementing comfortable Java applications is simplified. Ever recurring tasks are solved, as among others
- providing a PrintWriter (out) for normal output,
- providing a PrintWriter (err) for error messages
- providing a PrintWriter (log) with optional branching to normal output and a file,
- optional providing of a logger connected to log,
- providing a BufferedReader (AppIO.in) for normal input,
- handling and checking (parsing) of programme parameters,
- handling of programme's properties and settings,
- support for (inter) nationalising,
- handling of recurring input and output problems,
- concurrent execution of actions,
- handling of (on-line) short documentation or helps,
- supporting a role as JMX server.
An application to use App by inheritance may do so directly or by a simple inner class. One just follows a schema best explained by examples like HelloFrame4J or SAXdemo. For the inner class scheme, see the end of AppLangMap's source as an example.
The schema in short is
1. In the application's start method (static main(String[] args) make the applications object by the default constructor and call one of App's go(...) methods:
  new MyAppInheritor().go(args, ...);
2. provide a simple MyAppInheritor.properties text file in the same directory or say you won't by overwriting allowNoPropertiesFile() with return true.
  If you do the text file put the (nationalised) help texts as property helpText, de.helpText, en.helpText there.
3. implement the abstract method doIt() to do the real work of your application:
  public int doIt(){
  log.prinln("Hi, I'm a sloth-bear."); return 0;}
4. (Type java MyAppInheritor -? and enjoy your help text.
Between the call of go(...) and the entry into doIt() all the initialising, command line parsing work is done and lot more — quite invisibly in the background.

© Copyright 1997 - 2006, 2009 Albrecht Weinert
Version:

65 (3.06.2024

Author:

Albrecht Weinert

See Also:

AppIO, Prop, go(String[], String, CharSequence)

Nested Class Summary
- Nested classes/interfaces inherited from interface de.frame4j.util.ComVar
  ComVar.Impl

Field Summary

Fields
Modifier and Type	Field and Description
`MinDoc`	`ano` The own MinDoc annotation.
`protected AppBase`	`appBase` The one (singleton) AppBase object.
`protected AppIO`	`appIO` An AppIO object for log output and console I/O.
`Instant`	`appStartTime` The application's start up time.
`long`	`appStartTimeMS` The application's start up time in ms since 1.1.1970.
`protected String[]`	`args` The start parameters.
`protected String[]`	`argsOrig` The start parameters.
`String`	`bgColor` Preferred background colour for graphical elements (if used).
`PrintWriter`	`err` The error output.
`String`	`fullClassName` The own class name.
`protected boolean`	`help` Only (on line) help output, no other effects.
`protected Image`	`icon` The application's icon, if any.
`PrintWriter`	`log` The log output.
`protected Thread`	`mainThread` The main thread.
`Class<? extends App>`	`myClass` The own class (the class object).
`protected Window`	`myFrame` The application's main / base graphical window, if any.
`protected String`	`name` The application's name.
`PrintWriter`	`out` The "normal" output.
`protected OutMode`	`outMode` Output mode for log and out files.
`String`	`packName` The own package name.
`protected Prop`	`prop` The Prop(erties) object.
`protected int`	`retCode` The return code of the application.
`protected boolean`	`runFlag` Flag to stop all threads of this application.
`String`	`shortClassName` The own class name.
`protected String`	`title` The preferred title for Frames or Dialogues (if used).
`protected boolean`	`verbose` Verbose reports.
`protected Verbos`	`verbosity` Report detailedness of this application.

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

Fields inherited from interface de.frame4j.net.AttrSettable
ILLEGAL_TYPE, ILLEGAL_VALUE, NO_ATTRIBUTE, NO_KNOWN_ATTRIBUTE, NO_VALUE, OK, retVtext

Constructor Summary

Constructors
Constructor and Description
`App()` The standard constructor.
`App(int outBuffLen, int logBuffLen)` Constructor setting buffer sizes for out and log.
`App(String[] args)` The make'n go constructor.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`actionPerformed(ActionEvent e)` The reaction to an action; mostly by a menu.
`protected boolean`	`allowNoPropertiesFile()` Decide, if the basic .properties file may be omitted.
`String`	`clientOrder(String command)` A client's command to this application.
`protected boolean`	`condHelpLog()` Conditional output of on-line help to log, and then stop.
`protected int`	`connect(OutMode outMode, Prop prop)` Connect the TeeWriter's outputs for log and out.
`protected abstract int`	`doIt()` This application's working method.
`int`	`errMeld(int errNum, Object suplText)` Output a (multi line) error report.
`int`	`errMeld(PrintStream out, int errNum, Object suplText)` Output a (multi line) error report.
`int`	`errorExit(int errNum, Exception ex, String errText)` Error exit with exception.
`int`	`errorExit(int errNum, String errText)` Error exit.
`String`	`errorText(int errNum, Object suplText)` Generate a multi line error report.
`protected String`	`extraPropertiesFile()` Decide, if and which extra .properties has to be loaded.
`String`	`formMessage(String key)` Make an (inter) nationalised message.
`String`	`formMessage(String key, int parInt)` Make an (inter) nationalised message.
`String`	`formMessage(String key, Object param)` Make an (inter) nationalised message..
`String`	`getAbout()` A (short) description of this application (about text).
`String`	`getAboutText()` A (short) description of this application (about text).
`String`	`getActTime()` The actual (system) time as text.
`Logger`	`getAppLogger()` The application's base Logger.
`Instant`	`getAppStartTime()` The application's start up time.
`String`	`getArgs()` The start parameters.
`String`	`getAuthor()` The author.
`String`	`getCopyright()` The copyright notice.
`protected Logger`	`getDbLogger()`
`long`	`getExecTimeMs()` The application's execution time (milliseconds) so far.
`Long`	`getExecTimeMsL()` The application's execution time (milliseconds) so far.
`String`	`getExecTimeString()` The application's execution time (milliseconds) so far as text.
`String`	`getHelp()` A text to guide the user of this App based application (help-Text).
`String`	`getHelpText()` A text to guide the user of this App based application (help-Text).
`Image`	`getIcon()` The application's icon, if any.
`String`	`getLanguage()` Get the short (2 character) notation of the user's language.
`LogWriterHandler`	`getLogHandler()` The Logger's handler.
`Object`	`getMessageComponent(int index)` Get a message component by its index.
`int`	`getMessageComponentsLength()` Number of messageFormat components of this application.
`Window`	`getMyFrame()` The applications main / base graphical window, if any.
`String`	`getName()` The program's name.
`String`	`getNameWithVersDate()` The application's name, version and last modification date.
`OutMode`	`getOutMode()` Output mode for log and out files.
`Prop`	`getProp()` The Prop(erties) object.
`String`	`getPurpose()` The purpose of this application.
`String`	`getStartTime()` The application's start up time as Text.
`String`	`getStateString()` The running state as text.
`WindowListener`	`getTheCloser(Window frame)` A simple stop all when Window closes.
`String`	`getTitle()` The preferred title for Frames or Dialogues (if used).
`String`	`getUsage()` The usage (quick help).
`String`	`getVerbose()` Detailedness of reports or logging.
`Verbos`	`getVerbosity()` Detailedness of reports or logging.
`String`	`getVersDate()` The program's version and revision date.
`protected int`	`go(String[] args)` Comfortably start the application.
`protected int`	`go(String[] args, String codePage)` Comfortable start of the application.
`protected int`	`go(String[] args, String codePage, CharSequence commBeg)` Comfortable start of the application.
`Image`	`haveIcon()` Get the application's icon.
`boolean`	`isDebug()` All reports — for test and debugging.
`boolean`	`isHelp()` Do only (on line) help output; have no other effects.
`protected boolean`	`isHelpLog()` The condition of (just) outputting the on-line help.
`boolean`	`isNormal()` Just the normal reports.
`boolean`	`isRunFlag()` Flag to stop all threads of this application.
`boolean`	`isSilent()` Almost no reports.
`boolean`	`isTest()` Many reports — for testing.
`boolean`	`isVerbose()` Report detailedness of this application.
`void`	`logVerbose(String sourceClass, String sourceMethod, String msg)` Log also into a DB (data base).
`void`	`logVerbose(String sourceClass, String sourceMethod, String msg, Object[] params)` Log also into a DB (data base).
`StringBuilder`	`makeStatusTextEnd(StringBuilder bastel)` Append the standard end to a status text.
`StringBuilder`	`makeStatusTextStart(StringBuilder bastel)` Append the standard start to a status text.
`StringBuilder`	`messageFormat(StringBuilder bastel, CharSequence patternKey, String patternDefault, Object args)` A keyed message formatter.
`int`	`normalExit(int returnCode)` Normal exit.
`boolean`	`parsePartial()` Partial evaluation of start parameters by Prop.
`boolean`	`performeAction(String command, AWTEvent e)` The reaction to an action; implementation.
`void`	`queueAction(String command, AWTEvent event)` React to an event by queueing an action.
`String`	`regAsStdMBean()` Register this application as standard MBean.
`void`	`repExc(Appendable out, Throwable exc, boolean trace)` Report an exception.
`void`	`setAboutText(CharSequence aboutText)` Set the (short) description of this application (about text).
`protected int`	`setAttribute(String name, char name0, Object value, Class<?> vClass, boolean isNull, boolean isStringVal)` Overridable implementation of setAtttibute(String, Object).
`int`	`setAttribute(String name, Object value)` AttrSettable implementation.
`void`	`setAuthor(String author)` Set the author(s).
`void`	`setBgColor(CharSequence bgColor)` Preferred background colour for graphical elements (if used).
`void`	`setCodePages(String codePage)` Setting the code pages for the Reader in and the Writers out and err.
`void`	`setCopyright(CharSequence copyright)` Set the copyright notice.
`void`	`setHelp(boolean help)` Do only (on line) help output; have no other effects.
`void`	`setLogOut2(OutputStream os2, String cp2)` Set log's second Writer as Stream.
`void`	`setName(String name)` Set the (short) name.
`void`	`setOutMode(CharSequence outMode)` Set output mode for log, out and may be other files.
`void`	`setOutMode(OutMode outMode)` Set output mode for log, out and may be other files.
`void`	`setPurpose(CharSequence purpose)` Set the purpose of this application.
`void`	`setTitle(String title)` The preferred title for Frames or Dialogues (if used).
`void`	`setUsage(CharSequence usage)` Set the usage (quick help).
`void`	`setVerbose(boolean verbose)` Set the report detailedness of this application.
`void`	`setVerbose(String verbosity)` Set the report detailedness of this application.
`void`	`setVerbosity(int value)` Set the report detailedness of this application.
`void`	`setVerbosity(String verbosity)` Set the report detailedness of this application.
`void`	`setVersDate(String versDate)` Set version with date and optional author / last modifier.
`void`	`stop()` Stop the application.
`StringBuilder`	`threeLineEndMsg()` Two line standard end report (nationalised).
`String`	`toString()` As String.
`StringBuilder`	`twoLineEndMsg()` Two line standard end report (nationalised).
`StringBuilder`	`twoLineStartMsg()` Two line standard start report (nationalised).
`String`	`valueLang(CharSequence key)` Get a value for a key — regarding set user language.
`String`	`valueLang(CharSequence key, String def)` Get a value for a key — regarding set user language.
`boolean`	`wakeMainThread()` Wake up the main thread.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface de.frame4j.net.AttrSettable
retVtext

Field Detail
- appStartTime
```
public final Instant appStartTime
```
  The application's start up time.
  
  See Also:
  
  getAppStartTime()
- appStartTimeMS
```
public final long appStartTimeMS
```
  The application's start up time in ms since 1.1.1970.
- args
```
protected String[] args
```
  The start parameters.
  
  Usually set by one of the start methods go(...) called within void main(String[] args).
  Here in args the parameters used in (partial) parsing will be set null, while argsOrig will be an untouched copy.
  
  default: ComVar.NO_STRINGS
- argsOrig
```
protected String[] argsOrig
```
  The start parameters.
  
  Usually set by one of the start methods go(...) called within void main(String[] args).
  Here in args the parameters used in (partial) parsing will be set null, while argsOrig will be an untouched copy.
  
  default: ComVar.NO_STRINGS
- verbosity
```
protected Verbos verbosity
```
  Report detailedness of this application.
  
  default: Verbos.NORMAL
  
  See Also:
  
  getVerbosity()
- verbose
```
protected boolean verbose
```
  Verbose reports.
  
  It is the same value as verbosity.verbose and is (to be) kept so whenever verbosity changes.
  
  See Also:
  
  verbose, setVerbose(boolean), setVerbosity(String), setVerbosity(int)
- help
```
protected boolean help
```
  Only (on line) help output, no other effects.
  
  See Also:
  
  isHelp()
- outMode
```
protected OutMode outMode
```
  Output mode for log and out files.
  
  See Also:
  
  getOutMode()
- runFlag
```
protected volatile boolean runFlag
```
  Flag to stop all threads of this application.
  
  This application and all its threads shall only run as long as this variable is true.
  
  Important implementation hint: The only reason for this variable being protected is the very frequent reading by some inheritors. Under no circumstances an inheritor is entitled to write to runFlag. One legal way to to set it false is the method stop().
  
  See Also:
  
  isRunFlag(), stop()
- title
```
protected String title
```
  The preferred title for Frames or Dialogues (if used).
  
  See Also:
  
  getTitle()
- myFrame
```
protected Window myFrame
```
  The application's main / base graphical window, if any.
  
  An inheritor may (and should) use this field with a reference to its main window. If doing so it must not override getMyFrame() as it returns myFrame.
- icon
```
protected Image icon
```
  The application's icon, if any.
- bgColor
```
public String bgColor
```
  Preferred background colour for graphical elements (if used).
  
  Initial value: "white" (0xFFffFF)
- myClass
```
public final Class<? extends App> myClass
```
  The own class (the class object).
  
  Set finally at construction (App()).
  
  Hint: Clearly, it is not App.class, but that of the inheritor.
- fullClassName
```
public final String fullClassName
```
  The own class name.
  
  Set finally at construction (App()), the long form meaning all. The short form is without packages and without inner or embedded classes, be the named or anonymous (no $-numbering or $-names). The packName is the package part with trailing dot or empty.
  
  Hint: Clearly, in nearly all cases it is not "de.frame4j.util.App" but the inheritor's package name.
- shortClassName
```
public final String shortClassName
```
  The own class name.
  
  Set finally at construction (App()), the long form meaning all. The short form is without packages and without inner or embedded classes, be the named or anonymous (no $-numbering or $-names). The packName is the package part with trailing dot or empty.
  
  Hint: Clearly, in nearly all cases it is not "de.frame4j.util.App" but the inheritor's package name.
- packName
```
public final String packName
```
  The own package name.
  
  Set finally at construction (App()). It is this class' package part with trailing dot or empty.
  
  Hint: Clearly, it is not "de.frame4j.util." but the inheritor's full or short class name.
- ano
```
public final MinDoc ano
```
  The own MinDoc annotation.
  
  Set finally at construction (App()).
  If the inheritor is MinDoc annotated, this annotation is set here. Otherwise that of an enclosing class or an ancestor is taken; that may be lastly that of this class App.
- prop
```
protected volatile Prop prop
```
  The Prop(erties) object.
  
  See Also:
  
  getProp()
- mainThread
```
protected volatile Thread mainThread
```
  The main thread.
  
  mainThread is the thread which the working method doIt() was started in. This variable will be set prior to entering doIt() and reset to null after return from it.
  
  Hint: Setting this variable null within doIt() immediately before returning will be interpreted as signal to "carry on" even after ending doIt() and hence its thread:
  mainThread = null; // carry on
  return 0; // end of main Thread
  
  See Also:
  
  go(String[], String, CharSequence), go(String[], String)
- appBase
```
protected final AppBase appBase
```
  The one (singleton) AppBase object.
  
  The AppBase object organises the concurrent run of multiple App based or other applications using the same Frame4J resources. It features especially services for a "well behaved" ending of one or all those applications.
  
  Additionally AppBase object organises JMX service.
- appIO
```
protected final AppIO appIO
```
  An AppIO object for log output and console I/O.
  
  The AppIO object appIO features robust and comfortable I/O.
  A PrintWriter appIO.out outputs to normal out (System.out) and optionally to a file.
  A PrintWriter appIO.log outputs to appIO.out and optionally to the file appIO.logDat.
  The other PrintWriter appIO.err and the BufferedReader appIO.in are of less interest for graphical applications.
  The output branches described will be made in the AppIO object by the use of two TeeWriters; details see there.
- out
```
public final PrintWriter out
```
  The "normal" output.
  
  Output to out goes by default to normal out (System.out) and optionally to a file.
  
  (Identical to appIO.out.)
- err
```
public final PrintWriter err
```
  The error output.
  
  This is the appIO object's err, that is System.err decorated with a PrintWriter.
- log
```
public final PrintWriter log
```
  The log output.
  
  Outputs to log will be branched to out and if given to the log file appIO.logDat.
  (It is appIO.log.)
- retCode
```
protected int retCode
```
  The return code of the application.
  
  Start value: ComVar.NO_PARS_ERROR (Start and evaluation problems)
  
  Hint: Internal use. Not to be manipulated by inheritor's.
- name
```
protected String name
```
  The application's name.

Constructor Detail
- App
```
public App()
```
  The standard constructor.
  
  This constructor (by just calling App(-1, -1)) does all basic initialisations for the made (this) App object:
  - gets or makes the (singleton-) AppBase object by AppBase.getAppBase(this),
  - gets or makes the AppIO object by AppBase.getAppEA(this, -1, -1, null) fetching from there
  - the initialised PrintWriter out, log and err.
  Other settings (like getting and parsing the arguments args) are done afterwards by using one of the starter methods go(....).
  
  As this constructor is called by the default constructors of inheriting classes, there is usually no need to write a constructor for inheritors.
  See Also:
  
  AppBase.getAppBase(), App(int, int)
- App
```
public App(int outBuffLen,
           int logBuffLen)
```
  Constructor setting buffer sizes for out and log.
  
  The (then to be written) parameterless constructor of an inheriting class must call this explicitly, if not satisfied with default buffer sizes.
  Otherwise the standard (default) constructor chain is sufficient and should not be changed.
  
  Implementation hint: All constructors must go through this, as is done by App() calling App(-1, -1).
  
  Parameters:
  
  outBuffLen - TeeWriter's buffer size for out, 1024 .. 400000 characters, default 20K
  
  logBuffLen - TeeWriter's buffer size for log, 1024 .. 400000 characters, default 10K
  
  See Also:
  
  App()
- App
```
public App(String[] args)
```
  The make'n go constructor.
  
  This constructor is meant for non complex extensions of App and may well be used in anonymous embedded classes. The simple idiom to make any class (not itself extending App} an "Application" with all inherited comfort is:
```
       public static void main(String[] args) {
          new App(args){
             protected int doIt() {
                log.println(twoLineStartMsg());
                /// do the task
                log.println(twoLineEndMsg());
                return retCode;
             } // doIt
          }; // App
      } // main (String[])  my class as App  
```
  This constructor does all basic initialisations for the made App object and then directly starts the application like a starter method go(....).
  
  This is especially comfortable for not so complex inheritors, as is often the case with anonymous inner classes extending App.
  Parameters:
  
  args - start parameters for the application
  
  See Also:
  
  AppBase.getAppBase(), App(int, int)

Method Detail

getAppStartTime
```
public final Instant getAppStartTime()
```
The application's start up time.

Returns:

the application's start time

See Also:

appStartTime

getStartTime
```
public String getStartTime()
```
The application's start up time as Text.

Returns appStartTime formatted according to AppLangMap.valueUL("wedaclock").

Hint: The formatting is only done once, appStartTime being final. Afterwards a stored String is returned (singleton).

Specified by:

getStartTime in interface AppMBean

Returns:

the application's start time

See Also:

getStartTime()

getMessageComponentsLength
```
public int getMessageComponentsLength()
```
Number of messageFormat components of this application.

Specified by:

getMessageComponentsLength in interface TextHelper.MessageComponents

Returns:

29 if not overridden

See Also:

getMessageComponent(int)

getMessageComponent
```
public Object getMessageComponent(int index)
```
Get a message component by its index.

This method fetches the following information on this application:
[5] : actual Time (formatted)
[7] : start up Time
[8] : start up Time (formatted)
[9] : execution time (duration formatted)
[10]: fullClassName (full class name; by class not by command)
[11]: name (short class name; not by command as [24])
[12]: title
[13]: author
[14]: copyright
[15]: versDate
[16]: nameWithVersDate
[17]: aboutText
[18]: purpose
[19]: usage
[20]: help text
[21]: user language set (two letter)
[22]: how handle output to existing files
[23]: getStateString() (multi-line status text)
[24]: ComVar.PROG_NAME full program/class; by command, not class
[25]: ComVar.PROG_SHORT (short program name; by command
[26]: ComVar.OS (operating system's name, like Windows 10)
[27]: ComVar.HOST_NAME host's name if can be determined
[28]: ComVar.ON_PI true when running on a Pi
[0..4]: reserved for user defined Object arrays to distinguish them by number from message components; returns null here overridden.
[27..]: null if this method and getMessageComponentsLength() are not overridden to tell otherwise.

Specified by:

getMessageComponent in interface TextHelper.MessageComponents

Parameters:

index - Range 0 .. getMessageComponentsLength() - 1

Returns:

the (actual) piece of information or null.

See Also:

AppLangMap.formMessageUL(CharSequence, String, Object)

twoLineStartMsg

public StringBuilder twoLineStartMsg()

Two line standard start report (nationalised).

returns e.g. for German, English, French:

  
   ///   AppLangMap V2.10 (15.12.2004, A. Weinert)
   ///   Start:  Mi, 15.12.2004, 17:14:44
 
   ///   AppLangMap V2.10 (15.12.2004, A. Weinert)
   ///   start:  We, Dec. 15 2004, 17:13:42
  
   ///   AppLangMap V2.10 (15.12.2004, A. Weinert)
   ///   d�marrage:  me, 15.12.2004, 17:14:20

The first line is obtained by getNameWithVersDate().

Returns:: the report
See Also:: AppLangMap, TextHelper.messageFormat(StringBuilder, CharSequence, Object), getMessageComponent(int)

twoLineEndMsg
```
public StringBuilder twoLineEndMsg()
```
Two line standard end report (nationalised).

See the resembling twoLineStartMsg().

Returns:

the report

See Also:

getMessageComponent(int)

threeLineEndMsg
```
public StringBuilder threeLineEndMsg()
```
Two line standard end report (nationalised).

See the resembling twoLineStartMsg() and twoLineEndMsg().
The difference to twoLineEndMsg() is an extra line reporting the execution time.

Returns:

the report

See Also:

getMessageComponent(int), getExecTimeMs(), getExecTimeString()

valueLang
```
public final String valueLang(CharSequence key,
                              String def)
```
Get a value for a key — regarding set user language.

This method tries (hard) to get an user language specific value for key taking language and region into account searching in this (App) object's prop (properties) and in AppLangMap.

If all fails or key is empty def is returned.

Parameters:

key - the key to get a value for

def - the default value if nothing can be found by key

Returns:

the key's or the default value

See Also:

Prop.valueLang(CharSequence), AppLangMap.valueUL(CharSequence)

valueLang
```
public final String valueLang(CharSequence key)
```
Get a value for a key — regarding set user language.

The call is equivalent to
valueLang(key, null).

Parameters:

key - the key to get a value for

Returns:

the key's value or null if nothing coud be found for key

See Also:

AppLangMap.valueUL(CharSequence), Prop.valueLang(CharSequence)

getLanguage
```
public final String getLanguage()
```
Get the short (2 character) notation of the user's language.

If prop is not (yet) null, prop.getLanguage() is returned.
Next choice is AppLangMap.getUMap().getLanguage(), if available. Otherwise ComVar.UL is returned.

Specified by:

getLanguage in interface AppMBean

Returns:

the language code (2 letter)

messageFormat
```
public StringBuilder messageFormat(StringBuilder bastel,
                                   CharSequence patternKey,
                                   String patternDefault,
                                   Object args)
```
A keyed message formatter.

This method is just an replacement for the otherwise (hopefully for internationalisation) often used sequence:
```
      String pattern = valueLang(patternKey, patternDefault);
      TextHelper.messageFormat(bastel, pattern, args);
```
Parameters:

bastel - StringBuilder on which to append to; if null it will be made with starting capacity of 81

patternKey - key for pattern (nationalised) to append to bastel

patternDefault - pattern to append to bastel

args - Array of arguments; may be of type Object[] or int[]; null oder empty means that pattern is to be appended to bastel without any interpretation (message formatting). If args is no array it is treated as an one elementary just for the spot {0} in the pattern. (This saves throw-away objects for very frequent cases).

Returns:

bastel (parameter or new, never null

See Also:

AppLangMap, valueLang(CharSequence, String), TextHelper.messageFormat(StringBuilder, CharSequence, Object)

getActTime
```
public final String getActTime()
```
The actual (system) time as text.

The actual platform time is updated to system clock and then formatted according to AppLangMap.valueUL("wedaclock").

In the case of user language German the format is "D, d.m.Y, H:i:s"; in the case of English it would be "w, M d Y, H:i:s". That would give "Do, 05.02.2009, 13:45:19" or "Th, Feb. 05 2009, 13:45:19" respectively.

Specified by:

getActTime in interface AppMBean

Returns:

the platform's time

See Also:

AppHelper.getActTime()

getArgs
```
public final String getArgs()
```
The start parameters.

Applications based on the Framework Frame4J will be inheritors of @link App} in most cases. They get their start parameters as String array by one of the methods App.go(). And go() is usually called in the applications void main(String[] args) forwarding just the start parameter array supplied by the JVM.

In the spirit of JVM's treaty with main(String[]) that array will never be null. But it may be the empty array ComVar.NO_STRINGS.

This method returns the originally supplied start parameters (see argsOrig) as one String containing the start parameters space separated (as from the shell's command line).

Specified by:

getArgs in interface AppMBean

Returns:

the application's start parameters

See Also:

TextHelper.prepParams(String[])

regAsStdMBean
```
public String regAsStdMBean()
                     throws JMException
```
Register this application as standard MBean.

Returns:

the registered object name

Throws:

JMException - if the registering fails

getVerbosity
```
public final Verbos getVerbosity()
```
Detailedness of reports or logging.

The levels are defined according to the table in AppHelper.Verbos.toString().

default: Verbos.NORMAL

Returns:

the current verbosity

See Also:

isSilent(), setVerbosity(int), setVerbosity(String), getVerbose()

getVerbose
```
public String getVerbose()
```
Detailedness of reports or logging.

The levels are defined according to the table in AppHelper.Verbos.toString().

Specified by:

getVerbose in interface AppMBean

Returns:

AppHelper.getVerbosityAsString(verbosity)

See Also:

getVerbosity()

setVerbosity
```
public void setVerbosity(int value)
```
Set the report detailedness of this application.

Hint: All other methods setting the report detailedness use this method. So (only) this method has to be overridden if modifications are necessary.

Parameters:

value - Level Verbos.DEBUG .. Verbos.SILENT; default: Verbos.NORMAL

See Also:

getVerbosity(), setVerbosity(String), Verbos.NORMAL, Verbos.toString(), Verbos.getVerbosityLevel()

setVerbosity
```
public final void setVerbosity(String verbosity)
```
Set the report detailedness of this application.

The parameter verbosity will be interpreted by the method AppHelper.Verbos.getVerbosity(String) and the result will be passed to setVerbosity(int).

Parameters:

verbosity - the verbosity level to be set

See Also:

getVerbosity(), setVerbosity(int)

setVerbose
```
public final void setVerbose(String verbosity)
```
Set the report detailedness of this application.

Parameters:

verbosity - the verbosity level to be set

See Also:

setVerbosity(verbosity)

setVerbose
```
public final void setVerbose(boolean verbose)
```
Set the report detailedness of this application.

Parameters:

verbose - the verbosity level to be set; true: verbose; false: normal

See Also:

verbose

isVerbose
```
public final boolean isVerbose()
```
Report detailedness of this application.

This method just returns verbose.

Returns:

the current verbosity level; true: above normal

See Also:

getVerbosity()

isSilent
```
public final boolean isSilent()
```
Almost no reports.

If true only reports on catastrophic events are to be generated.

Returns:

the current verbosity level; true: silent

See Also:

verbose, isNormal(), getVerbosity()

isNormal
```
public final boolean isNormal()
```
Just the normal reports.

If true the so called "normal" events shall be generated, those of every day relevance for the process done or controlled by this application.

Returns:

the current verbosity level; true: normal (or more)

See Also:

verbose, isSilent(), getVerbosity()

isTest
```
public final boolean isTest()
```
Many reports — for testing.

If true many events, also to a very fine granularity (normally of low relevance for the process done or controlled by this application), are generated.

Returns:

the current verbosity level; true: test events (or more)

See Also:

verbose, isSilent(), isNormal(), getVerbosity()

isDebug
```
public final boolean isDebug()
```
All reports — for test and debugging.

If true many events, also programme technical ones (normally of nil relevance for the process done or controlled by this application), are generated.

Returns:

the current verbosity level; true: debug (or more)

See Also:

verbose, isSilent(), isNormal(), getVerbosity()

queueAction
```
public final void queueAction(String command,
                              AWTEvent event)
```
React to an event by queueing an action.

This method is provided for graphical App inheritors mostly for being used in graphical event listeners indirectly via actionPerformed() etc.

It may be called directly as well.

If command and event are null or empty nothing happens.

If command is null, it will be tried to determine it directly as actionCommand or indirectly (via getSource() respectively getItemSelectable()) from event.

If that is not possible or if command is now still null or empty nothing is done.

Otherwise using the (given or determined) command and event performeAction(String, AWTEvent) will be called. This is done via a queue in a special thread. The actions of this class's performeAction(String, AWTEvent) and its extensions do not run in the thread that directly or indirectly called this method.

The queue implemented here independently from AWT or swing fulfils the recommendation or request not to handle longer actions in the event source's thread.

The queue's length is limited to 110 events. Overflow forgets the oldest event. This border is a hint which event handler execution time would require an extra thread.

Hint: If verbosity is <= Verbos.TEST e.g. equal to Verbos.DEBUG every action will be logged on log before calling performeAction(String, AWTEvent).

Parameters:

command - the command, if null it will be extracted from event

event - graphical event, may be null if command is not null

See Also:

performeAction(String, AWTEvent)

performeAction
```
public boolean performeAction(String command,
                              AWTEvent e)
```
The reaction to an action; implementation.

This method will be called indirectly via queueAction(String, AWTEvent). It may as well be called directly.

This implementation reacts to no command at all (as of January 2010). As long as runFlag is true and if verbosity is <= Verbos.DEBUG the command will be logged with the actual time.

In case of a possible reaction true is returned. true is also returned without any action performed if runFlag is false.

All other cases return false.

This signalling by boolean return value allows an overriding method to use this method purposefully: if (super.performeAction(command, e)) return true; // Implementing further actions / commands This behaviour should be kept over the whole inheritance chain.
Parameters:

command - the "action command"

e - if given an ActionEvent or an ItemEvent;
may be null or give supplementary information on the desired action

Returns:

true if no more actions are to be performed

actionPerformed
```
public void actionPerformed(ActionEvent e)
```
The reaction to an action; mostly by a menu.

This method will be called by the underlying graphical system as a reaction to the user's actions (menu or button events).

This implementation determines in the end the command from the ActionEvent e and calls if one was given performeAction(command, e).

Important detail: This implementation will put this call by using the method queueAction(String, AWTEvent) into a thread different from the one calling this method actionPerformed(ActionEvent).

Hint: It will usually be better for extending classes to override performeAction() instead of this method actionPerformed(ActionEvent). The extra gift is the decoupling thread working independently from swing, AWT or other event sources.

Hint 2: This method implements the interface ActionListener.

Hint 3: Touching Swing components by the method performeAction() have nevertheless to obey all Swing threading rules (usually by using invokeLater() for that purpose).

Specified by:

actionPerformed in interface ActionListener

Parameters:

e - the action to be queued

isHelp
```
public final boolean isHelp()
```
Do only (on line) help output; have no other effects.

If inheriting / implementing classes (objects) find this property set true (by start parameters option -? or -help or else) the normal work of the application shall never begin. Instead only the online help text (hopefully nationalised) shall be output.

Graphical applications may start the graphics so far as to output the help text graphically (text window) instead of using log.

Considering the start parameters none of them except -? or -help itself shall have any effect. The first exception from that rule are those switching the user language. i.e. -en, -de, -fr etc. The second exception may be those that branch the log output to a file. The methods go(..) would normally have done all this before the overridden doIt() must decide to do just help output plus nothing.

This property shall be evaluated on application's startup (in the sense of entering doIt()) only. Setting it to true later must have no effect.

default: false

Returns:

true if a help output (-help -?) is requested

setHelp
```
public final void setHelp(boolean help)
```
Do only (on line) help output; have no other effects.

Parameters:

help - true if a help output (-help -?) is requested

See Also:

isHelp()

getOutMode
```
public final OutMode getOutMode()
```
Output mode for log and out files.

default: Ask

Returns:

the mode for logging and else output

See Also:

setOutMode(CharSequence), setOutMode(OutMode)

setOutMode
```
public final void setOutMode(OutMode outMode)
```
Set output mode for log, out and may be other files.

Parameters:

outMode - null: no change

See Also:

getOutMode()

setOutMode
```
public final void setOutMode(CharSequence outMode)
```
Set output mode for log, out and may be other files.

Parameters:

outMode - null, empty, no fit : no change

See Also:

getOutMode(), OutMode.of(CharSequence, OutMode)

isRunFlag
```
public final boolean isRunFlag()
```
Flag to stop all threads of this application.

This flag will be set false before or on ending this application. If false it is a signal to all the application's threads to end their work gracefully but without any undue delay. The usual coding will be while(runFlag) or while(isRunFlag()). This also the correct substitute for the depreciated Thread.stop().

Using the flag is application / extension programmer's responsibility. To set it to false use stop().

Start value: true

This method returns the AND of the runFlag (reset by stop()) and the common runFlag's, i.e. AppBase.commonRun. If only the latter is false, this method will call stop().

Returns:

true if the application may run on

See Also:

AppBase.isCommonRun()

stop
```
public void stop()
```
Stop the application.

This method shall gracefully end this application. It will set the runFlag to false if it is not yet so.

If runFlag is false, this method does nothing.

Otherwise the runFlag is set false. The enforced output buffering (optionally set for graphical inheritors) of log and out is switched off. The application's main thread is interrupted by Thread.interrupt() (if it still exists and if this method is not called by it).

It is the responsibility of the application (i.e. its waked up main thread and all its other threads to end in an ordered fashion. This proceeding to end (by App's contract) in calling normalExit() or errorExit().

It can be said that this method stop() is the signal to end and the methods xyzExit() are the end itself. The latter may be called without former stop signal.

Is this application the "mother application" of a whole bundle of applications AppBase.commonRun will be set false also as a stop signal to all others.

Specified by:

stop in interface AppMBean

See Also:

stop()

wakeMainThread
```
public final boolean wakeMainThread()
```
Wake up the main thread.

This method supports applications that want to do triggered tasks in their main thread (mainThread, that is doIt()). This thread will be woken up robustly and reliably. Success will be signalled by returning true.

Missing preconditions or (non probable) wake up exceptions will be signalled by returning false.

Implementation hint: If this application shall run and if the mainThread still exists and if the caller itself is not the main thread will be interrupted.

Returns:

true if the main thread was woken up

See Also:

AppHelper.sleep(long), AppHelper.getTimer(), AppHelper.scheduleAbsolute(TimerTask, long, long), AppHelper.scheduleAtFixedRate(TimerTask, long, long)

isHelpLog
```
protected boolean isHelpLog()
```
The condition of (just) outputting the on-line help.

This method returns (among others for condHelpLog() the condition that an on-line help output to log shall be the only work or effect of this application's actual execution.

This implementation just returns help. This is the standard condition.

An inheritor may override this method to modify this condition, may be to output the online help on missing or wrong parameters also, e.g. by doing return help || extraCondition(); // like args.length == 0
Returns:

help

See Also:

isHelp(), condHelpLog()

condHelpLog
```
protected final boolean condHelpLog()
```
Conditional output of on-line help to log, and then stop.

If the method isHelpLog() returns true, this method does the following:
```
     log.println(helpText));
     stop();
```
This outputs the (nationalised) help text and ends this application.

If isHelpLog() returns false this method does nothing.
Returns:

isHelpLog()

See Also:

isHelp(), go(..)

clientOrder

public String clientOrder(String command)
                   throws AttributeNotFoundException

A client's command to this application.

This method will be called if a (may be remote, may be JMX, JConsole or alike) client has an order (agreed upon). The parameter command must contain all necessary denotations, like command, parameter, credentials and so on. command must not be empty.

The text returned shall be a report on the execution of the order given. It shall be human readable. If the order has to be refused, this may as well or better be done by an IllegalArgumentException with a expressive message.

For the sake of uniformity every App inheritor, whose object are usable as MBeans, shall implement the parameterless commands "help" and "status".
"help" shall provide a survey on all (public) orders (clientOrders) and "status" shall give information on the applications current execution state.

This implementation realises this minimal standard with "help" and "status" as well as some command not published by "help" for sake or inheriting classes:

Command	Parameter	Effect / text returned
help, ?	none	shows help and status as the command list.
status	none	shows the execution state like returned by `getStateString()`.
appHelp	none	shows the help text as by `helpText`.
about	none	shows a describing text as by `getAboutText()`.
log	none	returns the (last 10000 characters) of the log output.
out	none	returns the (last 10000 characters) of the output to out.
prop	none	returns all properties (`Prop` `prop`) as Text.
stop	none	ends this application by calling `stop()`).
others	others	throw an IllegalArgumentException aus.

Hint 1: An extending class may, of course, use this comprehensive implementation as is. Normally it will override it, and be it only to add the commands already implemented here to the help list; see above. The overriding method will use this implementation by super.clientOrder(command) after doing additional command or blocking unwanted ones.

Parameters:: command - the order (containing all parameters and else)
Returns:: success report or information requested
Throws:: AttributeNotFoundException - if the order is not implemented or if the parameters are wrong; see table

getStateString
```
public String getStateString()
```
The running state as text.

This method returns an informing text about the actual execution state of this application. This method may be overridden accordingly in extending classes.

This implementation returns the concatenation of makeStatusTextStart(.) and makeStatusTextEnd(.).

Returns:

the application's state

makeStatusTextStart
```
public StringBuilder makeStatusTextStart(StringBuilder bastel)
```
Append the standard start to a status text.

Appended to the StringBuilder bastel will be the full class name, runFlag's state as "active" or "ending", the state of verbosity as text like by getVerbose(). No line feed follows.

Parameters:

bastel - the StringBuilder to append to; if null it is made

Returns:

bastel (i.e. the StringBuilder for further use)

makeStatusTextEnd
```
public StringBuilder makeStatusTextEnd(StringBuilder bastel)
```
Append the standard end to a status text.

Appended to the StringBuilder bastel will be a line feed and the six lines lines with informations on window title, start arguments, open mode for log files, start time, execution time so far and system time.

Parameters:

bastel - the StringBuilder to append to; if null it is made

Returns:

bastel

getTitle
```
public final String getTitle()
```
The preferred title for Frames or Dialogues (if used).

If not set (by application's .properties as normal case) it will default to the application's simple (w/o package) class name.

Specified by:

getTitle in interface UIInfo

Returns:

the (window) title

See Also:

setTitle(String)

setTitle
```
public void setTitle(String title)
```
The preferred title for Frames or Dialogues (if used).

Parameters:

title - the (window) title

See Also:

getTitle()

getMyFrame
```
public Window getMyFrame()
```
The applications main / base graphical window, if any.

If the inheritor is a graphical application it will have a main window. This will usually be of type [J]Dialog, [J]Frame or [J]Window.

This implementation returns null. That can and probably will be changed by (graphical) inheritors.

Returns:

the basic frame

getTheCloser
```
public WindowListener getTheCloser(Window frame)
```
A simple stop all when Window closes.

This method produces and registers a Listener which regularly shuts down this App when the given frame closes.
If myFrame is null it will be set by the parameter frame.

Parameters:

frame - The window the listener is to be made for; if null myFrame is used. If still null nothing is done.

Returns:

the Listener made or null if frame is null

getIcon
```
public Image getIcon()
```
The application's icon, if any.

Returns:

the application's icon

See Also:

haveIcon()

haveIcon
```
public Image haveIcon()
```
Get the application's icon.

If an icon was already set it is returned. Otherwise the weinert-automation's logo will be set and returned.

Returns:

the application's icon (already set or now made)

See Also:

getIcon()

setBgColor
```
public void setBgColor(CharSequence bgColor)
```
Preferred background colour for graphical elements (if used).

The parameter bgColor will be stripped from surrounding white space and must (then) be interpretable as colour name or number according to the method's ColorHelper.getColor(CharSequence) rules.

Null or (stripped) empty defaults to the previous value, initially "white" (0xFFFFFF).

Setting to an uninterpretable character sequence will / should have the consequence of using the background colour of graphical parent containers.

default: "white"

Parameters:

bgColor - the new background colour

toString
```
public String toString()
```
As String.

This implementation returns
"de.frame4j.util.App <-- fullClassName".

Overrides:

toString in class Object

allowNoPropertiesFile
```
protected boolean allowNoPropertiesFile()
```
Decide, if the basic .properties file may be omitted.

Starting an application inheriting from App with a go method constructs the App's Prop object. In this process .properties files of appropriate name (appName.properties) are searched as file or as resource (in the .jar).

It is a basic (compile time) property of the application class, if or if not one such .properties file must be found. If true and neither such file nor resource can be found and read, this would be an initialisation error, detaining the application from being started.

At all places (in this class) the decision if no such file found is an initialisation error, is done by calling this method. It can (or must) be overridden in extending classes accordingly.

This implementation returns
- false (basic .properties mandatory) in "normal" cases and
- true (basic .properties not required) if the inheritor is an anonymous extension of App.
The start up procedure (usually by one of the methods go()) constructs a Prop object for the application using a constructor like Prop(App, CharSequence). Hereby a basic property file named shortClassName.properties is searched for as file or resource at different places. Finding it nowhere gets a FileNotFoundException going up to the starter method. The reason for that stringency is, that App-Extensions and their .properties file are considered as a unit. If not this is considered as the special case "allowNoPropertiesFile".

Without that file one only has the common default properties for all Apps (seeProp()).

Hint: If there is a inheritance hierarchy of App only the last ones base .properties file is searched for.
Returns:

false: normal App class, true: inner class

extraPropertiesFile
```
protected String extraPropertiesFile()
```
Decide, if and which extra .properties has to be loaded.

If this method returns a non empty String it is taken as the name of an extra .properties file to be loaded before class related ones.

Returns:

null

getProp
```
public Prop getProp()
```
The Prop(erties) object.

It will be made on initialisation by the methods go(..), loaded and partly evaluated.

Returns:

the properties

parsePartial
```
public boolean parsePartial()
```
Partial evaluation of start parameters by Prop.

This method has to return true if the Prop object shall evaluate and check the start parameters (see args) only partially. For the meaning of "partial evaluation" please see Prop#parse(String[],CharSequence,boolean) Prop.parse(String[], CharSequence, boolean).

As the partial evaluation of start arguments by Prop is a fixed property of an application classes extending App must override this method finally this methods default behaviour is not wanted.

Returns:

false except when made by the make'n go constructor App(String[])

getLogHandler
```
public final LogWriterHandler getLogHandler()
```
The Logger's handler.

This method returns a Handler connected to log. It will be made on the first call. This method just delegates to appIO.getLogHandler().)

Returns:

the handler

getAppLogger
```
public final Logger getAppLogger()
```
The application's base Logger.

This method fetches this application's base logger.
The effect is almost identical to appIO.getAppLogger(). If the Logger is newly generated its Level will be set according to getVerbosity().

Returns:

the logger

See Also:

Verbos.getVerbosityLevel(), setVerbosity(int)

getDbLogger
```
protected Logger getDbLogger()
```

logVerbose
```
public final void logVerbose(String sourceClass,
                             String sourceMethod,
                             String msg,
                             Object[] params)
```
Log also into a DB (data base).

The message consisting of the parameters will be generated and logged using the Level.FINE that is equivalent to Verbos.VERBOSE. If a separate dbLogger was made with the logging will be into the database.

Parameters:

sourceClass - source of log message

sourceMethod - source of log message

msg - log message

params - further parameters for log message

logVerbose
```
public final void logVerbose(String sourceClass,
                             String sourceMethod,
                             String msg)
```
Log also into a DB (data base).

Like logVerbose(String, String, String, Object[]), but without parameter array.

Parameters:

sourceClass - source of log message

sourceMethod - source of log message

msg - log message

setCodePages
```
public void setCodePages(String codePage)
```
Setting the code pages for the Reader in and the Writers out and err.

This method calls appIO.setCodePages() if and only if this application is the (one) base / mother application. That is the one which made the singleton AppBase object.

Otherwise nothing happens at all.

Parameters:

codePage - the new encoding for all text I/O streams

setLogOut2
```
public void setLogOut2(OutputStream os2,
                       String cp2)
```
Set log's second Writer as Stream.

The call is equivalent to:
appIO.setLogOut2(os2, cp2)

Parameters:

os2 - the new second (Tee) writer

cp2 - its encoding

connect
```
protected int connect(OutMode outMode,
                      Prop prop)
```
Connect the TeeWriter's outputs for log and out.

If this application is not the mother application nothing happens (except return -1).

Otherwise it will be tried to connect in AppIO object appIO in each case an output of the TeeWriters log and out to the files specified by the properties logDat respectively outDat. The mode (append, create, overwrite, ask) will be determined by the parameter outMode.

If one of the connections fails (due to rejection or file problems e.g.) 1 is returned (logDat) or 2 (outDat). If both succeed 0 is returned.

If asking for a file is necessary and the asking shall be done graphically the parameter prop will be used to determine the asking windows properties (see de.frame4j.io.FileVisitor.AskGrafImpl).

Parameters:

outMode - the mode for opening an output stream

prop - the properties to get all information from

Returns:

0: OK; 1,2: connection failed

See Also:

ComVar.INIT_ERROR, ComVar.LOG_OUT_ERROR

go
```
protected final int go(String[] args,
                       String codePage,
                       CharSequence commBeg)
                throws FileNotFoundException,
                       IllegalArgumentException
```
Comfortable start of the application.

This is a comfortable and universal starting method for an Application featuring evaluation of start arguments .properties files and (inter) nationalising.

This method also sets the code pages of in, out and err if this application is the base ("mother") application.

After all initialisations the (overridden) method doIt() will be called.

The call is slightly equivalent to:setCodePages(codePage); prop = new Prop(this, commBeg, partial); go(args, 1, 0);

ComVar.NO_PARS_ERROR or ComVar.INIT_ERROR is returned on initialisation problems (without calling doIt()).
Otherwise doIt()'s return value is returned.

Parameters:

args - start arguments passed on (not null)

codePage - the encoding for in, out and err (or null)

commBeg - the start pattern of a start argument's comment; the comment would be the end of the start arguments

Returns:

ComVar.NO_PARS_ERROR: Start problem,
0: OK (or any other return from doIt())

Throws:

IllegalArgumentException - on parameter evaluating errors

FileNotFoundException - base .properties file is missing

See Also:

go(String[], String)

go
```
protected final int go(String[] args)
                throws FileNotFoundException,
                       IllegalArgumentException
```
Comfortably start the application.

This method is equivalent to go(args, null, partial, null) except for those extras:

Before calling doIt() the equivalent of the following will be done| if (connect(outMode, prop) > 0) | return minDoc.errMeld(ComVar.LOG_OUT_ERROR, valueLang("logouterr")); | | if (help) { | minDoc.list(log); | return 0; | } // -help oder -? That would be the standard start of most non graphical applications and can hence be omitted using this go().

Hint: If help is true or isHelpLog() returns true, the method doIt() is not called; 0 (ComVar.JOB_DONE_OK) is returned as exit code.
Parameters:

args - the start arguments passed on

Returns:

ComVar.NO_PARS_ERROR: Start problem,
0: OK (or any other return from doIt())

Throws:

FileNotFoundException - forwarded from go(String[], String, CharSequence)

IllegalArgumentException

See Also:

go(String[], String, CharSequence), condHelpLog()

go
```
protected final int go(String[] args,
                       String codePage)
                throws FileNotFoundException,
                       IllegalArgumentException
```
Comfortable start of the application.

This is the most comfortable starting method for an Application featuring evaluation of start arguments .properties files and (inter) nationalising.

This method also sets the code pages of in, out and err if this application is the base ("mother") application.

After all initialisations the (overridden) method doIt() will be called.

The call is slightly equivalent to:setCodePages(codePage); prop = new Prop(this, commBeg, partial); go(args, 1, 0);

ComVar.NO_PARS_ERROR or ComVar.INIT_ERROR is returned on initialisation problems (without calling doIt()).
Otherwise doIt()'s return value is returned.

Parameters:

args - start arguments passed on (not null)

codePage - the encoding for in, out and err (or null)

Returns:

ComVar.NO_PARS_ERROR: Start problem,
0: OK (or any other return from doIt())

Throws:

IllegalArgumentException - on parameter evaluating errors

FileNotFoundException - base .properties file is missing

See Also:

go(String[])

repExc
```
public final void repExc(Appendable out,
                         Throwable exc,
                         boolean trace)
```
Report an exception.

Parameters:

out - the output for the report

exc - the exception to report on

trace - true: print also a stack trace (and only if out is a PrintWriter or a PrrintStream)

formMessage
```
public final String formMessage(String key,
                                Object param)
```
Make an (inter) nationalised message..

By using prop.valueLang(key, null) a user language dependent pattern is determined for key. If the pattern cannot be determined the empty String ComVar.EMPTY_STRING is returned.

If param is the pattern (itself) is returned. (Therefore the calling valueLang() would have been sufficient.)

Using the determined pattern and the parameter param the method messageFormat(null, pattern, param) is used to form a message that will be returned as String.

Parameters:

key - language independent key for a language dependent pattern

param - the parameter(s) to be parts of the (nationalised) message to be formed

Returns:

the (inter) nationalised message as String

formMessage
```
public final String formMessage(String key)
```
Make an (inter) nationalised message.

See formMessage(String, Object); this is the "auto boxing" variant for the frequent case of just one (index [0]) integer message parameter.

Parameters:

key - language independent key for a language dependent pattern

Returns:

the (inter) nationalised message as String

formMessage
```
public final String formMessage(String key,
                                int parInt)
```
Make an (inter) nationalised message.

See getMessageComponent(int); this is the "self contained" variant using this App's message components[5..23].

Parameters:

key - language independent key for a language dependent pattern

parInt - the one integer parameter to be parts of the (nationalised) message to be formed

Returns:

the (inter) nationalised message as String

doIt
```
protected abstract int doIt()
```
This application's working method.

This method (abstract in App) must be implemented by an inheritor.

The application's intrinsic or core task are done here after having inherited all initialisation by App's constructors and go() methods in a simple main(String[]) just doing new MyApp().go(args, false), for example.

Returns:

the exit code; 0 means OK

See Also:

Prop, go(String[]), go(String[], String, CharSequence), mainThread

normalExit
```
public int normalExit(int returnCode)
```
Normal exit.

The call is equivalent to
appBase.normalExit(this, returnCode).

Parameters:

returnCode - return/exit value; > 0 (on Win/DOS) : error number

Returns:

returnCode

See Also:

ComVar.JOB_DONE_OK, ComVar.NO_PARS_ERROR, ComVar.LOG_OUT_ERROR, ComVar.INIT_ERROR

errorExit
```
public int errorExit(int errNum,
                     String errText)
```
Error exit.

The call is equivalent to
appBase.errorExit(this, returnCode, errText).

Parameters:

errNum - > 0 : error number

errText - additional error text

Returns:

errNum for comfortable use in doIt()'s return

See Also:

ComVar.JOB_DONE_OK, ComVar.NO_PARS_ERROR, ComVar.LOG_OUT_ERROR, ComVar.INIT_ERROR

errorExit
```
public int errorExit(int errNum,
                     Exception ex,
                     String errText)
```
Error exit with exception.

If the verbosity level (verbosity) is > Verbos.VERBOSE the stack trace of ex will be output to log; otherwise only ex's message is used.

The call ends by
appBase.errorExit(this, returnCode, null).

Parameters:

errNum - >0 : error number

ex - the exception that made any further work senseless

errText - additional error text; may usually be null as ex's message will be logged

Returns:

errNum for comfortable use in doIt()'s return

See Also:

ComVar.NO_PARS_ERROR, ComVar.LOG_OUT_ERROR, ComVar.INIT_ERROR

getExecTimeString
```
public final String getExecTimeString()
```
The application's execution time (milliseconds) so far as text.

Returns:

time since the application's start formatted as 9788ms, 3599s, 1h00min or 1d00h00min

See Also:

getExecTimeMs(), AppBase.setActTime(), TextHelper.formatDuration(StringBuilder, long)

getExecTimeMs
```
public final long getExecTimeMs()
```
The application's execution time (milliseconds) so far.

Returns:

Elapsed (not CPU) time in milliseconds since startup;

See Also:

getExecTimeString(), AppBase.setActTime()

getExecTimeMsL
```
public final Long getExecTimeMsL()
```
The application's execution time (milliseconds) so far.

Specified by:

getExecTimeMsL in interface AppMBean

Returns:

Elapsed (not CPU) time in (Long) milliseconds since startup;

See Also:

getExecTimeMs(), AppBase.setActTime()

getAbout
```
public final String getAbout()
```
A (short) description of this application (about text).

Specified by:

getAbout in interface UIInfo

Returns:

the short about text

getHelp
```
public String getHelp()
```
A text to guide the user of this App based application (help-Text).

This method generates and returns a (nationalised, multi line) text composed from name, version and copyright information plus
- the property "helpText" or if not available
- the MinDoc's annotation "usage" supplemented by App's common options info.
Specified by:

getHelp in interface UIInfo

Returns:

the help text

setVersDate
```
public void setVersDate(String versDate)
```
Set version with date and optional author / last modifier.

This method sets the field versDate, it it was not yet set and if the parameter is not empty even after stripping surrounding white space.

Parameters:

versDate - version and date of this App inheritors class (taken without surrounding white spaces)

See Also:

getVersDate()

getVersDate
```
public String getVersDate()
```
Description copied from interface: AppMBean

The program's version and revision date.

Specified by:

getVersDate in interface AppMBean

Specified by:

getVersDate in interface UIInfo

Returns:

the application's version and revision date

getName
```
public String getName()
```
Description copied from interface: AppMBean

The program's name.

Specified by:

getName in interface AppMBean

Specified by:

getName in interface UIInfo

Returns:

the application's short name

setName
```
public void setName(String name)
```
Set the (short) name.

Parameters:

name - the application's short name

getNameWithVersDate
```
public String getNameWithVersDate()
```
The application's name, version and last modification date.

Returns:

the applications name, version and revision date

getAuthor
```
public String getAuthor()
```
The author.

See description in UIInfo.
This method returns the name(s) explicitly set or tries to set and get a default by setAuthor(null).

Noting set is returned as ComVar.EMPTY_STRING.

default: ComVar.AUTHOR

Specified by:

getAuthor in interface UIInfo

Returns:

the name of the source code author

setAuthor
```
public void setAuthor(String author)
```
Set the author(s).

See description in UIInfo.

The parameter, stripped from surrounding white space, is taken as author(s) of the application.
null does nothing if already set. Otherwise a default value is determined from MinDoc-annotation or as ComVar.AUTHOR.

Parameters:

author - null and already set: do nothing;
null and not set: get default; else: set as author.

getCopyright
```
public String getCopyright()
```
The copyright notice.

This method provides this application's copyright note in the usual format
Copyright 1999 - 2002, Albrecht Weinert

default: ComVar.COPYRIGHT

Specified by:

getCopyright in interface AppMBean

Specified by:

getCopyright in interface UIInfo

Returns:

the application's copyright text

See Also:

getAbout(), getAuthor()

setCopyright
```
public void setCopyright(CharSequence copyright)
```
Set the copyright notice.

This method sets this application's copyright note copyright, only if not yet set and if the parameter, stripped from surrounding white spaces, is not empty.

Parameters:

copyright - The note to be set

See Also:

getCopyright(), getAbout(), getAuthor()

getPurpose
```
public String getPurpose()
```
The purpose of this application.

This is a short (not longer than eight lines) description of this class / application. It is the essential part of an "about text".

In this text's original setting a sequence {11} gets replaced by the (name) (see getMessageComponent(int)).

Example:
"The application {11} copies a file or an URL into a file "

Specified by:

getPurpose in interface AppMBean

Returns:

the short application's purpose text

See Also:

getPurpose()

setPurpose
```
public void setPurpose(CharSequence purpose)
```
Set the purpose of this application.

This method is to set a short purpose text for this class / application.

If the parameter is null, the text to set is taken from the MinDoc's purpose field. If no such annotation ano is set (nearly impossible) or its purpose field is empty "de.frame4j.util.App <-- {11}" is set instead.

Parameters:

purpose - null: no effect if set or set to annotation (default)

See Also:

getPurpose(), getMessageComponent(int)

getAboutText
```
public String getAboutText()
```
A (short) description of this application (about text).

Returns:

the short about text

setAboutText
```
public void setAboutText(CharSequence aboutText)
```
Set the (short) description of this application (about text).

This method is to set a short introductory text for this class / application.
If the parameter is null and the about text was not set yet the text will be composed of (as default setting) getNameWithVersDate(), getCopyright() and getPurpose().

Parameters:

aboutText - null: no effect if set or set default.

See Also:

getAbout(), getMessageComponent(int)

setAttribute
```
public final int setAttribute(String name,
                              Object value)
```
AttrSettable implementation.

This method does the the settings of the properties: verbose/verbosity, outMode, title, author, aboutText, bgColor, codePages, copyright, name, usage and versDate (mostly) by delegating to the appropriate setter (with one parameter).

One effect of this method is the saving of introspection expenses at startup. Inheritors may override the method setAttribute(String, char, Object, Class, boolean, boolean) to implement similar savings if adding many settable properties. It is called here if none of the property settings implemented here is affected.

The intensive checking and forwarding of essential results makes the implementation / overriding of setAttribute(String, char, Object, Class, boolean, boolean) quite simple. Nevertheless, overriding this method setAttribute(String, Object) is also feasible. In any case the overriding method must delegate back to the overridden one if it could not handle a non null name.

Specified by:

setAttribute in interface AttrSettable

Parameters:

name - the property's / attributes name; if null, empty or not lower case (Java name convention) AttrSettable.NO_ATTRIBUTE is returned and nothing is done

value - the value to set as Object; the type CharSequence should always be accepted

Returns:

status / result of the setting

setAttribute
```
protected int setAttribute(String name,
                           char name0,
                           Object value,
                           Class<?> vClass,
                           boolean isNull,
                           boolean isStringVal)
```
Overridable implementation of setAtttibute(String, Object).

This method will be called by App.setAttribute(name, value) for all name value pairs not clearly handled or rejected by said App's method. In this call all parameters are correct and the parameter value is converted to String if it was (only) of type CharSequence.

Hint: The gain (for the prize of 6 parameters) is that all preliminaries, and checks otherwise necessary (if directly overriding setAttribute(String, Object)) are superfluous here.
Hint2: Not overriding either would have no effect except for start-up performance. App and PropMap would do the same job using introspection.

Parameters:

name - name of the property (never empty)

name0 - first character of name (>= a)

value - the (new) value of the property

vClass - the (original) class of value (or null if isNull)

isNull - true if value is null

isStringVal - true if value is of type String

Returns:

AttrSettable.NO_KNOWN_ATTRIBUTE

See Also:

AttrSettable, AttrSettable.ILLEGAL_TYPE, AttrSettable.ILLEGAL_VALUE, AttrSettable.NO_VALUE, AttrSettable.OK

getUsage
```
public String getUsage()
```
The usage (quick help).

This is a short textual guidance to use this class / application. It may be used in the sense of a online help. There's no limit to the number of lines, bat more than 50 usually should go to a separate multi-page manual.

In this text's original setting a sequence {11} gets replaced by the (name) (see getMessageComponent(int)).

Example:
"Start by java {11} [file | URL [file]]"

Specified by:

getUsage in interface UIInfo

Returns:

a short hint text on the application's usage

See Also:

getHelpText()

setUsage
```
public void setUsage(CharSequence usage)
```
Set the usage (quick help).

The short textual guidance (see getUsage()) will be set.
If the parameter is null and the text was not set yet it will be taken from the MinDoc's pusage field. If no such annotation ano is set (nearly impossible) or its usage field is empty "java {10} -help" is set instead.

Parameters:

usage - null: no effect if set or set default.

See Also:

getUsage(), getMessageComponent(int)

getHelpText
```
public String getHelpText()
```
A text to guide the user of this App based application (help-Text).

This method generates and returns a (nationalised, multi line) text composed from name, version and copyright information plus
- the property "helpText" or if not available
- the MinDoc's annotation "usage" supplemented by App's common options info.
Returns:

the help text

errorText
```
public String errorText(int errNum,
                        Object suplText)
```
Generate a multi line error report.

A String is generated and returned consisting of those parts:
- an empty line
- nameWithVersDate
  Error
  errnum, if > 0
- suplText
If the extra text suplText is a character sequence, format elements like {11} e.g. are replaced is replaced accordingly.
Parameters:

errNum - the error number, if > 0

suplText - an extra text (String, StringBuilder, CharSequence respectively Exception or Throwable)

Returns:

the error report text

See Also:

TextHelper.messageFormat(StringBuilder, CharSequence, Object), getMessageComponent(int)

errMeld
```
public final int errMeld(int errNum,
                         Object suplText)
```
Output a (multi line) error report.

On log an error text, produced according to errorText(errNum, suplText), is output.

Is the parameter suplText an Exception and the level of verbosity <= Verbos.TEST, the exception's call stack is output, too.
Parameters: errNum - the error number, if > 0 suplText - additional text, describing the error may be String, StringBuilder, CharSequence or Exception) Returns: errNum (the error number)







errMeld
public int errMeld(PrintStream out,
                   int errNum,
                   Object suplText)
Output a (multi line) error report. 

  

  On out an error text, produced according to
  errorText(errNum, suplText), is 
  output.

  

  Is the parameter suplText an Exception and the 
  level of  verbosity <= Verbos.TEST,
  the exception's call stack is output, too.

  


Parameters:
errNum - the error number, if > 0
suplText - additional text, describing the error
    
                  may be String, StringBuilder, CharSequence or Exception)
out - the Stream to output to
Returns:
errNum (the error number)
See Also:
condHelpLog()

Class App

Nested Class Summary

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

Field Summary

Fields inherited from interface de.frame4j.util.ComVar

Fields inherited from interface de.frame4j.net.AttrSettable

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface de.frame4j.net.AttrSettable

Field Detail

appStartTime

appStartTimeMS

args

argsOrig

verbosity

verbose

help

outMode

runFlag

title

myFrame

icon

bgColor

myClass

fullClassName

shortClassName

packName

ano

prop

mainThread

appBase

appIO

out

err

log

retCode

name

Constructor Detail

App

App

App

Method Detail

getAppStartTime

getStartTime

getMessageComponentsLength

getMessageComponent

twoLineStartMsg

twoLineEndMsg

threeLineEndMsg

valueLang

valueLang

getLanguage

messageFormat

getActTime

getArgs

regAsStdMBean

getVerbosity

getVerbose

setVerbosity

setVerbosity

setVerbose

setVerbose

isVerbose

isSilent

isNormal

isTest

isDebug

queueAction

performeAction

actionPerformed

isHelp

setHelp

getOutMode

setOutMode

setOutMode

isRunFlag

stop

wakeMainThread

isHelpLog