<?xml version="1.0"?>
<!-- 
/*
 * Copyright 2001-2004 The Apache Software Foundation.
 * 
 * Licensed 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.
 */
 -->

<document>

 <properties>
  <title>Turbine Services - Logging Service</title>
 </properties>

<body>

<section name="Logging Service">

<p>
Turbine's logging service is exceptionally powerful. And it was
proprietary. So we ripped it out post Turbine 2.2 and replaced it with
<a href="http://jakarta.apache.org/commons/logging">commons-logging</a>
 backed by <a href="http://jakarta.apache.org/log4j/">Log4j</a>. You
configure the new logging with a Log4j.properties file which can be
configured with the log4j.file property in TurbineResource.properties:
</p>

</section>

<section name="Configuration">

<source><![CDATA[
# -------------------------------------------------------------------
#
#  L O G 4 J - L O G G I N G
#
# -------------------------------------------------------------------

log4j.file = /WEB-INF/conf/Log4j.properties
]]></source>

</section>

<section name="Log4j Configuration">

<p>
To use the Logging system, all you need to do is configure some
loggers in your Log4j.properties. This is an example how to do it:
</p>

<source><![CDATA[
# ------------------------------------------------------------------------
#
# Logging Configuration
#
# $Id$
#
# ------------------------------------------------------------------------

#
# If we don't know the logging facility, put it into the
# turbine.log
#
log4j.rootLogger = INFO, turbine

#
# Turbine goes into Turbine Log
#
log4j.category.org.apache.turbine = INFO, turbine
log4j.additivity.org.apache.turbine = false

#
# Torque has its own log file
#
log4j.category.org.apache.torque = INFO, torque
log4j.additivity.org.apache.torque = false

#
# Velocity Logfile
#
log4j.category.velocity = INFO, velocity
log4j.additivity.velocity = false

#
# Scheduler Category
#
log4j.category.scheduler = INFO, scheduler
log4j.additivity.scheduler = false

########################################################################
#
# Logfile definitions
#
########################################################################

#
# turbine.log
#
log4j.appender.turbine = org.apache.log4j.FileAppender
log4j.appender.turbine.file = ${applicationRoot}/logs/turbine.log
log4j.appender.turbine.layout = org.apache.log4j.PatternLayout
log4j.appender.turbine.layout.conversionPattern = %d [%t] %-5p %c - %m%n
log4j.appender.turbine.append = false

#
# torque.log
# 
log4j.appender.torque = org.apache.log4j.FileAppender
log4j.appender.torque.file = ${applicationRoot}/logs/torque.log
log4j.appender.torque.layout = org.apache.log4j.PatternLayout
log4j.appender.torque.layout.conversionPattern = %d [%t] %-5p %c - %m%n
log4j.appender.torque.append = false

#
# Scheduler Output
#
log4j.appender.scheduler = org.apache.log4j.FileAppender
log4j.appender.scheduler.file = ${applicationRoot}/logs/scheduler.log
log4j.appender.scheduler.layout = org.apache.log4j.PatternLayout
log4j.appender.scheduler.layout.conversionPattern = %d [%t] %-5p %c - %m%n
log4j.appender.scheduler.append = false

#
# Velocity gets configured to write its output onto the velocity
# category.
#
log4j.appender.velocity = org.apache.log4j.FileAppender
log4j.appender.velocity.file = ${applicationRoot}/logs/velocity.log
log4j.appender.velocity.layout = org.apache.log4j.PatternLayout
log4j.appender.velocity.layout.conversionPattern = %d [%t] %-5p %c - %m%n
log4j.appender.velocity.append = false
]]></source>

<p>
Sub Projects like Torque and Velocity get either configured correctly
by their Services (Velocity by the VelocityService) or already know
about commons-logging (Torque). 
</p>

</section>

<section name="Usage">

<p>
You use the logging by accessing it via commons-logging. This is an
example how to do it.
</p>

<source><![CDATA[
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

// Provide a logger with the class name as category. This
// is recommended because you can split your log files
// by packages in the Log4j.properties. You can provide
// any other category name here, though.
private Log log = LogFactory.getLog(this.getClass());

log.info("this message would go to any facility configured to use the " + this.getClass().getName() + " Facility");
]]></source>

<p>
It is recommended for performance reasons that you provide a class wide logger like this:
</p>

<source><![CDATA[
package foo;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

public class Bar
{
    // Classwide static logger
    private static Log log = LogFactory.getLog(Bar.class);
.
.
.
}
]]></source>

</section>
</body>
</document>