Apache Log4j API 2.22.0 · org.apache.logging.log4j.message.Message

An interface for various Message implementations that can be logged. Messages can act as wrappers around Objects so that user can have control over converting Objects to Strings when necessary without requiring complicated formatters and as a way to manipulate the message based on information available at runtime such as the locale of the system.

Custom Message implementations should consider implementing the StringBuilderFormattable interface for more efficient processing. Garbage-free Layouts will call formatTo(StringBuilder) instead of Message#getFormattedMessage() if the Message implements StringBuilderFormattable.

Note

Message objects should not be considered to be thread safe nor should they be assumed to be safely reusable even on the same thread. The logging system may provide information to the Message objects and the Messages might be queued for asynchronous delivery. Thus, any modifications to a Message object by an application should by avoided after the Message has been passed as a parameter on a Logger method.

Method Summary

Modifier and Type	Method and Description
public String	Returns: The message format. Some implementations, such as ParameterizedMessage, will use this as the message "pattern". Other Messages may simply return an empty String. TODO Do all messages have a format? What syntax? Using a Formatter object could be cleaner. (RG) In SimpleMessage the format is identical to the formatted message. In ParameterizedMessage and StructuredDataMessage it is not. It is up to the Message implementer to determine what this method will return. A Formatter is inappropriate as this is very specific to the Message implementation so it isn't clear to me how having a Formatter separate from the Message would be cleaner. getFormat() Gets the format portion of the Message.
public String	Returns: The message String. getFormattedMessage() Gets the Message formatted as a String.
public Object[]	Returns: An array of parameter values or null. getParameters() Gets parameter values, if any.
public Throwable	Returns: the throwable or null. getThrowable() Gets the throwable, if any.

Method Detail

getFormat	back to summary
public String getFormat() Gets the format portion of the Message. Returns:String The message format. Some implementations, such as ParameterizedMessage, will use this as the message "pattern". Other Messages may simply return an empty String. TODO Do all messages have a format? What syntax? Using a Formatter object could be cleaner. (RG) In SimpleMessage the format is identical to the formatted message. In ParameterizedMessage and StructuredDataMessage it is not. It is up to the Message implementer to determine what this method will return. A Formatter is inappropriate as this is very specific to the Message implementation so it isn't clear to me how having a Formatter separate from the Message would be cleaner.

getFormat

back to summary

public String getFormat()

Gets the format portion of the Message.

Returns:String: The message format. Some implementations, such as ParameterizedMessage, will use this as the message "pattern". Other Messages may simply return an empty String. TODO Do all messages have a format? What syntax? Using a Formatter object could be cleaner. (RG) In SimpleMessage the format is identical to the formatted message. In ParameterizedMessage and StructuredDataMessage it is not. It is up to the Message implementer to determine what this method will return. A Formatter is inappropriate as this is very specific to the Message implementation so it isn't clear to me how having a Formatter separate from the Message would be cleaner.

getFormattedMessage back to summary

getFormattedMessage	back to summary
public String getFormattedMessage() Gets the Message formatted as a String. Each Message implementation determines the appropriate way to format the data encapsulated in the Message. Messages that provide more than one way of formatting the Message will implement MultiformatMessage. When configured to log asynchronously, this method is called before the Message is queued, unless this message implements `ReusableMessage` or is annotated with `AsynchronouslyFormattable`. This gives the Message implementation class a chance to create a formatted message String with the current value of any mutable objects. The intention is that the Message implementation caches this formatted message and returns it on subsequent calls. (See LOG4J2-763.) When logging synchronously, this method will not be called for Messages that implement the `StringBuilderFormattable` interface: instead, the `formatTo(StringBuilder)` method will be called so the Message can format its contents without creating intermediate String objects. Returns:String The message String.

public String getFormattedMessage()

Gets the Message formatted as a String. Each Message implementation determines the appropriate way to format the data encapsulated in the Message. Messages that provide more than one way of formatting the Message will implement MultiformatMessage.

When configured to log asynchronously, this method is called before the Message is queued, unless this message implements ReusableMessage or is annotated with AsynchronouslyFormattable. This gives the Message implementation class a chance to create a formatted message String with the current value of any mutable objects. The intention is that the Message implementation caches this formatted message and returns it on subsequent calls. (See LOG4J2-763.)

When logging synchronously, this method will not be called for Messages that implement the StringBuilderFormattable interface: instead, the formatTo(StringBuilder) method will be called so the Message can format its contents without creating intermediate String objects.

Returns:String: The message String.

getParameters	back to summary
public Object[] getParameters() Gets parameter values, if any. Returns:Object[] An array of parameter values or null.

getParameters

back to summary

public Object[] getParameters()

Gets parameter values, if any.

Returns:Object[]: An array of parameter values or null.

getThrowable	back to summary
public Throwable getThrowable() Gets the throwable, if any. Returns:Throwable the throwable or null.

getThrowable

back to summary

public Throwable getThrowable()

Gets the throwable, if any.

Returns:Throwable: the throwable or null.

public Interface Message

Method Summary

Method Detail