Author: rwatler
Date: Fri May 15 17:14:38 2009
New Revision: 775240
URL: http://svn.apache.org/viewvc?rev=775240&view=rev
Log:
Document APA-Logging
Added:
portals/applications/src/site/xdoc/logging/
portals/applications/src/site/xdoc/logging/index.xml
Modified:
portals/applications/src/site/xdoc/index.xml
Modified: portals/applications/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/portals/applications/src/site/xdoc/index.xml?rev=775240&r1=775239&r2=775240&view=diff
==============================================================================
--- portals/applications/src/site/xdoc/index.xml (original)
+++ portals/applications/src/site/xdoc/index.xml Fri May 15 17:14:38 2009
@@ -105,6 +105,11 @@
<td>A portlet application dedicated to RSS-based portlet development</td>
<td>application</td>
</tr>
+<tr>
+<td><a href="./logging/index.html">Logging</a></td>
+<td>Utilities used to setup and deploy logging for portlet and simple web
applications.</td>
+<td>archive</td>
+</tr>
</table>
</subsection>
<subsection name='Mission'>
@@ -188,4 +193,4 @@
</subsection>
</section>
</body>
-</document>
\ No newline at end of file
+</document>
Added: portals/applications/src/site/xdoc/logging/index.xml
URL:
http://svn.apache.org/viewvc/portals/applications/src/site/xdoc/logging/index.xml?rev=775240&view=auto
==============================================================================
--- portals/applications/src/site/xdoc/logging/index.xml (added)
+++ portals/applications/src/site/xdoc/logging/index.xml Fri May 15 17:14:38
2009
@@ -0,0 +1,139 @@
+<?xml version="1.0"?>
+<!--
+ 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.
+ -->
+<document>
+ <properties>
+ <title>Apache Portals Applications Logging</title>
+ <subtitle>Welcome to Apache Portals Applications Logging</subtitle>
+ <authors>
+ <person name="Randy Watler" email="[email protected]"/>
+ </authors>
+ </properties>
+ <body>
+ <section name="Welcome to Apache Portals Applications Logging">
+ <div id="downloadbox">
+ <h5>Get Portals Applications</h5>
+ <p>
+ <a href="../download.html"><img valign="top"
src="images/folder-open.gif" border="0" alt="" title="download"/>Download</a>
+ Portals Applications 2.2 Downloads <small>(MB)</small>
+ </p>
+ <ul>
+ <li>
+ <a href="../getting-started.html">System Requirements</a>
+ </li>
+ </ul>
+ </div>
+ <p>
+ Apache Portals Applications Logging, (APA Logging), is a utility
library used to setup and deploy logging
+ configuration properties for portlet and portal web applications. APA
Logging is currently used by all APA
+ web applications and the Jetspeed 2 portal to initialize the internal
Log4j logging implementations. This
+ approach is independent of APA and Jetspeed 2 and can be used stand
alone in any application container. The
+ following containers are supported:
+ <ul>
+ <li>Tomcat 5.5</li>
+ <li>Tomcat 6</li>
+ </ul>
+ The community is encouraged to contribute utilities to support other
platforms.
+ </p>
+ <subsection name="Overview">
+ <p>
+ APA Logging utilities manage and provied a system property,
<code>org.apache.portals.logdir</code>, that
+ can be used by deployed web applications to collocate logs in a
centralized location external to the
+ web application itself. The utilities include an application web
container listener to set the property
+ globally before web applications are started and tools to automate
the configuration of this listener.
+ </p>
+ </subsection>
+ <subsection name="Log4j Web Application Configuration">
+ <p>
+ Any logging solution can be used with APA Logging that can be
configured using the
+ <code>org.apache.portals.logdir</code> system property. Log4j is
used internally by most of the APA portlet
+ applications and Jetspeed 2. Here is and example Log4j
configuration, (<code>log4j.properties</code>),
+ that leverages these utilities:
+ <source>
+ <![CDATA[
+# root logger
+log4j.rootLogger = ERROR, pa
+
+# portlet application category
+log4j.category.org.apache.portals = INFO, pa
+log4j.additivity.org.apache.portals = false
+
+# portlet application APA Logging log file
+log4j.appender.pa = org.apache.log4j.FileAppender
+log4j.appender.pa.file = ${org.apache.portals.logdir}/my-pa.log
+log4j.appender.pa.layout = org.apache.log4j.PatternLayout
+log4j.appender.pa.layout.conversionPattern = %d [%t] %-5p %c - %m%n
+log4j.appender.pa.append = false]]>
+ </source>
+ To prevent potential log file overwriting and/or truncation, only
one portlet web application should
+ write to an individual file. By convention, web applications should
prefix log file names with their
+ deployed context name.
+ </p>
+ </subsection>
+ <subsection name="Manual Configuration">
+ <p>
+ Since the APA Logging approach depends only on a global system
property, manual configuration that does
+ not utilize these utilities is possible in most web application
container environments. For Tomcat, one
+ can specify system properties on the command line or in the
<code>CATALINA_OPTS</code> environment
+ variable using the standard JVM syntax:
+ <source>
+ <![CDATA[
+-Dorg.apache.portals.logdir=/var/log/portal]]>
+ </source>
+ </p>
+ </subsection>
+ <subsection name="Tomcat Listener">
+ <p>
+ The Tomcat listener implementation,
<code>LoggingPropertiesServerListener</code>, uses the
+ <code>catalina.base</code> or <code>catalina.home</code> system
properties to locate the Tomcat logs
+ directory by default. The listener can also be instantiated with the
<code>logdir</code> attribute to
+ specify the APA Logging property value. To use the default Tomcat
logs directory, the following tag
+ must be inserted in the <code>Server</code>, <code>Service</code>,
or <code>Engine</code>
+ configurations in the Tomcat <code>server.xml</code> file:
+ <source>
+ <![CDATA[
+<Listener
className="org.apache.portals.applications.logging.tomcat.LoggingPropertiesServerListener"/>]]>
+ </source>
+ To specify an APA Logging directory, the following can also be used:
+ <source>
+ <![CDATA[
+<Listener
className="org.apache.portals.applications.logging.tomcat.LoggingPropertiesServerListener"
logdir="/var/log/portal"/>]]>
+ </source>
+ The listener only configures the property if not already set, so
manual configuration of the logging
+ system property will override computed or specified by the listener.
The APA Logging jar artifact must
+ be installed in the Tomcat system library classpath, (i.e. in
<code>server/lib</code> for Tomcat 5.5 and
+ <code>lib</code> for Tomcat 6), since the listener is invoked by
Tomcat itself.
+ </p>
+ </subsection>
+ <subsection name="Tomcat Deployment">
+ <p>
+ The Tomcat deployment tool, <code>ServerXMLConfigurer</code>,
deploys the default APA Logging
+ <code>Listener</code> tag into the <code>server.xml</code> file. The
tool is used as part of the
+ Jetspeed 2 deployment Maven2 plugin,
(<code>jetspeed-deploy-maven-plugin</code>), to provide a self
+ configuring development and demo environment. As noted above, this
results in all APA Logging compatible
+ log files being located in the standard Tomcat installation logs
directory.
+ </p>
+ <p>
+ The deployment tool checks to ensure the listener has not already
been installed and/or configured
+ before running. The <code>Listener</code> tag is inserted within the
<code>Engine</code> tag.
+ Tomcat installation configurations with multiple <code>Engine</code>
tags should be configured
+ manually to ensure proper operation.
+ </p>
+ </subsection>
+ </section>
+ </body>
+</document>
