org.vishia.mainCmd
Class MainCmd

java.lang.Object
  org.vishia.mainCmd.MainCmd

All Implemented Interfaces:

MainCmd_ifc, Report

Direct Known Subclasses:

CmdHeader2Reflection, CorrectHref.Main, Java2C, Main.CmdLine, MainCmdSwt, MainCmdWin, SampleCmdLine.CmdLine, SampleZbnfJava, SocketTester, Textfile2Html, Xslt.CmdLine, Xsltpre.CmdLine, Zbnf2Xml.CmdLine, Zmake.CmdLine

public abstract class MainCmd
extends java.lang.Object
implements MainCmd_ifc

class MainCmd - Description

• Parsing of cmd line arguments:
• Realising of the system outputs
• Provides an interface for reporting to a file.
• Gathering of the maximum of the exitErrorLevel, see setExitErrorLevel().
• Provides a method to execute external cmd lines in a simple way for the user, see executeCmdLine()
• Defining of a system for the application (abstract methods), for the way to give informations from the application. see writeAboutInfo(), writeHelpInfo().

    ---|> means an inherition
    <>--> means a composition or aggregation
    ----> means a association


    +-------------+        +-------------+        +-------------+
    |             |------|>| MainCmd     |------|>| MainCmd_Ifc |
    |UserMainClass|        +-------------+        +-------------+
    |             |                                      ^
    |             |        +-------------+    main       |
    |             |<>----->| UserClasses |---------------+
    +-------------+        +-------------+

    in cmdlines:

    class UserMainClass extends MainCmd
    { final UserClasses userClasses = new UserClasses(this);  //... the user's classes
    }

    class UserClasses
    { final MainCmd_Ifc main;        //the aggregation to Main
      UserClasses(MainCmd_Ifc main)
      { this.main = main;
      }
    }
    

date       who        what
2007-03-07 JcHartmut  Method getReportFileName
2007-03-07 JcHartmut  callWithoutArgument do not exit but throws an exception likewise by an error of arguments.
2006-04-02 JcHartmut  writeInfo__ new methods write__Directly, solution of concurrency to write to report.
2006-01-17 JcHartmut  testArgument() may thrown an ParseException.
2006-01-21 JcHartmut  bugfix callWithoutArguments() should be protected, not package private.
2004-06-00 JcHartmut  initial revision

fReport

public FileWrite fReport

The report file. This attribute is set to null, if no report is desired by missing the argument -r REPORTFILE

nReportLevel

public int nReportLevel

All reports with a level less than or equal this level will be reported. Other report calls has non effect.

sFileReport

private java.lang.String sFileReport

nReportLevelDisplay

public int nReportLevelDisplay

All reports with a level less than or equal this level will be written on display. Note: using Report.writeInfo(String) etc. writes to display also if this attribute is 0.

nLevelDisplayToReport

public int nLevelDisplayToReport

writeError(), writeWarning(), writeInfo() are also reported if the level is equal or greater than 1,2,3

listHelpInfo

protected java.util.List<java.lang.String> listHelpInfo

List of strings contents help Info in form of lines. The list should be filled with method addHelpInfo(String);

listAboutInfo

protected java.util.List<java.lang.String> listAboutInfo

List of strings contents about Info in form of lines. The list should be filled with method addHelpInfo(String);

nMaxErrorLevel

private int nMaxErrorLevel

The maximum of the value given with setExitErrorLevel

cmdLineArgs

protected java.lang.String[] cmdLineArgs

array of arguments from command line

iArgs

private int iArgs

number of the argument is parsing

report_spaces

private static final java.lang.String report_spaces

access to some spaces via Report.spaces.substring(0,n)

See Also:

Constant Field Values

kInfo_writeInfoDirectly

protected static final short kInfo_writeInfoDirectly

Some bits to mark the kind of output

See Also:

Constant Field Values

kInfoln_writeInfoDirectly

protected static final short kInfoln_writeInfoDirectly

See Also:

Constant Field Values

kWarning_writeInfoDirectly

protected static final short kWarning_writeInfoDirectly

See Also:

Constant Field Values

