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

java.lang.Object
- java.io.Writer
- - de.frame4j.io.TeeWriter

All Implemented Interfaces:

Closeable, Flushable, Appendable, AutoCloseable
```
@MinDoc(copyright="Copyright  2001 - 2002, 2009  A. Weinert",
        author="Albrecht Weinert",
        version="V.44",
        lastModified="6.05.2021",
        usage="use where one Writer is handled but two are needed",
        purpose="a Writer that outputs the content to two branches")
public class TeeWriter
extends Writer
```
A branching Writer.

It is a recurring requirement to branch one output to two streams. One standard example are log messages for a (console) output towards a human observer that should or must also go into a log file. Handling this branching at the application programming is cumbersome, hardly maintainable, resource consuming and error-prone. (And it is less trivial as fist sight may reveal.)

Structure and function

A TeeWriter — so called after the capital letter T respectively the Unix tool Tee — is a Writer, that branches the output it receives to up to two other Writers. out1 -- < ----X-[ Thread ]----------- > -- out2 (flush1()) block1() / (flush2()) unBlock1() / / (write()) / -- > ------[ Buffer ]-------/ : :.....- > (getContent()) The TeeWriter's structure

Branching to more than two Writers may be done by cascading / decorating. Extra abilities like line structure and formating (by PrintWriter) etc. will be put once and for all in front of the (first) TeeWriter (decorator pattern). For a decorating PrintWriter, almost always needed, there is a method getPrintWriter(). And the buffering (usually used in line oriented output with good reason) is done in the TeeWriter.

So, besides the basic branching function, a TeeWriter additionally features those functions:
- build in buffering. Prepending a decorating BufferedWriter is never needed.
- snap shoots of the actual buffer (as String). That is used for e.g. for extra display windows showing the last (tail) log outputs.
- De-coupling the output to one of the connected Writers out1 by a Thread. This (plus the internal buffering) the delivering / outputting / working thread is effectively shielded from the "taking qualities" of the first Writer out1.
- Switchability of both output writers without bothering the "front end".
The third point makes TeeWriter a de-coupling, non-blocking and in that sense "better" BufferedWriter.
The last point brings the switching of log files or encodings without the logging / working users having to take notice. Besides the obvious comfort effect, this switching ability allows publishing the used TeeWriter (log writer) as final, so solving a lot of concurrency problems without loosing the hinted flexibility.
For the input side SwitchedReader brings that switchabilty / flexibility, being in this respect only TeeWriter's complement.

Exception handling

It is unwanted, that Exceptions occurring to one of two output Writers out1 or out2 impede the writing to the TeeWriter as whole. So they are caught internally and the methods write(..) and others are free from menaced exceptions. About problems arisen one may extract information via exc1, exc2 and lostChars1.

Buffer flushing

The flushing to the connected Writers may be ordered explicitly by flush1(), flush2() or flush()). A prepended PrintWriter with autoFlush (see getPrintWriter(boolean)) automatically calls flush() at line boundaries.
The TeeWriter itself flushes
- to every connected Writer individually, if its buffered and not yet output share goes above a threshold autoFlushThr
- and additionally for the thread de-coupled Writer out1 every 6.8 s (if something is ready to be output there) respectively as late as every 121 s is noExplFlush1 is set.
The second point ensures the (human) user seeing anything (even not complete lines) after at least 7 seconds or 2 minutes no matter what implicit or explicit flushing is used (or not).

Hints on blocking normal output

It's not so widely known that console / shell outputs (usually taken as System.out or System.err) may block. As a matter of fact a (some Window's at least) console output is blocked for ever by just marking text. (And this quite often happens inadvertently e.g. by mouse movements, may be cause on error about the focus.)
The frequent use case is a long running server application branching to a log file ( out2) and to the console (out1). The latter is just done for the seldom case of a human controller / observer watching. Of course here it would be unwanted to catastrophic if a night-watchman on his round would block the console (which may not be avoided) and hence the server application.

The asymmetry of "Thread de-coupling"

