Class IoBuilder
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
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate boolean
private boolean
private int
private Charset
private String
private InputStream
private Level
private final ExtendedLogger
private Marker
private OutputStream
private Reader
private Writer
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionBuilds a newInputStream
that is wiretapped by its underlying Logger.Builds a newOutputStream
that is backed by a Logger and optionally writes to another OutputStream as well.Builds a newPrintStream
that is backed by a Logger and optionally writes to another OutputStream as well.Builds a newPrintWriter
that is backed by a Logger and optionally writes to another Writer as well.Builds a newReader
that is wiretapped by its underlying Logger.Builds a newWriter
that is backed by a Logger and optionally writes to another Writer as well.filter
(InputStream inputStream) Configures anInputStream
to be wiretapped when building an InputStream.filter
(OutputStream outputStream) Configures anOutputStream
to be written to in addition to the underlying Logger.Configures aReader
to be wiretapped when building a Reader.Configures aWriter
to be written to in addition to the underlying Logger.static IoBuilder
Creates a new builder using a Logger named after the calling Class.static IoBuilder
Creates a new builder using a Logger named after a given Class.static IoBuilder
Creates a new builder using a Logger name.static IoBuilder
Creates a new builder for a givenLogger
.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.setBuffered
(boolean buffered) Enables or disables using a buffered variant of the desired IO class.setBufferSize
(int bufferSize) Configures the buffer size to use when building aBufferedReader
orBufferedInputStream
LoggerStream.setCharset
(Charset charset) Specifies theLevel
to log at.Specifies an optionalMarker
to use in all logging messages.setWrapperClassName
(String fqcn) Specifies the fully qualified class name of the IO wrapper class implementation.
-
Field Details
-
logger
-
level
-
marker
-
fqcn
-
autoFlush
private boolean autoFlush -
buffered
private boolean buffered -
bufferSize
private int bufferSize -
charset
-
reader
-
writer
-
inputStream
-
outputStream
-
-
Constructor Details
-
IoBuilder
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 Details
-
forLogger
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
-