kError_writeInfoDirectly

protected static final short kError_writeInfoDirectly

See Also:

Constant Field Values

mNewln_writeInfoDirectly

protected static final short mNewln_writeInfoDirectly

If this bit is setted in param kind of writeDirectly a newline should be inserted at begin of output

See Also:

Constant Field Values

mWarning_writeInfoDirectly

protected static final short mWarning_writeInfoDirectly

If this bit is setted in param kind of writeDirectly a warning is to be outputted

See Also:

Constant Field Values

mError_writeInfoDirectly

protected static final short mError_writeInfoDirectly

If this bit is setted in param kind of writeDirectly an error is to be outputted

See Also:

Constant Field Values

logMessageConsole

MainCmd.LogMessageImplConsole logMessageConsole

logMessageFile

MainCmd.LogMessageImplFile logMessageFile

MainCmd

protected MainCmd()

Empty Constructor of the main class. The command line args should be set in the derivated class.

MainCmd

protected MainCmd(java.lang.String[] args)

Constructor of the main class.

addStandardHelpInfo

protected void addStandardHelpInfo()

Adds the help info for standard arguments. The text is the followed:

    addHelpInfo("--about show the help infos");
    addHelpInfo("--help  show the help infos");
    addHelpInfo("--report=FILE  write the report (log) into the given file, create or clear the file.");
    addHelpInfo("--report+=FILE add to the end of given file or create the report file.");
    addHelpInfo("--rlevel=R     set the level of report, R is number from 1 to 6.");
    addHelpInfo("--rlevel=DR    also write reports upto level D on display, sample: ..-rlevel:24");
    addHelpInfo("--rlevel=WDR   write output also in report, W is nr from 1 to 3 (error, warning, info");
    

addHelpInfo

protected void addHelpInfo(java.lang.String info)

Addes a helpinfo-line to the internal list. This method should be called from the user on startup to set the help infos. The help info is used by writeHelpInfo() called if the argument --help is given or without arguments. .

Parameters:

info - String contains 1 line of a help Info.

addAboutInfo

protected void addAboutInfo(java.lang.String info)

Addes a helpinfo-line to the internal list. This method should be called from the user on startup to set the help infos. The help info is used by evaluating command line arguments.

Parameters:

info - String contains 1 line of a help Info.

writeHelpInfo

public void writeHelpInfo()

prints the help info to the console output. This Method may be overloaded in MainCmdWin to show the contents in a window.

writeAboutInfo

public void writeAboutInfo()

prints the help info to the console output. This Method may be overloaded in MainCmdWin to show the contents in a window.

parseArguments

public final void parseArguments()
                          throws java.text.ParseException

Parses the cmdLine-arguments. The args should be set in constructor.

Throws:

java.text.ParseException

See Also:

parseArguments(String [] args)

parseArguments

public final void parseArguments(java.lang.String[] args)
                          throws java.text.ParseException

Parses the cmdLine-arguments. The user should invoked this method in his static main method or in the main-method often named execute().
On every not-standard argument this method calles testArgument(String, int) inside. That is a abstract methode, the user must overwrite it, see there. If this method returns false, a writeError() with a matched text is called and a ParseException("", N) ist thrown, N is the number of the argument. Standard arguments are parsed here, see addStandardHelpInfo(). On end the methode checkArguments() is called. If it returns false, an ParseException("", 0) is thrown. The user should had write an output message with writeError() inside its checkArguments()
:TODO: It should be helpfull to read arguments also from file. An cmd line argument in the form @@filepath should be evaluated in this form, that every line of the readed file is used as one argument additionaly. At example a cmd line invoke like >cmd -a arg1 @@file -x argx results in the followed argument array:
-a arg1 arguments-from-file-lines -x argx

Throws:

java.text.ParseException

openReportfile

public void openReportfile(java.lang.String sFileReport,
                           boolean bAppendReport)
                    throws java.io.FileNotFoundException

Specified by:

openReportfile in interface Report

Throws:

java.io.FileNotFoundException

checkArguments

protected abstract boolean checkArguments()