This feature is done only for one (out1) of the both output Writers. The rationale behind is on one hand an expected technical asymmetry of the branches, like console and file in the above example. On the other hand it is an usual asymmetry of the requirements. One of the outputs (the log file in the above example) has to have the guarantee to get all outputs without loosing a single character. If it blocks due to speed problems beyond what buffering can level the outputting thread has to be blocked. It is the responsibility of the user / programmer / start-up operator to use performing and reliable resources (local file on fast and big drive or RAID e.g.) for those purposes.
On the other extra / supplementary / unreliable branches outputs the loosing of output is, of course, not quite desirable but much more acceptable then blocking the application.

TeeWriter's ability to tolerate (erroneous) transitional blocking of out1 allows to use those blocking by will. This is done by the methods (block1() and unBlock1().

© Copyright 1998 - 2003, Albrecht Weinert.
See Also:

App, Input

Field Summary

Fields
Modifier and Type	Field and Description
`int`	`autoFlushThr` The threshold for automatic flushing.
`int`	`buffLen` The buffer's length.
`IOException`	`exc1` The first Writer's last caught exception.
`IOException`	`exc2` The second Writer's last caught exception.
`protected Thread`	`flush1Thread` First Writer's flush thread.
`protected int`	`lostChars1` Number of characters lost by (blocked) first Writer.
`protected int`	`maxBlockTime` Maximum block or jamming time by the first Writer / ms .
`boolean`	`noExplFlush1` The first Writer ignores explicit flush().
`boolean`	`noExplFlush2` The second Writer ignores explicit flush().
`protected Writer`	`out1` The first Writer.
`protected Writer`	`out2` The second Writer.
`protected PrintWriter`	`vPw` The PrintWriter "before" this TeeWriter.

Fields inherited from class java.io.Writer
lock

Constructor Summary

Constructors
Constructor and Description
`TeeWriter(int buffLen, int maxBlockTime)` Make a TeeWriter with no outputs.
`TeeWriter(OutputStream out)` Make a TeeWriter for an OutputStream.
`TeeWriter(Writer writer1)` Make a TeeWriter with one output.
`TeeWriter(Writer writer1, OutputStream os2)` Make a TeeWriter with two outputs.
`TeeWriter(Writer writer1, Writer writer2)` Make a TeeWriter with two outputs.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`block1()` Blocking the first Writer.
`void`	`close()` Close the TeeWriter.
`void`	`close1()` Closing the first Writer.
`void`	`close2()` Closing the second Writer.
`void`	`flush()` Flushing the TeeWriter.
`void`	`flush1()` Flushing the first Writer.
`void`	`flush2()` Flushing the second Writer.
`void`	`forceFlush1()` Flushing the first Writer (forcefully).
`int`	`getBuffLen()` This TeeWriter's buffer length.
`String`	`getContent(int maxLen, boolean early, int maxNLsearch)` The buffer's current content as String.
`int`	`getContentLen()` The buffer's current length / the number of available characters.
`int`	`getLostChars1(boolean doClear)` Number of characters lost by (blocked) first Writer.
`int`	`getMaxBlockTime()` Maximum blocking / jamming time by the first Writer in ms .
`Writer`	`getOut1()` The first Writer.
`Writer`	`getOut2()` The second Writer.
`PrintWriter`	`getPrintWriter(boolean autoflush)` Get the (one) PrintWriter connected to this TeeWriter.
`boolean`	`isClosed()` Closed and dead.
`boolean`	`isOpen()` Not yet closed / still usable.
`void`	`setMaxBlockTime(int maxBlockTime)` Set maximum Block or jamming time by the first Writer / ms .
`TeeWriter`	`setOut1(OutputStream os1)` Setting / connecting the first Writer as OutputStream.
`TeeWriter`	`setOut1(OutputStream os1, CharSequence cp1)` Setting / connecting the first Writer.
`TeeWriter`	`setOut1(Writer wr1)` Setting / connecting the first Writer.
`TeeWriter`	`setOut2(OutputStream os2)` Setting the second Writer as OutputStream.
`TeeWriter`	`setOut2(OutputStream os2, CharSequence cp2)` Setting the second Writer.
`TeeWriter`	`setOut2(Writer wr2)` Setting the second Writer.
`TeeWriter`	`switchOut1(Writer wr1)` Switching the first Writer.
`void`	`unBlock1()` Unblocking the first Writer.
`void`	`write(char c)` Output a character (char) to the TeeWriter.
`void`	`write(char[] cbuf, int off, int len)` Output a char[] to the TeeWriter.
`void`	`write(int ic)` Output a character (char provided as int) to the TeeWriter.

