de.frame4j.io

Class AppIO

java.lang.Object

de.frame4j.io.AppIO

@MinDoc(copyright="Copyright  2001, 2009, 2014  A. Weinert",
        author="Albrecht Weinert",
        version="V.44",
        lastModified="6.05.2021",
        usage="use instead of own normal I/O plumbing",
        purpose="the I/O base for java applications")
public final class AppIO
extends Object

Base of input and output for Java applications.

For Java applications this class sets the basis for comfortable and robust input and output. Recurring I/O tasks are handled here

• providing a PrintWriter (out) for normal output,
• a PrintWriter (err) for error messages
• a PrintWriter (log) with optional branching to normal output and to a file,
• a BufferedReader (in) for normal input,
• handling the different code-pages of / within console (System.out, .err and .in) and graphic / file encoding. These differences usually occur with Windows' shell.

To have this comfort (compared to the Spartan default features for Java applications) the system streams are decorated by Reader / Writers. Two TeeWriters are utilised in the following way:



The I/O structure (click for full size)
(To an ugly text depiction for browsers with defaulted graphic support.)

Applications extending App get these functions automatically by an associated AppIO (and anAppBase) object.

© Copyright 2000 - 2005 Albrecht Weinert

See Also:

App, TeeWriter

Field Summary

Fields

Modifier and Type	Field and Description
protected String	codePage Code-Page for Reader in and the Writer out and err.
protected String	cp2 The TeeWriter's log encoding for its second output stream.
PrintWriter	err The error output as PrintWriter.
TeeWriter	errTW The TeeWriter for err.
protected OutputStreamWriter	esw The OutputStreamWriter decorating System.err .
BufferedReader	in The normal input as BufferedReader.
protected InputStreamReader	isr The InputStreamReader underlying the SwitchedReader swr.
PrintWriter	log A log output as PrintWriter.
protected String	logDat The name of a log file (if given / used).
protected File	logFile The log file (if given / used).
TeeWriter	logTW The TeeWriter connected to the PrintWriter log .
protected OutputStreamWriter	osw The OutputStreamWriter decorating System.out .
PrintWriter	out The standard output as PrintWriter.
protected String	outDat The name of a out file (if given / used).
protected File	outFile The out file (if given / used).
TeeWriter	outTW The TeeWriter for out.
protected SwitchedReader	swr The SwitchedReader underlying the BufferedReader in.

Method Summary

Modifier and Type	Method and Description
void	closeLogHandler() Closing the Logger handler.
int	connect(OutMode outMode, PropMap prop, boolean askGraf) Connect the TeeWriter's outputs for log and out by a PropMap.
static AppIO	get() Make with default settings.
static AppIO	get(int outBuffLen, int logBuffLen, Object consEncoding) Make with settings.
Logger	getAppLogger() Base logger for the applications.
String	getCodePage() Code-Page for Reader in and the Writer out and err.
String	getLogDat() The name of a log file (if given / used).
File	getLogFile() The log file (if given / used).
LogWriterHandler	getLogHandler() The Logger handler.
String	getOutDat() The name of a out file (if given / used).
File	getOutFile() The out file (if given / used).
void	set(PropMap prop) Set some properties by a PropMap object.
boolean	setCodePages(CharSequence codePage) Set code-Page for Reader in and the Writer out and err.
boolean	setErrCodePage(CharSequence codePage) Set PrintWriter err's code page (character encoding).
boolean	setInCodePage(CharSequence codePage) Set BufferedReader in's code page (character encoding).
boolean	setLogDat(String name, String encoding, OutMode outMode, boolean logOnLog) Setting a file for the log output.
void	setLogOut2(OutputStream os2, String cp2) Set log's second writer as stream.
void	setLogOut2(Writer wr2) Set log's second writer as writer.
boolean	setOutCodePage(CharSequence codePage) Set normal out's code page (character encoding).
boolean	setOutDat(String name, String encoding, OutMode outMode, boolean logOnLog) Setting the file fort the output out.
PrintWriter	toOutln(CharSequence s) Output only a not empty String as line.

Methods inherited from class java.lang.Object

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

Field Detail

in

public final BufferedReader in

The normal input as BufferedReader.

This Reader is a /better) substitute for the byte stream System.in, which delivers it to via isr.

Hint 1: A BufferedReader's methods may throw IOExceptions, which System.in avoids.

Hint 2: Entering cntl-Z (control-Z) on the keyboard as the only character in a line will be interpreted by readline() as EoF (End of File).

See Also:

setInCodePage(String), out, err, log, FilterReader

swr

protected final SwitchedReader swr

The SwitchedReader underlying the BufferedReader in.