Checks the arguments after parsing from command line, test of consistence. This method must overwrite from the user, may be with a return true. The method is ocalled at last inside parseArguments(). If this method returns false, parseArguments throws an exception in the same manner if on argument errors.

Returns:

true if all is ok. If false,

callWithoutArguments

protected void callWithoutArguments()
                             throws java.text.ParseException

Invoked from parseArguments if no argument is given. In the default implementation a help info is written and the application is terminated. The user should overwrite this method if the call without comand line arguments is meaningfull.

Throws:

java.text.ParseException

getArgument

protected java.lang.String getArgument(int pos)

Returns the argument contents. The user should invoke this method in his testArgument()-method. If the actually argument is longer as pos, the contents is the substring starts on pos. If the actually argument is no longer as pos( in praxis equal pos), the contents is the contents of the next argument. In this way the getArgument()-method supplies both argument methods:

• -kcontents
• -k contents

In this sample -k is the key to recognize the argument and contens is the appendant content.

Parameters:

pos - position of the beginning of the information in a argument. In the sample above use the value 2.

testArgument

protected abstract boolean testArgument(java.lang.String argc,
                                        int nArg)
                                 throws java.text.ParseException

Tests one argument, called from parseArguments() on every argument excluding standard arguments -r and -rlevel. The user must overwrite this method to test the application-specific paramters.

Parameters:

argc - The argument to test

nArg - number of argument, the first argument is numbered with 1.

Returns:

false, if the argument doesn't match, true if ok. if the method returns false, an exception in parseArgument is thrown to abort the argument test or to abort the programm. @see parseArgument().

Throws:

java.text.ParseException - The Methode may thrown this excpetion if a conversion error or such other is thrown.

setExitErrorLevel

public void setExitErrorLevel(int level)

set the exitErrorLevel of the maximum of given level of every call.

Specified by:

setExitErrorLevel in interface Report

Parameters:

level - Errorlevel how defined in Report, 0 is the lowest level (successfull), >0 is worse.

getExitErrorLevel

public int getExitErrorLevel()

get the maximum of errorLevel setted with setExitErrorLevel().

Specified by:

getExitErrorLevel in interface Report

Returns:

the errorlevel

exit

public void exit()

Exits the cmdline application with the maximum of setted exit error level. This method should be called only on end of the application, never inside. If the user will abort the application from inside, he should throw an exception instead. So an comprising application may catch the exception and works beyond. This method is not member of MainCmd_Ifc and is setted protected, because the users Main class (UserMain in the introcuction) only should call exit.

executeCmdLine

public int executeCmdLine(java.lang.String cmd,
                          int nReportLevel,
                          java.lang.StringBuffer output,
                          java.lang.String input)

Execute a command invoke a cmdline call, implements MainCmd_Ifc.

Specified by:

executeCmdLine in interface MainCmd_ifc

Parameters:

cmd - String represents the command with all arguments. The arguments must be separated by exactly one space. The rest of paramter and return see executeCmdLine(String[], ...).

executeCmdLine

public int executeCmdLine(java.lang.String[] cmd,
                          int nReportLevel,
                          java.lang.StringBuffer output,
                          java.lang.String input)

Execute a command invoke a cmdline call, implements MainCmd_Ifc. The call must not be needed any input (:TODO:?). The output is written with a separate thread, using the internal (private) class ShowCmdOutput. This class use the method writeInfoln() from here. The writeInfoln-Method writes to console for MainCmd, but it may be overloaded, to example for MainCmdWin it may be writed to a box in the GUI.

Specified by:

executeCmdLine in interface MainCmd_ifc

Parameters:

cmd - String with the separeted parts of the command. cmd[0] is the command to invoke.

nReportLevel - Determines the kind of writing the output. Possible values are 1..6 using Report.error to Report.fineInfo and -1..-3 using -Report.error to -report.info (with a negativ sign!). On negativ values the report is written to display with the write..()-methods of this interface, with the positive value, the report is written to Report.report..()-Methods.
The error output is always written to the reportfile with Report.error or with writeError().
Example: -3 detemines, that the normal output is written with writeInfoln() and the error output is written with writeError(), 3 detemines that the normal output is written with reportln(3,...) and the error output is written with Report(1, ...).

