log4j-2.0-beta4/manual/messages.html - logging-log4j-site - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <!-- Generated by Apache Maven Doxia at Jan 28, 2013 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 	<head>
 		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
 		<title>
     Log4j 2 API Messages - Apache Log4j 2</title>
 		<link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" />
 		<link rel="stylesheet" href="../css/site.css" type="text/css" />
 		<script type="text/javascript" src="../js/jquery.min.js"></script>
 		<script type="text/javascript" src="../js/bootstrap.min.js"></script>
 		<script type="text/javascript" src="../js/prettify.min.js"></script>
 		<script type="text/javascript" src="../js/site.js"></script>
 			<meta name="author" content="Ralph Goers" />
 		<meta name="Date-Revision-yyyymmdd" content="20130128" />
 		<meta http-equiv="Content-Language" content="en" />

 				</head>
 	<body class="composite">
 		<img class="logo-left" src="../images/ls-logo.jpg" alt="Apache logging services logo" />
 		<img class="logo-right" src="../images/logo.jpg" alt="Apache log4j logo" />
 		<div class="clear"></div>

 		<div class="navbar">
 			<div class="navbar-inner">
 				<div class="container-fluid">
 					<a class="brand" href="http://logging.apache.org/log4j/2.x/">Apache Log4j 2 &trade;</a>
 						<ul class="nav">
 						<li>


 				<a href="http://wiki.apache.org/logging" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a>
 			</li>
 					<li>


 				<a href="http://www.apache.org/" class="external" target="_blank" title="Apache">Apache</a>
 			</li>
 					<li>
 									<a href="../../../" title="Logging Services">Logging Services</a>
 			</li>
 		</ul>
 				</div>
 			</div>
 		</div>

 		<div class="container-fluid">
 			<table class="layout-table">
 				<tr>
 					<td class="sidebar">
 						<div class="well sidebar-nav">
 										<ul class="nav nav-list">
 								 <li class="nav-header"><i class="icon-home"></i>Apache Log4j™ 2</li>
 																	<li class="none">
 								<a href="../index.html" title="About">About</a>
 			</li>
 										<li class="none">
 								<a href="../download.html" title="Download">Download</a>
 			</li>
 										<li class="none">
 								<a href="../build.html" title="Build and Install">Build and Install</a>
 			</li>
 										<li class="none">
 								<a href="../changelog.html" title="Changelog">Changelog</a>
 			</li>
 							</ul>
 			<ul class="nav nav-list">
 								 <li class="nav-header"><i class="icon-book"></i>Manual</li>
 																	<li class="none">
 								<a href="../manual/index.html" title="Introduction">Introduction</a>
 			</li>
 										<li class="none">
 								<a href="../manual/architecture.html" title="Architecture">Architecture</a>
 			</li>
 										<li class="none">
 								<a href="../manual/migration.html" title="Log4j 1.x Migration">Log4j 1.x Migration</a>
 			</li>
 																																																																												<li class="expanded">
 								<a href="../manual/api.html" title="API">API</a>
 							<ul>
 												<li class="none">
 								<a href="../manual/flowtracing.html" title="Flow Tracing">Flow Tracing</a>
 			</li>
 												<li class="none">
 								<a href="../manual/markers.html" title="Markers">Markers</a>
 			</li>
 												<li class="none">
 								<a href="../manual/eventlogging.html" title="Event Logging">Event Logging</a>
 			</li>
 													<li class="none active">
 								<a href="../manual/messages.html" title="Messages">Messages</a>
 			</li>
 												<li class="none">
 								<a href="../manual/thread-context.html" title="ThreadContext">ThreadContext</a>
 			</li>
 							</ul>
 				</li>
 																																																																																									<li class="collapsed">
 								<a href="../manual/configuration.html" title="Configuration">Configuration</a>
 						</li>
 																																																					<li class="collapsed">
 								<a href="../manual/plugins.html" title="Plugins">Plugins</a>
 						</li>
 																																																																																<li class="collapsed">
 								<a href="../manual/lookups.html" title="Lookups">Lookups</a>
 						</li>
 																																																																																																																																																								<li class="collapsed">
 								<a href="../manual/appenders.html" title="Appenders">Appenders</a>
 						</li>
 																																																																																<li class="collapsed">
 								<a href="../manual/layouts.html" title="Layouts">Layouts</a>
 						</li>
 																																																																																																																				<li class="collapsed">
 								<a href="../manual/filters.html" title="Filters">Filters</a>
 						</li>
 										<li class="none">
 								<a href="../manual/jmx.html" title="JMX">JMX</a>
 			</li>
 										<li class="none">
 								<a href="../manual/logsep.html" title="Logging Separation">Logging Separation</a>
 			</li>
 																																																																																																																				<li class="collapsed">
 								<a href="../manual/extending.html" title="Extending Log4j">Extending Log4j</a>
 						</li>
 							</ul>
 			<ul class="nav nav-list">
 								 <li class="nav-header"><i class="icon-cog"></i>Components</li>
 																	<li class="none">
 								<a href="../log4j-api/index.html" title="API">API</a>
 			</li>
 										<li class="none">
 								<a href="../log4j-core/index.html" title="Implementation">Implementation</a>
 			</li>
 										<li class="none">
 								<a href="../log4j-jcl/index.html" title="Commons Logging Bridge">Commons Logging Bridge</a>
 			</li>
 										<li class="none">
 								<a href="../log4j-1.2-api/index.html" title="Log4J 1.2 API">Log4J 1.2 API</a>
 			</li>
 										<li class="none">
 								<a href="../log4j-slf4j-impl/index.html" title="SLF4J Binding">SLF4J Binding</a>
 			</li>
 										<li class="none">
 								<a href="../log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter">Log4j 2 to SLF4J Adapter</a>
 			</li>
 										<li class="none">
 								<a href="../log4j-flume-ng/index.html" title="Apache Flume">Apache Flume</a>
 			</li>
 										<li class="none">
 								<a href="../log4j-web/index.html" title="Log4j Web">Log4j Web</a>
 			</li>
 							</ul>
 			<ul class="nav nav-list">
 								 <li class="nav-header"><i class="icon-info-sign"></i>Project Information</li>
 																	<li class="none">
 								<a href="../dependencies.html" title="Dependencies">Dependencies</a>
 			</li>
 										<li class="none">
 								<a href="../dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
 			</li>
 										<li class="none">
 								<a href="../dependency-management.html" title="Dependency Management">Dependency Management</a>
 			</li>
 										<li class="none">
 								<a href="../team-list.html" title="Project Team">Project Team</a>
 			</li>
 										<li class="none">
 								<a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a>
 			</li>
 										<li class="none">
 								<a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
 			</li>
 										<li class="none">
 								<a href="../license.html" title="Project License">Project License</a>
 			</li>
 										<li class="none">
 								<a href="../source-repository.html" title="Source Repository">Source Repository</a>
 			</li>
 										<li class="none">
 								<a href="../project-summary.html" title="Project Summary">Project Summary</a>
 			</li>
 							</ul>
 			<ul class="nav nav-list">
 								 <li class="nav-header"><i class="icon-cog"></i>Project Reports</li>
 																	<li class="none">
 								<a href="../changes-report.html" title="Changes Report">Changes Report</a>
 			</li>
 										<li class="none">
 								<a href="../jira-report.html" title="JIRA Report">JIRA Report</a>
 			</li>
 										<li class="none">
 								<a href="../surefire-report.html" title="Surefire Report">Surefire Report</a>
 			</li>
 										<li class="none">
 								<a href="../rat-report.html" title="RAT Report">RAT Report</a>
 			</li>
 							</ul>
 							</div>
 						<div id="poweredBy">
 															<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
 				<img class="poweredBy" alt="Built by Maven" src="../images/maven-feather.png" />
 			</a>
 									</div>
 					</td>
 					<td class="content">
 						<!-- Licensed to the Apache Software Foundation (ASF) under one or more
     contributor license agreements.  See the NOTICE file distributed with
     this work for additional information regarding copyright ownership.
     The ASF licenses this file to You under the Apache License, Version 2.0
     (the "License"); you may not use this file except in compliance with
     the License.  You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing, software
     distributed under the License is distributed on an "AS IS" BASIS,
     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     See the License for the specific language governing permissions and
     limitations under the License. -->

     <div class="section"><h2>Log4j 2 API<a name="Log4j_2_API"></a></h2>
       <a name="Messages"></a>
       <div class="section"><h3>Messages<a name="Messages"></a></h3>
         <p>
           Although Log4j 2 provides Logger methods that accept Strings and Objects, all of these are ulitmately
           captured in Message objects that are then associated with the log event. Applications are free to
           construct Messages of their own and pass them to the Logger. Although it may seem more expensive than
           passing the message format and parameters directly to the event, testing has shown that with modern
           JVMs the cost of creating and destroying events is minor, especially when complex tasks are encapsulated
           in the Message instead of the application. In addition, when using the methods that accept Strings and
           parameters, the underlying Message object will only be created if any configured global filters
           or the Logger's log level allow the message to be processed.
         </p>
         <p>
           Consider an application that has a Map object containing {&quot;Name&quot; = &quot;John Doe&quot;, &quot;Address&quot; = &quot;123 Main
           St.&quot;,
           &quot;Phone&quot; = &quot;(999) 555-1212&quot;} and a User object that has a getId method that returns &quot;jdoe&quot;. The developer
           would like to add an informational message that returns &quot;User John Doe has logged in using id jdoe&quot;. The
           way this could be accomplished is by doing:
         </p>
         <div class="prettyprint"><pre>logger.info(&quot;User {} has logged in using id {}&quot;, map.get(&quot;Name&quot;), user.getId());</pre></div>
         <p>
           While there is nothing inherently wrong with this, as the complexity of the objects and desired output
           increases this technique becomes harder to use. As an alternative, using Messages allows:
         </p>
         <div class="prettyprint"><pre>logger.info(new LoggedInMessage(map, user));</pre></div>
         <p>
           In this alternative the formatting is delegated to the LoggedInMessage object's getFormattedMessage
           method.
           Although in this alternative a new object is created, none of the methods on the objects passed to the
           LoggedInMessage are invoked until the LoggedInMessage is formatted. This is especially useful when an
           Object's toString method does not produce the information you would like to appear in the log.
         </p>
         <p>
           Another advantage to Messages is that they simplify writing Layouts. In other logging frameworks the
           Layout must loop through the parameters individually and determine what to do based on what objects
           are encountered. With Messages the Layout has the option of delegating the formatting to the Message or
           performing its formatting based on the type of Message encountered.
         </p>
         <p>
           Borrowing from the earlier example illustrating Markers to identify SQL statements being logged, Messages
           can also be leveraged. First, the Message is defined.
         </p>
         <div class="prettyprint linenums"><pre>
 public class SQLMessage implements Message {
   public enum SQLType {
       UPDATE,
       QUERY
   };

   prviate final SQLType type;
   private final String table;
   private final Map&lt;String, String&gt; cols;

   public SQLMessage(SQLType type, String table) {
       this(type, table, null);
   }

   public SQLMessage(SQLType type, String table, Map&lt;String, String&gt; cols) {
       this.type = type;
       this.table = table;
       this.cols = cols;
   }

   public String getFormattedMessage() {
       switch (type) {
           case UPDATE:
             return createUpdateString();
             break;
           case QUERY:
             return createQueryString();
             break;
           default;
       }
   }

   public String getMessageFormat() {
       return type + &quot; &quot; + table;
   }

   public Object getParameters() {
       return cols;
   }

   private String createUpdateString() {
   }

   private String createQueryString() {
   }

   private String formatCols(Map&lt;String, String&gt; cols) {
       StringBuilder sb = new StringBuilder();
       boolean first = true;
       for (Map.Entry&lt;String, String&gt; entry : cols.entrySet()) {
           if (!first) {
               sb.append(&quot;, &quot;);
           }
           sb.append(entry.getKey()).append(&quot;=&quot;).append(entry.getValue());
           first = false;
       }
       return sb.toString();
   }
 }</pre></div>
       <p>
         Next we can use the message in our application.
       </p>
         <div class="prettyprint linenums"><pre>
 import org.apache.logging.log4j.Logger;
 import org.apache.logging.log4j.LogManager;
 import java.util.Map;

 public class MyApp {

     private Logger logger = LogManager.getLogger(MyApp.class.getName());
     private static final Marker SQL_MARKER = MarkerManager.getMarker(&quot;SQL&quot;);
     private static final Marker UPDATE_MARKER = MarkerManager.getMarker(&quot;SQL_UPDATE&quot;, SQL_MARKER);
     private static final Marker QUERY_MARKER = MarkerManager.getMarker(&quot;SQL_QUERY&quot;, SQL_MARKER);

     public String doQuery(String table) {
         logger.entry(param);

         logger.debug(QUERY_MARKER, new SQLMessage(SQLMessage.SQLType.QUERY, table);

         return logger.exit();
     }

     public String doUpdate(String table, Map&lt;String, String&gt; params) {
         logger.entry(param);

         logger.debug(UPDATE_MARKER, new SQLMessage(SQLMessage.SQLType.UPDATE, table, parmas);

         return logger.exit();
     }
 }</pre></div>
         <p>
           Notice that in contrast to the prior version of this example, the logger.debug in doUpdate no longer
           needs to be wrapped in an isDebugEnabled call as creation of the SQLMessage is on the same order of
           magnitude of performing that check. Furthermore, all the formatting of the SQL columns is now hidden
           in the SQLMessage instead of having to take place in the business logic. Finally, if desired, Filters
           and/or Layouts can be written to take special action when an SQLMessage is encountered.
         </p>
       <a name="FormattedMessage"></a>
       <div class="section"><h4>FormattedMessage<a name="FormattedMessage"></a></h4>
         <p>
           The message pattern passed to a
           <a href="../log4j-api/apidocs/org/apache/logging/log4j/message/FormattedMessage.html">FormattedMessage</a>
           is first checked to see if it is a valid java.text.MessageFormat pattern. If it is, a MessageFormatMessage is
           used to format it. If not it is next checked to see if it contains any tokens that are valid format
           specifiers for String.format(). If so, a StringFormattedMessage is used to format it. Finally, if the
           pattern doesn't match either of those then a ParameterizedMessage is used to format it.
         </p>
       <a name="LocalizedMessage"></a>
       </div><div class="section"><h4>LocalizedMessage<a name="LocalizedMessage"></a></h4>
         <p>
           <a href="../log4j-api/apidocs/org/apache/logging/log4j/message/LocalizedMessage.html">LocalizedMessage</a>
           is provided primarily to provide compatibility with Log4j 1.x. Generally,
           the best approach to localization is to have the client UI render the events in the client's locale.
         </p>
         <p>
           LocalizedMessage incorporates a ResourceBundle and allows the message pattern parameter to be the key to
           the message pattern in the bundle. If no bundle is specified,
           LocalizedMessage will attempt to locate a bundle with the name of the Logger used to log the event. The
           message retrieved from the bundle will be formatted using a FormattedMessage.
         </p>
       <a name="LoggerNameAwareMessage"></a>
       </div><div class="section"><h4>LoggerNameAwareMessage<a name="LoggerNameAwareMessage"></a></h4>
         <p>
           LoggerNameAwareMessage is an interface with a setLoggerName method. This method will be called during
           event construction so that the Message has the name of the Logger used to log the event when the
           message is being formatted.
         </p>
       <a name="MapMessage"></a>
       </div><div class="section"><h4>MapMessage<a name="MapMessage"></a></h4>
         <p>
           A MapMessage contains a Map of String keys and values. MapMessage implements FormattedMessage and accepts
           a format specifier of &quot;XML&quot;, in which case the Map will be formatted as XML. Otherwise, the Map will be
           formatted as &quot;key1=value1 key2=value2...&quot;.
         </p>
         <a name="MessageFormatMessage"></a>
         </div><div class="section"><h4>MessageFormatMessage<a name="MessageFormatMessage"></a></h4>
         <p>
           <a href="../log4j-api/apidocs/org/apache/logging/log4j/message/MessageFormatMessage.html">MessageFormatMessage</a>
           handles messages that use a <a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/text/MessageFormat.html">conversion format</a>.
           While this Message has more flexibility than ParameterizedMessage, it is also about two times slower.
         </p>
       <a name="MultiformatMessage"></a>
       </div><div class="section"><h4>MultiformatMessage<a name="MultiformatMessage"></a></h4>
         <p>
           A MultiformatMessage will have a getFormats method and a getFormattedMessage method that accepts and array
           of format Strings. The getFormats method may be called by a Layout to provide it information on what
           formatting optionsthe Message supports. The Layout may then call getFormattedMessage with one or more
           for the formats. If the Message doesn't recognize the format name it will simply format the data using its
           default format. An example of this is the StructuredDataMessage which accepts a format String of &quot;XML&quot;
           which will cause it to format the event data as XML instead of the RFC 5424 format.
         </p>
       <a name="ObjectMessage"></a>
       </div><div class="section"><h4>ObjectMessage<a name="ObjectMessage"></a></h4>
         <p>
           Formats an Object by calling its toString method.
         </p>
       <a name="ParameterizedMessage"></a>
       </div><div class="section"><h4>ParameterizedMessage<a name="ParameterizedMessage"></a></h4>
         <p>
           <a href="../log4j-api/apidocs/org/apache/logging/log4j/message/ParameterizedMessage.html">ParameterizedMessage</a>
           handles messages that contain &quot;{}&quot; in the format to represent replaceable tokens and the replacement
           parameters.
         </p>
       <a name="SimpleMessage"></a>
       </div><div class="section"><h4>SimpleMessage<a name="SimpleMessage"></a></h4>
         <p>
           SimpleMessage contains a String that requires no formatting.
         </p>
       <a name="StringFormattedMessage"></a>
       </div><div class="section"><h4>StringFormattedMessage<a name="StringFormattedMessage"></a></h4>
         <p>
           <a href="../log4j-api/apidocs/org/apache/logging/log4j/message/StringFormattedMessage.html">StringFormattedMessage</a>
           handles messages that use a <a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html#syntax">conversion format</a>
           that is compliant with <a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/lang/String.html#format(java.lang.String, java.lang.Object...)">java.lang.String.format()</a>.
           While this Message has more flexibility than ParameterizedMessage, it is also 5 to 10 times slower.
         </p>
       <a name="StructuredDataMessage"></a>
       </div><div class="section"><h4>StructuredDataMessage<a name="StructuredDataMessage"></a></h4>
         <p>
           <a href="../log4j-api/apidocs/org/apache/logging/log4j/message/StructuredDataMessage.html">StructuredDataMessage</a>
           allows applications to add items to a Map as well as set the id to allow a message to be formatted as a
           Structured Data element in accordance with <a class="externalLink" href="http://tools.ietf.org/html/rfc5424">RFC 5424</a>.
         </p>
       <a name="ThreadDumpMessage"></a>
       </div><div class="section"><h4>ThreadDumpMessage<a name="ThreadDumpMessage"></a></h4>
         <p>
           A ThreadDumpMessage, if logged, will generate stack traces for all threads. If running on Java 6+ the
           stack traces will include any locks that are held.
         </p>
       <a name="TimestampMessage"></a>
       </div><div class="section"><h4>TimestampMessage<a name="TimestampMessage"></a></h4>
         <p>
           A TimestampMessage will provide a getTimestamp method that is called during event construction. The
           timestamp in the Message will be used in lieu of the current timestamp.
         </p>
       </div></div>
     </div>


 					</td>
 				</tr>
 			</table>
 		</div>

 		<div class="footer">
 							<p>Copyright &copy; 1999-2013 <a class="external" href="http://www.apache.org">Apache Software Foundation</a>. All Rights Reserved.</p>
 				<p>Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p>
 				<p>Site powered by <a class="external" href="http://twitter.github.com/bootstrap/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p>
 			</div>
 		</div>
 	</body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<!-- Generated by Apache Maven Doxia at Jan 28, 2013 -->
	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>
	Log4j 2 API Messages - Apache Log4j 2</title>
	<link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" />
	<link rel="stylesheet" href="../css/site.css" type="text/css" />
	<script type="text/javascript" src="../js/jquery.min.js"></script>
	<script type="text/javascript" src="../js/bootstrap.min.js"></script>
	<script type="text/javascript" src="../js/prettify.min.js"></script>
	<script type="text/javascript" src="../js/site.js"></script>
	<meta name="author" content="Ralph Goers" />
	<meta name="Date-Revision-yyyymmdd" content="20130128" />
	<meta http-equiv="Content-Language" content="en" />

	</head>
	<body class="composite">
	<img class="logo-left" src="../images/ls-logo.jpg" alt="Apache logging services logo" />
	<img class="logo-right" src="../images/logo.jpg" alt="Apache log4j logo" />
	<div class="clear"></div>

	<div class="navbar">
	<div class="navbar-inner">
	<div class="container-fluid">
	<a class="brand" href="http://logging.apache.org/log4j/2.x/">Apache Log4j 2 ™</a>
	<ul class="nav">
	<li>


	<a href="http://wiki.apache.org/logging" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a>
	</li>
	<li>


	<a href="http://www.apache.org/" class="external" target="_blank" title="Apache">Apache</a>
	</li>
	<li>
	<a href="../../../" title="Logging Services">Logging Services</a>
	</li>
	</ul>
	</div>
	</div>
	</div>

	<div class="container-fluid">
	<table class="layout-table">
	<tr>
	<td class="sidebar">
	<div class="well sidebar-nav">
	<ul class="nav nav-list">
	<li class="nav-header"><i class="icon-home"></i>Apache Log4j™ 2</li>
	<li class="none">
	<a href="../index.html" title="About">About</a>
	</li>
	<li class="none">
	<a href="../download.html" title="Download">Download</a>
	</li>
	<li class="none">
	<a href="../build.html" title="Build and Install">Build and Install</a>
	</li>
	<li class="none">
	<a href="../changelog.html" title="Changelog">Changelog</a>
	</li>
	</ul>
	<ul class="nav nav-list">
	<li class="nav-header"><i class="icon-book"></i>Manual</li>
	<li class="none">
	<a href="../manual/index.html" title="Introduction">Introduction</a>
	</li>
	<li class="none">
	<a href="../manual/architecture.html" title="Architecture">Architecture</a>
	</li>
	<li class="none">
	<a href="../manual/migration.html" title="Log4j 1.x Migration">Log4j 1.x Migration</a>
	</li>
	<li class="expanded">
	<a href="../manual/api.html" title="API">API</a>
	<ul>
	<li class="none">
	<a href="../manual/flowtracing.html" title="Flow Tracing">Flow Tracing</a>
	</li>
	<li class="none">
	<a href="../manual/markers.html" title="Markers">Markers</a>
	</li>
	<li class="none">
	<a href="../manual/eventlogging.html" title="Event Logging">Event Logging</a>
	</li>
	<li class="none active">
	<a href="../manual/messages.html" title="Messages">Messages</a>
	</li>
	<li class="none">
	<a href="../manual/thread-context.html" title="ThreadContext">ThreadContext</a>
	</li>
	</ul>
	</li>
	<li class="collapsed">
	<a href="../manual/configuration.html" title="Configuration">Configuration</a>
	</li>
	<li class="collapsed">
	<a href="../manual/plugins.html" title="Plugins">Plugins</a>
	</li>
	<li class="collapsed">
	<a href="../manual/lookups.html" title="Lookups">Lookups</a>
	</li>
	<li class="collapsed">
	<a href="../manual/appenders.html" title="Appenders">Appenders</a>
	</li>
	<li class="collapsed">
	<a href="../manual/layouts.html" title="Layouts">Layouts</a>
	</li>
	<li class="collapsed">
	<a href="../manual/filters.html" title="Filters">Filters</a>
	</li>
	<li class="none">
	<a href="../manual/jmx.html" title="JMX">JMX</a>
	</li>
	<li class="none">
	<a href="../manual/logsep.html" title="Logging Separation">Logging Separation</a>
	</li>
	<li class="collapsed">
	<a href="../manual/extending.html" title="Extending Log4j">Extending Log4j</a>
	</li>
	</ul>
	<ul class="nav nav-list">
	<li class="nav-header"><i class="icon-cog"></i>Components</li>
	<li class="none">
	<a href="../log4j-api/index.html" title="API">API</a>
	</li>
	<li class="none">
	<a href="../log4j-core/index.html" title="Implementation">Implementation</a>
	</li>
	<li class="none">
	<a href="../log4j-jcl/index.html" title="Commons Logging Bridge">Commons Logging Bridge</a>
	</li>
	<li class="none">
	<a href="../log4j-1.2-api/index.html" title="Log4J 1.2 API">Log4J 1.2 API</a>
	</li>
	<li class="none">
	<a href="../log4j-slf4j-impl/index.html" title="SLF4J Binding">SLF4J Binding</a>
	</li>
	<li class="none">
	<a href="../log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter">Log4j 2 to SLF4J Adapter</a>
	</li>
	<li class="none">
	<a href="../log4j-flume-ng/index.html" title="Apache Flume">Apache Flume</a>
	</li>
	<li class="none">
	<a href="../log4j-web/index.html" title="Log4j Web">Log4j Web</a>
	</li>
	</ul>
	<ul class="nav nav-list">
	<li class="nav-header"><i class="icon-info-sign"></i>Project Information</li>
	<li class="none">
	<a href="../dependencies.html" title="Dependencies">Dependencies</a>
	</li>
	<li class="none">
	<a href="../dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
	</li>
	<li class="none">
	<a href="../dependency-management.html" title="Dependency Management">Dependency Management</a>
	</li>
	<li class="none">
	<a href="../team-list.html" title="Project Team">Project Team</a>
	</li>
	<li class="none">
	<a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a>
	</li>
	<li class="none">
	<a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
	</li>
	<li class="none">
	<a href="../license.html" title="Project License">Project License</a>
	</li>
	<li class="none">
	<a href="../source-repository.html" title="Source Repository">Source Repository</a>
	</li>
	<li class="none">
	<a href="../project-summary.html" title="Project Summary">Project Summary</a>
	</li>
	</ul>
	<ul class="nav nav-list">
	<li class="nav-header"><i class="icon-cog"></i>Project Reports</li>
	<li class="none">
	<a href="../changes-report.html" title="Changes Report">Changes Report</a>
	</li>
	<li class="none">
	<a href="../jira-report.html" title="JIRA Report">JIRA Report</a>
	</li>
	<li class="none">
	<a href="../surefire-report.html" title="Surefire Report">Surefire Report</a>
	</li>
	<li class="none">
	<a href="../rat-report.html" title="RAT Report">RAT Report</a>
	</li>
	</ul>
	</div>
	<div id="poweredBy">
	<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
	<img class="poweredBy" alt="Built by Maven" src="../images/maven-feather.png" />
	</a>
	</div>
	</td>
	<td class="content">
	<!-- Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License. -->

	<div class="section"><h2>Log4j 2 API<a name="Log4j_2_API"></a></h2>
	<a name="Messages"></a>
	<div class="section"><h3>Messages<a name="Messages"></a></h3>
	<p>
	Although Log4j 2 provides Logger methods that accept Strings and Objects, all of these are ulitmately
	captured in Message objects that are then associated with the log event. Applications are free to
	construct Messages of their own and pass them to the Logger. Although it may seem more expensive than
	passing the message format and parameters directly to the event, testing has shown that with modern
	JVMs the cost of creating and destroying events is minor, especially when complex tasks are encapsulated
	in the Message instead of the application. In addition, when using the methods that accept Strings and
	parameters, the underlying Message object will only be created if any configured global filters
	or the Logger's log level allow the message to be processed.
	</p>
	<p>
	Consider an application that has a Map object containing {"Name" = "John Doe", "Address" = "123 Main
	St.",
	"Phone" = "(999) 555-1212"} and a User object that has a getId method that returns "jdoe". The developer
	would like to add an informational message that returns "User John Doe has logged in using id jdoe". The
	way this could be accomplished is by doing:
	</p>
	<div class="prettyprint"><pre>logger.info("User {} has logged in using id {}", map.get("Name"), user.getId());</pre></div>
	<p>
	While there is nothing inherently wrong with this, as the complexity of the objects and desired output
	increases this technique becomes harder to use. As an alternative, using Messages allows:
	</p>
	<div class="prettyprint"><pre>logger.info(new LoggedInMessage(map, user));</pre></div>
	<p>
	In this alternative the formatting is delegated to the LoggedInMessage object's getFormattedMessage
	method.
	Although in this alternative a new object is created, none of the methods on the objects passed to the
	LoggedInMessage are invoked until the LoggedInMessage is formatted. This is especially useful when an
	Object's toString method does not produce the information you would like to appear in the log.
	</p>
	<p>
	Another advantage to Messages is that they simplify writing Layouts. In other logging frameworks the
	Layout must loop through the parameters individually and determine what to do based on what objects
	are encountered. With Messages the Layout has the option of delegating the formatting to the Message or
	performing its formatting based on the type of Message encountered.
	</p>
	<p>
	Borrowing from the earlier example illustrating Markers to identify SQL statements being logged, Messages
	can also be leveraged. First, the Message is defined.
	</p>
	<div class="prettyprint linenums"><pre>
	public class SQLMessage implements Message {
	public enum SQLType {
	UPDATE,
	QUERY
	};

	prviate final SQLType type;
	private final String table;
	private final Map<String, String> cols;

	public SQLMessage(SQLType type, String table) {
	this(type, table, null);
	}

	public SQLMessage(SQLType type, String table, Map<String, String> cols) {
	this.type = type;
	this.table = table;
	this.cols = cols;
	}

	public String getFormattedMessage() {
	switch (type) {
	case UPDATE:
	return createUpdateString();
	break;
	case QUERY:
	return createQueryString();
	break;
	default;
	}
	}

	public String getMessageFormat() {
	return type + " " + table;
	}

	public Object getParameters() {
	return cols;
	}

	private String createUpdateString() {
	}

	private String createQueryString() {
	}

	private String formatCols(Map<String, String> cols) {
	StringBuilder sb = new StringBuilder();
	boolean first = true;
	for (Map.Entry<String, String> entry : cols.entrySet()) {
	if (!first) {
	sb.append(", ");
	}
	sb.append(entry.getKey()).append("=").append(entry.getValue());
	first = false;
	}
	return sb.toString();
	}
	}</pre></div>
	<p>
	Next we can use the message in our application.
	</p>
	<div class="prettyprint linenums"><pre>
	import org.apache.logging.log4j.Logger;
	import org.apache.logging.log4j.LogManager;
	import java.util.Map;

	public class MyApp {

	private Logger logger = LogManager.getLogger(MyApp.class.getName());
	private static final Marker SQL_MARKER = MarkerManager.getMarker("SQL");
	private static final Marker UPDATE_MARKER = MarkerManager.getMarker("SQL_UPDATE", SQL_MARKER);
	private static final Marker QUERY_MARKER = MarkerManager.getMarker("SQL_QUERY", SQL_MARKER);

	public String doQuery(String table) {
	logger.entry(param);

	logger.debug(QUERY_MARKER, new SQLMessage(SQLMessage.SQLType.QUERY, table);

	return logger.exit();
	}

	public String doUpdate(String table, Map<String, String> params) {
	logger.entry(param);

	logger.debug(UPDATE_MARKER, new SQLMessage(SQLMessage.SQLType.UPDATE, table, parmas);

	return logger.exit();
	}
	}</pre></div>
	<p>
	Notice that in contrast to the prior version of this example, the logger.debug in doUpdate no longer
	needs to be wrapped in an isDebugEnabled call as creation of the SQLMessage is on the same order of
	magnitude of performing that check. Furthermore, all the formatting of the SQL columns is now hidden
	in the SQLMessage instead of having to take place in the business logic. Finally, if desired, Filters
	and/or Layouts can be written to take special action when an SQLMessage is encountered.
	</p>
	<a name="FormattedMessage"></a>
	<div class="section"><h4>FormattedMessage<a name="FormattedMessage"></a></h4>
	<p>
	The message pattern passed to a
	<a href="../log4j-api/apidocs/org/apache/logging/log4j/message/FormattedMessage.html">FormattedMessage</a>
	is first checked to see if it is a valid java.text.MessageFormat pattern. If it is, a MessageFormatMessage is
	used to format it. If not it is next checked to see if it contains any tokens that are valid format
	specifiers for String.format(). If so, a StringFormattedMessage is used to format it. Finally, if the
	pattern doesn't match either of those then a ParameterizedMessage is used to format it.
	</p>
	<a name="LocalizedMessage"></a>
	</div><div class="section"><h4>LocalizedMessage<a name="LocalizedMessage"></a></h4>
	<p>
	<a href="../log4j-api/apidocs/org/apache/logging/log4j/message/LocalizedMessage.html">LocalizedMessage</a>
	is provided primarily to provide compatibility with Log4j 1.x. Generally,
	the best approach to localization is to have the client UI render the events in the client's locale.
	</p>
	<p>
	LocalizedMessage incorporates a ResourceBundle and allows the message pattern parameter to be the key to
	the message pattern in the bundle. If no bundle is specified,
	LocalizedMessage will attempt to locate a bundle with the name of the Logger used to log the event. The
	message retrieved from the bundle will be formatted using a FormattedMessage.
	</p>
	<a name="LoggerNameAwareMessage"></a>
	</div><div class="section"><h4>LoggerNameAwareMessage<a name="LoggerNameAwareMessage"></a></h4>
	<p>
	LoggerNameAwareMessage is an interface with a setLoggerName method. This method will be called during
	event construction so that the Message has the name of the Logger used to log the event when the
	message is being formatted.
	</p>
	<a name="MapMessage"></a>
	</div><div class="section"><h4>MapMessage<a name="MapMessage"></a></h4>
	<p>
	A MapMessage contains a Map of String keys and values. MapMessage implements FormattedMessage and accepts
	a format specifier of "XML", in which case the Map will be formatted as XML. Otherwise, the Map will be
	formatted as "key1=value1 key2=value2...".
	</p>
	<a name="MessageFormatMessage"></a>
	</div><div class="section"><h4>MessageFormatMessage<a name="MessageFormatMessage"></a></h4>
	<p>
	<a href="../log4j-api/apidocs/org/apache/logging/log4j/message/MessageFormatMessage.html">MessageFormatMessage</a>
	handles messages that use a <a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/text/MessageFormat.html">conversion format</a>.
	While this Message has more flexibility than ParameterizedMessage, it is also about two times slower.
	</p>
	<a name="MultiformatMessage"></a>
	</div><div class="section"><h4>MultiformatMessage<a name="MultiformatMessage"></a></h4>
	<p>
	A MultiformatMessage will have a getFormats method and a getFormattedMessage method that accepts and array
	of format Strings. The getFormats method may be called by a Layout to provide it information on what
	formatting optionsthe Message supports. The Layout may then call getFormattedMessage with one or more
	for the formats. If the Message doesn't recognize the format name it will simply format the data using its
	default format. An example of this is the StructuredDataMessage which accepts a format String of "XML"
	which will cause it to format the event data as XML instead of the RFC 5424 format.
	</p>
	<a name="ObjectMessage"></a>
	</div><div class="section"><h4>ObjectMessage<a name="ObjectMessage"></a></h4>
	<p>
	Formats an Object by calling its toString method.
	</p>
	<a name="ParameterizedMessage"></a>
	</div><div class="section"><h4>ParameterizedMessage<a name="ParameterizedMessage"></a></h4>
	<p>
	<a href="../log4j-api/apidocs/org/apache/logging/log4j/message/ParameterizedMessage.html">ParameterizedMessage</a>
	handles messages that contain "{}" in the format to represent replaceable tokens and the replacement
	parameters.
	</p>
	<a name="SimpleMessage"></a>
	</div><div class="section"><h4>SimpleMessage<a name="SimpleMessage"></a></h4>
	<p>
	SimpleMessage contains a String that requires no formatting.
	</p>
	<a name="StringFormattedMessage"></a>
	</div><div class="section"><h4>StringFormattedMessage<a name="StringFormattedMessage"></a></h4>
	<p>
	<a href="../log4j-api/apidocs/org/apache/logging/log4j/message/StringFormattedMessage.html">StringFormattedMessage</a>
	handles messages that use a <a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html#syntax">conversion format</a>
	that is compliant with <a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/java/lang/String.html#format(java.lang.String, java.lang.Object...)">java.lang.String.format()</a>.
	While this Message has more flexibility than ParameterizedMessage, it is also 5 to 10 times slower.
	</p>
	<a name="StructuredDataMessage"></a>
	</div><div class="section"><h4>StructuredDataMessage<a name="StructuredDataMessage"></a></h4>
	<p>
	<a href="../log4j-api/apidocs/org/apache/logging/log4j/message/StructuredDataMessage.html">StructuredDataMessage</a>
	allows applications to add items to a Map as well as set the id to allow a message to be formatted as a
	Structured Data element in accordance with <a class="externalLink" href="http://tools.ietf.org/html/rfc5424">RFC 5424</a>.
	</p>
	<a name="ThreadDumpMessage"></a>
	</div><div class="section"><h4>ThreadDumpMessage<a name="ThreadDumpMessage"></a></h4>
	<p>
	A ThreadDumpMessage, if logged, will generate stack traces for all threads. If running on Java 6+ the
	stack traces will include any locks that are held.
	</p>
	<a name="TimestampMessage"></a>
	</div><div class="section"><h4>TimestampMessage<a name="TimestampMessage"></a></h4>
	<p>
	A TimestampMessage will provide a getTimestamp method that is called during event construction. The
	timestamp in the Message will be used in lieu of the current timestamp.
	</p>
	</div></div>
	</div>


	</td>
	</tr>
	</table>
	</div>

	<div class="footer">
	<p>Copyright © 1999-2013 <a class="external" href="http://www.apache.org">Apache Software Foundation</a>. All Rights Reserved.</p>
	<p>Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p>
	<p>Site powered by <a class="external" href="http://twitter.github.com/bootstrap/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p>
	</div>
	</div>
	</body>
	</html>