You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bu...@apache.org on 2012/05/22 10:25:36 UTC
svn commit: r818658 [4/23] - in /websites/staging/sling/trunk/content: ./
tutorials-how-tos/
Added: websites/staging/sling/trunk/content/authentication-framework.html
==============================================================================
--- websites/staging/sling/trunk/content/authentication-framework.html (added)
+++ websites/staging/sling/trunk/content/authentication-framework.html Tue May 22 08:25:32 2012
@@ -0,0 +1,217 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ 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.
+-->
+ <head>
+ <title>Apache Sling - Authentication - Framework</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a>
+ </div>
+ <h1>Authentication - Framework</h1>
+ <h1 id="framework">Framework</h1>
+<p>The core piece of functionality with respect to authentication in Sling is contained in the Sling Commons Auth bundle. This bundle provides the API for Sling and Sling applications to make use of authentication.</p>
+<p>This support encompasses three parts:</p>
+<ul>
+<li>The <code>AuthenticationSupport</code> service provided by the <code>SlingAuthenticator</code> class. This service can be used by implementations of the OSGi <code>HttpContext</code> interface to delegate authentication.</li>
+<li>The <code>Authenticator</code> service also provided by the <code>SlingAuthenticator</code> class. This service may be used by Sling Applications to help clients login and logout.</li>
+<li>The <code>AuthenticationHandler</code> service interface. These services may be implemented by extensions to support various ways for transporting credentials from clients to the Sling server.</li>
+</ul>
+<p>This page describes how the <code>SlingAuthenticator</code> class provides the <code>AuthenticationSupport</code> and <code>Authenticator</code> services. For a description of the <code>AuthenticationHandler</code> service interface and the interaction between the <code>SlingAuthenticator</code> and the <code>AuthenticationHandler</code> services refer to the <a href="/authentication-authenticationhandler.html">AuthenticationHandler</a> page.</p>
+<p>The <code>SlingAuthenticator</code> class is an internal class of the <code>org.apache.sling.commons.auth</code> bundle and implements the <code>Authenticator</code> and <code>AuthenticationSupport</code> services.</p>
+<h2 id="authenticationsupport">AuthenticationSupport</h2>
+<p>The <code>AuthenticationSupport</code> service interface defines a single method: <code>handleSecurity</code>. This method is intended to be called by the <code>handleSecurity</code> method of any <code>HttpContext</code> implementation wishing to make use of the Sling Authentication Framework.</p>
+<p>The Sling Authenticator implementation selects an <code>AuthenticationHandler</code> service appropriate for the request and calls the <code>AuthenticationHandler.extractCredentials</code> method to extract the credentials from the request. If no credentials could be extracted, the Sling Authenticator either admits the request as an anonymous request or requests authentication from the client by calling its own <code>login</code> method.</p>
+<p>The implementation follows this algorithm:</p>
+<ol>
+<li>Select one or more <code>AuthenticationHandler</code> for the request according to the request URL's scheme and authorization part.</li>
+<li>Call the <code>extractCredentials</code> method of each authentication handler, where the order of handler call is defined by the length of the registered path: handlers registered with longer paths are called before handlers with shorter paths. The goal is to call the handlers in order from longest request path match to shortest match. Handlers not matching the request path at all are not called.</li>
+<li>The first handler returning a non-<code>null</code> <code>AuthenticationInfo</code> result "wins" and the result is used for authentication.</li>
+<li>If any <code>AuthenticationInfoPostProcessor</code> services are registered, the <code>AuthenticationInfo</code> object is passed to their <code>postProcess()</code> method.</li>
+<li>If no handler returns a non-<code>null</code> result, the request may be handled anonymously. In these cases, an empty <code>AuthenticationInfo</code> object is passed to any <code>AuthenticationInfoPostProcessor</code> services.</li>
+<li>(Try to) log into the repository either with the provided credentials or anonymously.</li>
+<li>If there were credentials provided and the login was successful, a login event is posted <em>if</em> the <code>AuthenticationInfo</code> object contains a non-null object with the key <code>$$auth.info.login$$</code> (<code>AuthConstants.AUTH*INFO*LOGIN</code>). This event is posted with the topic <code>org/apache/sling/auth/core/Authenticator/LOGIN</code>. (added in Sling Auth Core 1.1.0)</li>
+<li>Set request attributes listed below.</li>
+</ol>
+<p>Extracting the credentials and trying to login to the repository may yield the following results:</p>
+<p>| Credentials | Login | Consequence |
+| present | successfull | Continue with an authenticated request |
+| present | failed | Select <code>AuthenticationHandler</code> and call <code>requestCredentials</code> method |
+| missing | anonymous allowed | Continue with a non authenticated request using anonymous access to the repository |
+| missing | anonymous forbidden | Select <code>AuthenticationHandler</code> and call <code>requestCredentials</code> method |</p>
+<p>{note}
+Only one <code>AuthenticationHandler</code> is able to provide credentials for a given request. If the credentials provided by the handler cannot be used to login to the repository, authentication fails and no further <code>AuthenticationHandler</code> is consulted.
+{note}</p>
+<h4 id="request-attributes-on-successful-login">Request Attributes on Successful Login</h4>
+<p>The <code>handleSecurity</code> method gets credentials from the <code>AuthenticationHandler</code> and logs into the JCR repository using those credentials. If the login is successful, the <code>SlingAuthenticator</code> sets the following request attributes:</p>
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>org.osgi.service.http.authentication.remote.user</code></td>
+<td>The user ID of the JCR Session. This attribute is used by the HTTP Service implementation to implement the <code>HttpServletRequest.getRemoteUser</code> method.</td>
+</tr>
+<tr>
+<td><code>org.osgi.service.http.authentication.type</code></td>
+<td>The authentication type defined by the <code>AuthenticationHandler</code>. This attribute is used by the HTTP Service implementation to implement the <code>HttpServletRequest.getAuthType</code> method.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.commons.auth.ResourceResolver</code></td>
+<td>The <code>ResourceResolver</code> created from the credentials and the logged in JCR Session. This attribute may be used by servlets to access the repository. Namely the <code>SlingMainServlet</code> uses this request attribute to provide the <code>ResourceResolver</code> to handle the request.</td>
+</tr>
+<tr>
+<td><code>javax.jcr.Session</code></td>
+<td>The JCR Session. This attribute is for backwards compatibility only. <em>Its use is deprecated and the attribute will be removed in future versions</em>.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.commons.auth.spi.AuthenticationInfo</code></td>
+<td>The <code>AuthenticationInfo</code> object produced from the <code>AuthenticationHandler</code>.</td>
+</tr>
+</tbody>
+</table>
+<p><em>NOTE</em>: Do <em>NOT</em> use the <code>javax.jcr.Session</code> request attribute in your Sling applications. This attribute must be considered implementation specific to convey the JCR Session to the <code>SlingMainServlet</code>. In future versions of the Sling Commons Auth bundle, this request attribute will not be present anymore. To get the JCR Session for the current request adapt the request's resource resolver to a JCR Session:</p>
+<div class="codehilite"><pre><span class="n">Session</span> <span class="n">session</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">getResourceResolver</span><span class="p">()</span><span class="o">.</span><span class="n">adaptTo</span><span class="p">(</span><span class="n">Session</span><span class="o">.</span><span class="n">class</span><span class="p">);</span>
+</pre></div>
+
+
+<h4 id="anonymous-login">Anonymous Login</h4>
+<p>The <code>SlingAuthenticator</code> provides high level of control with respect to allowing anonymous requests or requiring authentication up front:</p>
+<ul>
+<li>Global setting of whether anonymous requests are allowed or not. This is the value of the <em>Allow Anonymous Access</em> (<code>auth.annonymous</code>) property of the <code>SlingAuthenticator</code> configuration. This property is supported for backwards compatibility and defaults to <code>true</code> (allowing anonymous access).</li>
+<li>Specific configuration per URL. The <em>Authentication Requirements</em> (<code>sling.auth.requirements</code>) property of the <code>SlingAuthenticator</code> configuration may provide a list of URLs for which authentication may be required or not: Any entry prefixed with a dash <code>-</code> defines a subtree for which authentication is not required. Any entry not prefixed with a dash or prefixed with a plus <code>+</code> defines a subtree for which authentication is required up front and thus anonymous access is not allowed. This list is empty by default.</li>
+<li>Any OSGi service may provide a <code>sling.auth.requirements</code> registration property which is used to dynamically extend the authentication requirements from the <em>Authentication Requirements</em> configuration. This may for example be set by <code>AuthenticationHandler</code> implementations providing a login form to ensure access to the login form does not require authentication. The value of this property is a single string, an array of strings or a Collection of strings and is formatted in the same way as the <em>Authentication Requirements</em> configuration property.</li>
+</ul>
+<p>The URLs set on the <em>Authentication Requirements</em> configuration property or the <code>sling.auth.requirements</code> service registration property can be absolute paths or URLs like the <code>path</code> service registration property of <code>AuthenticationHandler</code> services. This allows the limitation of this setup to certain requests by scheme and/or virtual host address.</p>
+<p><em>Examples</em></p>
+<ul>
+<li>
+<p>The <code>LoginServlet</code> contained in the Commons Auth bundle registers itself with the service registration property <code>sling.auth.requirements = "-/system/sling/login"</code> to ensure the servlet can be accessed without requiring authentication.</p>
+</li>
+<li>
+<p>An authentication handler may register itself with the service registration property <code>sling.auth.requirements = "-/apps/sample/loginform"</code> to ensure the login form can be rendered without requiring authentication.</p>
+</li>
+</ul>
+<h2 id="authenticator-implementation">Authenticator implementation</h2>
+<p>The implementation of the <code>Authenticator</code> interface is similar for both methods:</p>
+<p><em><code>login</code></em></p>
+<ol>
+<li>Select one or more <code>AuthenticationHandler</code> for the request according to the request URL's scheme and authorization part.</li>
+<li>Call the <code>requestCredentials</code> method of each authentication handler, where the order of handler call is defined by the length of the registered path: handlers registered with longer paths are called before handlers with shorter paths. The goal is to call the handlers in order from longest request path match to shortest match. Handlers not matching the request path at all are not called.</li>
+<li>As soon as the first handlers returns <code>true</code>, the process ends and it is assumed credentials have been requested from the client.</li>
+</ol>
+<p>The <code>login</code> method has three possible exit states:</p>
+<table>
+<thead>
+<tr>
+<th>Exit State</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Normal</td>
+<td>An <code>AuthenticationHandler</code> could be selected to which the login request could be forwarded.</td>
+</tr>
+<tr>
+<td><code>NoAuthenticationHandlerException</code></td>
+<td>No <code>AuthenticationHandler</code> could be selected to forward the login request to. In this case, the caller can proceed as appropriate. For example a servlet, which should just login a user may send back a 403/FORBIDDEN status because login is not possible. Or a 404/NOT FOUND handler, which tried to login as a fallback, may continue and send back the regular 404/NOT FOUND response.</td>
+</tr>
+<tr>
+<td><code>IllegalStateException</code></td>
+<td>The response has already been committed and the login request cannot be processed. Normally to request login, the current response must be reset and a new response has to be prepared. This is only possible if the request has not yet been committed.</td>
+</tr>
+</tbody>
+</table>
+<p><em><code>logout</code></em>
+1. Select one or more <code>AuthenticationHandler</code> for the request according to the request URL's scheme and authorization part.
+1. Call the <code>dropCredentials</code> method of each authentication handler, where the order of handler call is defined by the length of the registered path: handlers registered with longer paths are called before handlers with shorter paths. The goal is to call the handlers in order from longest request path match to shortest match. Handlers not matching the request path at all are not called.</p>
+<p>Unlike for the <code>login</code> method in the <code>logout</code> method case all <code>AuthenticationHandler</code> services selected in the first step are called. If none can be selected or none can actually handle the <code>dropCredentials</code> request, the <code>logout</code> silently returns.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/authentication-tasks.html
==============================================================================
--- websites/staging/sling/trunk/content/authentication-tasks.html (added)
+++ websites/staging/sling/trunk/content/authentication-tasks.html Tue May 22 08:25:32 2012
@@ -0,0 +1,112 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ 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.
+-->
+ <head>
+ <title>Apache Sling - Authentication - Tasks</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a>
+ </div>
+ <h1>Authentication - Tasks</h1>
+ <h1 id="tasks">Tasks</h1>
+<p>Authentication of HTTP Requests is generally a two-step process: First the credentials must be extracted from the request and second the credentials must be validated. In the case of Sling this means acquiring a JCR Session.</p>
+<h2 id="extract-credentials-from-the-request">Extract Credentials from the Request</h2>
+<ul>
+<li>Implemented and controlled by the Sling Commons Auth bundle</li>
+<li>Takes <code>HttpServletRequest</code></li>
+<li>Provides credentials for futher processing (basically JCR <code>Credentials</code> and Workspace name)</li>
+<li>Extensible with the help of <code>AuthenticationHandler</code> services</li>
+</ul>
+<h2 id="login-to-the-jcr-repository">Login to the JCR Repository</h2>
+<ul>
+<li>Implemented and controlled by the JCR Repository</li>
+<li>Takes JCR <code>Credentials</code> and Workspace name</li>
+<li>Provides a JCR <code>Session</code></li>
+<li>Implementation dependent process. Jackrabbit provides extensibility based on <code>LoginModules</code>; Sling's Embedded Jackrabbit Repository bundle provides extensibility with <code>LoginModulePlugin</code> services.</li>
+</ul>
+<p>Currently the credentials are always verified by trying to login to the JCR repository. Once an <a href="">ResourceResolverFactory</a> API has been added, the process of validating the credentials and logging in is actualy replaced by a process of requesting a <code>ResourceResolver</code> from the <code>ResourceResolverFactory</code>. Of course, the JCR Repository will still be the main underlying repository and as such be used to validate the credentials and get a JCR Session.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Modified: websites/staging/sling/trunk/content/authentication.html
==============================================================================
--- websites/staging/sling/trunk/content/authentication.html (original)
+++ websites/staging/sling/trunk/content/authentication.html Tue May 22 08:25:32 2012
@@ -82,94 +82,30 @@
<a href="/">Home</a>
</div>
<h1>Authentication</h1>
- <p><a name="Authentication-Authentication"></a></p>
-<h1 id="authentication">Authentication</h1>
-<!--
-{excerpt:hidden=true}
-How requests are authenticated.
-{excerpt}
--->
-
-<p>This section describes the framework provided by Sling to authenticate HTTP
-requests.</p>
-<p>Let's look at generic request processing of Sling: Sling is linked into the
-outside world by registering the Sling Main Servlet -- implemented by the
-<em>SlingMainServlet</em> class in the Sling Engine bundle -- with an OSGi
-<em>HttpService</em>. This registration is accompanyied with an implementation
-instance of the OSGi <em>HttpContext</em> interface, which defines a method to
-authenticate requests: <em>handleSecurity</em>.</p>
-<p>This method is called by the OSGi HTTP Service implementation after the
-servlet has been selected to handle the request but before actually calling
-the servlet's <em>service</em> method.</p>
+ <h1 id="authentication">Authentication</h1>
+<p>This section describes the framework provided by Sling to authenticate HTTP requests.</p>
+<p>Let's look at generic request processing of Sling: Sling is linked into the outside world by registering the Sling Main Servlet -- implemented by the <code>SlingMainServlet</code> class in the Sling Engine bundle -- with an OSGi <code>HttpService</code>. This registration is accompanyied with an implementation instance of the OSGi <code>HttpContext</code> interface, which defines a method to authenticate requests: <code>handleSecurity</code>.</p>
+<p>This method is called by the OSGi HTTP Service implementation after the servlet has been selected to handle the request but before actually calling the servlet's <code>service</code> method.</p>
<p>{section}
{column}
-<img style="border: 0px solid black" title="Request Processing " src="authentication.png">
!authentication.png|thumbnail!
{column}
{column}
-1. First the OSGi HTTP Service implementation is analyzing the request URL
-to find a match for a servlet or resource registered with the HTTP Service.
-1. Now the HTTP Service implementation has to call the <em>handleSecurity</em>
-method of the <em>HttpContext</em> object with which the servlet or resource has
-been registered. This method returns <em>true</em> if the request should be
-serviced. If this method returns <em>false</em> the HTTP Service implementation
-terminates the request sending back any response which has been prepared by
-the <em>handleSecurity</em> method. Note, that the <em>handleSecurity</em> method
-must prepare the failure response sent to the client, the HTTP Service adds
-nothing here. If the <em>handleSecurity</em> method is successful, it must add
-two (or three) request attributes described below.
-1. When the <em>handleSecurity</em> method returns <em>true</em> the HTTP Service
-either calls the <em>Servlet.service</em> method or sends back the requested
-resource depending on whether a servlet or a resource has been selected in
-the first step.
+1. First the OSGi HTTP Service implementation is analyzing the request URL to find a match for a servlet or resource registered with the HTTP Service.
+1. Now the HTTP Service implementation has to call the <code>handleSecurity</code> method of the <code>HttpContext</code> object with which the servlet or resource has been registered. This method returns <code>true</code> if the request should be serviced. If this method returns <code>false</code> the HTTP Service implementation terminates the request sending back any response which has been prepared by the <code>handleSecurity</code> method. Note, that the <code>handleSecurity</code> method must prepare the failure response sent to the client, the HTTP Service adds nothing here. If the <code>handleSecurity</code> method is successful, it must add two (or three) request attributes described below.
+1. When the <code>handleSecurity</code> method returns <code>true</code> the HTTP Service either calls the <code>Servlet.service</code> method or sends back the requested resource depending on whether a servlet or a resource has been selected in the first step.
{column}
{section}</p>
-<p>The important thing to note here is, that at the time the
-<em>handleSecurity</em> method is called, the <em>SlingMainServlet</em> is not yet in
-control of the request. So any functionality added by the
-<em>SlingMainServlet</em>, notably the <em>SlingHttpServletRequest</em> and
-<em>SlingHttpServletResponse</em> objects are not available to the
-implementation of the <em>handleSecurity</em> method.</p>
-<p>The following pages describe the full details of request authentication in
-Sling in full detail:</p>
+<p>The important thing to note here is, that at the time the <code>handleSecurity</code> method is called, the <code>SlingMainServlet</code> is not yet in control of the request. So any functionality added by the <code>SlingMainServlet</code>, notably the <code>SlingHttpServletRequest</code> and <code>SlingHttpServletResponse</code> objects are not available to the implementation of the <code>handleSecurity</code> method.</p>
+<p>The following pages describe the full details of request authentication in Sling in full detail:</p>
<ul>
-<li>
-<dl>
-<dt><a href="authentication---tasks.html">Tasks</a></dt>
-<dd>Authentication of HTTP Requests is generally a two-step process:
-First the credentials must be extracted from the request and second the
-credentials must be validated. In the case of Sling this means acquiring a
-JCR Session.</dd>
-</dl>
-</li>
-<li>
-<dl>
-<dt><a href="authentication---actors.html">Actors</a></dt>
-<dd>The authentication process involves a number of actors
-contributing to the concepts, the API and the particular
-implementations.</dd>
-</dl>
-</li>
-<li>
-<dl>
-<dt><a href="authentication---framework.html">Framework</a></dt>
-<dd>The core piece of functionality with respect to authentication in
-Sling is contained in the Sling Commons Auth bundle. This bundle provides
-the API for Sling and Sling applications to make use of
-authentication.</dd>
-</dl>
-</li>
-<li>
-<dl>
-<dt><a href="authentication---authenticationhandler.html">AuthenticationHandler</a></dt>
-<dd>The <em>AuthenticationHandler</em> interface defines the service API
-which may be implemented by authentication handlers registered as OSGi
-services.</dd>
-</dl>
-</li>
+<li><a href="/authentication-tasks.html">Tasks</a>: Authentication of HTTP Requests is generally a two-step process: First the credentials must be extracted from the request and second the credentials must be validated. In the case of Sling this means acquiring a JCR Session. </li>
+<li><a href="/authentication-actors.html">Actors</a>: The authentication process involves a number of actors contributing to the concepts, the API and the particular implementations. </li>
+<li><a href="/authentication-framework.html">Framework</a>: The core piece of functionality with respect to authentication in Sling is contained in the Sling Commons Auth bundle. This bundle provides the API for Sling and Sling applications to make use of authentication. </li>
+<li><a href="/authentication-authenticationhandler.html">AuthenticationHandler</a>: The {{AuthenticationHandler}} interface defines the service API which may be implemented by authentication handlers registered as OSGi services. </li>
</ul>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1328924 by fmeschbe on Sun, 22 Apr 2012 18:26:44 +0000
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
Added: websites/staging/sling/trunk/content/bundle-resources-extensions-bundleresource.html
==============================================================================
--- websites/staging/sling/trunk/content/bundle-resources-extensions-bundleresource.html (added)
+++ websites/staging/sling/trunk/content/bundle-resources-extensions-bundleresource.html Tue May 22 08:25:32 2012
@@ -0,0 +1,139 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ 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.
+-->
+ <head>
+ <title>Apache Sling - Bundle Resources (extensions.bundleresource)</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a>
+ </div>
+ <h1>Bundle Resources (extensions.bundleresource)</h1>
+ <h1 id="bundle-resources">Bundle Resources</h1>
+<div class="toc">
+<ul>
+<li><a href="#bundle-resources">Bundle Resources</a><ul>
+<li><a href="#introduction">Introduction</a></li>
+<li><a href="#resource-types">Resource Types</a></li>
+<li><a href="#adapters">Adapters</a></li>
+<li><a href="#configuration">Configuration</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<h2 id="introduction">Introduction</h2>
+<p>The Bundle Resource Provider provides access to files/directories included in an OSGi bundle through the Sling <code>ResourceResolver</code>. </p>
+<h2 id="resource-types">Resource Types</h2>
+<p>Files and directories are mapped into the resource tree as regular <code>Resource</code> instances whose resource type depends on the actual nature of the mapped resource:</p>
+<ul>
+<li>Regular files are assigned the <code>nt:file</code> resource type</li>
+<li>Directories are assigned the <code>nt:folder</code> resource type</li>
+</ul>
+<h2 id="adapters">Adapters</h2>
+<p>Filesystem resources extend from Sling's <code>AbstractResource</code> class and thus are adaptable to any type for which an <code>AdapterFactory</code> is registered supporting bundle resources. In addition <code>BundleResource</code> support the following adapters natively:</p>
+<ul>
+<li><code>java.net.URL</code> -- A valid <code>bundle://</code> URL to the resource in the bundle. </li>
+<li><code>java.io.InputStream</code> -- An <code>InputStream</code> to read file contents. Doesn't apply to folders.</li>
+</ul>
+<h2 id="configuration">Configuration</h2>
+<p>Providing bundles have a Bundle manifest header <code>Sling-Bundle-Resources</code> containing a list of absolute paths provided by the bundle. The paths are separated by comma or whitespace (SP, TAB, VTAB, CR, LF). </p>
+<p>Example (manifest.mf):</p>
+<div class="codehilite"><pre><span class="o">...</span>
+<span class="n">Sling</span><span class="o">-</span><span class="n">Bundle</span><span class="o">-</span><span class="n">Resources:</span> <span class="sr">/libs/s</span><span class="n">ling</span><span class="o">/</span><span class="n">explorer</span><span class="p">,</span>
+ <span class="sr">/libs/s</span><span class="n">ling</span><span class="sr">/servlet/</span><span class="n">default</span><span class="o">/</span><span class="n">explorer</span>
+<span class="o">...</span>
+</pre></div>
+
+
+<p>It's also possible to map resources from the bundle to a different location in the resource tree. In this case the path has to be extended with a path attrribute to declare where the resources are in the bundle:</p>
+<div class="codehilite"><pre><span class="o">...</span>
+<span class="n">Sling</span><span class="o">-</span><span class="n">Bundle</span><span class="o">-</span><span class="n">Resources:</span> <span class="sr">/somepath/i</span><span class="n">nthe</span><span class="sr">/resourcetree;path:=/</span><span class="n">path</span><span class="sr">/inthe/</span><span class="n">bundle</span>
+<span class="o">...</span>
+</pre></div>
+
+
+<p>The Bundle Resource Provider also has a web console plugin through which the currently installed bundles can be seen.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Modified: websites/staging/sling/trunk/content/bundles.html
==============================================================================
--- websites/staging/sling/trunk/content/bundles.html (original)
+++ websites/staging/sling/trunk/content/bundles.html Tue May 22 08:25:32 2012
@@ -82,49 +82,43 @@
<a href="/">Home</a>
</div>
<h1>Bundles</h1>
- <p><a name="Bundles-Bundles"></a></p>
-<h1 id="bundles">Bundles</h1>
-<p><a name="Bundles-Content"></a></p>
+ <h1 id="bundles">Bundles</h1>
<h2 id="content">Content</h2>
-<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Content</span> <span class="n">Loading</span> <span class="p">(</span><span class="n">jcr</span><span class="o">.</span><span class="n">contentloader</span><span class="p">)](</span><span class="n">content</span><span class="o">-</span><span class="n">loading</span><span class="o">-</span><span class="p">(</span><span class="n">jcr</span><span class="o">.</span><span class="n">contentloader</span><span class="p">)</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">Internationalization</span> <span class="n">Support</span> <span class="p">(</span><span class="n">i18n</span><span class="p">)](</span><span class="n">internationalization</span><span class="o">-</span><span class="n">support</span><span class="o">-</span><span class="p">(</span><span class="n">i18n</span><span class="p">)</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">Manipulating</span> <span class="n">Content</span> <span class="o">-</span> <span class="n">The</span> <span class="n">SlingPostServlet</span> <span class="p">(</span><span class="n">servlets</span><span class="o">.</span><span class="n">post</span><span class="p">)](</span><span class="n">manipulating</span><span class="o">-</span><span class="n">content</span><span class="o">---</span><span class="n">the</span><span class="o">-</span><span class="n">slingpostservlet</span><span class="o">-</span><span class="p">(</span><span class="n">servlets</span><span class="o">.</span><span class="n">post</span><span class="p">)</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Content</span> <span class="n">Loading</span> <span class="p">(</span><span class="n">jcr</span><span class="o">.</span><span class="n">contentloader</span><span class="p">)](</span><span class="sr">/content-loading-jcr-contentloader.html)</span>
+<span class="sr">* [Internationalization Support (i18n)](/i</span><span class="n">nternationalization</span><span class="o">-</span><span class="n">support</span><span class="o">-</span><span class="n">i18n</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Manipulating</span> <span class="n">Content</span> <span class="o">-</span> <span class="n">The</span> <span class="n">SlingPostServlet</span> <span class="p">(</span><span class="n">servlets</span><span class="o">.</span><span class="n">post</span><span class="p">)](</span><span class="o">/</span><span class="n">manipulating</span><span class="o">-</span><span class="n">content</span><span class="o">-</span><span class="n">the</span><span class="o">-</span><span class="n">slingpostservlet</span><span class="o">-</span><span class="n">servlets</span><span class="o">-</span><span class="n">post</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
</pre></div>
-<p><a name="Bundles-ResourceProviders"></a></p>
<h2 id="resource-providers">Resource Providers</h2>
-<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Accessing</span> <span class="n">Filesystem</span> <span class="n">Resources</span> <span class="p">(</span><span class="n">extensions</span><span class="o">.</span><span class="n">fsresource</span><span class="p">)](</span><span class="n">accessing</span><span class="o">-</span><span class="n">filesystem</span><span class="o">-</span><span class="n">resources</span><span class="o">-</span><span class="p">(</span><span class="n">extensions</span><span class="o">.</span><span class="n">fsresource</span><span class="p">)</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">Bundle</span> <span class="n">Resources</span> <span class="p">(</span><span class="n">extensions</span><span class="o">.</span><span class="n">bundleresource</span><span class="p">)](</span><span class="n">bundle</span><span class="o">-</span><span class="n">resources</span><span class="o">-</span><span class="p">(</span><span class="n">extensions</span><span class="o">.</span><span class="n">bundleresource</span><span class="p">)</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Accessing</span> <span class="n">Filesystem</span> <span class="n">Resources</span> <span class="p">(</span><span class="n">extensions</span><span class="o">.</span><span class="n">fsresource</span><span class="p">)](</span><span class="sr">/accessing-filesystem-resources-extensions-fsresource.html)</span>
+<span class="sr">* [Bundle Resources (extensions.bundleresource)](/</span><span class="n">bundle</span><span class="o">-</span><span class="n">resources</span><span class="o">-</span><span class="n">extensions</span><span class="o">-</span><span class="n">bundleresource</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
</pre></div>
-<p><a name="Bundles-Users,Groups,Access,Permissions"></a></p>
<h2 id="users-groups-access-permissions">Users, Groups, Access, Permissions</h2>
-<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Managing</span> <span class="n">users</span> <span class="ow">and</span> <span class="n">groups</span> <span class="p">(</span><span class="n">jackrabbit</span><span class="o">.</span><span class="n">usermanager</span><span class="p">)](</span><span class="n">managing</span><span class="o">-</span><span class="n">users</span><span class="o">-</span><span class="ow">and</span><span class="o">-</span><span class="n">groups</span><span class="o">-</span><span class="p">(</span><span class="n">jackrabbit</span><span class="o">.</span><span class="n">usermanager</span><span class="p">)</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">Managing</span> <span class="n">permissions</span> <span class="p">(</span><span class="n">jackrabbit</span><span class="o">.</span><span class="n">accessmanager</span><span class="p">)](</span><span class="n">managing</span><span class="o">-</span><span class="n">permissions</span><span class="o">-</span><span class="p">(</span><span class="n">jackrabbit</span><span class="o">.</span><span class="n">accessmanager</span><span class="p">)</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Managing</span> <span class="n">users</span> <span class="ow">and</span> <span class="n">groups</span> <span class="p">(</span><span class="n">jackrabbit</span><span class="o">.</span><span class="n">usermanager</span><span class="p">)](</span><span class="sr">/managing-users-and-groups-jackrabbit-usermanager.html)</span>
+<span class="sr">* [Managing permissions (jackrabbit.accessmanager)](/m</span><span class="n">anaging</span><span class="o">-</span><span class="n">permissions</span><span class="o">-</span><span class="n">jackrabbit</span><span class="o">-</span><span class="n">accessmanager</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
</pre></div>
-<p><a name="Bundles-Installer"></a></p>
<h2 id="installer">Installer</h2>
-<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">OSGi</span> <span class="n">Installer</span><span class="p">](</span><span class="n">osgi</span><span class="o">-</span><span class="n">installer</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">JCR</span> <span class="n">Installer</span> <span class="n">Provider</span><span class="p">](</span><span class="n">jcr</span><span class="o">-</span><span class="n">installer</span><span class="o">-</span><span class="n">provider</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">OSGi</span> <span class="n">Installer</span><span class="p">](</span><span class="sr">/osgi-installer.html)</span>
+<span class="sr">* [JCR Installer Provider](/</span><span class="n">jcr</span><span class="o">-</span><span class="n">installer</span><span class="o">-</span><span class="n">provider</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
</pre></div>
-<p><a name="Bundles-Misc"></a></p>
<h2 id="misc">Misc</h2>
-<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Commons</span> <span class="n">Thread</span> <span class="n">Pools</span><span class="p">](</span><span class="n">slingxsite:apache</span><span class="o">-</span><span class="n">sling</span><span class="o">-</span><span class="n">commons</span><span class="o">-</span><span class="n">thread</span><span class="o">-</span><span class="n">pool</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">Commons</span> <span class="n">HTML</span> <span class="n">Utilities</span><span class="p">](</span><span class="n">commons</span><span class="o">-</span><span class="n">html</span><span class="o">-</span><span class="n">utilities</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">MIME</span> <span class="n">Type</span> <span class="n">Support</span> <span class="p">(</span><span class="n">commons</span><span class="o">.</span><span class="n">mime</span><span class="p">)](</span><span class="n">mime</span><span class="o">-</span><span class="n">type</span><span class="o">-</span><span class="n">support</span><span class="o">-</span><span class="p">(</span><span class="n">commons</span><span class="o">.</span><span class="n">mime</span><span class="p">)</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">Output</span> <span class="n">Rewriting</span> <span class="n">Pipelines</span> <span class="p">(</span><span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling</span><span class="o">.</span><span class="n">rewriter</span><span class="p">)](</span><span class="n">output</span><span class="o">-</span><span class="n">rewriting</span><span class="o">-</span><span class="n">pipelines</span><span class="o">-</span><span class="p">(</span><span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling</span><span class="o">.</span><span class="n">rewriter</span><span class="p">)</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">Sling</span> <span class="n">Settings</span> <span class="p">(</span><span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling</span><span class="o">.</span><span class="n">settings</span><span class="p">)](</span><span class="n">sling</span><span class="o">-</span><span class="n">settings</span><span class="o">-</span><span class="p">(</span><span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling</span><span class="o">.</span><span class="n">settings</span><span class="p">)</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">Scheduler</span> <span class="n">Service</span> <span class="p">(</span><span class="n">commons</span> <span class="n">scheduler</span><span class="p">)](</span><span class="n">scheduler</span><span class="o">-</span><span class="n">service</span><span class="o">-</span><span class="p">(</span><span class="n">commons</span><span class="o">-</span><span class="n">scheduler</span><span class="p">)</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">Web</span> <span class="n">Console</span> <span class="n">Extensions</span> <span class="p">(</span><span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling</span><span class="o">.</span><span class="n">extensions</span><span class="o">.</span><span class="n">webconsolebranding</span><span class="p">,</span> <span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling</span><span class="o">.</span><span class="n">extensions</span><span class="o">.</span><span class="n">webconsolesecurityprovider</span><span class="p">)](</span><span class="n">web</span><span class="o">-</span><span class="n">console</span><span class="o">-</span><span class="n">extensions</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Commons</span> <span class="n">Thread</span> <span class="n">Pools</span><span class="p">]()</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Commons</span> <span class="n">HTML</span> <span class="n">Utilities</span><span class="p">](</span><span class="sr">/commons-html-utilities.html)</span>
+<span class="sr">* [MIME Type Support (commons.mime)](/mim</span><span class="n">e</span><span class="o">-</span><span class="n">type</span><span class="o">-</span><span class="n">support</span><span class="o">-</span><span class="n">commons</span><span class="o">-</span><span class="n">mime</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Output</span> <span class="n">Rewriting</span> <span class="n">Pipelines</span> <span class="p">(</span><span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling</span><span class="o">.</span><span class="n">rewriter</span><span class="p">)](</span><span class="sr">/output-rewriting-pipelines-org-apache-sling-rewriter.html)</span>
+<span class="sr">* [Sling Settings (org.apache.sling.settings)](/s</span><span class="n">ling</span><span class="o">-</span><span class="n">settings</span><span class="o">-</span><span class="n">org</span><span class="o">-</span><span class="n">apache</span><span class="o">-</span><span class="n">sling</span><span class="o">-</span><span class="n">settings</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Scheduler</span> <span class="n">Service</span> <span class="p">(</span><span class="n">commons</span> <span class="n">scheduler</span><span class="p">)](</span><span class="sr">/scheduler-service-commons-scheduler.html)</span>
+<span class="sr">* [Web Console Extensions (org.apache.sling.extensions.webconsolebranding, org.apache.sling.extensions.webconsolesecurityprovider)](/</span><span class="n">web</span><span class="o">-</span><span class="n">console</span><span class="o">-</span><span class="n">extensions</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
</pre></div>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1328899 by fmeschbe on Sun, 22 Apr 2012 16:52:13 +0000
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
Modified: websites/staging/sling/trunk/content/client-request-logging.html
==============================================================================
--- websites/staging/sling/trunk/content/client-request-logging.html (original)
+++ websites/staging/sling/trunk/content/client-request-logging.html Tue May 22 08:25:32 2012
@@ -82,194 +82,299 @@
<a href="/">Home</a>
</div>
<h1>Client Request Logging</h1>
- <p><a name="ClientRequestLogging-ClientRequestLogging"></a></p>
-<h1 id="client-request-logging">Client Request Logging</h1>
-<p>Sling provides extensive support to log various information at the before
-and after processing client requests. Out of the box, there are two loggers
-configured to write traditional <em>access.log</em> and <em>request.log</em> files.
-In addition more logging can be configured by providing OSGi Configuration
-Admin configuration.</p>
-<p><a name="ClientRequestLogging-Traditionalaccess.logandrequest.logFiles"></a></p>
+ <h1 id="client-request-logging">Client Request Logging</h1>
+<p>Sling provides extensive support to log various information at the before and after processing client requests. Out of the box, there are two loggers configured to write traditional <code>access.log</code> and <code>request.log</code> files. In addition more logging can be configured by providing OSGi Configuration Admin configuration.</p>
<h2 id="traditional-accesslog-and-requestlog-files">Traditional access.log and request.log Files</h2>
-<p>In the Web Console configure the <em>Apache Sling Request Logger</em>
-(PID=<em>org.apache.sling.engine.impl.log.RequestLogger</em>) configuration.</p>
-<p>In the Sling Web Console locate the Configuration page
-(<em>/system/console/configMgr</em>) and click on the <em>+</em> (plus) symbol on the
-<em>Apache Sling Customizable Request Data Logger</em> line. This opens a dialog
-to enter the configuration whose properties can be configured as follows:</p>
+<p>In the Web Console configure the <em>Apache Sling Request Logger</em> (PID=<code>org.apache.sling.engine.impl.log.RequestLogger</code>) configuration.</p>
+<p>In the Sling Web Console locate the Configuration page (<code>/system/console/configMgr</code>) and click on the <code>+</code> (plus) symbol on the <em>Apache Sling Customizable Request Data Logger</em> line. This opens a dialog to enter the configuration whose properties can be configured as follows:</p>
<table>
-<tr><th> Parameter </th><th> Name </th><th> Default </th><th> Description </th></tr>
-<tr><td> Request Log Name </td><td> *request.log.output* </td><td> Name of the destination for the request log. The request log logs the entry and exit of each request into and out of the system together with the entry time, exit time, time to process the request, a request counter as well as the final status code and response content type. In terms of Request Logger Service formats, request entry is logged with the format and request exit is logged with the format (See [#Log Format Specification]
- below for the specification of the format). </td></tr>
-<tr><td> Request Log Type </td><td> *request.log.outputtype* </td><td> Type of Logger named with
-the Logger Name parameter. See [#Log Output](#log-output.html)
- below </td></tr>
-<tr><td> Enable Request Log </td><td> *request.log.enabled* </td><td> Whether to enable Request
-logging or not. </td></tr>
-<tr><td> Access Log Name </td><td> *access.log.output* </td><td> Name of the destination for the
-access log. The access log writes an entry for each request as the request
-terminates using the NCSA extended/combined log format. In terms of Request
-Logger Service formats the access log is written with the format (See [#Log Format Specification](#log-format-specification.html)
- below for the specification of the format). </td></tr>
-<tr><td> Access Log Type </td><td> *access.log.outputtype* </td><td> Type of Logger named with
-the Logger Name parameter. See [#Log Output](#log-output.html)
- below </td></tr>
-<tr><td> Enable Access Log </td><td> *access.log.enabled* </td><td> Whether to enable Access
-logging or not. </td></tr>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Name</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Request Log Name</td>
+<td><code>request.log.output</code></td>
+<td>Name of the destination for the request log. The request log logs the entry and exit of each request into and out of the system together with the entry time, exit time, time to process the request, a request counter as well as the final status code and response content type. In terms of Request Logger Service formats, request entry is logged with the format <code>%t \[%R]() \-> %m %U%q %H</code> and request exit is logged with the format <code>%\{end}t \[%R] <\- %s %\{Content-Type}o %Dms</code> (See [#Log Format Specification] below for the specification of the format).</td>
+<td></td>
+</tr>
+<tr>
+<td>Request Log Type</td>
+<td><code>request.log.outputtype</code></td>
+<td>Type of Logger named with the Logger Name parameter. See <a href="">#Log Output</a> below</td>
+<td></td>
+</tr>
+<tr>
+<td>Enable Request Log</td>
+<td><code>request.log.enabled</code></td>
+<td>Whether to enable Request logging or not.</td>
+<td></td>
+</tr>
+<tr>
+<td>Access Log Name</td>
+<td><code>access.log.output</code></td>
+<td>Name of the destination for the access log. The access log writes an entry for each request as the request terminates using the NCSA extended/combined log format. In terms of Request Logger Service formats the access log is written with the format <code>%h %l %u %t "%r" %>s %b "%\{Referer}i" "%\{User-Agent}i"</code> (See <a href="">#Log Format Specification</a> below for the specification of the format).</td>
+<td></td>
+</tr>
+<tr>
+<td>Access Log Type</td>
+<td><code>access.log.outputtype</code></td>
+<td>Type of Logger named with the Logger Name parameter. See <a href="">#Log Output</a> below</td>
+<td></td>
+</tr>
+<tr>
+<td>Enable Access Log</td>
+<td><code>access.log.enabled</code></td>
+<td>Whether to enable Access logging or not.</td>
+<td></td>
+</tr>
+</tbody>
</table>
-
-<p><a name="ClientRequestLogging-LogOutput"></a></p>
<h4 id="log-output">Log Output</h4>
-<p>Output of client request logging is defined by the Logger Type and and
-Logger Name where the use of the Logger Name property value depends on the
-Logger Type:</p>
+<p>Output of client request logging is defined by the Logger Type and and Logger Name where the use of the Logger Name property value depends on the Logger Type:</p>
<table>
-<tr><th> Type Code </th><th> Type Name </th><th> Description and Logger Name interpretation </th></tr>
-<tr><td> 0 </td><td> Logger Name </td><td> Writes the logging information to a named SLF4J Logger.
-The name of the Logger is defined in the Logger Name property. The actual
-destination of the log messages is defined the SLF4J configuration for the
-named logger </td></tr>
-<tr><td> 1 </td><td> File Name </td><td> Writes the logging information to a file, on message per
-line. The file name is an absolute or relative path name. If the name is
-relative, it is resolved against the *sling.home* framework property. </td></tr>
-<tr><td> 2 </td><td> RequestLog Service </td><td> Sends the logging information to a
-*org.apache.sling.engine.RequestLog* service whose *requestlog.name*
-service registration property must the same as the value of the Logger Name
-property. If more than one such service is registered, all services are
-called. If no such service is registered, the logging information is
-discarded. Using RequestLog Services is deprecated. </td></tr>
+<thead>
+<tr>
+<th>Type Code</th>
+<th>Type Name</th>
+<th>Description and Logger Name interpretation</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>0</td>
+<td>Logger Name</td>
+<td>Writes the logging information to a named SLF4J Logger. The name of the Logger is defined in the Logger Name property. The actual destination of the log messages is defined the SLF4J configuration for the named logger</td>
+</tr>
+<tr>
+<td>1</td>
+<td>File Name</td>
+<td>Writes the logging information to a file, on message per line. The file name is an absolute or relative path name. If the name is relative, it is resolved against the <code>sling.home</code> framework property.</td>
+</tr>
+<tr>
+<td>2</td>
+<td>RequestLog Service</td>
+<td>Sends the logging information to a <code>org.apache.sling.engine.RequestLog</code> service whose <code>requestlog.name</code> service registration property must the same as the value of the Logger Name property. If more than one such service is registered, all services are called. If no such service is registered, the logging information is discarded. Using RequestLog Services is deprecated.</td>
+</tr>
+</tbody>
</table>
-
-<p><em>Note:</em> If logging to a file, this file is not rotated and/or limited by
-size. To get log file rotation use the <em>Logger Name</em> logging type. See <a href="#rotating-logger-files.html">#Rotating Logger Files</a>
- below for information on how logging information can be written to rotated
-and/or size limited files.</p>
-<p><a name="ClientRequestLogging-Additionalper-requestLoggers"></a></p>
+<p><em>Note:</em> If logging to a file, this file is not rotated and/or limited by size. To get log file rotation use the <em>Logger Name</em> logging type. See <a href="">#Rotating Logger Files</a> below for information on how logging information can be written to rotated and/or size limited files.</p>
<h3 id="additional-per-request-loggers">Additional per-request Loggers</h3>
-<p>In the Web Console create <em>Apache Sling Customizable Request Data Logger</em>
-(Factory PID=<em>org.apache.sling.engine.impl.log.RequestLoggerService</em>)
-configuration.</p>
-<p>In the Sling Web Console locate the Configuration page
-(<em>/system/console/configMgr</em>) and click on the <em>+</em> (plus) symbol on the
-<em>Apache Sling Customizable Request Data Logger</em> line. This opens a dialog
-to enter the configuration whose properties can be configured as follows:</p>
+<p>In the Web Console create <em>Apache Sling Customizable Request Data Logger</em> (Factory PID=<code>org.apache.sling.engine.impl.log.RequestLoggerService</code>) configuration.</p>
+<p>In the Sling Web Console locate the Configuration page (<code>/system/console/configMgr</code>) and click on the <code>+</code> (plus) symbol on the <em>Apache Sling Customizable Request Data Logger</em> line. This opens a dialog to enter the configuration whose properties can be configured as follows:</p>
<table>
-<tr><th> Parameter </th><th> Name </th><th> Default </th><th> Description </th></tr>
-<tr><td> Log Format </td><td> *request.log.service.format* </td><td> Specify a [#Log Format Specification](#log-format-specification.html)
- as described below </td></tr>
-<tr><td> Logger Type </td><td> *request.log.service.outputtype* </td><td> Logger Name/*0* </td><td>
-Type of Logger named with the Logger Name parameter. See [#Log Output](#log-output.html)
- above </td></tr>
-<tr><td> Logger Name </td><td> *request.log.service.output* </td><td> *request.log* </td><td> Name of
-the Logger to be used. See [#Log Output](#log-output.html)
- above </td></tr>
-<tr><td> Request Entry </td><td> *request.log.service.onentry* </td><td> unchecked/*false* </td><td>
-Whether logger is called at the start of request processing or after
-processing the request </td></tr>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Name</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Log Format</td>
+<td><code>request.log.service.format</code></td>
+<td>Specify a <a href="">#Log Format Specification</a> as described below</td>
+<td></td>
+</tr>
+<tr>
+<td>Logger Type</td>
+<td><code>request.log.service.outputtype</code></td>
+<td>Logger Name/<code>0</code></td>
+<td>Type of Logger named with the Logger Name parameter. See <a href="">#Log Output</a> above</td>
+</tr>
+<tr>
+<td>Logger Name</td>
+<td><code>request.log.service.output</code></td>
+<td><code>request.log</code></td>
+<td>Name of the Logger to be used. See <a href="">#Log Output</a> above</td>
+</tr>
+<tr>
+<td>Request Entry</td>
+<td><code>request.log.service.onentry</code></td>
+<td>unchecked/<code>false</code></td>
+<td>Whether logger is called at the start of request processing or after processing the request</td>
+</tr>
+</tbody>
</table>
-
-<p><a name="ClientRequestLogging-LogFormatSpecification"></a></p>
<h4 id="log-format-specification">Log Format Specification</h4>
-<p>The log format specification follows the <a href="http://httpd.apache.org/docs/current/mod/mod_log_config.html">definition of the <em>format</em> argument for the <em>LogFormat</em> and <em>CustomLog</em> directives of Apache httpd</a>
-:</p>
-<p>The characteristics of the request itself are logged by placing "%"
-directives in the format string, which are replaced in the log file by the
-values as follows:</p>
+<p>The log format specification follows the <a href="">definition of the <code>format</code> argument for the <code>LogFormat</code> and <code>CustomLog</code> directives of Apache httpd</a>:</p>
+<p>The characteristics of the request itself are logged by placing "%" directives in the format string, which are replaced in the log file by the values as follows:</p>
<table>
-<tr><th> Format String </th><th> Description </th></tr>
-<tr><td> *%%* </td><td> The percent sign </td></tr>
-<tr><td> *%a* </td><td> Remote IP-address </td></tr>
-<tr><td> *%A* </td><td> Local IP-address </td></tr>
-<tr><td> *%B* </td><td> Size of response in bytes, excluding HTTP headers. </td></tr>
-<tr><td> *%b* </td><td> Size of response in bytes, excluding HTTP headers. In CLF
-format, i.e. a '-' rather than a 0 when no bytes are sent. </td></tr>
-<tr><td> *%\{Foobar}C* </td><td> The contents of cookie Foobar in the request sent to
-the server. </td></tr>
-<tr><td> *%D* </td><td> The time taken to serve the request, in microseconds. </td></tr>
-<tr><td> *%\{FOOBAR}e* </td><td>Not supported in Sling; prints nothing. </td></tr>
-<tr><td> *%f* </td><td> The absolute path of the resolved resource </td></tr>
-<tr><td> *%h* </td><td> Remote host </td></tr>
-<tr><td> *%H* </td><td> The request protocol </td></tr>
-<tr><td> *%\{Foobar}i* </td><td> The contents of Foobar: header line(s) in the request
-sent to the server. </td></tr>
-<tr><td> *%k* </td><td> Not supported in Sling; prints nothing. </td></tr>
-<tr><td> *%l* </td><td> Not supported in Sling; prints nothing. </td></tr>
-<tr><td> *%m* </td><td> The request method </td></tr>
-<tr><td> *%\{Foobar}n* </td><td> Not supported in Sling; prints nothing. </td></tr>
-<tr><td> *%\{Foobar}o* </td><td> The contents of Foobar: header line(s) in the reply. </td></tr>
-<tr><td> *%p* </td><td> The canonical port of the server serving the request </td></tr>
-<tr><td> *%\{format}p* </td><td> The canonical port of the server serving the request
-or the server's actual port or the client's actual port. Valid formats are
-canonical, local, or remote. </td></tr>
-<tr><td> *%P* </td><td> The _name of the thread_ -process ID of the child- that
-serviced the request. </td></tr>
-<tr><td> *%\{format}P* </td><td> Same as *%P*; the *format* parameter is ignored. </td></tr>
-<tr><td> *%q* </td><td> The query string (prepended with a ? if a query string exists,
-otherwise an empty string) </td></tr>
-<tr><td> *%r* </td><td> First line of request </td></tr>
-<tr><td> *%R* </td><td> The number of requests processed by Sling since the last start.
-</td></tr>
-<tr><td> *%s* </td><td> Status. </td></tr>
-<tr><td> *%t* </td><td> Time the request was received (standard english format) </td></tr>
-<tr><td> *%\{format}t* </td><td> Same as *%t*; the *format* parameter is ignored
-unless it is the literal value _end_ indicating to use the time of request
-terminating (instead of the time of request receipt). </td></tr>
-<tr><td> *%T* </td><td> The time taken to serve the request, in seconds. </td></tr>
-<tr><td> *%u* </td><td> Remote user (from auth; may be bogus if return status (%s) is
-401) </td></tr>
-<tr><td> *%U* </td><td> The URL path requested, not including any query string. </td></tr>
-<tr><td> *%v* </td><td> The canonical ServerName of the server serving the request. </td></tr>
-<tr><td> *%V* </td><td> Same as *%v*. </td></tr>
-<tr><td> *%X* </td><td> Not supported in Sling; prints nothing. </td></tr>
-<tr><td> *%I* </td><td> Not supported in Sling; prints nothing. </td></tr>
-<tr><td> *%O* </td><td> Not supported in Sling; prints nothing. </td></tr>
+<thead>
+<tr>
+<th>Format String</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>%%</code></td>
+<td>The percent sign</td>
+</tr>
+<tr>
+<td><code>%a</code></td>
+<td>Remote IP-address</td>
+</tr>
+<tr>
+<td><code>%A</code></td>
+<td>Local IP-address</td>
+</tr>
+<tr>
+<td><code>%B</code></td>
+<td>Size of response in bytes, excluding HTTP headers.</td>
+</tr>
+<tr>
+<td><code>%b</code></td>
+<td>Size of response in bytes, excluding HTTP headers. In CLF format, i.e. a '-' rather than a 0 when no bytes are sent.</td>
+</tr>
+<tr>
+<td><code>%\{Foobar}C</code></td>
+<td>The contents of cookie Foobar in the request sent to the server.</td>
+</tr>
+<tr>
+<td><code>%D</code></td>
+<td>The time taken to serve the request, in microseconds.</td>
+</tr>
+<tr>
+<td><code>%\{FOOBAR}e</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+<tr>
+<td><code>%f</code></td>
+<td>The absolute path of the resolved resource</td>
+</tr>
+<tr>
+<td><code>%h</code></td>
+<td>Remote host</td>
+</tr>
+<tr>
+<td><code>%H</code></td>
+<td>The request protocol</td>
+</tr>
+<tr>
+<td><code>%\{Foobar}i</code></td>
+<td>The contents of Foobar: header line(s) in the request sent to the server.</td>
+</tr>
+<tr>
+<td><code>%k</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+<tr>
+<td><code>%l</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+<tr>
+<td><code>%m</code></td>
+<td>The request method</td>
+</tr>
+<tr>
+<td><code>%\{Foobar}n</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+<tr>
+<td><code>%\{Foobar}o</code></td>
+<td>The contents of Foobar: header line(s) in the reply.</td>
+</tr>
+<tr>
+<td><code>%p</code></td>
+<td>The canonical port of the server serving the request</td>
+</tr>
+<tr>
+<td><code>%\{format}p</code></td>
+<td>The canonical port of the server serving the request or the server's actual port or the client's actual port. Valid formats are canonical, local, or remote.</td>
+</tr>
+<tr>
+<td><code>%P</code></td>
+<td>The <em>name of the thread</em> -process ID of the child- that serviced the request.</td>
+</tr>
+<tr>
+<td><code>%\{format}P</code></td>
+<td>Same as <code>%P</code>; the <code>format</code> parameter is ignored.</td>
+</tr>
+<tr>
+<td><code>%q</code></td>
+<td>The query string (prepended with a ? if a query string exists, otherwise an empty string)</td>
+</tr>
+<tr>
+<td><code>%r</code></td>
+<td>First line of request</td>
+</tr>
+<tr>
+<td><code>%R</code></td>
+<td>The number of requests processed by Sling since the last start.</td>
+</tr>
+<tr>
+<td><code>%s</code></td>
+<td>Status.</td>
+</tr>
+<tr>
+<td><code>%t</code></td>
+<td>Time the request was received (standard english format)</td>
+</tr>
+<tr>
+<td><code>%\{format}t</code></td>
+<td>Same as <code>%t</code>; the <code>format</code> parameter is ignored unless it is the literal value <em>end</em> indicating to use the time of request terminating (instead of the time of request receipt).</td>
+</tr>
+<tr>
+<td><code>%T</code></td>
+<td>The time taken to serve the request, in seconds.</td>
+</tr>
+<tr>
+<td><code>%u</code></td>
+<td>Remote user (from auth; may be bogus if return status (%s) is 401)</td>
+</tr>
+<tr>
+<td><code>%U</code></td>
+<td>The URL path requested, not including any query string.</td>
+</tr>
+<tr>
+<td><code>%v</code></td>
+<td>The canonical ServerName of the server serving the request.</td>
+</tr>
+<tr>
+<td><code>%V</code></td>
+<td>Same as <code>%v</code>.</td>
+</tr>
+<tr>
+<td><code>%X</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+<tr>
+<td><code>%I</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+<tr>
+<td><code>%O</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+</tbody>
</table>
-
<p><em>Modifiers</em></p>
-<p>Particular items can be restricted to print only for responses with
-specific HTTP status codes by placing a comma-separated list of status
-codes immediately following the "%". For example, "%400,501{User-agent}i"
-logs User-agent on 400 errors and 501 errors only. For other status codes,
-the literal string "-" will be logged. The status code list may be preceded
-by a "!" to indicate negation: "%!200,304,302{Referer}i" logs Referer on
-all requests that do not return one of the three specified codes.</p>
-<p>The Apache httpd modifiers "<" and ">" are not supported by Sling and
-currently ignored.</p>
+<p>Particular items can be restricted to print only for responses with specific HTTP status codes by placing a comma-separated list of status codes immediately following the "%". For example, "%400,501{User-agent}i" logs User-agent on 400 errors and 501 errors only. For other status codes, the literal string "-" will be logged. The status code list may be preceded by a "!" to indicate negation: "%!200,304,302{Referer}i" logs Referer on all requests that do not return one of the three specified codes.</p>
+<p>The Apache httpd modifiers "<" and ">" are not supported by Sling and currently ignored.</p>
<p><em>Some Notes</em></p>
-<p>For security reasons non-printable and other special characters in %C, %i
-and %o are escaped using \uhhhh sequences, where hhhh stands for the
-hexadecimal representation of the character's unicode value. Exceptions
-from this rule are " and \, which are escaped by prepending a backslash,
-and all whitespace characters, which are written in their Java-style
-notation (\n, \t, etc).</p>
-<p><a name="ClientRequestLogging-RotatingLoggerFiles"></a></p>
+<p>For security reasons non-printable and other special characters in %C, %i and %o are escaped using \uhhhh sequences, where hhhh stands for the hexadecimal representation of the character's unicode value. Exceptions from this rule are " and \, which are escaped by prepending a backslash, and all whitespace characters, which are written in their Java-style notation (\n, \t, etc).</p>
<h4 id="rotating-logger-files">Rotating Logger Files</h4>
-<p>If you want to write the request (and access) logging information into a
-rotated file, you should configure as follows:</p>
+<p>If you want to write the request (and access) logging information into a rotated file, you should configure as follows:</p>
<ol>
-<li>Configure the Log Type to be a <em>Logger Name</em> and some usefull Logger
-name. For example <em>clientlog.request</em>.</li>
-<li>Create an <em>Apache Sling Logging Logger Configuration</em> for this Logger
-name according to <a href="logging#logger-configuration.html">Logging Configuration</a>
- with the following setup:
- <strong> Allow message at INFO (Information) level to be logged which is the
-level used by the request loggers
- </strong> Define the appropriate log file name, for example
-<em>logs/client.request.log</em>
- <strong> Use only <em>{5</em>} as the message format because request logger
-messages are generally already fully formated with required timestamp etc.
+<li>Configure the Log Type to be a <em>Logger Name</em> and some usefull Logger name. For example <code>clientlog.request</code>.</li>
+<li>Create an <em>Apache Sling Logging Logger Configuration</em> for this Logger name according to <a href="">Logging Configuration</a> with the following setup:
+ <strong> Allow message at INFO (Information) level to be logged which is the level used by the request loggers
+ </strong> Define the appropriate log file name, for example <code>logs/client.request.log</code>
+ <strong> Use only <code>\{5</code>} as the message format because request logger messages are generally already fully formated with required timestamp etc.
<br />
-</strong> Add any Logger names used for the client request log configuration,
-<em>clientlog.request</em> in the example above, to the Logger field. By
-clicking on the <em>+</em> (plus) button you may add more than a single logger
-name whose messages are written to this file.</li>
-<li>Optionally, you may create an <em>Apache Sling Logging Writer
-Configuration</em> for the log file defined in the previous step to better
-control rotation setup. See <a href="logging#log-writer-configuration.html">Log Writer Configuration</a>
- for full details.</li>
+</strong> Add any Logger names used for the client request log configuration, <code>clientlog.request</code> in the example above, to the Logger field. By clicking on the <code>+</code> (plus) button you may add more than a single logger name whose messages are written to this file.</li>
+<li>Optionally, you may create an <em>Apache Sling Logging Writer Configuration</em> for the log file defined in the previous step to better control rotation setup. See <a href="">Log Writer Configuration</a> for full details.</li>
</ol>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1328899 by fmeschbe on Sun, 22 Apr 2012 16:52:13 +0000
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
Modified: websites/staging/sling/trunk/content/commons-html-utilities.html
==============================================================================
--- websites/staging/sling/trunk/content/commons-html-utilities.html (original)
+++ websites/staging/sling/trunk/content/commons-html-utilities.html Tue May 22 08:25:32 2012
@@ -82,13 +82,10 @@
<a href="/">Home</a>
</div>
<h1>Commons HTML Utilities</h1>
- <p><a name="CommonsHTMLUtilities-CommonsHTMLUtilities(org.apache.sling.commons.html)"></a></p>
-<h1 id="commons-html-utilities-orgapacheslingcommonshtml">Commons HTML Utilities (org.apache.sling.commons.html)</h1>
-<p>The Apache Sling Commons HTML Utilities bundle provides an HTML parser
-which can be used to parse HTML and either generate a DOM or SAX events out
-of the HTML. Therefore the parser transforms the HTML into proper XHTML.</p>
+ <h1 id="commons-html-utilities-orgapacheslingcommonshtml">Commons HTML Utilities (org.apache.sling.commons.html)</h1>
+<p>The Apache Sling Commons HTML Utilities bundle provides an HTML parser which can be used to parse HTML and either generate a DOM or SAX events out of the HTML. Therefore the parser transforms the HTML into proper XHTML.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1328899 by fmeschbe on Sun, 22 Apr 2012 16:52:13 +0000
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project