<document>
	<!-- 
		
		Warning: do not use any auto-format function on this file.
		Since "source" divs use pre as white-space, it affects the
		look of the code parts in this document.
		
	-->


	<body>
		<h2>Chapter 5: Layouts</h2>
		<div class="author">
			Authors: Ceki G&#252;lc&#252;, S&#233;bastien Pennec
		</div>


		<table>
			<tr>
				<td valign="top" align="top">
						<a rel="license"
							href="http://creativecommons.org/licenses/by-nc-sa/2.5/">
							<img alt="Creative Commons License"
								style="border-width: 0"
								src="http://creativecommons.org/images/public/somerights20.png" />
						</a>
				</td>
				<td>
					<p>Copyright &#169; 2000-2006, QOS.ch</p>

					<p>
						<!--Creative Commons License-->
						This work is licensed under a
						<a rel="license"
							href="http://creativecommons.org/licenses/by-nc-sa/2.5/">
							Creative Commons
							Attribution-NonCommercial-ShareAlike 2.5
							License
						</a>
						.
						<!--/Creative Commons License-->
					</p>
				</td>
			</tr>
		</table>

		<h2>What is a layout</h2>

		<p>
			While appenders are responsible for writing logging output
			to an appender dependent device, layouts are responsible for
			the format of the output. In case you were wondering,
			layouts have nothing to do with large estates in Florida.
			The
			<code>format()</code>
			method in the Layout class takes a object that represents
			the logging event and returns a String. A synopsis of the
			Layout interface is shown below.
		</p>
		<div class="source">public interface Layout extends ContextAware, LifeCycle {

  String doLayout(Object event);

  String getHeader();

  String getFooter();

  String getContentType();
}</div>
		<p>
			This interface is really simple and yet is sufficent for
			many formatting needs.
		</p>

		<!-- Do we add here something about one's personal implementation of Layout?  -->

		<h2>Logback classic</h2>

		<p>
			As we've seen, a Layout implementation takes as a parameter
			an object that represents a logging event. The typing of the
			parameter to
			<code>Object</code>
			is because logging events may have different ways of being
			designed. In logback classic, a logging event is represented
			by the
			<code>ch.qos.logback.classic.LoggingEvent</code>
			class. Therefore, all layouts in logback classic implement a
			sub-interface of
			<code>Layout</code>
			named
			<code>ClassicLayout</code>
			.
		</p>

		<p>
			Here is what a
			<code>ClassicLayout</code>
			looks like:
		</p>

		<div class="source">public interface ClassicLayout extends Layout {

  String doLayout(LoggingEvent event);

}</div>

		<h3>PatternLayout</h3>

		<p>
			Logback ships with a flexible layout called
			<code>PatternLayout</code>
			. As all classic layouts,
			<code>PatternLayout</code>
			takes a logging event and returns a String. However, the
			returned String can be modified at will by tweaking its
			conversion pattern.
		</p>
		<p>
			The conversion pattern of
			<code>PatternLayout</code>
			is closely related to the conversion pattern of the
			<code>printf()</code>
			function in the C programming language. A conversion pattern
			is composed of literal text and format control expressions
			called conversion specifiers. You are free to insert any
			literal text within the conversion pattern. Each conversion
			specifier starts with a percent sign (%) and is followed by
			optional format modifiers and a conversion word. The
			conversion word controls the type of data to use, e.g.
			logger name, level, date, thread name. The format modifiers
			control such things as field width, padding, and left or
			right justification. The following is a simple example.
		</p>
		<em>
			Example 5.1: Sample usage of a PatternLayout
			(examples/chapter5/PatternSample.java)
		</em>
		<div class="source">public class PatternSample {

  static public void main(String[] args) throws Exception {
    Logger rootLogger = (Logger)
    LoggerFactory.getLogger("root");

    <b>PatternLayout layout = new PatternLayout();
    layout.setPattern("%-5level [%thread]: %message%n");
    layout.start();</b>

    ConsoleAppender appender = new ConsoleAppender();
    appender.setContext(rootLogger.getLoggerContext());
    appender.setLayout(layout); appender.start();

    rootLogger.addAppender(appender);

    rootLogger.debug("Message 1"); 
    rootLogger.warn("Message 2");
  } 
}</div>

		<p>
			The conversion pattern is set to be <em>%-5level [%thread]:
			%message%n</em>. Running PatternSample will yield the following
			output on the console.
		</p>
		<div class="source">DEBUG [main]: Message 1 