Methods inherited from class java.io.Writer
append, append, append, write, write, write

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

- Field Detail
  - vPw
```
protected volatile PrintWriter vPw
```
    The PrintWriter "before" this TeeWriter.
    
    See Also:
    
    getPrintWriter()
  - buffLen
```
public final int buffLen
```
    The buffer's length.
    
    See Also:
    
    getBuffLen()
  - autoFlushThr
```
public final int autoFlushThr
```
    The threshold for automatic flushing.
    
    If at least autoFlushThr characters are held back in the buffer from one of the output writers it will be flushed.
    Set to about 70% of the buffer's size (buffLen).
  - out1
```
protected volatile Writer out1
```
    The first Writer.
    
    This is one branch for the output.
  - exc1
```
public volatile IOException exc1
```
    The first Writer's last caught exception.
    
    This will be set by every caught exception of out1. It may be reset by the application. It is reset if out1 is switched.
  - noExplFlush1
```
public volatile boolean noExplFlush1
```
    The first Writer ignores explicit flush().
    
    If noExplFlush1 is true, explicit calls of flush() (flush1()) will not be executed any more for out1. Hence the output behind will receive any calls quite seldom using TeeWriter's and out1's buffering (if given) much more efficiently.
    
    The (internal) decoupling thread so efficiently becomes a background thread outputting large amounts seldom. This setting is only suitable for a non visible branch of the TeeWriter (a log file e.g) due to the latency. It restricts the effect of flushing the TeeWriter to it's other branch out2.
    
    Hint: Remember that the decoupled out1 is normally taken for the visible branch blockable by humans (like standard out).
  - flush1Thread
```
protected Thread flush1Thread
```
    First Writer's flush thread.
  - maxBlockTime
```
protected int maxBlockTime
```
    Maximum block or jamming time by the first Writer / ms .
    
    See Also:
    
    getMaxBlockTime()
  - lostChars1
```
protected int lostChars1
```
    Number of characters lost by (blocked) first Writer.
    
    See Also:
    
    getLostChars1(boolean)
  - out2
```
protected volatile Writer out2
```
    The second Writer.
    
    This is the second branch for the output.
  - exc2
```
public volatile IOException exc2
```
    The second Writer's last caught exception.
    
    This will be set by every caught exception of out2. It may be reset by the application. It is reset if out2 is switched.
  - noExplFlush2
```
public volatile boolean noExplFlush2
```
    The second Writer ignores explicit flush().
    
    If noExplFlush2 is true, explicit calls of flush() (flush2()) will not be executed any more for out2. The effect will be out2's not receiving further calls.
    
    In contrast to noExplFlush1 this noExplFlush2 will be (automatic) reset by the following events:
    - close2() close()
    - setOut2()
    - reaching the autoflush threshold autoFlushThr i(in the buffer)
    As out2 has no decoupling thread this auto reset avoids a jamming of the TeeWriter due to noExplFlush2.
- Constructor Detail
  - TeeWriter
```
public TeeWriter(OutputStream out)
```
    Make a TeeWriter for an OutputStream.
    
    A TeeWriter is made and its first output Writer is connected to the Stream out supplied as parameter using the default encoding.
    
    The call is equivalent to: new TeeWriter(new OutputStreamWriter(out)).
    
    Parameters:
    
    out - the stream to be used as one T output
    
    Throws:
    
    NullPointerException - if out is null
  - TeeWriter
```
public TeeWriter(Writer writer1)
```
    Make a TeeWriter with one output.
    
    A TeeWriter is made and its first output Writer is connected to the supplied writer1.
    
    The internal buffer size buffLen is set to 20480 characters and the maximal blocking time maxBlockTime to 50 ms.
    
    Parameters:
    
    writer1 - the Writer to be used as one T output
  - TeeWriter
