Interface ReusableMessage

  • All Superinterfaces:
    Message, java.io.Serializable, org.apache.logging.log4j.util.StringBuilderFormattable
    All Known Implementing Classes:
    ReusableObjectMessage, ReusableParameterizedMessage, ReusableSimpleMessage

    public interface ReusableMessage
    extends Message, org.apache.logging.log4j.util.StringBuilderFormattable
    Messages implementing this interface are reused between logging calls.

    If a Message is reusable, downstream components should not hand over this instance to another thread, but extract its content (via the StringBuilderFormattable.formatTo(StringBuilder) method) instead.

    Since:
    2.6
    See Also:
    ReusableMessageFactory
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      short getParameterCount()
      Returns the number of parameters that was used to initialize this reusable message for the current content.
      Message memento()
      Returns an immutable snapshot of the current internal state of this reusable message.
      java.lang.Object[] swapParameters​(java.lang.Object[] emptyReplacement)
      Returns the parameter array that was used to initialize this reusable message and replaces it with the specified array.
      • Methods inherited from interface org.apache.logging.log4j.util.StringBuilderFormattable

        formatTo
    • Method Detail

      • swapParameters

        java.lang.Object[] swapParameters​(java.lang.Object[] emptyReplacement)
        Returns the parameter array that was used to initialize this reusable message and replaces it with the specified array. The returned parameter array will no longer be modified by this reusable message. The specified array is now "owned" by this reusable message and can be modified if necessary for the next log event.

        ReusableMessages that have no parameters return the specified array.

        This method is used by asynchronous loggers to pass the parameter array to a background thread without allocating new objects. The actual number of parameters in the returned array can be determined with getParameterCount().

        Parameters:
        emptyReplacement - the parameter array that can be used for subsequent uses of this reusable message. This replacement array must have at least 10 elements (the number of varargs supported by the Logger API).
        Returns:
        the parameter array for the current message content. This may be a vararg array of any length, or it may be a reusable array of 10 elements used to hold the unrolled vararg parameters.
        See Also:
        getParameterCount()
      • getParameterCount

        short getParameterCount()
        Returns the number of parameters that was used to initialize this reusable message for the current content.

        The parameter array returned by swapParameters(Object[]) may be larger than the actual number of parameters. Callers should use this method to determine how many elements the array contains.

        Returns:
        the current number of parameters
      • memento

        Message memento()
        Returns an immutable snapshot of the current internal state of this reusable message. The returned snapshot will not be affected by subsequent modifications of this reusable message.
        Returns:
        an immutable snapshot of this message