org.apache.logging.log4j.io
Class IoBuilder

java.lang.Object
  org.apache.logging.log4j.io.IoBuilder

public class IoBuilder
extends Object

Builder class to wrap Loggers into Java IO compatible classes.

Both the InputStream/OutputStream and Reader/Writer family of classes are supported. OutputStream and Writer instances can be wrapped by a filtered version of their corresponding classes (FilterOutputStream and FilterWriter) in order to log all lines written to these instances. InputStream and Reader instances can be wrapped by a sort of wiretapped version of their respective classes; all lines read from these instances will be logged.

The main feature, however, is the ability to create a PrintWriter, PrintStream, Writer, BufferedWriter, OutputStream, or BufferedOutputStream that is backed by a Logger. The main inspiration for this feature is the JDBC API which uses a PrintWriter to perform debug logging. In order to properly integrate APIs like JDBC into Log4j, create a PrintWriter using this class.

The IoBuilder support configuration of the logging Level it should use (defaults to the level of the underlying Logger), and an optional Marker. The other configurable objects are explained in more detail below.

Since:

2.1

Constructor Summary

protected

IoBuilder(org.apache.logging.log4j.Logger logger) Constructs a new IoBuilder for the given Logger.

Method Summary

InputStream	buildInputStream() Builds a new InputStream that is wiretapped by its underlying Logger.
OutputStream	buildOutputStream() Builds a new OutputStream that is backed by a Logger and optionally writes to another OutputStream as well.
PrintStream	buildPrintStream() Builds a new PrintStream that is backed by a Logger and optionally writes to another OutputStream as well.
PrintWriter	buildPrintWriter() Builds a new PrintWriter that is backed by a Logger and optionally writes to another Writer as well.
Reader	buildReader() Builds a new Reader that is wiretapped by its underlying Logger.
Writer	buildWriter() Builds a new Writer that is backed by a Logger and optionally writes to another Writer as well.
IoBuilder	filter(InputStream inputStream) Configures an InputStream to be wiretapped when building an InputStream.
IoBuilder	filter(OutputStream outputStream) Configures an OutputStream to be written to in addition to the underlying Logger.
IoBuilder	filter(Reader reader) Configures a Reader to be wiretapped when building a Reader.
IoBuilder	filter(Writer writer) Configures a Writer to be written to in addition to the underlying Logger.
static IoBuilder	forLogger() Creates a new builder using a Logger named after the calling Class.
static IoBuilder	forLogger(Class<?> clazz) Creates a new builder using a Logger named after a given Class.
static IoBuilder	forLogger(org.apache.logging.log4j.Logger logger) Creates a new builder for a given Logger.
static IoBuilder	forLogger(String loggerName) Creates a new builder using a Logger name.
IoBuilder	setAutoFlush(boolean autoFlush) Indicates whether or not a built PrintWriter or PrintStream should automatically flush when one of the println, printf, or format methods are invoked, or when a new line character is printed.
IoBuilder	setBuffered(boolean buffered) Enables or disables using a buffered variant of the desired IO class.
IoBuilder	setBufferSize(int bufferSize) Configures the buffer size to use when building a BufferedReader or BufferedInputStream LoggerStream.
IoBuilder	setCharset(Charset charset) Specifies the character set to use when building an InputStream, OutputStream, or PrintStream.
IoBuilder	setLevel(org.apache.logging.log4j.Level level) Specifies the Level to log at.
IoBuilder	setMarker(org.apache.logging.log4j.Marker marker) Specifies an optional Marker to use in all logging messages.
IoBuilder	setWrapperClassName(String fqcn) Specifies the fully qualified class name of the IO wrapper class implementation.

Methods inherited from class java.lang.Object

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

Constructor Detail

IoBuilder

protected IoBuilder(org.apache.logging.log4j.Logger logger)

Constructs a new IoBuilder for the given Logger. This method is provided for extensibility of this builder class. The static factory methods should be used normally.

Parameters:

logger - the ExtendedLogger to wrap

Method Detail

forLogger

public static IoBuilder forLogger(org.apache.logging.log4j.Logger logger)

Creates a new builder for a given Logger. The Logger instance must implement ExtendedLogger or an exception will be thrown.

Parameters:

logger - the Logger to wrap into a LoggerStream

Returns:

a new IoBuilder

Throws:

UnsupportedOperationException - if logger does not implement ExtendedLogger or if logger is null

forLogger

public static IoBuilder forLogger(String loggerName)

Creates a new builder using a Logger name. The name provided is used to get a Logger from LogManager.getLogger(String) which will be wrapped into a LoggerStream.

Parameters:

loggerName - the name of the Logger to wrap into a LoggerStream

Returns:

a new IoBuilder

forLogger

public static IoBuilder forLogger(Class<?> clazz)

Creates a new builder using a Logger named after a given Class. The Class provided is used to get a Logger from LogManager.getLogger(Class) which will be wrapped into a LoggerStream.

Parameters:

clazz - the Class to use as the Logger name to wrap into a LoggerStream

Returns:

a new IoBuilder

forLogger

public static IoBuilder forLogger()

Creates a new builder using a Logger named after the calling Class. This is equivalent to the following:

     IoBuilder builder = IoBuilder.forLogger(LogManager.getLogger());
 