```
public TeeWriter(Writer writer1,
                 Writer writer2)
```
    Make a TeeWriter with two outputs.
    
    A TeeWriter is made and its two outputs / branches are connected to the supplied writer1 and writer2.
    
    Parameters:
    
    writer1 - the Writer to be used as one T output
    
    writer2 - the Writer to be used as second T output
  - TeeWriter
```
public TeeWriter(Writer writer1,
                 OutputStream os2)
```
    Make a TeeWriter with two outputs.
    
    A TeeWriter is made and its two outputs / branches are connected to the supplied Writer writer1 and OutputStream os2, the latter using default encoding.
    
    Parameters:
    
    writer1 - the Writer to be used as one T output
    
    os2 - the stream to be used as second T output
  - TeeWriter
```
public TeeWriter(int buffLen,
                 int maxBlockTime)
```
    Make a TeeWriter with no outputs.
    
    A TeeWriter is made and its two outputs are unconnected.
    
    The internal buffer size buffLen and the maximal blocking time are set according to the supplied parameter values.
    
    The buffer size is limited to the range 1024 .. 40000.
    
    Parameters:
    
    maxBlockTime - new maximal blocking time in ms; limited to 4...9800
    
    buffLen - the buffer size (1025 .. 400001)
    
    See Also:
    
    setMaxBlockTime(int)
- Method Detail
  - getPrintWriter
```
public PrintWriter getPrintWriter(boolean autoflush)
```
    Get the (one) PrintWriter connected to this TeeWriter.
    
    This method gets one PrintWriter set as decorator in front of this TeeWriter. It is made on the first call.
    
    Parameters:
    
    autoflush - if true, the println, printf, or format methods will flush the output buffer
  - isClosed
```
public boolean isClosed()
```
    Closed and dead.
    
    Returns true , if this TeeWriter was closed.
    
    You cannot output to a closed TeeWriter. The methods write(), flush..() and close() don't do anything at all in this state. Only buffer content (if there) can be retrieved by getContent() and getContentLen().
    
    Returns:
    
    true if already closed
    
    See Also:
    
    close()
  - isOpen
```
public boolean isOpen()
```
    Not yet closed / still usable.
    
    Returns false if this TeeWriter was closed.
    
    Returns:
    
    true if still open (and hopefully usable)
    
    See Also:
    
    close(), isClosed(), Channel.isOpen()
  - close
```
public void close()
```
    Close the TeeWriter.
    
    After closing the TeeWriter is "dead", see isClosed().
    
    If there are (decorating) prepended Writers the most in front of those should get the close() and not this TeeWriter directly. For the PrintWriter made / got by getPrintWriter() this is not necessary.
    
    Exceptions are caught silently.
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    Specified by:
    
    close in class Writer
    
    See Also:
    
    isClosed()
  - getBuffLen
```
public final int getBuffLen()
```
    This TeeWriter's buffer length.
    
    The TeeWriter buffers its incoming output. The buffers has a size between 1024 and 400000 characters; the default is 20480 (20K).
    
    Returns:
    
    the buffer's size as set finally on construction
    
    See Also:
    
    flush1(), flush2(), flush(), getPrintWriter()
  - getContentLen
```
public final int getContentLen()
```
    The buffer's current length / the number of available characters.
    
    See Also:
    
    write(), close(), getContent()
  - getContent
```
public final String getContent(int maxLen,
                               boolean early,
                               int maxNLsearch)
```
    The buffer's current content as String.
    
    Is the parameter value maxLen more than the actual buffer content size (see getContentLen()) it will be reduced to it. This method returns up to maxLen buffered characters as String. Is early false, the end of the buffer is chosen (the latest output) otherwise the start of the buffer (the oldest output not overwritten yet).
    
    If maxNLsearch is greater than 0 and less than 1/3 of the (may be reduced) maxLen the start and end of chosen buffer range is shortened by at most maxNLsearch character to let the String returned start and end at line borders. (80 .. 150 are a good choices). no such clipping occurs on very first or very last (before close) output.
    
    If the buffer has no content or if maxLen is <= 0, the empty String is returned.
    
    See Also:
    
    write(), getContentLen()
  - getOut1
```
public Writer getOut1()
```
    The first Writer.
    
    The associated Writers out1 and out2 would normally not be used or controlled directly. Whenever possible use setOut1(), setOut2(), flush1(), flush2(), close1() and close2() instead.
  - block1
