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 booleanprivate booleanprivate intprivate Charsetprivate Stringprivate InputStreamprivate Levelprivate final ExtendedLoggerprivate Markerprivate OutputStreamprivate Readerprivate Writer -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionBuilds a newInputStreamthat is wiretapped by its underlying Logger.Builds a newOutputStreamthat is backed by a Logger and optionally writes to another OutputStream as well.Builds a newPrintStreamthat is backed by a Logger and optionally writes to another OutputStream as well.Builds a newPrintWriterthat is backed by a Logger and optionally writes to another Writer as well.Builds a newReaderthat is wiretapped by its underlying Logger.Builds a newWriterthat is backed by a Logger and optionally writes to another Writer as well.filter(InputStream inputStream) Configures anInputStreamto be wiretapped when building an InputStream.filter(OutputStream outputStream) Configures anOutputStreamto be written to in addition to the underlying Logger.Configures aReaderto be wiretapped when building a Reader.Configures aWriterto be written to in addition to the underlying Logger.static IoBuilderCreates a new builder using a Logger named after the calling Class.static IoBuilderCreates a new builder using a Logger named after a given Class.static IoBuilderCreates a new builder using a Logger name.static IoBuilderCreates a new builder for a givenLogger.setAutoFlush(boolean autoFlush) Indicates whether or not a builtPrintWriterorPrintStreamshould automatically flush when one of theprintln,printf, orformatmethods 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 aBufferedReaderorBufferedInputStreamLoggerStream.setCharset(Charset charset) Specifies theLevelto log at.Specifies an optionalMarkerto 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- theExtendedLoggerto wrap
-
-
Method Details
-
forLogger
Creates a new builder for a givenLogger. The Logger instance must implementExtendedLoggeror an exception will be thrown.- Parameters:
logger- the Logger to wrap into a LoggerStream- Returns:
- a new IoBuilder
- Throws:
UnsupportedOperationException- ifloggerdoes not implementExtendedLoggeror ifloggerisnull
-
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 theLevelto 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 optionalMarkerto 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 builtPrintWriterorPrintStreamshould automatically flush when one of theprintln,printf, orformatmethods are invoked, or when a new line character is printed.- Parameters:
autoFlush- iftrue, thenprintln,printf, andformatwill 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) toBufferedReaderandBufferedInputStreamrespectively. This option does not have any effect on the other built variants.- Parameters:
buffered- indicates whether or not a wrappedInputStreamorReadershould be buffered- Returns:
this
-
setBufferSize
Configures the buffer size to use when building aBufferedReaderorBufferedInputStreamLoggerStream.- 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 aReaderto be wiretapped when building a Reader. This must be set to a non-nullvalue in order to callbuildReader().- Parameters:
reader- the Reader to wiretap- Returns:
this
-
filter
Configures aWriterto 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 anInputStreamto be wiretapped when building an InputStream. This must be set to a non-nullvalue in order to callbuildInputStream().- Parameters:
inputStream- the InputStream to wiretap- Returns:
this
-
filter
Configures anOutputStreamto 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 newReaderthat is wiretapped by its underlying Logger. If buffering is enabled, then aBufferedReaderwill be returned.- Returns:
- a new Reader wiretapped by a Logger
- Throws:
IllegalStateException- if no Reader was configured for this builder
-
buildWriter
Builds a newWriterthat 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
FilterWriterbacked by a Logger
-
buildPrintWriter
Builds a newPrintWriterthat 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 newInputStreamthat is wiretapped by its underlying Logger. If buffering is enabled, then aBufferedInputStreamwill be returned.- Returns:
- a new InputStream wiretapped by a Logger
- Throws:
IllegalStateException- if no InputStream was configured for this builder
-
buildOutputStream
Builds a newOutputStreamthat 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 newPrintStreamthat 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
-