It will be finally made on construction and be the backup for the (final) Reader in.

See Also:

setInCodePage(String)

isr

protected InputStreamReader isr

The InputStreamReader underlying the SwitchedReader swr.

It will be made using the default code page CONSOL_ENCODING.

See Also:

setInCodePage(String)

err

public final PrintWriter err

The error output as PrintWriter.

This Writer is a (better) substitute for the byte Stream System.err, which it is connected to by esw and errTW.

See Also:

setErrCodePage(String), out, in, log

errTW

public final TeeWriter errTW

The TeeWriter for err.

This TeeWriter is finally connected to err for getting output.

Its own output (2) is connected via esw to System.err. The branching to the other output may be set by setOut1() if needed.

esw

protected volatile OutputStreamWriter esw

The OutputStreamWriter decorating System.err .

It will be made using the default code page CONSOL_ENCODING.

See Also:

setErrCodePage()

out

public final PrintWriter out

The standard output as PrintWriter.

This Writer is a (better) substitute for the byte Stream System.out, which it is connected to by osw and outTW.

This features a comfortable and robust normal output. By de-coupling it will not block the application if the console output is blocked.

Hint: Against some people's unbelief the (Windows) console can easily be blocked for ever by just marking text.

See Also:

setOutCodePage(), in, err, log

osw

protected volatile OutputStreamWriter osw

The OutputStreamWriter decorating System.out .

It will be made using the default code page CONSOL_ENCODING.

See Also:

setOutCodePage()

outTW

public final TeeWriter outTW

The TeeWriter for out.

This TeeWriter is finally connected to outfor getting output.

Its own output (1) is connected via osw to System.out. The branching to the other output may be set by setOut2() if needed.

log

public final PrintWriter log

A log output as PrintWriter.

This Writer feeds via the TeeWriter logTW the (normal) output outTW and optionally a (log) file.

If needed use setLogOut2() to set the second output to whatever (usually a file).

See Also:

in, out, err

logTW

public final TeeWriter logTW

The TeeWriter connected to the PrintWriter log .

cp2

protected String cp2

The TeeWriter's log encoding for its second output stream.

If the TeeWriter's logTW second output was set with an explicit encoding it is stored here.

default: null

logDat

protected volatile String logDat

The name of a log file (if given / used).

The file name the logFile was created / opened with is stored here. null means no extra file logging for log.

default: null

logFile

protected volatile File logFile

The log file (if given / used).

outDat

protected volatile String outDat

The name of a out file (if given / used).

The named file (if used) takes the outputs to out instead of them going to System.out .

default: "System.out"

outFile

protected volatile File outFile

The out file (if given / used).

codePage

protected volatile String codePage

Code-Page for Reader in and the Writer out and err.

See Also:

getCodePage()

Method Detail

getLogHandler

public final LogWriterHandler getLogHandler()

The Logger handler.

This method delivers a Handler connected to log. It is made on the first call.

closeLogHandler

public final void closeLogHandler()

Closing the Logger handler.

If there is (still) a LogWriterHandler made by getLogHandler(), it will be closed, opted out (if known to it) from an appLogger and cleared away.

getAppLogger

public final Logger getAppLogger()

Base logger for the applications.

This method delivers a basic Logger for the application utilising this AppIO object. The Logger will be made on the first call.

The Logger's name will be "de.frame4j"
In the basic settings made it uses the Handler available by getLogHandler(), and hence a LogTextFormatter object for output to log.
The Level set will be t INFO. If this Logger should have been indirectly via App.getAppLogger() the Level will be set automatically according to App.verbosity. The same applies for logHandler.

This Logger is the last one in a handler chain; that means it will not delegate further to a Java-Logging-API made default Logger, like ConsoleHandler. This would counteract all Frame4J's respectively AppIO's or App's I/O organisation.

getLogDat

public final String getLogDat()

The name of a log file (if given / used).

The file name the logFile was created / opened with is returned here. null means no extra file logging for log.

default: null

getLogFile

public File getLogFile()

The log file (if given / used).

setLogDat

public boolean setLogDat(String name,
                         String encoding,
                         OutMode outMode,
                         boolean logOnLog)

Setting a file for the log output.

Parameters:

name - the file name; null or "null" just means close the actual file.

encoding - character encoding; null or "defaultEncoding" or non implemented ones mean default (system file) encoding.

outMode - Ask, Append, Overwrite or Create

logOnLog - true means do report success or failure on log

Returns:

true on success

getOutDat

public final String getOutDat()

The name of a out file (if given / used).

The named file (if used) takes the outputs to out instead of them going to System.out .

default: "System.out"

getOutFile