output - If not null, than the stdout is written in this Buffer. If null, the stdout is written to report.

input - If not null, this input is send to the cmdline process. If null, no input is send.

Returns:

exitErrorLevel from the command line process.

executeCmdLine

public int executeCmdLine(java.lang.String cmd,
                          java.lang.ProcessBuilder processBuilder,
                          int nReportLevel,
                          java.lang.StringBuffer output,
                          java.lang.String input)

Deprecated. 

Execute a command invoke a cmdline call, implements MainCmd_Ifc. The call must not be needed any input (:TODO:?). The output is written with a separate thread, using the internal (private) class ShowCmdOutput. This class use the method writeInfoln() from here. The writeInfoln-Method writes to console for MainCmd, but it may be overloaded, to example for MainCmdWin it may be writed to a box in the GUI.

executeCmdLine

public int executeCmdLine(java.lang.String[] cmd,
                          java.lang.ProcessBuilder processBuilder,
                          int nReportLevel,
                          java.lang.StringBuffer output,
                          java.lang.String input)

Deprecated. 

Parameters:

cmd -

processBuilder -

nReportLevel -

output -

input -

Returns:

executeCmdLine

public int executeCmdLine(java.lang.ProcessBuilder processBuilder,
                          java.lang.String cmd,
                          java.lang.String input,
                          int nReportLevel,
                          java.lang.StringBuffer output,
                          java.lang.StringBuffer error)

Executes a command line call maybe as pipe, waiting for finishing.. The output is written with a separate thread, using the internal (private) class ShowCmdOutput.

Specified by:

executeCmdLine in interface MainCmd_ifc

Parameters:

processBuilder - The ProcessBuilder. There may be assigned environment variables and a current directory.

cmd - The cmd and arguments. If it is null, the command assigened to the processBuilder is used.

input - Any pipe-input. It may be null.

nReportLevel - The report level which is used for output. If it is 0, then the output isn't written TODO

output - The output pipe.

error - The error pipe. If it is null, then errors are written in the output pipe.

Returns:

executeCmdLine

public int executeCmdLine(java.lang.ProcessBuilder processBuilder,
                          java.lang.String[] cmd,
                          java.lang.String input,
                          int nReportLevel,
                          java.lang.StringBuffer output,
                          java.lang.StringBuffer error)

Executes a command line call maybe as pipe, waiting for finishing.. The output is written with a separate thread, using the internal (private) class ShowCmdOutput.

Specified by:

executeCmdLine in interface MainCmd_ifc

Parameters:

processBuilder - The ProcessBuilder. There may be assigned environment variables and a current directory.

cmd - The cmd and arguments. If it is null, the command assigend to the processBuilder is used.

input - Any pipe-input. It may be null.

nReportLevel - The report level which is used for output. If it is 0, then the output isn't written TODO

output - The output pipe.

error - The error pipe. If it is null, then errors are written in the output pipe.

Returns:

startCmdLine

public int startCmdLine(java.lang.ProcessBuilder processBuilder,
                        java.lang.String cmd)

Starts a command invocation for a independent window. This command does not have any input or output. The command will be started, the finishing isn't await. This command line invocation is proper for commands, which create a new window in the operation system. The new window has its own live cycle then, independent of the invocation.

Specified by:

startCmdLine in interface MainCmd_ifc

Parameters:

cmd - The command. Some arguments are possible, they should be separated by space.

processBuilder - The processBuilder.

Returns:

startCmdLine

public int startCmdLine(java.lang.ProcessBuilder processBuilder,
                        java.lang.String[] cmd)

Starts a command invocation for a independent window. This command does not have any input or output. The command will be started, the finishing isn't await. This command line invocation is proper for commands, which create a new window in the operation system. The new window has its own live cycle then, independent of the invocation.

Specified by:

startCmdLine in interface MainCmd_ifc

Parameters:

cmd - The command and some arguments.

processBuilder - The processBuilder.

Returns:

0 on success, 255 if any start error.

switchToWindowOrStartCmdline

