Package org.apache.logging.log4j.io

Class IoBuilder

  • public class IoBuilder
extends java.lang.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 Description
      protected IoBuilder​(Logger logger)
      Constructs a new IoBuilder for the given Logger.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.io.InputStream buildInputStream()
      Builds a new InputStream that is wiretapped by its underlying Logger.
      java.io.OutputStream buildOutputStream()
      Builds a new OutputStream that is backed by a Logger and optionally writes to another OutputStream as well.
      java.io.PrintStream buildPrintStream()
      Builds a new PrintStream that is backed by a Logger and optionally writes to another OutputStream as well.
      java.io.PrintWriter buildPrintWriter()
      Builds a new PrintWriter that is backed by a Logger and optionally writes to another Writer as well.
      java.io.Reader buildReader()
      Builds a new Reader that is wiretapped by its underlying Logger.
      java.io.Writer buildWriter()
      Builds a new Writer that is backed by a Logger and optionally writes to another Writer as well.
      IoBuilder filter​(java.io.InputStream inputStream)
      Configures an InputStream to be wiretapped when building an InputStream.
      IoBuilder filter​(java.io.OutputStream outputStream)
      Configures an OutputStream to be written to in addition to the underlying Logger.
      IoBuilder filter​(java.io.Reader reader)
      Configures a Reader to be wiretapped when building a Reader.
      IoBuilder filter​(java.io.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​(java.lang.Class<?> clazz)
      Creates a new builder using a Logger named after a given Class.
      static IoBuilder forLogger​(java.lang.String loggerName)
      Creates a new builder using a Logger name.
      static IoBuilder forLogger​(Logger logger)
      Creates a new builder for a given Logger.
      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​(java.nio.charset.Charset charset)
      Specifies the character set to use when building an InputStream, OutputStream, or PrintStream.
      IoBuilder setLevel​(Level level)
      Specifies the Level to log at.
      IoBuilder setMarker​(Marker marker)
      Specifies an optional Marker to use in all logging messages.
      IoBuilder setWrapperClassName​(java.lang.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

    • Field Detail

      • level

        private Level level

      • marker

        private Marker marker

      • fqcn

        private java.lang.String fqcn

      • autoFlush

        private boolean autoFlush

      • buffered

        private boolean buffered

      • bufferSize

        private int bufferSize

      • charset

        private java.nio.charset.Charset charset

      • reader

        private java.io.Reader reader

      • writer

        private java.io.Writer writer

      • inputStream

        private java.io.InputStream inputStream

      • outputStream

        private java.io.OutputStream outputStream

    • Constructor Detail

      • 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 Detail

      • 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:
        java.lang.UnsupportedOperationException - if logger does not implement ExtendedLogger or if logger is null

      • forLogger

        public static IoBuilder forLogger​(java.lang.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​(java.lang.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​(java.lang.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​(java.nio.charset.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​(java.io.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​(java.io.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​(java.io.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​(java.io.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 java.io.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:
        java.lang.IllegalStateException - if no Reader was configured for this builder

      • buildWriter

        public java.io.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 java.io.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 java.io.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:
        java.lang.IllegalStateException - if no InputStream was configured for this builder

      • buildOutputStream

        public java.io.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 java.io.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