Returns:

a new IoBuilder

setLevel

public IoBuilder setLevel(org.apache.logging.log4j.Level level)

Specifies the Level to log at. If no Level is configured, then the Level of the wrapped Logger will be used.

Parameters:

level - the Level to use for logging

Returns:

this

setMarker

public IoBuilder setMarker(org.apache.logging.log4j.Marker marker)

Specifies an optional Marker to use in all logging messages. If no Marker is specified, then no Marker will be used.

Parameters:

marker - the Marker to associate with all logging messages

Returns:

this

setWrapperClassName

public IoBuilder setWrapperClassName(String fqcn)

Specifies the fully qualified class name of the IO wrapper class implementation. This method should only be used when making significant extensions to the provided classes in this component and is normally unnecessary.

Parameters:

fqcn - the fully qualified class name of the IO wrapper class being built

Returns:

this

setAutoFlush

public IoBuilder setAutoFlush(boolean autoFlush)

Indicates whether or not a built PrintWriter or PrintStream should automatically flush when one of the println, printf, or format methods are invoked, or when a new line character is printed.

Parameters:

autoFlush - if true, then println, printf, and format will auto flush

Returns:

this

setBuffered

public IoBuilder setBuffered(boolean buffered)

Enables or disables using a buffered variant of the desired IO class. If this is set to true, then the instances returned by buildReader() and buildInputStream() can be safely cast (if necessary) to BufferedReader and BufferedInputStream respectively. This option does not have any effect on the other built variants.

Parameters:

buffered - indicates whether or not a wrapped InputStream or Reader should be buffered

Returns:

this

setBufferSize

public IoBuilder setBufferSize(int bufferSize)

Configures the buffer size to use when building a BufferedReader or BufferedInputStream LoggerStream.

Parameters:

bufferSize - the buffer size to use or a non-positive integer to use the default size

Returns:

this

setCharset

public IoBuilder setCharset(Charset charset)

Specifies the character set to use when building an InputStream, OutputStream, or PrintStream. If no character set is specified, then Charset.defaultCharset() is used.

Parameters:

charset - the character set to use when building an InputStream, OutputStream, or PrintStream

Returns:

this

filter

public IoBuilder filter(Reader reader)

Configures a Reader to be wiretapped when building a Reader. This must be set to a non-null value in order to call buildReader().

Parameters:

reader - the Reader to wiretap

Returns:

this

filter

public IoBuilder filter(Writer writer)

Configures a Writer to be written to in addition to the underlying Logger. If no Writer is specified, then the built Writer or PrintWriter will only write to the underlying Logger.

Parameters:

writer - the Writer to write to in addition to the Logger

Returns:

this

filter

public IoBuilder filter(InputStream inputStream)

Configures an InputStream to be wiretapped when building an InputStream. This must be set to a non-null value in order to call buildInputStream().

Parameters:

inputStream - the InputStream to wiretap

Returns:

this

filter

public IoBuilder filter(OutputStream outputStream)

Configures an OutputStream to be written to in addition to the underlying Logger. If no OutputStream is specified, then the built OutputStream or PrintStream will only write to the underlying Logger.

Parameters:

outputStream - the OutputStream to write to in addition to the Logger

Returns:

this

buildReader

public Reader buildReader()

Builds a new Reader that is wiretapped by its underlying Logger. If buffering is enabled, then a BufferedReader will be returned.

Returns:

a new Reader wiretapped by a Logger

Throws:

IllegalStateException - if no Reader was configured for this builder

buildWriter

public Writer buildWriter()

Builds a new Writer that is backed by a Logger and optionally writes to another Writer as well. If no Writer is configured for this builder, then the returned Writer will only write to its underlying Logger.

Returns:

a new Writer or FilterWriter backed by a Logger

buildPrintWriter

public PrintWriter buildPrintWriter()

Builds a new PrintWriter that is backed by a Logger and optionally writes to another Writer as well. If no Writer is configured for this builder, then the returned PrintWriter will only write to its underlying Logger.

Returns:

a new PrintWriter that optionally writes to another Writer in addition to its underlying Logger

buildInputStream

public InputStream buildInputStream()

Builds a new InputStream that is wiretapped by its underlying Logger. If buffering is enabled, then a BufferedInputStream will be returned.

Returns:

a new InputStream wiretapped by a Logger

Throws:

IllegalStateException - if no InputStream was configured for this builder

buildOutputStream

public OutputStream buildOutputStream()

Builds a new OutputStream that is backed by a Logger and optionally writes to another OutputStream as well. If no OutputStream is configured for this builder, then the returned OutputStream will only write to its underlying Logger.

Returns:

a new OutputStream that optionally writes to another OutputStream in addition to its underlying Logger

buildPrintStream

public PrintStream buildPrintStream()

Builds a new PrintStream that is backed by a Logger and optionally writes to another OutputStream as well. If no OutputStream is configured for this builder, then the returned PrintStream will only write to its underlying Logger.

Returns:

a new PrintStream that optionally writes to another OutputStream in addition to its underlying Logger

Throws:

org.apache.logging.log4j.LoggingException - if the configured character set is unsupported by PrintStream