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
  • Field Details

    • logger

      private final ExtendedLogger logger
    • level

      private Level level
    • marker

      private Marker marker
    • fqcn

      private String fqcn
    • autoFlush

      private boolean autoFlush
    • buffered

      private boolean buffered
    • bufferSize

      private int bufferSize
    • charset

      private Charset charset
    • reader

      private Reader reader
    • writer

      private Writer writer
    • inputStream

      private InputStream inputStream
    • outputStream

      private OutputStream outputStream
  • Constructor Details

    • 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 - the ExtendedLogger to wrap
  • Method Details

    • forLogger

      public static IoBuilder forLogger(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(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(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:
      LoggingException - if the configured character set is unsupported by PrintStream