xdocs/services/logging-service.xml - turbine-core - Git at Google

 <?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>
	<?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>