WARN  [main]: Message 2</div>
		<p>
			Note that in the conversion pattern <em>%-5level [%thread]:
			%message%n</em> there is no explicit separator between literal
			text and conversion specifiers. When parsing a conversion
			pattern,
			<code>PatternLayout</code>
			is capable of differentiating between literal text (space
			characters, the brackets, colon character) and conversion
			specifiers. In the example above, the conversion specifier
			%-5level means the level of the logging event should be left
			justified to a width of five characters. Format specifiers
			will be explained in a short moment.
		</p>
		<p>
			Some conversion words can handle options. These are informations
			added to the conversion word between braces. A sample conversion
			word with options could be <em>%word{option}</em>. The options that
			are specific to a conversion word will be explained shortly, along with
			the conversion word's definition.
		</p>
		<table border="1" CELLPADDING="8">
			<th>Conversion Word</th>
			<th>Effect</th>

			<tr>
				<td align="center">
					<b>c / l / lo / logger</b>
				</td>

				<td>
					<p>
						Used to output the logger of the logging event.
					</p>
					<p>
						The logger name conversion word can take an
						integer as a first option. This will use
						logback's abbreviation mechanism to display a
						shorter logger name, without loosing it's
						meaning.
					</p>

					<p>The next table should clear things up.</p>

					<table BORDER="1" CELLPADDING="8">

						<tr>
							<th>Conversion Pattern</th>
							<th>Logger name</th>
							<th>Result</th>
						</tr>

						<tr>
							<td>%logger{10}</td>
							<td>mainPackage.sub.sample.Bar</td>
							<td>m.s.s.Bar</td>
						</tr>

						<tr>
							<td>%logger{15}</td>
							<td>mainPackage.sub.sample.Bar</td>
							<td>m.s.sample.Bar</td>
						</tr>

						<tr>
							<td>%logger{16}</td>
							<td>mainPackage.sub.sample.Bar</td>
							<td>m.sub.sample.Bar</td>
						</tr>

						<tr>
							<td>%logger{26}</td>
							<td>mainPackage.sub.sample.Bar</td>
							<td>mainPackage.sub.sample.Bar</td>
						</tr>
					</table>
				</td>
			</tr>
			<tr>
				<td align="center">
					<b>C / class</b>
				</td>

				<td>
					<p>
						Used to output the fully qualified class name of
						the caller issuing the logging request.
					</p>
					<p>
						Just like the previous conversion word, this
						word can take an interger as it's first option
						and use logback's abbreviation mechanisme to
						shorten its output.
					</p>
					<p>
						By default the class name is output in fully
						qualified form.
					</p>
					<p>
						<b>WARNING</b>
						Generating the caller class information is slow.
						Thus, it's use should be avoided unless
						execution speed is not an issue.
					</p>
				</td>
			</tr>

			<tr>
				<td align="center">
					<b>d / date</b>
				</td>
				<td>
					<p>
						Used to output the date of the logging event.
						The date conversion specifier may be followed by
						a set of braces containing a date and time
						pattern strings used by
						<code>java.text.SimpleDateFormat</code>
						.
						<em>ABSOLUTE</em>
						,
						<em>DATE</em>
						or
						<em>ISO8601</em>
						can also be used.
					</p>
					<p>
						For example,
						<b>%d{HH:mm:ss,SSS}</b>
						,
						<b>
							%d{dd&#160;MMM&#160;yyyy&#160;;HH:mm:ss,SSS}
						</b>
						or
						<b>%d{DATE}</b>
						. If no date format specifier is given then
						ISO8601 format is assumed.
					</p>
				</td>
			</tr>

			<tr>
				<td align="center">
					<b>F / file</b>
				</td>

				<td>
					<p>
						Used to output the file name where the logging
						request was issued.
					</p>
					<p>
						<b>WARNING</b>
						Generating caller file information is extremely
						slow. Its use should be avoided unless execution
						speed is not an issue.
					</p>
				</td>
			</tr>

			<tr>
				<td align="center">
					<b>caller</b>
				</td>

				<td>
					<p>
						Used to output location information of the
						caller which generated the logging event.
					</p>
					<p>
						The location information depends on the JVM
						implementation but usually consists of the fully
						qualified name of the calling method followed by
						the caller's source the file name and line
						number between parentheses.
					</p>
					<p>
						A integer can be added to the
						<em>caller</em>
						conversion specifier's options to configure the depth of
						the information to be displayed.
					</p>
					<p>For example, <b>%caller{2}</b> would display the following excerpt:</p>
					
<div class="source">0    [main] DEBUG - logging statement Caller+0	 \
at mainPackage.sub.sample.Bar.sampleMethodName(Bar.java:22)
Caller+1	 at mainPackage.sub.sample.Bar.createLoggingRequest(Bar.java:17)</div>
					<p>And <b>%caller{3}</b> would display this other excerpt:</p>
<div class="source">16   [main] DEBUG - logging statement Caller+0	 \
at mainPackage.sub.sample.Bar.sampleMethodName(Bar.java:22)
Caller+1	 at mainPackage.sub.sample.Bar.createLoggingRequest(Bar.java:17)
Caller+2	 at mainPackage.ConfigTester.main(ConfigTester.java:38)</div>
					
					<p>
						This conversion word can also use evaluators to test logging events
						against a given criteria before creating the output. For example, 
						using <b>%caller{3, CALLER_DISPLAY_EVAL}</b> will display three lines
						of stacktrace, only if the evaluator called <em>CALLER_DISPLAY_EVAL</em>
						returns a <b>positive</b> answer. 
						This behaviour comes from the fact that displaying
						caller data is very expensive, and one should generally not display it
						unless the evaluator would return a positive value.
				</p>
				 <p>Evaluators are described
						further down this document.
					</p>
					<p>
						The location information can be very useful.
						However, it's generation is
						<em>extremely</em>
						slow. It's use should be avoided unless
						execution speed is not an issue.
					</p>
				</td>
			</tr>

			<tr>
				<td align="center">
					<b>L / line</b>
				</td>

				<td>
					<p>
						Used to output the line number from where the
						logging request was issued.
					</p>
					<p>
						<b>WARNING</b>
						Generating caller location information is
						extremely slow. It's use should be avoided
						unless execution speed is not an issue.
					</p>
				</td>
			</tr>


			<tr>
				<td align="center">
					<b>m / msg / message</b>
				</td>
				<td>
					Used to output the application supplied message
					associated with the logging event.
				</td>
			</tr>

			<tr>
				<td align="center">
					<b>M / method</b>
				</td>

				<td>
					<p>
						Used to output the method name where the logging
						request was issued.
					</p>
					<p>
						<b>WARNING</b>
						Generating caller location information is
						extremely slow. It's use should be avoided
						unless execution speed is not an issue.
					</p>
				</td>
			</tr>

			<tr>
				<td align="center">
					<b>n</b>
				</td>

				<td>
					<p>
						Outputs the platform dependent line separator
						character or characters.
					</p>
					<p>
						This conversion word offers practically the
						same performance as using non-portable line
						separator strings such as "\n", or "\r\n". Thus,
						it is the preferred way of specifying a line
						separator.
					</p>
				</td>

			</tr>

			<tr>
				<td align="center">
					<b>p / le / level</b>
				</td>
				<td>Used to output the level of the logging event.</td>
			</tr>

			<tr>

				<td align="center">
					<b>r / relative</b>
				</td>

				<td>
					Used to output the number of milliseconds elapsed
					since the start of the application until the
					creation of the logging event.
				</td>
			</tr>


			<tr>
				<td align="center">
					<b>t / thread</b>
				</td>

				<td>
					Used to output the name of the thread that generated
					the logging event.
				</td>

			</tr>

			<tr>
				<td align="center">
					<b>X / mdc</b>
				</td>

				<td>

					<p>
						Used to output the MDC (mapped diagnostic
						context) associated with the thread that
						generated the logging event.
					</p>
					<p>
						The
						<b>X</b>
						conversion word can be followed by the key
						for the map placed between braces, as in
						<b>%X{clientNumber}</b>
						where
						<code>clientNumber</code>
						is the key. The value in the MDC corresponding
						to the key will be output.
					</p>
					<p>
						If no additional sub-option is specified, then
						the entire contents of the MDC key value pair
						set is output using a format key1=val1,
						key2=val2.
					</p>

					<p>
						See
						<a
							href="http://logback.qos.ch/apidocs/ch/qos/logback/classic/MDC.html">
							MDC
						</a>
						class for more details.
					</p>

				</td>
			</tr>
			<tr>
				<td align="center">
					<b>ex / throwable</b>
				</td>

				<td>
					<p>
						Used to output the Throwable trace that has been
						bound to the LoggingEvent, by default this will
						output the full trace as one would normally find
						by a call to Throwable.printStackTrace(). 
				 </p>
				 <p>The
						throwable conversion word can be followed by an
						option in the form
						<b>%throwable{short}</b>
						which will only output the first line of the
						ThrowableInformation.
					</p>
					
					<p>
						This conversion word can also use evaluators to test logging events
						against a given criteria before creating the output. For example, 
						using <b>%ex{full, EX_DISPLAY_EVAL}</b> will display the full 
						stacktrace of the exception, only if the evaluator called <em>EX_DISPLAY_EVAL</em>
						returns a <b>negative</b> answer. This behaviour comes from the fact that
						throwable data is generally displayed unless the evaluator would 
						return a positive value. Evaluators are described
						further down this document. 
					</p>
				</td>
			</tr>

			<tr>

				<td align="center">
					<b>%</b>
				</td>

				<td>The sequence %% outputs a single percent sign.</td>
			</tr>

		</table>
		<p>
			By default the relevant information is output as is.
			However, with the aid of format modifiers it is possible to
			change the minimum field width, the maximum field width and
			justification.
		</p>
		<p>
			The optional format modifier is placed between the percent
			sign and the conversion character or word.
		</p>
		<p>
			The first optional format modifier is the
			<em>left justification flag</em>
			which is just the minus (-) character. Then comes the
			optional
			<em>minimum field width</em>
			modifier. This is a decimal constant that represents the
			minimum number of characters to output. If the data item
			requires fewer characters, it is padded on either the left
			or the right until the minimum width is reached. The default
			is to pad on the left (right justify) but you can specify
			right padding with the left justification flag. The padding
			character is space. If the data item is larger than the
			minimum field width, the field is expanded to accommodate
			the data. The value is never truncated.
		</p>
		<p>
			This behavior can be changed using the
			<em>maximum field width</em>
			modifier which is designated by a period followed by a
			decimal constant. If the data item is longer than the
			maximum field, then the extra characters are removed from
			the
			<em>beginning</em>
			of the data item and not from the end. For example, it the
			maximum field width is eight and the data item is ten
			characters long, then the first two characters of the data
			item are dropped. This behavior deviates from the printf
			function in C where truncation is done from the end.
		</p>
		<p>
			Below are various format modifier examples for the logger
			conversion specifier.
		</p>

		<table BORDER="1" CELLPADDING="8">
			<th>Format modifier</th>
			<th>Left justify</th>
			<th>Minimum width</th>
			<th>Maximum width</th>
			<th>Comment</th>

			<tr>
				<td align="center">%20l</td>
				<td align="center">false</td>
				<td align="center">20</td>
				<td align="center">none</td>
				<td>
					Left pad with spaces if the category name is less
					than 20 characters long.
				</td>
			</tr>
			<tr>
				<td align="center">%-20l</td>
				<td align="center">true</td>
				<td align="center">20</td>
				<td align="center">none</td>
				<td>
					Right pad with spaces if the logger name is less
					than 20 characters long.
				</td>
			</tr>
			<tr>
				<td align="center">%.30l</td>
				<td align="center">NA</td>
				<td align="center">none</td>
				<td align="center">30</td>
				<td>
					Truncate from the beginning if the logger name is
					longer than 30 characters.
				</td>
			</tr>
			<tr>
				<td align="center">%20.30l</td>
				<td align="center">false</td>
				<td align="center">20</td>
				<td align="center">30</td>
				<td>
					Left pad with spaces if the logger name is shorter
					than 20 characters. However, if logger name is
					longer than 30 characters, then truncate from the
					beginning.
				</td>
			</tr>
			<tr>
				<td align="center">%-20.30l</td>
				<td align="center">true</td>
				<td align="center">20</td>
				<td align="center">30</td>
				<td>
					Right pad with spaces if the logger name is shorter
					than 20 characters. However, if logger name is
					longer than 30 characters, then truncate from the
					beginning.
				</td>
			</tr>
		</table>


		<h3>Option handling</h3>

		<p>
			A conversion specifier can be followed by options between
			braces. We have already seen some of the
			possibilities offered by logback's option handling with, for
			example, the MDC conversion specifier:
			<em>%mdc{someKey}</em>
			.
		</p>
		<p>However, there is more to it than that.</p>

		<p><b>ADD OPTIONS EXAMPLES</b></p>

		<h4>Evaluators</h4>
		<p>
			Another very useful way of adding options to a conversion
			specifier is when
			<code>PatternLayout</code>
			is used with
			<code>EventEvaluators</code>
			.
		</p>
		<p>
			<code>EventEvaluators</code>
			have the responsability to check wether a given event
			matches a given criteria.
		</p>
		<p>
			Let's look at an example using
			<code>EventEvaluators</code>
			. The following configuration file outputs the logging
			events to the console, displaying date, thread, level,
			message and caller data.
		</p>
		<p>
			Since displaying the caller data of a logging event is very
			expensive, this information will be displayed only when the
			logging request comes from a specific logger, and whose
			message contains a certain string. By doing that, we make
			sure that only the most important logging requests will have
			their caller information generated and displayed, without
			penalizing application performance.
		</p>

		<p>
			Here is how to configure logback to behave like we
			described:
		</p>
		<em>
			Example 5.2: Sample usage of EventEvaluators
			(examples/chapter5/callerEvaluatorConfig.xml)
		</em>
		<div class="source">&lt;configuration>
  <b>&lt;evaluator name="DISP_CALLER_EVAL">
    &lt;Expression>logger.getName().contains("chapter5") &amp;amp;&amp;amp; \
      message.contains("stacktrace")&lt;/Expression>
  &lt;/evaluator></b>

  &lt;appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> 
    &lt;layout class="ch.qos.logback.classic.PatternLayout"> 
      &lt;param name="Pattern" value="%-4relative [%thread] %-5level - %msg \
        <b>%caller{2, DISP_CALLER_EVAL}</b>%n" /> 
    &lt;/layout>
  &lt;/appender>

  &lt;root> 
    &lt;level value="debug" /> 
    &lt;appender-ref ref="STDOUT" /> 
  &lt;/root>
&lt;/configuration></div>
		<p>Please note that the &amp; value cannot be written like one would do in a java
		class, because of XML format encoding.</p>
		<p>Let's test this configuration with the following code.</p>
		<em>
			Example 5.2: Sample usage of EventEvaluators
			(examples/chapter5/EventEvaluatorExample.java)
		</em>
		<div class="source">public class CallerEvaluatorExample {

  public static void main(String[] args)  {
    Logger logger = (Logger) LoggerFactory
        .getLogger(CallerEvaluatorExample.class);
    LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();

    try {
      JoranConfigurator configurator = new JoranConfigurator();
      configurator.setContext(lc);
      configurator.doConfigure(args[0]);
    } catch (JoranException je) {
      StatusPrinter.print(lc);
    }

    <b>for (int i = 0; i &lt; 5; i++) {
      if (i == 3) {
        logger.debug("stacktrace logging statement" + i);
      } else {
        logger.debug("logging statement" + i);
      }
    }</b>
  }
}</div>
		<p>
			This excerpt does nothing very fancy. Five logging requests
			are issued, the third one being different from the others.
		</p>
		<p>
			When a logging request is sent, the corresponding logging
			event will pass through the evaluation process. Here,
			obviously, the third request will match the evaluation,
			causing its caller data to be displayed.
		</p>
		<p>
			Here is the output of the
			<code>EventEvaluatorExample</code>
			class.
		</p>
		<div class="source">0    [main] DEBUG - logging statement0 
0    [main] DEBUG - logging statement1 
0    [main] DEBUG - logging statement2 
0    [main] DEBUG - stacktrace logging statement3 Caller+0	 \
  at chapter5.CallerEvaluatorExample.main(CallerEvaluatorExample.java:28)

0    [main] DEBUG - logging statement4 
</div>

		<p>
			Of course, one can change the expression to match one's
			specific situation. An expression testing logger name and
			request level could also be meaningful: all logging requests of
			level <em>WARN</em> and up, coming from a sensible part of an application
			like a financial transaction module, would have their caller data displayed.
		</p>
		<p><b>Important:</b> With the <em>caller</em> conversion specifier, the data is
		displayed when <em>the expression passed to the evaluator is <b>true</b>.</em></p>
		<p>
			Let's look at a different situation. When exceptions are
			added to a logging request, they are usually displayed. However, in some cases,
			one might want some exceptions never to be displayed.
		</p>
		<p>The java code shown below is creating five log requests, each one
		with an exception. However, we do not want request number 3 to display
		its exception in the logging output.</p>

<div class="source">public class ExceptionEvaluatorExample {

  public static void main(String[] args) {
    Logger logger = (Logger) LoggerFactory
        .getLogger(ExceptionEvaluatorExample.class);
    LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();

    try {
      JoranConfigurator configurator = new JoranConfigurator();
      configurator.setContext(lc);
      configurator.doConfigure(args[0]);
    } catch (JoranException je) {
      StatusPrinter.print(lc);
    }
    <b>for (int i = 0; i &lt; 5; i++) {
      if (i == 3) {
        logger.debug("logging statement " + i, new TestException(
            "do not display this"));
      } else {
        logger.debug("logging statement " + i, new Exception("display"));
      }
    }</b>
  }
}</div>
		
		<p>The following configuration will allow that.</p>
		<em>
			Example 5.3: Sample usage of EventEvaluators
			(examples/chapter5/exceptionEvaluatorConfig.xml)
		</em>
		<div class="source">&lt;configuration>

  <b>&lt;evaluator name="DISPLAY_EX_EVAL">
    &lt;Expression>throwable != null &amp;&amp; throwable instanceof  \
      chapter5.TestException&lt;/Expression>
  &lt;/evaluator></b>
	
  &lt;appender name="STDOUT"
    class="ch.qos.logback.core.ConsoleAppender">
    &lt;layout class="ch.qos.logback.classic.PatternLayout">
      &lt;param name="Pattern"
        value="%-4relative [%thread] %-5level - %msg \
          <b>%ex{full, DISPLAY_EX_EVAL}</b>%n" />
    &lt;/layout>
  &lt;/appender>

  &lt;root>
    &lt;level value="debug" />
    &lt;appender-ref ref="STDOUT" />
  &lt;/root>
&lt;/configuration></div>

		<p>
			With this configuration, each time an instance of the
			<em>chapter5.TestException</em>
			will be associated with a logging request containing an
			exception, no information will be displayed about the
			exception.
		</p>
		<p><b>Important:</b> With the <em>ex</em> conversion specifier, the data is
		displayed when <em>the expression passed to the evaluator is <b>false</b>.</em></p>

		<h3>HTMLLayout</h3>
		<p>HTMLLayout outputs events in an HTML table. Each row of the table corresponds to an event.</p>
		<p>
			The content of the table columns are specified using a
			conversion pattern. See <code>PatternLayout</code> for documentation on
			the available patterns.
		</p>
		<p>One notable point about the use of <code>PatternLayout</code> with <code>HTMLLayout</code>
		is that conversion specifiers should not be separated by a space. Each specifier found in the
		pattern will result in a separate column, meaning that spaces will create empty columns.</p>
		<p>
			The pattern <em>%ex</em>
			used to display an Exception is not the only way to display
			an Exception with this layout. If you use this pattern, a
			table column will be created to display the potential
			Exception's stacktrace.
		</p>
		<p>
			However, a better solution is available in the form of
			implementations of the <code>IThrowableRenderer</code> interface.
			These implementations can be called and assigned to
			HTMLLayout to manage the display of anything related to
			Exceptions.
		</p>
		<p>
			By default, a <code>DefaultThrowableRenderer</code> is
			assigned to the HTMLLayout. It writes the Exception on a new
			table row, along with its stacktrace, in a easily readable
			manner.
		</p>
		<p>
			If one wants to use the
			<em>&amp;ex</em>
			pattern anyway, then a <code>NOPThrowableRenderer</code> can be specified
			in the configuration file.
		</p>
		<p>
			A user-specified external CSS file can be linked to the html
			page. In case one does not want to customize the html
			output, an internal CSS style is used. In that case, the following
			xml element can be nested into the <code>&lt;layout&gt;</code> element.
		</p>
<div class="source">&lt;layout>
  ...
  &lt;cssBuilder class="ch.qos.logback.core.helpers.CssBuilder">
    &lt;param name="url" value="path_to_StyleFile.css" />
  &lt;/cssBuilder>	
  ...
&lt;/layout></div>
		
		<p>
			The HTMLLayout is often used in conjunction with
			SMTPAppender, to send a nicely formatted html email. Of
			course, it can be used with any other Appender.
		</p>
		<p>
			When one wants to use the HTMLLayout with a SMTPAppender,
			the following configuration is typically used.
		</p>
		<div class="source">&lt;configuration&gt;
  &lt;appender name="SMTP" class="ch.qos.logback.classic.net.SMTPAppender"&gt;
    &lt;layout class="ch.qos.logback.classic.html.HTMLLayout"&gt;
      &lt;param name="pattern" value="%relative%thread%mdc%level%class%msg" /&gt;
    &lt;/layout&gt;
    &lt;throwableRenderer class="ch.qos.logback.classic.html.DefaultThrowableRenderer" /&gt;
   &lt;param name="From" value="sender.email@domain.net" /&gt;
   &lt;param name="SMTPHost" value="mail.domain.net" /&gt;
   &lt;param name="Subject" value="LastEvent: %class - %msg" /&gt;
   &lt;param name="To" value="destination.email@domain.net" /&gt;
  &lt;/appender&gt;

  &lt;root&gt;
    &lt;level value="debug" /&gt;
    &lt;appender-ref ref="SMTP" /&gt;
  &lt;/root&gt;
&lt;/configuration&gt;</div>
		<p>
			In this configuration file, the
			<em>throwableRenderer</em>
			element specifies the default implementation of
			IThrowableRenderer. It could be omitted, but is showed for
			educationnal purposes.
		</p>

		<h2>Logback access</h2>
		<p>Just like <code>ClassicLayout</code> represents the <code>Layout</code> interface
		for the classic module, the <code>AccessLayout</code> exists for the access module. It's
		implementation is very straight-forward.</p>
		
		<div class="source">public interface AccessLayout extends Layout {

  String doLayout(AccessEvent event);

}</div>

		<p>Many access layouts are actually adaptations of classic layouts. Logback
		modules classic and access address pretty different needs, but offer the same power
		and flexibility to the user.</p>
		
		<h3>PatternLayout</h3>
		<p>Access' <code>PatternLayout</code> work the exact same way as it's classic counterpart.
		</p>
		<p>However, the conversion specifier are different, giving specific access to request
		and response objects' attributes.</p>
		
		<p>Here are the conversion specifier one can use with logback access 
		<code>PatternLayout</code>.</p>
		
		<table border="1" CELLPADDING="8">
			<th align="center">Conversion Word</th>
			<th align="center">Effect</th>

		<tr>
			<td align="center"><b>a / remoteIP</b></td>
			<td>
				<p>
					Remote IP address.
				</p>
			</td>
		</tr>
		<tr>
			<td align="center"><b>A / localIP</b></td>
			<td>
				<p>
					Local IP address.
				</p>
			</td>
		</tr>		
		<tr>
			<td align="center"><b>b / B / byteSent</b></td>
			<td>
				<p>
					Response's content length.
				</p>
			</td>
		</tr>				
		<tr>
			<td align="center"><b>h / clientHost</b></td>
			<td>
				<p>
					Remote host.
				</p>
			</td>
		</tr>
		<tr>
			<td align="center"><b>H / protocol</b></td>
			<td>
				<p>
					Request protocol.
				</p>
			</td>
		</tr>
    <tr>
      <td align="center"><b>l</b></td>
			<td>
				<p>
					Remote log name. In logback-access, this converter always
					returns the value "-".
				</p>
			</td>
		</tr>

		<tr>
			<td align="center"><b>reqParameter{paramName}</b></td>
			<td>
				<p>
					Parameter of the response.
				</p>
				<p>This conversion word takes the first option in braces and looks
				for the corresponding parameter in the request.</p>
				<p><b>%reqParameter{input_data}</b> 
				displays the corresponding parameter.</p>
			</td>
		</tr>		
		<tr>
			<td align="center"><b>i{header} / header{header}</b></td>
			<td>
				<p>
					Request header.
				</p>
				<p>This conversion word takes the first option in braces and looks
				for the corresponding header in the request.</p>
				<p><b>%header{Referer}</b> displays the referer of the request.</p>
			</td>
		</tr>	
		<tr>
			<td align="center"><b>m / requestMethod</b></td>
			<td>
				<p>
					Request method.
				</p>
			</td>
		</tr>		
		<tr>
			<td align="center"><b>r / requestURL</b></td>
			<td>
				<p>
					URL requested.
				</p>
			</td>
		</tr>
		<tr>
			<td align="center"><b>s / statusCode</b></td>
			<td>
				<p>
					Status code of the request.
				</p>
			</td>
		</tr>		
		<tr>
			<td align="center"><b>t / date</b></td>
			<td>
					<p>
						Used to output the date of the logging event.
						The date conversion specifier may be followed by
						a set of braces containing a date and time
						pattern strings used by
						<code>java.text.SimpleDateFormat</code>
						.
						<em>ABSOLUTE</em>
						,
						<em>DATE</em>
						or
						<em>ISO8601</em>
						can also be used.
					</p>
					<p>
						For example,
						<b>%d{HH:mm:ss,SSS}</b>
						,
						<b>
							%d{dd&#160;MMM&#160;yyyy&#160;;HH:mm:ss,SSS}
						</b>
						or
						<b>%d{DATE}</b>
						. If no date format specifier is given then
						ISO8601 format is assumed.
					</p>
			</td>
		</tr>
		<tr>
			<td align="center"><b>u / user</b></td>
			<td>
				<p>
					Remote user.
				</p>
			</td>
		</tr>		
		<tr>
			<td align="center"><b>U / requestURI</b></td>
			<td>
				<p>
					Requested URI.
				</p>
			</td>
		</tr>		
		<tr>
			<td align="center"><b>v / server</b></td>
			<td>
				<p>
					Server name.
				</p>
			</td>
		</tr>
		<tr>
			<td align="center"><b>localPort</b></td>
			<td>
				<p>
					Local port.
				</p>
			</td>
		</tr>
		<tr>
			<td align="center"><b>reqAttribute{attributeName}</b></td>
			<td>
				<p>
					Attribute of the request.
				</p>^
				<p>This conversion word takes the first option in braces and looks
				for the corresponding attribute in the request.</p>
				<p><b>%reqAttribute{SOME_ATTRIBUTE}</b> 
				displays the corresponding attribute.</p>
			</td>
		</tr>
		<tr>
			<td align="center"><b>reqCookie{cookie}</b></td>
			<td>
				<p>
					Request cookie.
				</p>
				<p>This conversion word takes the first option in braces and looks
				for the corresponding cookie in the request.</p>
				<p><b>%cookie{COOKIE_NAME}</b> displays corresponding cookie.</p>
			</td>
		</tr>
		<tr>
			<td align="center"><b>responseHeader{header}</b></td>
			<td>
				<p>
					Header of the response.
				</p>
				<p>This conversion word takes the first option in braces and looks
				for the corresponding header in the response.</p>
				<p><b>%header{Referer}</b> displays the referer of the response.</p>
			</td>
		</tr>
		</table>
		
		<p>Logback access' <code>PatternLayout</code> also recognize three keywords, which
		act like shortcuts to a certain pattern.</p>

	 <ul>
	 	<p><em>common</em> or <em>CLF</em></p>
	 	<p><em>combined</em></p>
	 	</ul>
	 	
	 	<p>The <em>common</em> keyword corresponds to the pattern <em>%h %l %u %t \"%r\" %s %b</em>
	 	which displays client host, remote log name, user, date, requested URL, status code 
	 	and response's content length</p>
	 	
	 	<p>The <em>combined</em> keyword is a shortcut to 
	 	<em>%h %l %u %t \"%r\" %s %b \"%i{Referer}\" \"%i{User-Agent}\"</em>. This pattern begins
	 	much like the <em>common</em> pattern but also displays two request headers, namely
	 	 referer, and user-agent.</p>

		<h3>HTMLLayout</h3>
		
		<p>The access version of <code>HTMLLayout</code> works like logback classic's
		version.</p>

	</body>
</document>