public File getOutFile()

The out file (if given / used).

setOutDat

public boolean setOutDat(String name,
                         String encoding,
                         OutMode outMode,
                         boolean logOnLog)

Setting the file fort the output out.

Parameters:

name - the file name; null or "null" just means close the actual file.

encoding - character encoding; null or "defaultEncoding" or non implemented ones mean default (system file) encoding.

outMode - Ask, Append, Overwrite or Create

logOnLog - true means do report success or failure on log

Returns:

true on success

set

public void set(PropMap prop)

Set some properties by a PropMap object.

If prop is null nothing happens.

Otherwise the following properties are taken (if given) from the PropMap object:
logDat, outDat.

get

public static AppIO get(int outBuffLen,
                        int logBuffLen,
                        Object consEncoding)

Make with settings.

An AppIO object is made with setting the buffer sizes of both TeeWriters logTW and outTW as well as the console I/O's encoding.

outTW's output 2 remains unconnected as well as errTW's output 1.

Parameters:

outBuffLen - buffer size out TeeWriter, 1024 to 400000 character, default 20K

logBuffLen - buffer size log TeeWriter, 1024 to 400000 character, default 10K

consEncoding - null: CONSOL_ENCODING;
an other AppIO object: take its settings;
String: names the character encoding for console I/O, "defaultEncoding" or naming a non implemented encoding uses the (file) default encoding.

get

public static AppIO get()

Make with default settings.

If a (singleton) AppIO object exists it is returned. Otherwise it is made with basic default settings.
For console I/O CONSOL_ENCODING is used and the platforms default file encoding for all else.

setLogOut2

public void setLogOut2(OutputStream os2,
                       String cp2)

Set log's second writer as stream.

If there is / was a second writer already it is cleared (flush()) and closed (close()).
os2 will be decorated by a Writer and set as log's second output.

Internal implementation hint: it is logTW's out1.

Parameters:

os2 - The stream to connect to

cp2 - The encoding to use; null will be CONSOL_ENCODING

setLogOut2

public void setLogOut2(Writer wr2)

Set log's second writer as writer.

If there is / was a second writer already it is cleared (flush()) and closed (close()).
wr2 will be set as log's second output.

Internal implementation hint: it is logTW's out1.

Parameters:

wr2 - the Writer to connect to

setOutCodePage

public boolean setOutCodePage(CharSequence codePage)

Set normal out's code page (character encoding).

The TeeWriter's outTW encoding for branch normal output will be changed.
If codePage is empty CONSOL_ENCODING is used.

Parameters:

codePage - encoding to set

Returns:

true on success

setErrCodePage

public boolean setErrCodePage(CharSequence codePage)

Set PrintWriter err's code page (character encoding).

The TeeWriter's errTW encoding for branch normal output will be changed.
If codePage is empty CONSOL_ENCODING is used.

Parameters:

codePage - encoding to set

Returns:

true on success

setInCodePage

public boolean setInCodePage(CharSequence codePage)

Set BufferedReader in's code page (character encoding).

The input's in (normal input) encoding will be changed.
If codePage is empty CONSOL_ENCODING is used.

Parameters:

codePage - encoding to set

Returns:

true on success

getCodePage

public String getCodePage()

Code-Page for Reader in and the Writer out and err.

If the character encoding for Reader in and the Writer out and err are commonly set by setCodePages(CharSequence) the setting is provided here for reference. null means no such or failed setting attempt.

setCodePages

public boolean setCodePages(CharSequence codePage)

Set code-Page for Reader in and the Writer out and err.

If codePage is empty CONSOL_ENCODING is used.

Parameters:

codePage - encoding to set

Returns:

true on success

See Also:

setOutCodePage(), setErrCodePage(), setInCodePage()

toOutln

public PrintWriter toOutln(CharSequence s)

Output only a not empty String as line.

The parameter s will be passed via out.println(), if and only if if is not empty.

Parameters:

s - the character sequence to output to out

Returns:

Writer out

connect

public int connect(OutMode outMode,
                   PropMap prop,
                   boolean askGraf)

Connect the TeeWriter's outputs for log and out by a PropMap.

If properties logDat and / or outDat are file names the will be used and be set as extra branches for the TeeWriters logTW respectively outTW using the appropriate connect..() methods.

If one of these connections fails (due to reject or file problems) this is signalled by return 1 (logDat) respectively return 2 (outDat). Success returns 0.

Besides being the source for the names outDot and logDat prop serves to set the properties of the graphical "file ask window" if that could be needed (askGraf true) (see FileVisitor.AskGrafImpl).

Parameters:

prop - must not be null

outMode - null acts like OutMode.ASK