001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache license, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the license for the specific language governing permissions and 015 * limitations under the license. 016 */ 017package org.apache.logging.log4j.message; 018 019import java.io.Serializable; 020import org.apache.logging.log4j.util.StringBuilderFormattable; 021 022/** 023 * An interface for various Message implementations that can be logged. Messages can act as wrappers 024 * around Objects so that user can have control over converting Objects to Strings when necessary without 025 * requiring complicated formatters and as a way to manipulate the message based on information available 026 * at runtime such as the locale of the system. 027 * <p> 028 * Custom Message implementations should consider implementing the {@link StringBuilderFormattable} 029 * interface for more efficient processing. Garbage-free Layouts will call 030 * {@link StringBuilderFormattable#formatTo(StringBuilder) formatTo(StringBuilder)} instead of 031 * {@link Message#getFormattedMessage()} if the Message implements StringBuilderFormattable. 032 * </p> 033 *<p> 034 * Note: Message objects should not be considered to be thread safe nor should they be assumed to be 035 * safely reusable even on the same thread. The logging system may provide information to the Message 036 * objects and the Messages might be queued for asynchronous delivery. Thus, any modifications to a 037 * Message object by an application should by avoided after the Message has been passed as a parameter on 038 * a Logger method. 039 * </p> 040 * TODO Interfaces should rarely extend Serializable according to Effective Java 2nd Ed pg 291. 041 * (RG) That section also says "If a class or interface exists primarily to participate in a framework that 042 * requires all participants to implement Serializable, then it makes perfect sense for the class or 043 * interface to implement or extend Serializable". Such is the case here as the LogEvent must be Serializable. 044 * 045 * @see StringBuilderFormattable 046 */ 047public interface Message extends Serializable { 048 049 /** 050 * Gets the Message formatted as a String. Each Message implementation determines the 051 * appropriate way to format the data encapsulated in the Message. Messages that provide 052 * more than one way of formatting the Message will implement MultiformatMessage. 053 * <p> 054 * This method will not be called for Messages that implement the 055 * {@link StringBuilderFormattable} interface: instead, the 056 * {@link StringBuilderFormattable#formatTo(StringBuilder) formatTo(StringBuilder)} method will be called so the 057 * Message can format its contents without creating intermediate String objects. 058 * </p> 059 * 060 * @return The message String. 061 */ 062 String getFormattedMessage(); 063 064 /** 065 * Gets the format portion of the Message. 066 * 067 * @return The message format. Some implementations, such as ParameterizedMessage, will use this as 068 * the message "pattern". Other Messages may simply return an empty String. 069 * TODO Do all messages have a format? What syntax? Using a Formatter object could be cleaner. 070 * (RG) In SimpleMessage the format is identical to the formatted message. In ParameterizedMessage and 071 * StructuredDataMessage it is not. It is up to the Message implementer to determine what this 072 * method will return. A Formatter is inappropriate as this is very specific to the Message 073 * implementation so it isn't clear to me how having a Formatter separate from the Message would be cleaner. 074 */ 075 String getFormat(); 076 077 /** 078 * Gets parameter values, if any. 079 * 080 * @return An array of parameter values or null. 081 */ 082 Object[] getParameters(); 083 084 /** 085 * Gets the throwable, if any. 086 * 087 * @return the throwable or null. 088 */ 089 Throwable getThrowable(); 090}