public int switchToWindowOrStartCmdline(java.lang.ProcessBuilder processBuilder,
                                        java.lang.String sCmd,
                                        java.lang.String sWindowTitle)

Description copied from interface: MainCmd_ifc

Searches the window for the already running process or starts the process with command invocation for a independent window. This command does not have any input or output. The command will be started, the finishing isn't await. This command line invocation is proper for commands, which create a new window in the operation system. The new window has its own live cycle then, independent of the invocation.

Specified by:

switchToWindowOrStartCmdline in interface MainCmd_ifc

Parameters:

processBuilder - The processBuilder.

sWindowTitle - The title or the start of the window if the process is running already. Note: The title is depending from the application. Sometimes the title starts with the associated file, forex calling windows-notepad.

Returns:

0 on success, 255 if any start error.

writeInfo

public final void writeInfo(java.lang.String sInfo)

Writes an information, implementation of MainCmd_Ifc. The info is written also to report depended on command line arguments --rlevel. If the user will overwrite the kind of output, overwrite writeInfoDirectly, it is called here.

Specified by:

writeInfo in interface Report

Parameters:

sInfo - String to be written.

writeInfoln

public final void writeInfoln(java.lang.String sInfo)

Writes an information line, implementation of MainCmd_Ifc. The info is written also to report depended on command line arguments --rlevel. If the user will overwrite the kind of output, overwrite writeInfolnDirectly, it is called here.

Specified by:

writeInfoln in interface Report

Parameters:

sInfo - String to be written.

writeWarning

public final void writeWarning(java.lang.String sInfo)

Writes an warning line, implementation of MainCmd_Ifc. The info is written also to report depended on command line arguments --rlevel. If the user will overwrite the kind of output, overwrite writeWarningDirectly, it is called here.

Specified by:

writeWarning in interface Report

Parameters:

sInfo - The error text, it should be without such hot spot words line "!!!WARNING!!!", because the distinction in display should be done by the implementation of this method. A good sample is writeErrorln("file is empty: " + sFileName);

writeError

public final void writeError(java.lang.String sInfo)

Writes an error line, implementation of MainCmd_Ifc. The info is written also to report depended on command line arguments --rlevel. If the user will overwrite the kind of output, overwrite writeErrorDirectly, it is called here.

Specified by:

writeError in interface Report

Parameters:

sInfo - The error text, it should be without such hot spot words line "!!!ERROR!!!", because the distinction in display should be done by the implementation of this method. A good sample is writeErrorln("cannot create file: " + sFileName);

writeError

public final void writeError(java.lang.String sInfo,
                             java.lang.Exception exception)

Writes an error line with exception info, implementation of MainCmd_Ifc. The info is written also to report depended on command line arguments --rlevel. If the user will overwrite the kind of output, overwrite writeErrorDirectly, it is called here.

Specified by:

writeError in interface Report

Parameters:

sInfo - The error text, it should be without such hot spot words line "!!!ERROR!!!", because the distinction in display should be done by the implementation of this method. A good sample is writeErrorln("cannot create file: " + sFileName);

exception - The catched Exception. The getMessage()-part of the exception is written after sError. The stacktrace of the exception is written to report.

writeStackTrace

public void writeStackTrace(java.lang.Exception exception)

write out the stacktrace from a exception. Writes into reportfile and on screen

writeDirectly

protected void writeDirectly(java.lang.String sInfo,
                             short kind)

Writes out the Info, Warning or Error in the users way. This method is overwriteable to form or configure the users requests.

Parameters:

sInfo - The String to write

kind - Ones of the kWriteOut__

writeErrorDirectly

protected void writeErrorDirectly(java.lang.String sInfo,
                                  java.lang.Exception exception)

Writes an error line by console application directly to System.err.println with the String "EXCEPTION: " before and the exception message. The user can overwrite this method in the derived class of MainCmd to change to kind of output.

Parameters:

sInfo - Text to write in the new line after "EXCEPTION: ".

exception - Its getMessage will be written.

report

public void report(int nLevel,
                   java.lang.String ss)

report appending on exist line. If the report contains an newline char \n, a char '|' will be written. This newline is not interpreted as newline for the report file, but only as stochastic contents in the string.

