@MinDoc(copyright="Copyright 1997 - 2016, 2021 A. Weinert", author="Albrecht Weinert", version="V.51", lastModified="7.06.2021", 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
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.App
and the framework
Frame4J
implementing comfortable Java applications is simplified. Ever recurring
tasks are solved, as among othersout
) for normal output,err
) for error messageslog
) with optional branching to
normal output and a file,logger
connected
to log
,AppIO.in
) for normal input,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.App
's go(...)
methods:new MyAppInheritor().go(args, ...)
;allowNoPropertiesFile()
with return true.doIt()
to do the
real work of your application:public int doIt()
{log.prinln("Hi, I'm a sloth-bear."); return 0;
}java MyAppInheritor -?
and enjoy your help
text.go(...)
and the entry
into doIt()
all the initialising, command line parsing work is
done and lot more — quite invisibly in the background.AppIO
,
Prop
,
go(String[], String, CharSequence)
ComVar.Impl
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.
|
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
ILLEGAL_TYPE, ILLEGAL_VALUE, NO_ATTRIBUTE, NO_KNOWN_ATTRIBUTE, NO_VALUE, OK, retVtext
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.
|
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.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
retVtext
public final Instant appStartTime
getAppStartTime()
public final long appStartTimeMS
protected String[] args
go(...)
called within void main(String[] args)
.ComVar
.NO_STRINGS
protected String[] argsOrig
go(...)
called within void main(String[] args)
.ComVar
.NO_STRINGS
protected Verbos verbosity
getVerbosity()
protected boolean verbose
verbosity
.verbose
and is (to be) kept
so whenever verbosity
changes.verbose
,
setVerbose(boolean)
,
setVerbosity(String)
,
setVerbosity(int)
protected boolean help
isHelp()
protected OutMode outMode
getOutMode()
protected volatile boolean runFlag
runFlag
. One legal way to to set it false is
the method stop()
.isRunFlag()
,
stop()
protected String title
getTitle()
protected Window myFrame
getMyFrame()
as
it returns myFrame
. protected Image icon
public String bgColor
public final String fullClassName
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.public final String shortClassName
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.public final String packName
App()
).
It is this class' package part with trailing dot or empty.public final MinDoc ano
protected volatile Thread mainThread
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.doIt()
immediately
before returning will be interpreted as signal to "carry on"
even after ending doIt()
and hence its thread:mainThread
= null; // carry onprotected final AppBase appBase
protected final AppIO appIO
AppIO
object appIO
features robust and comfortable
I/O.PrintWriter
appIO.out outputs to normal out (System.out) and
optionally to a file.PrintWriter
appIO.log outputs to appIO.out and optionally to the
file appIO.logDat.PrintWriter
appIO.err and the BufferedReader
appIO.in are of less interest for graphical applications.AppIO
object by the use of two
TeeWriter
s; details see
there
.public final PrintWriter out
out
goes by default to normal out (System.out) and
optionally to a file.appIO
.out.)public final PrintWriter err
public final PrintWriter log
protected int retCode
ComVar.NO_PARS_ERROR
(Start and evaluation problems)protected String name
public App()
App(-1, -1)
) does all basic initialisations
for the made (this) App
object: AppBase
object by
AppBase.getAppBase(this),AppIO
object by
AppBase.getAppEA(this, -1, -1, null) fetching from thereargs
) are
done afterwards by using one of the starter methods go(....).AppBase.getAppBase()
,
App(int, int)
public App(int outBuffLen, int logBuffLen)
App()
calling
App(-1, -1)
.public App(String[] args)
App
and
may well be used in anonymous embedded classes. The simple idiom to make
any class (not itself extending App} an "App
lication"
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(....).App
.args
- start parameters for the applicationAppBase.getAppBase()
,
App(int, int)
public final Instant getAppStartTime()
appStartTime
public String getStartTime()
appStartTime
formatted according to
AppLangMap
.valueUL("wedaclock")
.appStartTime
being
final. Afterwards a stored String is returned (singleton).getStartTime
in interface AppMBean
getStartTime()
public int getMessageComponentsLength()
getMessageComponentsLength
in interface TextHelper.MessageComponents
getMessageComponent(int)
public Object getMessageComponent(int index)
actual Time
(formatted)start up Time
start up Time
(formatted)execution time
(duration formatted)fullClassName
(full class name; by class not by command)name
(short class name; not by command as [24])title
author
copyright
versDate
nameWithVersDate
aboutText
purpose
usage
help text
user language set
(two letter)how handle
output to existing filesgetStateString()
(multi-line status text)ComVar.PROG_NAME
full program/class; by command, not classComVar.PROG_SHORT
(short program name; by commandComVar.OS
(operating system's name, like Windows 10)ComVar.HOST_NAME
host's name if can be determinedComVar.ON_PI
true when running on a PigetMessageComponentsLength()
are not overridden to tell otherwise.getMessageComponent
in interface TextHelper.MessageComponents
index
- Range 0 .. getMessageComponentsLength()
- 1AppLangMap.formMessageUL(CharSequence, String, Object)
public StringBuilder twoLineStartMsg()
/// 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()
.AppLangMap
,
TextHelper.messageFormat(StringBuilder, CharSequence, Object)
,
getMessageComponent(int)
public StringBuilder twoLineEndMsg()
getMessageComponent(int)
public StringBuilder threeLineEndMsg()
twoLineStartMsg()
and twoLineEndMsg()
.twoLineEndMsg()
is an extra line reporting
the execution time.getMessageComponent(int)
,
getExecTimeMs()
,
getExecTimeString()
public final String valueLang(CharSequence key, String def)
key
taking language
and region into
account searching in this (App
) object's prop
(properties) and in AppLangMap
.def
is returned.key
- the key to get a value fordef
- the default value if nothing can be found by keyProp.valueLang(CharSequence)
,
AppLangMap.valueUL(CharSequence)
public final String valueLang(CharSequence key)
valueLang(key, null)
.key
- the key to get a value forAppLangMap.valueUL(CharSequence)
,
Prop.valueLang(CharSequence)
public final String getLanguage()
prop
is not (yet) null,
prop
.getLanguage()
is returned.AppLangMap
.getUMap()
.getLanguage()
, if available.
Otherwise ComVar
.UL
is returned.getLanguage
in interface AppMBean
public StringBuilder messageFormat(StringBuilder bastel, CharSequence patternKey, String patternDefault, Object args)
String pattern = valueLang(patternKey, patternDefault);
TextHelper.messageFormat(bastel, pattern, args);
bastel
- StringBuilder on which to append to; if null it will be
made with starting capacity of 81patternKey
- key for pattern (nationalised) to append to bastelpatternDefault
- pattern to append to bastelargs
- 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).AppLangMap
,
valueLang(CharSequence, String)
,
TextHelper.messageFormat(StringBuilder, CharSequence, Object)
public final String getActTime()
AppLangMap
.valueUL("wedaclock")
.getActTime
in interface AppMBean
AppHelper.getActTime()
public final String getArgs()
App.go()
.
And go()
is usually called in the applications
void main(String[] args)
forwarding just the start parameter
array supplied by the JVM.main(String[])
that array
will never be null. But it may be the empty array
ComVar.NO_STRINGS
.argsOrig
) as one String containing the start parameters
space separated (as from the shell's command line).getArgs
in interface AppMBean
TextHelper.prepParams(String[])
public String regAsStdMBean() throws JMException
JMException
- if the registering failspublic final Verbos getVerbosity()
AppHelper
.Verbos.toString()
.Verbos.NORMAL
isSilent()
,
setVerbosity(int)
,
setVerbosity(String)
,
getVerbose()
public String getVerbose()
AppHelper
.Verbos.toString()
.getVerbose
in interface AppMBean
AppHelper
.getVerbosityAsString(verbosity)
getVerbosity()
public void setVerbosity(int value)
report detailedness
use this method. So (only)
this method has to be overridden if modifications are necessary.value
- Level Verbos.DEBUG .. Verbos.SILENT;
default: Verbos.NORMALgetVerbosity()
,
setVerbosity(String)
,
Verbos.NORMAL
,
Verbos.toString()
,
Verbos.getVerbosityLevel()
public final void setVerbosity(String verbosity)
verbosity
will be interpreted by the method
AppHelper
.Verbos.getVerbosity(String)
and the result
will be passed to setVerbosity(int)
.verbosity
- the verbosity level to be setgetVerbosity()
,
setVerbosity(int)
public final void setVerbose(String verbosity)
verbosity
- the verbosity level to be setsetVerbosity(verbosity)
public final void setVerbose(boolean verbose)
verbose
- the verbosity level to be set; true: verbose; false: normalverbose
public final boolean isVerbose()
getVerbosity()
public final boolean isSilent()
verbose
,
isNormal()
,
getVerbosity()
public final boolean isNormal()
verbose
,
isSilent()
,
getVerbosity()
public final boolean isTest()
verbose
,
isSilent()
,
isNormal()
,
getVerbosity()
public final boolean isDebug()
verbose
,
isSilent()
,
isNormal()
,
getVerbosity()
public final void queueAction(String command, AWTEvent event)
App
inheritors mostly for
being used in graphical event listeners indirectly via
actionPerformed()
etc.command
and event
are null or empty nothing
happens.command
is null, it will be tried to determine it
directly as actionCommand or indirectly (via getSource() respectively
getItemSelectable()) from event
.command
is now still null or
empty nothing is done.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.verbosity
is <= Verbos.TEST
e.g. equal to
Verbos.DEBUG
every action will be logged on log
before
calling performeAction(String, AWTEvent)
.command
- the command, if null it will be extracted from eventevent
- graphical event, may be null if command is not nullperformeAction(String, AWTEvent)
public boolean performeAction(String command, AWTEvent e)
queueAction(String, AWTEvent)
. It may as well be called
directly.runFlag
is true and if
verbosity
is <= Verbos.DEBUG
the
command
will be logged with the actual time.runFlag
is false.
if (super.performeAction(command, e)) return true;
// Implementing further actions / commands
This behaviour should be kept over the whole inheritance chain.command
- the "action command"e
- if given an ActionEvent
or an ItemEvent
;public void actionPerformed(ActionEvent e)
ActionEvent
e and calls if one was given
performeAction(command, e)
.queueAction(String, AWTEvent)
into a thread different
from the one calling this method
actionPerformed(ActionEvent)
.performeAction()
instead of this method
actionPerformed(ActionEvent)
. The extra gift is the decoupling
thread working independently from swing, AWT or other event sources.ActionListener
.performeAction()
have nevertheless to obey all
Swing threading rules (usually by using invokeLater() for that
purpose).actionPerformed
in interface ActionListener
e
- the action to be queuedpublic final boolean isHelp()
log
.go(..)
would normally have done all this
before the overridden doIt()
must decide to do just help output
plus nothing.doIt()
) only. Setting it to true later must have no
effect.public final void setHelp(boolean help)
help
- true if a help output (-help -?) is requestedisHelp()
public final OutMode getOutMode()
setOutMode(CharSequence)
,
setOutMode(OutMode)
public final void setOutMode(OutMode outMode)
outMode
- null: no changegetOutMode()
public final void setOutMode(CharSequence outMode)
outMode
- null, empty, no fit : no changegetOutMode()
,
OutMode.of(CharSequence, OutMode)
public final boolean isRunFlag()
while(runFlag)
or while(isRunFlag())
. This also the
correct substitute for the depreciated Thread.stop().stop()
.runFlag
(reset by
stop()
) and the common runFlag's, i.e.
AppBase
.commonRun
. If only the
latter is false, this method will call stop()
.AppBase.isCommonRun()
public void stop()
runFlag
to false if it is not yet so.runFlag
is false, this method does nothing.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).normalExit()
or
errorExit()
.stop()
is the signal to end
and the methods xyzExit() are the end itself. The latter may be called
without former stop signal.AppBase
.commonRun
will be set false
also as a stop signal to all others.public final boolean wakeMainThread()
mainThread
, that is doIt()
). This
thread will be woken up robustly and reliably. Success will be
signalled by returning true. mainThread
still exists and if the caller itself is not the main
thread will be interrupted.AppHelper.sleep(long)
,
AppHelper.getTimer()
,
AppHelper.scheduleAbsolute(TimerTask, long, long)
,
AppHelper.scheduleAtFixedRate(TimerTask, long, long)
protected boolean isHelpLog()
condHelpLog()
the condition
that an on-line help output to log
shall be the only work or
effect of this application's actual execution.help
. This is the standard
condition.
return help || extraCondition(); // like args.length == 0
help
isHelp()
,
condHelpLog()
protected final boolean condHelpLog()
isHelpLog()
returns true, this method does the
following:This outputs the (nationalised) help text and ends this application.log
.println(helpText)
);stop()
;
isHelpLog()
returns false this method does nothing.isHelpLog()
isHelp()
,
go(..)
public String clientOrder(String command) throws AttributeNotFoundException
command
must contain all necessary denotations, like command, parameter,
credentials and so on. command
must not be empty.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. |
command
- the order (containing all parameters and else)AttributeNotFoundException
- if the order is not implemented
or if the parameters are wrong; see tablepublic String getStateString()
makeStatusTextStart(.)
and
makeStatusTextEnd(.)
.public StringBuilder makeStatusTextStart(StringBuilder bastel)
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.bastel
- the StringBuilder to append to; if null it is madepublic StringBuilder makeStatusTextEnd(StringBuilder bastel)
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.bastel
- the StringBuilder to append to; if null it is madepublic final String getTitle()
getTitle
in interface UIInfo
setTitle(String)
public void setTitle(String title)
title
- the (window) titlegetTitle()
public Window getMyFrame()
public WindowListener getTheCloser(Window frame)
App
when the given frame closes.myFrame
is null it will be set by the parameter
frame.frame
- The window the listener is to be made for; if null
myFrame
is used. If still null nothing is done.public Image getIcon()
haveIcon()
public Image haveIcon()
icon
was already set it is returned.
Otherwise the
weinert-automation's logo
will be set and returned.getIcon()
public void setBgColor(CharSequence bgColor)
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.bgColor
- the new background colourprotected boolean allowNoPropertiesFile()
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).App
.go()
) constructs a Prop
object
for the application using a constructor like
Prop.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".Prop.Prop()
).App
only the
last ones base .properties file is searched for.protected String extraPropertiesFile()
public Prop getProp()
go(..)
, loaded
and partly evaluated.public boolean parsePartial()
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)
.Prop
is a
fixed property of an application classes extending App must override this
method finally this methods default behaviour is not wanted.App(String[])
public final LogWriterHandler getLogHandler()
Handler
connected to log
. It will
be made on the first call. This method just delegates to
appIO
.getLogHandler()
.)
public final Logger getAppLogger()
appIO
.getAppLogger()
. If the
Logger
is newly generated its Level
will be set according
to getVerbosity()
.Verbos.getVerbosityLevel()
,
setVerbosity(int)
protected Logger getDbLogger()
public final void logVerbose(String sourceClass, String sourceMethod, String msg, Object[] params)
Level
.FINE
that is equivalent to
Verbos.VERBOSE
. If a separate dbLogger
was made with the logging will be into the database.sourceClass
- source of log messagesourceMethod
- source of log messagemsg
- log messageparams
- further parameters for log messagepublic final void logVerbose(String sourceClass, String sourceMethod, String msg)
logVerbose(String, String, String, Object[])
, but without
parameter array.sourceClass
- source of log messagesourceMethod
- source of log messagemsg
- log messagepublic void setCodePages(String codePage)
appIO
.setCodePages()
if and only if this application is the (one) base / mother application.
That is the one which made the singleton AppBase
object.codePage
- the new encoding for all text I/O streamspublic void setLogOut2(OutputStream os2, String cp2)
os2
- the new second (Tee) writercp2
- its encodingprotected int connect(OutMode outMode, Prop prop)
AppIO
object appIO
in each case an output of the TeeWriter
s
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
.de.frame4j.io.FileVisitor.AskGrafImpl
).outMode
- the mode for opening an output streamprop
- the properties to get all information fromComVar.INIT_ERROR
,
ComVar.LOG_OUT_ERROR
protected final int go(String[] args, String codePage, CharSequence commBeg) throws FileNotFoundException, IllegalArgumentException
App
lication featuring evaluation of start arguments .properties
files and (inter) nationalising.in
,
out
and err
if this application is the base
("mother") application.doIt()
will be called.
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()
).doIt()
's return value is returned.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 argumentsComVar.NO_PARS_ERROR
: Start problem,IllegalArgumentException
- on parameter evaluating errorsFileNotFoundException
- base .properties file is missinggo(String[], String)
protected final int go(String[] args) throws FileNotFoundException, IllegalArgumentException
go(args, null, partial, null)
except for those extras: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().help
is true or isHelpLog()
returns true, the
method doIt()
is not called; 0 (ComVar.JOB_DONE_OK
) is
returned as exit code.args
- the start arguments passed onComVar.NO_PARS_ERROR
: Start problem,FileNotFoundException
- forwarded
from go(String[], String, CharSequence)
IllegalArgumentException
go(String[], String, CharSequence)
,
condHelpLog()
protected final int go(String[] args, String codePage) throws FileNotFoundException, IllegalArgumentException
App
lication featuring evaluation of start arguments .properties
files and (inter) nationalising.in
,
out
and err
if this application is the base
("mother") application.doIt()
will be called.
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()
).doIt()
's return value is returned.args
- start arguments passed on (not null)codePage
- the encoding for in, out and err (or null)ComVar.NO_PARS_ERROR
: Start problem,IllegalArgumentException
- on parameter evaluating errorsFileNotFoundException
- base .properties file is missinggo(String[])
public final void repExc(Appendable out, Throwable exc, boolean trace)
out
- the output for the reportexc
- the exception to report ontrace
- true: print also a stack trace
(and only if out is a PrintWriter or a PrrintStream)public final String formMessage(String key, Object param)
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.param
is the pattern (itself) is returned. (Therefore the
calling valueLang()
would
have been sufficient.)param
the method
messageFormat(null, pattern, param)
is used to form a message that will
be returned as String.key
- language independent key for a language dependent patternparam
- the parameter(s) to be parts of the (nationalised)
message to be formedpublic final String formMessage(String key)
formMessage(String, Object)
; this is the "auto
boxing" variant for the frequent case of just one (index [0])
integer message parameter.key
- language independent key for a language dependent patternpublic final String formMessage(String key, int parInt)
getMessageComponent(int)
; this is the "self
contained" variant using this App's
message components[5..23]
.key
- language independent key for a language dependent patternparInt
- the one integer parameter to be parts of the (nationalised)
message to be formedprotected abstract int doIt()
App
) must be implemented by an
inheritor. App
's constructors and
go()
methods in a simple main(String[])
just doing new MyApp().go(args, false)
, for example.Prop
,
go(String[])
,
go(String[], String, CharSequence)
,
mainThread
public int normalExit(int returnCode)
returnCode
- return/exit value; > 0 (on Win/DOS) : error
numberComVar.JOB_DONE_OK
,
ComVar.NO_PARS_ERROR
,
ComVar.LOG_OUT_ERROR
,
ComVar.INIT_ERROR
public int errorExit(int errNum, String errText)
errNum
- > 0 : error numbererrText
- additional error textdoIt()
's returnComVar.JOB_DONE_OK
,
ComVar.NO_PARS_ERROR
,
ComVar.LOG_OUT_ERROR
,
ComVar.INIT_ERROR
public int errorExit(int errNum, Exception ex, String errText)
verbosity
) is >
Verbos.VERBOSE
the stack trace of ex
will be output to log
; otherwise
only ex
's message is used.appBase
.errorExit(this, returnCode, null)
.errNum
- >0 : error numberex
- the exception that made any further work senselesserrText
- additional error text; may usually be null as ex's
message will be loggeddoIt()
's returnComVar.NO_PARS_ERROR
,
ComVar.LOG_OUT_ERROR
,
ComVar.INIT_ERROR
public final String getExecTimeString()
getExecTimeMs()
,
AppBase.setActTime()
,
TextHelper.formatDuration(StringBuilder, long)
public final long getExecTimeMs()
getExecTimeString()
,
AppBase.setActTime()
public final Long getExecTimeMsL()
getExecTimeMsL
in interface AppMBean
getExecTimeMs()
,
AppBase.setActTime()
public final String getAbout()
public String getHelp()
public void setVersDate(String versDate)
versDate
, it it was not
yet set and if the parameter is not empty even after stripping surrounding
white space.versDate
- version and date of this App
inheritors
class (taken without surrounding white spaces)getVersDate()
public String getVersDate()
AppMBean
getVersDate
in interface AppMBean
getVersDate
in interface UIInfo
public void setName(String name)
name
- the application's short namepublic String getNameWithVersDate()
public String getAuthor()
description
in UIInfo
.setAuthor(null)
.ComVar.EMPTY_STRING
.ComVar.AUTHOR
public void setAuthor(String author)
description
in UIInfo
.MinDoc
-annotation
or as
ComVar.AUTHOR
.author
- null and already set: do nothing;public String getCopyright()
ComVar.COPYRIGHT
getCopyright
in interface AppMBean
getCopyright
in interface UIInfo
getAbout()
,
getAuthor()
public void setCopyright(CharSequence copyright)
copyright
, only if not yet set and if the
parameter, stripped from surrounding white spaces, is not empty.copyright
- The note to be setgetCopyright()
,
getAbout()
,
getAuthor()
public String getPurpose()
name
) (see getMessageComponent(int)
).getPurpose
in interface AppMBean
getPurpose()
public void setPurpose(CharSequence purpose)
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.purpose
- null: no effect if set or set to annotation (default)getPurpose()
,
getMessageComponent(int)
public String getAboutText()
public void setAboutText(CharSequence aboutText)
getNameWithVersDate()
,
getCopyright()
and getPurpose()
.aboutText
- null: no effect if set or set default. getAbout()
,
getMessageComponent(int)
public final int setAttribute(String name, Object value)
verbose/verbosity
,
outMode
,
title
,
author
,
aboutText
,
bgColor
, codePages
,
copyright
,
name
, usage
and
versDate
(mostly) by delegating to the appropriate
setter (with one parameter).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.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.setAttribute
in interface AttrSettable
name
- the property's / attributes name; if null, empty or not
lower case (Java name convention) AttrSettable.NO_ATTRIBUTE
is returned and nothing is donevalue
- the value to set as Object; the type CharSequence
should always be acceptedprotected int setAttribute(String name, char name0, Object value, Class<?> vClass, boolean isNull, boolean isStringVal)
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
.setAttribute(String, Object)
) are superfluous here. name
- name of the property (never empty)name0
- first character of name (>= a)value
- the (new) value of the propertyvClass
- the (original) class of value (or null if isNull)isNull
- true if value is nullisStringVal
- true if value is of type StringAttrSettable.NO_KNOWN_ATTRIBUTE
AttrSettable
,
AttrSettable.ILLEGAL_TYPE
,
AttrSettable.ILLEGAL_VALUE
,
AttrSettable.NO_VALUE
,
AttrSettable.OK
public String getUsage()
name
) (see getMessageComponent(int)
).getUsage
in interface UIInfo
getHelpText()
public void setUsage(CharSequence usage)
getUsage()
) will be set.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.usage
- null: no effect if set or set default. getUsage()
,
getMessageComponent(int)
public String getHelpText()
public String errorText(int errNum, Object suplText)
nameWithVersDate
errNum
- the error number, if > 0suplText
- an extra text (String, StringBuilder, CharSequence
respectively Exception or Throwable)TextHelper.messageFormat(StringBuilder, CharSequence, Object)
,
getMessageComponent(int)
public final int errMeld(int errNum, Object suplText)
log
an error text, produced according to
errorText(errNum, suplText)
, is
output.suplText an Exception
and the
level of verbosity
<= Verbos.TEST
,
the exception's call stack is output, too.
errNum
- the error number, if > 0suplText
- additional text, describing the errorpublic int errMeld(PrintStream out, int errNum, Object suplText)
out
an error text, produced according to
errorText(errNum, suplText)
, is
output.suplText an Exception
and the
level of verbosity
<= Verbos.TEST
,
the exception's call stack is output, too.
errNum
- the error number, if > 0suplText
- additional text, describing the errorout
- the Stream to output tocondHelpLog()