```
public void block1()
```
    Blocking the first Writer.
    
    One branch out1 of the TeeWriter shall be blocked by will. If this blocking is transitional (what it normally should be) it is dismissed by unBlock1().
    
    A block like this enables the undisturbed (transitional) use of the first Writer out1 for other purposes (like e.g. an input dialogue via console).
  - unBlock1
```
public void unBlock1()
```
    Unblocking the first Writer.
    
    If blocked (block1()), the first Writer out1 will be unblocked and flushed (flush1()). If not blocked this method has no effect.
  - close1
```
public void close1()
```
    Closing the first Writer.
  - getMaxBlockTime
```
public final int getMaxBlockTime()
```
    Maximum blocking / jamming time by the first Writer in ms .
    
    If the first Writer out1 blocks and as consequence no further buffering is possible without overriding output not yet forwarded to out1, the whole TeeWriter is blocked at first. This blocking is (forcefully) removed after maxBlockTime milliseconds, even if that would mean loss of (part of) output to out1.
    
    The chance for such losses exists if the output to the TeeWriter (and out2's speed also) is faster than out1 or if out1 is simply jammed.
    If such losses occur (which will be recorded in lostChars1) they can to a certain extend be reduced by larger buffers or longer blocking times. But they are a symptom for out1 being slower than the application requires (and out2 allows).
    
    See Also:
    
    setMaxBlockTime(int)
  - setMaxBlockTime
```
public final void setMaxBlockTime(int maxBlockTime)
```
    Set maximum Block or jamming time by the first Writer / ms .
    
    Parameters:
    
    maxBlockTime - new maximal blocking time in ms; limited to 4...9800
    
    See Also:
    
    getMaxBlockTime()
  - getLostChars1
```
public int getLostChars1(boolean doClear)
```
    Number of characters lost by (blocked) first Writer.
    
    If the first Writer is blocked too long (or just jammed due to dead slowness), it will loose characters to its output (on first buffer round robin after block at latest). The number of lost characters is summed up.
    On closing (close1()) or switching (setOut1()) the first Writer the sum is reset to zero as well as by this method if doClear is true.
  - flush1
```
public void flush1()
```
    Flushing the first Writer.
  - forceFlush1
```
public void forceFlush1()
```
    Flushing the first Writer (forcefully).
    
    In contrast to flush1() this method's effect is not suspended by noExplFlush1.
  - setOut1
```
public TeeWriter setOut1(Writer wr1)
```
    Setting / connecting the first Writer.
    
    If the Parameter wr1 equals an already set Writer (be it 1 or 2) nothing happens.
    
    An existing Writer 1 will be flushed by flush1() (if not blocked) and closed by close1(). If the parameter wr1 is null that was all.
    
    Otherwise wr1 will be set as new Writer 1. It starts not blocked (unBlock1()), even if its predecessor switched from was. The setting noExplFlush1 will be kept unchanged.
    
    Returns:
    
    this TeeWriter (this)
  - switchOut1
```
public TeeWriter switchOut1(Writer wr1)
```
    Switching the first Writer.
    
    If the Parameter wr1 equals an already set Writer (be it 1 or 2) nothing happens. If there is no set Writer 1 yet this method acts like setOut1.
    
    Otherwise — contrary to setOut1 — the former first Writer is just disconnected, i.e neither flushed nor closed. It is replaced on the spot by the Writer wr1 supplied as parameter. All settings remain.
    
    Returns:
    
    this TeeWriter (this)
  - setOut1
```
public TeeWriter setOut1(OutputStream os1)
```
    Setting / connecting the first Writer as OutputStream.
    
    The OutputStream os1 will be decorated by a Writer (default encoding) and connected by setOut1(Writer) as first Writer.
    
    Parameters:
    
    os1 - the OutputStream to use as TeeWriter's first branch
    
    Returns:
    
    this TeeWriter (this)
  - setOut1
```
public TeeWriter setOut1(OutputStream os1,
                         CharSequence cp1)
```
    Setting / connecting the first Writer.
    
    The OutputStream os1 will be decorated by a Writer with the character encoding supplied by cp1 and connected by setOut1(Writer) as first Writer.
    
    Parameters:
    
    os1 - the OutputStream to use as TeeWriter's first branch
    
    cp1 - the encoding. null will be taken Cp850 (Western Windows). A non implemented encoding will be replaced by the default encoding
    
    Returns:
    
    this TeeWriter (this)
  - getOut2
```
public Writer getOut2()
```
    The second Writer.
    
    The associated Writers out1 and out2 would normally not be used or controlled directly. Whenever possible use setOut1(), setOut2(), flush1(), flush2(), close1() and close2() instead.
  - flush2
```
public void flush2()
```
    Flushing the second Writer.
  - close2
```
public void close2()
```
    Closing the second Writer.
  - setOut2
```
public TeeWriter setOut2(Writer wr2)
```
    Setting the second Writer.
    
    If the Parameter wr2 equals an already set Writer (be it 1 or 2) nothing happens.
    
    An existing Writer 2 will be closed by close2(). If the parameter wr2 is null that was all.
    
    Otherwise wr2 will be set as new Writer 2.
    
    Returns:
    
    this TeeWriter (this)
  - setOut2
```
public TeeWriter setOut2(OutputStream os2)
```
    Setting the second Writer as OutputStream.
    
    The OutputStream os2 will be decorated by a Writer (default encoding) and connected by setOut2(decoOs2) as second Writer.
    
    Parameters:
    
    os2 - the OutputStream to use as TeeWriter's second branch
    
    Returns:
    
    this TeeWriter (this)
  - setOut2
```
public TeeWriter setOut2(OutputStream os2,
                         CharSequence cp2)
```
    Setting the second Writer.
    
    The OutputStream os2 will be decorated by a Writer with the character encoding supplied by cp2 and connected by setOut2(Writer) as second Writer.
    
    Parameters:
    
    os2 - the OutputStream to use as TeeWriter's second branch
    
    cp2 - the encoding. null will be taken Cp850 (Western Windows). A not implemented encoding will be replaced by the default encoding
    
    Returns:
    
    this TeeWriter (this)
  - flush
```
public void flush()
```
    Flushing the TeeWriter.
    
    Exceptions by (hopefully only) one of the branches are caught to keep the other ant the TeeWriter operable.
    
    Specified by:
    
    flush in interface Flushable
    
    Specified by:
    
    flush in class Writer
  - write
```
public void write(char[] cbuf,
                  int off,
                  int len)
```
    Output a char[] to the TeeWriter.
    
    This method is used by all other (inherited) Writer's output methods except write(char) and write(int).
    
    Exceptions by (hopefully only) one of the branches are caught to keep the TeeWriter's other arm operable.
    
    Specified by:
    
    write in class Writer
  - write
```
public void write(int ic)
```
    Output a character (char provided as int) to the TeeWriter.
    
    This method outputs the lower 16 Bit of ic as character (char) to this TeeWriter. The effect is like write((char) ic)
    Exceptions are caught.
    
    Overrides:
    
    write in class Writer
  - write
```
public void write(char c)
```
    Output a character (char) to the TeeWriter.
    
    This method outputs just one character extensively using the using the TeeWriters buffer. This method only flushes if one of the branches runs down to zero buffer space. The rationale behind is acceptable performance of not clever but sometimes easier looping over single character outputs.
    
    Exceptions are caught silently.

Class TeeWriter

Field Summary

Fields inherited from class java.io.Writer

Constructor Summary

Method Summary

Methods inherited from class java.io.Writer

Methods inherited from class java.lang.Object

Field Detail

vPw

buffLen

autoFlushThr

out1

exc1

noExplFlush1

flush1Thread

maxBlockTime

lostChars1

out2

exc2

noExplFlush2

Constructor Detail

TeeWriter

TeeWriter

TeeWriter

TeeWriter

TeeWriter

Method Detail

getPrintWriter

isClosed

isOpen

close

getBuffLen

getContentLen

getContent

getOut1

block1

unBlock1

close1

getMaxBlockTime

setMaxBlockTime

getLostChars1

flush1

forceFlush1

setOut1

switchOut1

setOut1

setOut1

getOut2

flush2

close2

setOut2

setOut2

setOut2

flush

write

write

write