Specified by:

report in interface Report

Parameters:

nLevel - write the report only if the demand level is greater or equal.

ss - String to write.

reportln

public void reportln(int nLevel,
                     int nLeftMargin,
                     java.lang.String ss)

report begins at a new a line with left margin

Specified by:

reportln in interface Report

Parameters:

nLevel - write the report only if the demand level is greater or equal.

nLeftMargin - determins a left margin. First a new line is outputted, followed by '*' and spaces.

ss - String to write.

reportln

public void reportln(int nLevel,
                     java.lang.String ss)

Description copied from interface: Report

report begins at a new a line

Specified by:

reportln in interface Report

Parameters:

nLevel - write the report only if the demand level is greater or equal.

ss - String to write.

report

public void report(java.lang.String sInfo,
                   java.lang.Exception exception)

Reports an exception. This report is written unconditional, like Report.error. On Display, this report is only written if display output is enabled for the level Report.error.

Specified by:

report in interface Report

Parameters:

sInfo - Text to write in the new line after "EXCEPTION: ".

exception - Exception info to write

report

private void report(java.lang.String sInfo,
                    java.lang.Exception exception,
                    boolean bWrittenOnDisplay)

Internal method to write an exception to report. A third parameter idicates, wether or not the writing to display is always done.

Parameters:

sInfo - Text to write in the new line after "EXCEPTION: " and before the exception.getMessage is written.

exception - Exception info to write

bWrittenOnDisplay - true, than the writing to display is always done.

getReportLevel

public int getReportLevel()

Test wether the report is in the level.

Specified by:

getReportLevel in interface Report

Returns:

The report level, defined by user invoking.

setReportLevel

public int setReportLevel(int newLevel)

Set another level inside programming. It is advisable to restore the old level after the designated operation.

Parameters:

newLevel - The level to be set, use one of the defines Report.info to Report.fineDebug

Returns:

the current level, usefull to restore it.

flushReport

public void flushReport()

Description copied from interface: Report

Writes the content in the physical medium. The implementation of flush is in the best way as possible. It depends on the possibilities of the output medium.

Specified by:

flushReport in interface Report

setReportLevelToIdent

public void setReportLevelToIdent(int nLevel,
                                  int nLevelActive)

Description copied from interface: Report

Sets a dedicated level number to the known output priorities. This method helps to define several levels to dispatch it.

Specified by:

setReportLevelToIdent in interface Report

nLevelActive - Ones of the known priotity levels Report.error to Report.fineDebug.
Example of using:

   class MyModule
   { /**Define module-specific numbers to identify a level. 
      * The numbers should be define regarding a band of numbers in the application.
      * /  
     static final int myReportLevel1 = 3500, myReportLevel2=3501; 
     
     void init()
     { setLevelActive(myReportLevel1, Report.info);  //This reports should be outputted always
       setLevelActive(myReportLevel2, Report.debug); //This reports are debug infos.
     }
     
     void processAnything()
     { report.reportln( myReportLevel1, "InfoText"); //It depends on the report level settings 
       report.reportln( myReportLevel2, "DebugText");//wether it is outputted or not. 
     }  
 

getReportLevelFromIdent

public int getReportLevelFromIdent(int ident)

Description copied from interface: Report

gets the associated report level to a report identifier.

Specified by:

getReportLevelFromIdent in interface Report

Parameters:

ident - The identifier.

Returns:

the level.

getReportFileName

public java.lang.String getReportFileName()

Description copied from interface: MainCmd_ifc

Returns the name of the report file to write out as info.

Specified by:

getReportFileName in interface MainCmd_ifc

Returns:

name of Reportfile.

getLogMessageOutputConsole

public LogMessage getLogMessageOutputConsole()

Description copied from interface: Report

Gets a LogMessage output.

Specified by:

getLogMessageOutputConsole in interface Report

Returns:

never null.

getLogMessageOutputFile

public LogMessage getLogMessageOutputFile()

Description copied from interface: Report

Gets a LogMessage output.

Specified by:

getLogMessageOutputFile in interface Report

Returns:

never null.