Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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`

Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 1999-2015 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.