You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@turbine.apache.org by he...@apache.org on 2003/01/12 15:54:56 UTC
cvs commit: jakarta-turbine-2/xdocs/services index.xml logging-service.xml resources-service.xml
henning 2003/01/12 06:54:56
Modified: xdocs/services index.xml logging-service.xml
resources-service.xml
Log:
Updated the docs concerning Logging and Resources Service to resemble
something like the current Turbine code.
Revision Changes Path
1.6 +6 -6 jakarta-turbine-2/xdocs/services/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-2/xdocs/services/index.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- index.xml 10 Jan 2003 01:30:34 -0000 1.5
+++ index.xml 12 Jan 2003 14:54:56 -0000 1.6
@@ -6,6 +6,7 @@
<author email="criley@ekmail.com">Cameron Riley</author>
<author email="jvanzyl@apache.org">Jason van Zyl</author>
<author email="jon@latchkey.com">Jon S. Stevens</author>
+ <author email="hps@intermeta.de">Henning P. Schmiedehausen</author>
</properties>
<body>
@@ -97,9 +98,9 @@
<li>
<a href="logging-service.html">Logging Service</a>
<br/>
-The default Loggin implementation for Turbine, logging can be either
-through an explicite getLogger() method or by standard printing methods
-such as info or debug.
+The Logging Service has been removed and replaced with a commons-logging
+and log4j combination. Here you find some information how to use this
+in Turbine.
</li>
<li>
@@ -133,9 +134,8 @@
<li>
<a href="resources-service.html">Resources Service</a>
<br/>
-<b>[TO DO (Configuration)]</b> The Resources Service is the set of classes and
-the functionality that allows for the reading and acccessing data
-from within properties files.
+The Resources Service has been removed and replaced with commons-configuration. You
+find some explanation how to use commons-configuration here.
</li>
<li>
1.2 +135 -47 jakarta-turbine-2/xdocs/services/logging-service.xml
Index: logging-service.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-2/xdocs/services/logging-service.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- logging-service.xml 16 Aug 2001 05:10:44 -0000 1.1
+++ logging-service.xml 12 Jan 2003 14:54:56 -0000 1.2
@@ -5,6 +5,7 @@
<title>Turbine Services - Logging Service</title>
<author email="jvanzyl@apache.org">Jason van Zyl</author>
<author email="jon@latchkey.com">Jon S. Stevens</author>
+ <author email="hps@intermeta.de">Henning P. Schmiedehausen</author>
</properties>
<body>
@@ -12,13 +13,12 @@
<section name="Logging Service">
<p>
-Turbine's logging service is exceptionally powerful. The reason why it
-is so powerful is because it provides an API which is extensible in that
-any logging system can be configured to run under the covers. Turbine
-provides by default implementations for 4 different logging systems:
-Log4J, Avalon's LogKit, The Servlet API's logging system and a simple
-file logging system. The facility.className is what decides which
-logger system to use.
+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>
@@ -27,66 +27,154 @@
<source><![CDATA[
# -------------------------------------------------------------------
-#
-# S E R V I C E S
+#
+# L O G 4 J - L O G G I N G
#
# -------------------------------------------------------------------
-# Classes for Turbine Services should be defined here.
-# Format: services.[name].classname=[implementing class]
+
+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[
+# ------------------------------------------------------------------------
#
-# To specify properties of a service use the following syntax:
-# service.[name].[property]=[value]
+# Logging Configuration
+#
+# $Id$
+#
+# ------------------------------------------------------------------------
-services.LoggingService.classname=org.apache.turbine.services.logging.TurbineLoggingService
-.
-.
-.
-# -------------------------------------------------------------------
+#
+# 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
#
-# L O G S
+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
+
#
-# -------------------------------------------------------------------
-# This is the configuration for the logging system. In most cases
-# you don't need to modify anything. However, if you wish to add more
-# facilities or modify the existing settings, then you can do so.
+# Scheduler Output
#
-# destination.file: A path relative to the web app root
-# -------------------------------------------------------------------
-services.LoggingService.facilities=system,debug
-services.LoggingService.default=system
-services.LoggingService.loggingConfig=org.apache.turbine.services.logging.PropertiesLoggingConfig
-
-# A facility for system logging.
-services.LoggingService.system.destination.file=/path/to/file.log
-services.LoggingService.system.className=org.apache.turbine.services.logging.FileLogger
-services.LoggingService.system.level=INFO
-
-# A facility for the scheduler service
-# To disable started/stopped messages set the level to ERROR
-services.LoggingService.scheduler.destination.file=/path/to/file.log
-services.LoggingService.scheduler.className=org.apache.turbine.services.logging.FileLogger
-services.LoggingService.scheduler.level=INFO
+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>
-To use the Logging system, all you need to do is configure a facility in
-the TR.props file, what facilities to use for logging and then reference
-a facility in your code. It is also possible to configure a "default"
-logging facility where all log messages go when a facility is not
-specified.
+You use the logging by accessing it via commons-logging. This is an
+example how to do it.
</p>
<source><![CDATA[
-import org.apache.turbine.util.Log;
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
-Log.info("system", "this is a message that would go to the system facility");
+// 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>
-</section>
+<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>
1.2 +49 -33 jakarta-turbine-2/xdocs/services/resources-service.xml
Index: resources-service.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-2/xdocs/services/resources-service.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- resources-service.xml 16 Aug 2001 05:10:44 -0000 1.1
+++ resources-service.xml 12 Jan 2003 14:54:56 -0000 1.2
@@ -4,6 +4,7 @@
<properties>
<title>Turbine Services - Resources Service</title>
<author email="jvanzyl@apache.org">Jason van Zyl</author>
+ <author email="hps@intermeta.de">Henning P. Schmiedehausen</author>
</properties>
<body>
@@ -11,61 +12,76 @@
<section name="Resources Service">
<p>
-Within Turbine is a class for reading and accessing data in Property
-files. The classes that accomplish this have been borrowed from the Apache
-JServ project. These classes are called ExtendedProperties and are more
-feature complete than the Properties objects that are default in the Java
-Language specification. Turbine comes with a global properties file called
-TurbineResources.properties. This file is used to configure runtime directives
-within Turbine. You can also use this file to store your application specific
-resources or you can uses the Resources Services to create other files
-that are specific to your application.
+Within Turbine was a service for reading and accessing data in Property
+files. The classes that accomplish this have been borrowed from the
+Apache JServ project, moved many time and finally ended up in the <a
+href="http://jakarta.apache.org/commons/sandbox/configuration">commons-configuration</a>
+ sub-project. So we removed the Service itself and now use commons-configuration everywhere.
</p>
</section>
-<section name="Configuration">
+<section name="Configuring Turbine">
+
+<p>
+Turbine gets its configuration file from the servlet container at
+startup time. It is necessary to have an init parameter in the
+servlet section of your web.xml file:
+</p>
<source><![CDATA[
-.
-.
-.
+<init-param>
+ <param-name>properties</param-name>
+ <!-- This is relative to the docBase -->
+ <param-value>
+ /WEB-INF/conf/TurbineResources.properties
+ </param-value>
+</init-param>
]]></source>
</section>
-<section name="Usage">
+<section name="Accessing properties">
<p>
-To access data that is within the TurbineResources.properties file,
-all you need to do is this:
+Turbine post-2.2 uses commons-configuration all over the place, so if
+you want to access properties files, you can use it in two ways.
</p>
-<source><![CDATA[
+<p>
+Inside arbitrary code:
+</p>
-TurbineResources
- .setPropertiesFileName("d:/path/to/TurbineResources.properties");
+<source><![CDATA[
+import org.apache.commons.configuration.Configuration;
+import org.apache.turbine.Turbine;
-String foo = TurbineResources
- .getString("foo.data","defaultValue");
+//
+// Access all properties from TurbineResource.properties
+Configuration conf = Turbine.getConfiguration();
+String myProperty = conf.getString("this.is.my.property");
]]></source>
<p>
-The above code sets the properties file name path so that it can be found.
-This only needs to be executed once per instance of the JVM because it
-is a mostly static class and can cache this information. The getString()
-line will retrieve the value out of the properties file that starts with
-"<em>foo.data</em>". If that key value is not found in the properties file,
-then it will return the optional "<em>defaultValue</em>" as the String.
+Inside a service, you can easily access the already subclassed
+property object for your service (that is, with the services.<your service name>
+stripped away from the property:
</p>
-<p>There is also a class, TurbineResourceServices that allows you to use
-the Services functionality to access information within TurbineResources.
-Since this is more work for the programmer, I will leave this as an exercise
-that you can do on your own. It is recommended that you just use the simple
-example above instead.
-</p>
+<source><![CDATA[
+public class myService extends TurbineBaseService
+{
+.
+.
+.
+ Configuration conf = getConfiguration();
+ String myProp = conf.getString("my.property"); // services.myService.my.property
+.
+.
+.
+}
+]]></source>
</section>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>