Class IoBuilder
- java.lang.Object
-
- org.apache.logging.log4j.io.IoBuilder
-
public class IoBuilder extends Object
Builder class to wrapLoggers
into Java IO compatible classes.Both the
InputStream
/OutputStream
andReader
/Writer
family of classes are supported.OutputStream
andWriter
instances can be wrapped by a filtered version of their corresponding classes (FilterOutputStream
andFilterWriter
) in order to log all lines written to these instances.InputStream
andReader
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
, orBufferedOutputStream
that is backed by aLogger
. 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 optionalMarker
. The other configurable objects are explained in more detail below.- Since:
- 2.1
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description InputStream
buildInputStream()
Builds a newInputStream
that is wiretapped by its underlying Logger.OutputStream
buildOutputStream()
Builds a newOutputStream
that is backed by a Logger and optionally writes to another OutputStream as well.PrintStream
buildPrintStream()
Builds a newPrintStream
that is backed by a Logger and optionally writes to another OutputStream as well.PrintWriter
buildPrintWriter()
Builds a newPrintWriter
that is backed by a Logger and optionally writes to another Writer as well.Reader
buildReader()
Builds a newReader
that is wiretapped by its underlying Logger.Writer
buildWriter()
Builds a newWriter
that is backed by a Logger and optionally writes to another Writer as well.IoBuilder
filter(InputStream inputStream)
Configures anInputStream
to be wiretapped when building an InputStream.IoBuilder
filter(OutputStream outputStream)
Configures anOutputStream
to be written to in addition to the underlying Logger.IoBuilder
filter(Reader reader)
Configures aReader
to be wiretapped when building a Reader.IoBuilder
filter(Writer writer)
Configures aWriter
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(String loggerName)
Creates a new builder using a Logger name.static IoBuilder
forLogger(Logger logger)
Creates a new builder for a givenLogger
.IoBuilder
setAutoFlush(boolean autoFlush)
Indicates whether or not a builtPrintWriter
orPrintStream
should automatically flush when one of theprintln
,printf
, orformat
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 aBufferedReader
orBufferedInputStream
LoggerStream.IoBuilder
setCharset(Charset charset)
IoBuilder
setLevel(Level level)
Specifies theLevel
to log at.IoBuilder
setMarker(Marker marker)
Specifies an optionalMarker
to use in all logging messages.IoBuilder
setWrapperClassName(String fqcn)
Specifies the fully qualified class name of the IO wrapper class implementation.
-
-
-
Constructor Detail
-
IoBuilder
protected IoBuilder(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
- theExtendedLogger
to wrap
-
-
Method Detail
-
forLogger
public static IoBuilder forLogger(Logger logger)
Creates a new builder for a givenLogger
. The Logger instance must implementExtendedLogger
or an exception will be thrown.- Parameters:
logger
- the Logger to wrap into a LoggerStream- Returns:
- a new IoBuilder
- Throws:
UnsupportedOperationException
- iflogger
does not implementExtendedLogger
or iflogger
isnull
-
forLogger
public static IoBuilder forLogger(String loggerName)
Creates a new builder using a Logger name. The name provided is used to get a Logger fromLogManager.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 fromLogManager.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(Level level)
Specifies theLevel
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(Marker marker)
Specifies an optionalMarker
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 builtPrintWriter
orPrintStream
should automatically flush when one of theprintln
,printf
, orformat
methods are invoked, or when a new line character is printed.- Parameters:
autoFlush
- iftrue
, thenprintln
,printf
, andformat
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 totrue
, then the instances returned bybuildReader()
andbuildInputStream()
can be safely cast (if necessary) toBufferedReader
andBufferedInputStream
respectively. This option does not have any effect on the other built variants.- Parameters:
buffered
- indicates whether or not a wrappedInputStream
orReader
should be buffered- Returns:
this
-
setBufferSize
public IoBuilder setBufferSize(int bufferSize)
Configures the buffer size to use when building aBufferedReader
orBufferedInputStream
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 anInputStream
,OutputStream
, orPrintStream
. If no character set is specified, thenCharset.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 aReader
to be wiretapped when building a Reader. This must be set to a non-null
value in order to callbuildReader()
.- Parameters:
reader
- the Reader to wiretap- Returns:
this
-
filter
public IoBuilder filter(Writer writer)
Configures aWriter
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 anInputStream
to be wiretapped when building an InputStream. This must be set to a non-null
value in order to callbuildInputStream()
.- Parameters:
inputStream
- the InputStream to wiretap- Returns:
this
-
filter
public IoBuilder filter(OutputStream outputStream)
Configures anOutputStream
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 newReader
that is wiretapped by its underlying Logger. If buffering is enabled, then aBufferedReader
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 newWriter
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 newPrintWriter
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 newInputStream
that is wiretapped by its underlying Logger. If buffering is enabled, then aBufferedInputStream
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 newOutputStream
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 newPrintStream
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:
LoggingException
- if the configured character set is unsupported byPrintStream
-
-