IoBuilder (Apache Log4j Streaming Interface 2.3.2 API)

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

Constructors
Modifier Constructor and Description

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

Constructors
Modifier	Constructor and Description
`protected`	`IoBuilder(org.apache.logging.log4j.Logger logger)` Constructs a new IoBuilder for the given Logger.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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

Copyright © 1999-2021 Apache Software Foundation. All Rights Reserved.
Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, the Apache Logging project logo, and the Apache Log4j logo are trademarks of The Apache Software Foundation.

Class IoBuilder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

IoBuilder

Method Detail

forLogger

forLogger

forLogger

forLogger

setLevel

setMarker

setWrapperClassName

setAutoFlush

setBuffered

setBufferSize

setCharset

filter

filter

filter

filter

buildReader

buildWriter

buildPrintWriter

buildInputStream

buildOutputStream

buildPrintStream