incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r818667 [10/18] - in /websites/staging/sling/trunk/content: ./ authentication/ documentation/ documentation/bundles/ documentation/development/ documentation/getting-started/ documentation/the-sling-engine/ documentation/the-sling-engine/au...
Date Tue, 22 May 2012 09:41:27 GMT
Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/adapters.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/adapters.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/adapters.html Tue May 22 09:41:22 2012
@@ -0,0 +1,189 @@
+<!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 - Adapters</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 &amp; 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>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/the-sling-engine.html">The Sling Engine</a>
+      </div>
+      <h1>Adapters</h1>
+      <p>The <code>Resource</code> and <code>ResourceResolver</code> interfaces are defined with a method <code>adaptTo</code>, which adapts the object to other classes. Using this mechanism the JCR session of the resource resolver calling the <code>adaptTo</code> method with the <code>javax.jcr.Session</code> class object. Likewise the JCR node on which a resource is based can be retrieved by calling the <code>Resource.adaptTo</code> method with the <code>javax.jcr.Node</code> class object.</p>
+<p>To use resources as scripts, the <code>Resource.adaptTo</code> method must support being called with the <code>org.apache.sling.api.script.SlingScript</code> class object. But of course, we do not want to integrate the script manager with the resource resolver. To enable adapting objects to classes which are not foreseen by the original implementation, a factory mechanism is used. This way, the script manager can provide an adapter factory to adapt <code>Resource</code> to <code>SlingScript</code> objects.</p>
+<h2 id="adaptable">Adaptable</h2>
+<p>The <code>Adaptable</code> interface defines the API to be implemented by a class providing adaptability to another class. The single method defined by this interface is</p>
+<div class="codehilite"><pre>/**
+ * Adapts the adaptable to another type.
+ * <span class="nt">&lt;p&gt;</span>
+ * Please not that it is explicitly left as an implementation detail whether
+ * each call to this method with the same <span class="nt">&lt;code&gt;</span>type<span class="nt">&lt;/code&gt;</span> yields the same
+ * object or a new object on each call.
+ * <span class="nt">&lt;p&gt;</span>
+ * Implementations of this method should document their adapted types as
+ * well as their behaviour with respect to returning newly created or not
+ * instance on each call.
+ *
+ * @param <span class="nt">&lt;AdapterType&gt;</span> The generic type to which this resource is adapted
+ *            to
+ * @param type The Class object of the target type, such as
+ *            <span class="nt">&lt;code&gt;</span>javax.jcr.Node.class<span class="nt">&lt;/code&gt;</span> or
+ *            <span class="nt">&lt;code&gt;</span>java.io.File.class<span class="nt">&lt;/code&gt;</span>
+ * @return The adapter target or <span class="nt">&lt;code&gt;</span>null<span class="nt">&lt;/code&gt;</span> if the resource cannot
+ *         adapt to the requested type
+ */
+<span class="nt">&lt;AdapterType&gt;</span> AdapterType adaptTo(Class<span class="nt">&lt;AdapterType&gt;</span> type);
+</pre></div>
+
+
+<p>This method is called to get a view of the same object in terms of another class. Examples of implementations of this method is the Sling <code>ResourceResolver</code> implementation providing adapting to a JCR session and the Sling JCR based <code>Resource</code> implementation providing adapting to a JCR node.</p>
+<h2 id="extending-adapters">Extending Adapters</h2>
+<p>Sometimes an <code>Adaptable</code> implementation cannot foresee future uses and requirements. To cope with such extensibility requirements two interfaces and an abstract base class are defined:</p>
+<ul>
+<li><code>AdapterManager</code></li>
+<li><code>AdapterFactory</code></li>
+<li><code>SlingAdaptable</code></li>
+</ul>
+<h2 id="adapterfactory">AdapterFactory</h2>
+<p>The <code>AdapterFactory</code> interface defines the service interface and API for factories supporting extensible adapters for <code>SlingAdaptable</code> objects. The interface has a single method:</p>
+<div class="codehilite"><pre>/**
+ * Adapt the given object to the adaptable type. The adaptable object is
+ * guaranteed to be an instance of one of the classes listed in the
+ * {@link #ADAPTABLE_CLASSES} services registration property. The type
+ * parameter is one of the classes listed in the {@link #ADAPTER_CLASSES}
+ * service registration properties.
+ * <span class="nt">&lt;p&gt;</span>
+ * This method may return <span class="nt">&lt;code&gt;</span>null<span class="nt">&lt;/code&gt;</span> if the adaptable object cannot
+ * be adapted to the adapter (target) type for any reason. In this case, the
+ * implementation should log a message to the log facility noting the cause
+ * for not being able to adapt.
+ * <span class="nt">&lt;p&gt;</span>
+ * Note that the <span class="nt">&lt;code&gt;</span>adaptable<span class="nt">&lt;/code&gt;</span> object is not required to implement
+ * the <span class="nt">&lt;code&gt;</span>Adaptable<span class="nt">&lt;/code&gt;</span> interface, though most of the time this method
+ * is called by means of calling the {@link Adaptable#adaptTo(Class)}
+ * method.
+ *
+ * @param <span class="nt">&lt;AdapterType&gt;</span> The generic type of the adapter (target) type.
+ * @param adaptable The object to adapt to the adapter type.
+ * @param type The type to which the object is to be adapted.
+ * @return The adapted object or <span class="nt">&lt;code&gt;</span>null<span class="nt">&lt;/code&gt;</span> if this factory instance
+ *         cannot adapt the object.
+ */
+<span class="nt">&lt;AdapterType&gt;</span> AdapterType getAdapter(Object adaptable,
+        Class<span class="nt">&lt;AdapterType&gt;</span> type);
+</pre></div>
+
+
+<p>Implementations of this interface are registered as OSGi services providing two lists: The list of classes wich may be adapted (property named <em>adaptables</em>) and the list of classes to which the adapted class may be adapted (property named <em>adapters</em>). A good example of an Class implementing <code>AdapterFactory</code> is the <code>SlingScriptAdapterFactory</code>.</p>
+<p><code>AdapterFactory</code> services are gathered by a <code>AdapterManager</code> implementation for use by consumers. Consumers should not care for <code>AdapterFactory</code> services.</p>
+<h2 id="adaptermanager">AdapterManager</h2>
+<p>The <code>AdapterManager</code> is defines the service interface for the genralized and extensible use of <code>AdapterFactory</code> services. Thus the adapter manager may be retrieved from the service registry to try to adapt whatever object that needs to be adapted - provided appropriate adapters exist.</p>
+<p>The <code>AdapterManager</code> interface is defined as follows:</p>
+<div class="codehilite"><pre>/**
+ * Returns an adapter object of the requested <span class="nt">&lt;code&gt;</span>AdapterType<span class="nt">&lt;/code&gt;</span> for
+ * the given <span class="nt">&lt;code&gt;</span>adaptable<span class="nt">&lt;/code&gt;</span> object.
+ * <span class="nt">&lt;p&gt;</span>
+ * The <span class="nt">&lt;code&gt;</span>adaptable<span class="nt">&lt;/code&gt;</span> object may be any non-<span class="nt">&lt;code&gt;</span>null<span class="nt">&lt;/code&gt;</span> object
+ * and is not required to implement the <span class="nt">&lt;code&gt;</span>Adaptable<span class="nt">&lt;/code&gt;</span> interface.
+ *
+ * @param <span class="nt">&lt;AdapterType&gt;</span> The generic type of the adapter (target) type.
+ * @param adaptable The object to adapt to the adapter type.
+ * @param type The type to which the object is to be adapted.
+ * @return The adapted object or <span class="nt">&lt;code&gt;</span>null<span class="nt">&lt;/code&gt;</span> if no factory exists to
+ *         adapt the <span class="nt">&lt;code&gt;</span>adaptable<span class="nt">&lt;/code&gt;</span> to the <span class="nt">&lt;code&gt;</span>AdapterType<span class="nt">&lt;/code&gt;</span>
+ *         or if the <span class="nt">&lt;code&gt;</span>adaptable<span class="nt">&lt;/code&gt;</span> cannot be adapted for any other
+ *         reason.
+ */
+<span class="nt">&lt;AdapterType&gt;</span> AdapterType getAdapter(Object adaptable,
+        Class<span class="nt">&lt;AdapterType&gt;</span> type);
+</pre></div>
+
+
+<p>Any object can theoretically be adapted to any class even if it does not implement the <code>Adaptable</code> interface, if an <code>AdapterFactory</code> service delivers a <code>getAdapter()</code> method which adapts an object to another one. To check if there's any existing <code>AdapterFactory</code> which can adapt a given object to another one the <code>AdapterManager</code> service with it's <code>getAdapter()</code> method does the job. So the <code>Adaptable</code> interface merely is an indicator that the object provides built-in support for beeing adapted.</p>
+<h2 id="slingadaptable">SlingAdaptable</h2>
+<p>The <code>SlingAdaptable</code> class is an implementation of the <code>Adaptable</code> interface which provides built-in support to call the <code>AdapterManager</code> to provide an adapter from the <code>Adaptable</code> object to the requested class.</p>
+<p>An example of extending the <code>SlingAdaptable</code> class will be the Sling JCR based <code>Resource</code> implementation. This way, such a resource may be adapted to a <code>SlingScript</code> by means of an appropriatley programmed <code>AdapterFactory</code> (see below).</p>
+      <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+        Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +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/documentation/the-sling-engine/architecture.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/architecture.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/architecture.html Tue May 22 09:41:22 2012
@@ -0,0 +1,149 @@
+<!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 - Architecture</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 &amp; 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>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/the-sling-engine.html">The Sling Engine</a>
+      </div>
+      <h1>Architecture</h1>
+      <p>The following is a short list of high-lights of Sling:</p>
+<ul>
+<li><em><a href="">OSGi</a></em> --- The Sling application is built as a series of OSGi bundles and makes heavy use of a number of OSGi core and compendium services.</li>
+<li><em><a href="">#Sling API</a></em> --- To implement content based Web applications with Sling, an API has been defined, this extends the Servlet API and provides more functionality to work on the content.</li>
+<li><em><a href="">#Request Processing</a></em> --- Sling takes a unique approach to handling requests in that a request URL is first resolved to a resource, then based on the resource (and only the resource) it selects the actual servlet or script to handle the request.</li>
+<li><em><a href="">#Resources</a></em> --- The central mantra of Sling is the <em>Resource</em>, which represents the resource addressed by any request URL. It is the resource that is first resolved when handling a request. Based on the resource, a first servlet or script is then accessed to actually handle the request.</li>
+<li><em><a href="">#Servlets and Scripts</a></em> --- Servlets and Scripts are handled uniformly in that they are represented as resources themselves and are accessible by a resource path.</li>
+<li><em><a href="">#Launchpad</a></em> --- Sling uses a very thin launcher to integrate with an existing servlet container, launching Sling as a Web application or providing a main class to represent a standalone Java application.</li>
+</ul>
+<p>The following sections elaborate on each of these highlights.</p>
+<h2 id="osgi">OSGi</h2>
+<p><a href="">OSGi</a> is a consortium that has developed a specification to build modular and extensible applications. This offers [various benefits|http://www.osgi.org/About/WhyOSGi]. We deal mainly with two parts of the specifications: The Core Specification, which defines the OSGi Framework and Core Services, and the Compendium Services Specification, which defines a host of services that extend the functionality of the OSGi Framework.</p>
+<h3 id="osgi-framework">OSGi Framework</h3>
+<p>The OSGi Framework is made up of three layers -- Module, Lifecycle, and Services -- that define how extensible applications are built and deployed. The responsibilities of the layers are:</p>
+<ul>
+<li><em>Module</em> --- Defines how a module, or a <em>Bundle</em> in OSGi-speak, is defined. Basically, a bundle is just a plain old JAR file, whose manifest file has some defined entries. These entries identify the bundle with a symbolic name, a version and more. In addition there are headers which define what a bundle provides -- <code>Export-Package</code> -- and what a bundle requires to be operative -- <code>Import-Package</code> and <code>Require-Bundle</code>.</li>
+<li><em>Lifecycle</em> --- The lifecycle layer defines the states a bundle may be in and describes the state changes. By providing a class, which implements the <code>BundleActivator</code> interface and which is named in the <code>Bundle-Activator</code> manifest header, a bundle may hook into the lifecycle process when the bundle is started and stopped.</li>
+<li><em>Services</em> --- For the application to be able to interact, the OSGi Core Specification defines the service layer. This describes a registry for services, which may be shared.</li>
+</ul>
+<h3 id="compendium-services">Compendium Services</h3>
+<p>Based on the OSGi Framework specification, the Compendium Services specification defines a (growing) number of extension services, which may be used by applications for various tasks. Of these Compendium Services, Sling is using just a small number:</p>
+<ul>
+<li><em>Log Service</em> --- Sling comes with its own implementation of the OSGi Log Service specification. The respective bundle not only provides this implementation, it also exports the SLF4J, Log4J and Commons Logging APIs needed for the Sling application to perform logging.</li>
+<li><em>Http Service</em> --- Sling leverages the OSGi Http Service to hook into a servlet container to provide the Web Application Framework mechanism.</li>
+<li><em>Configuration Admin Service</em> --- To simplify configuration of services in Sling, the OSGi Configuration Admin service is used. This provides a uniform API to configure services and to build configuration management agents.</li>
+<li><em>Metatype Service</em> --- The OSGi Metatype Service defines a way to describe the data types. Sling uses this service to describe the configurations that may be created using the Configuration Admin Service. These meta type descriptions are used by configuration management agents to present to user interface to manage the configurations.</li>
+<li><em>Event Admin Service</em> --- Sling uses the OSGi EventAdmin service to dispatch events when scheduling tasks.</li>
+<li><em>Declarative Services</em> --- One of the most important (beside the Log Service) services used by Sling is the Declarative Services Specification. This specification defines how to declaratively create components and services to have the Declarative Services runtime actually manage the lifecycle, configuration and references of components.</li>
+</ul>
+<h2 id="sling-api">Sling API</h2>
+<p>The Sling API is an extension to the Servlet API which provides more functionality to interact with the Sling framework and also to extend Sling itself and to implement Sling applications.</p>
+<p>See the <a href="/old-stuff/sling-api.html">Sling API</a> page for more information.</p>
+<h2 id="request-processing">Request Processing</h2>
+<p>Traditional Web Application framework emply more or less elaborate methods to select a Servlet or Controller based on the request URL, which in turn tries to load some data (usually from a database) to act upon and finally to render the result somehow.</p>
+<p>Sling turns this processing around in that it places the data to act upon at the center and consequently uses the request URL to first resolve the data to process. This data is internally represented as an instance of the <code>Resource</code> interface. Based on this resource as well as the request method and more properties of the request URL a script or servlet is then selected to handle the request.</p>
+<p>See the <a href="/documentation/the-sling-engine/servlets.html">Servlets</a> page for more information.</p>
+<h2 id="resources">Resources</h2>
+<p>The Resource is one of the central parts of Sling. Extending from JCR's <em>Everything is Content</em>, Sling assumes <em>Everthing is a Resource</em>. Thus Sling is maintaining a virtual tree of resources, which is a merger of the actual contents in the JCR Repository and resources provided by so called resource providers.</p>
+<p>Each resource has a path by which it is addressed in the resource tree, a resource type and some resource metadata (such as file size, last modification time). It is important to understand, that a <code>Resource</code> instance actually is only a handle to the actual data. By virtue of the <code>adaptTo(Class&lt;Type&gt;)</code> method, a resource may be coerced into another data type, which may then be used while processing the request. Examples of data types are <code>javax.jcr.Node</code> and <code>java.io.InputStream</code>.</p>
+<p>See the <a href="/documentation/the-sling-engine/resources.html">Resources</a> page for more information.</p>
+<h2 id="servlets-and-scripts">Servlets and Scripts</h2>
+<p>Scripts are usually provided as content in a JCR repository. But since Sling is using a resource tree, a script actually is represented as a Resource and may be provided from within a Bundle (by virtue of the bundle resource provider) or even from the platform file system (by virtue of the file system resource provider).</p>
+<p>Accessing scripts in the resource tree, allows for a very easy to understand mapping from resource type to some script path.</p>
+<p>Having found the script resource, we still need access to the appropriate script language implementation to evaluate the script. To this avail, Sling is making use of the <code>Resource.adaptTo(Class&lt;Type&gt;)</code> method: If a script language implementation is available for the extension of the script name an adaptor for the script resource can be found, which handles the evaluation of the script.</p>
+<p>Besides scripting languages, such as ECMAScript, Groovy, JSP, Sling also supports regular servlets. To be able to use servlets for request processing, such servlets must be registered as OSGi services for the <code>javax.servlet.Servlet</code> interface and provide a number of service registration properties, which are used to use the servlets. In fact servlets thus registered as OSGi services are mapped into the resource tree by means of a servlet resource provider. This resource provider mapps the servlets into the resource tree using the service registration properties to build one or more resource paths for the servlet.</p>
+<p>As a result of mapping servlets into the resource tree and the possibility to adapt resource to an adaptor data type, scripts and servlets may be handled completely transparently: The servlet resolver just looks for a resource matching the resource type and adapts the resource found to <code>javax.jcr.Servlet</code>. If the resource happens to be provided by a servlet resource provider, the adapter is of course the servlet itself. If the resource happens to be a script, the adapter is a servlet facade which internally calls the script language implementation to evaluate the script.</p>
+<p>See the <a href="/old-stuff/servlet-resolution.html">Servlet Resolution</a> page for more information.</p>
+<h2 id="launchpad">Launchpad</h2>
+<p>Sling may be launched as a standalone application using the Sling Application or as a Web Application running inside any Servlet API 2.4 or newer Servlet Container.</p>
+<p>The Sling Application is a standalone Java Application which is really small: Just the main class and some glue classes. The OSGi framework as well as the OSGi API libraries are packaged as a JAR file, which is loaded through a custom classloader. This enables to update the framework and/or OSGi API libraries from within Sling by updating the system bundle.</p>
+<p>The Sling Servlet is equally small as the Sling Application. It uses the Felix <code>HttpService</code> bridge as the glue between the servlet container and the OSGi framework.</p>
+<p>As we have seen, Sling may be launched as a standalone Java Application or as a Web Application inside any compliant Servlet Container. To hide the differences of the launching mechanism, Sling internally registers a Servlet with an OSGi <code>HttpService</code>. Regardless of how Sling is launched, the Felix implementation of the OSGi <code>HttpService</code> specification is used. When Sling is launched as a standalone Java Application, Felix HttpService uses an embedded version of the Jetty servlet container. When Sling is launched as a Web Application, the Felix HttpService Bridge is used.</p>
+<p>Optionally, PAX Web's implementation of HttpService can be used when Sling is launched as a standalone Java Application. See the <a href="/documentation/development/maven-launchpad-plugin.html">Maven Launchpad Plugin</a> page for information on how to do this.</p>
+<p>See <a href="/documentation/the-sling-engine/the-sling-launchpad.html">The Sling Launchpad</a> for more information.</p>
+      <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+        Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +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/documentation/the-sling-engine/authentication.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication.html Tue May 22 09:41:22 2012
@@ -0,0 +1,116 @@
+<!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</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 &amp; 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>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/the-sling-engine.html">The Sling Engine</a>
+      </div>
+      <h1>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}
+!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 <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 <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><a href="/documentation/the-sling-engine/authentication/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="/documentation/the-sling-engine/authentication/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="/documentation/the-sling-engine/authentication/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="/documentation/the-sling-engine/authentication/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. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +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/documentation/the-sling-engine/authentication.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-actors.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-actors.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-actors.html Tue May 22 09:41:22 2012
@@ -0,0 +1,137 @@
+<!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 - Actors</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 &amp; 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>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/the-sling-engine.html">The Sling Engine</a>&nbsp;&raquo&nbsp;<a href="/documentation/the-sling-engine/authentication.html">Authentication</a>
+      </div>
+      <h1>Authentication - Actors</h1>
+      <p>The authentication process involves a number of actors contributing to the concepts, the API and the particular implementations.</p>
+<h2 id="osgi-http-service-specification">OSGi Http Service Specification</h2>
+<p>The main support for authentication is defined by the OSGi Http Service specification. This specification defines how an OSGi application can register servlets and resources to build web applications. As part of the servlet and/or resource registration a <code>HttpContext</code> may be provided, which allows for additional support.</p>
+<p>The main method of interest to the authentication process is the <code>handleSecurity</code> method. This is called by the OSGi Http Service implementation before the registered servlet is called. Its intent is to authenticate the request and to provide authentication information for the request object: the authentication type and the remote user name.</p>
+<p>The Sling Commons Auth bundle provides the <code>AuthenticationSupport</code> service which may be used to the implement the <code>HttpContext.handleSecurity</code> method.</p>
+<h2 id="sling-engine">Sling Engine</h2>
+<p>The Sling Engine implements the main entry point into the Sling system by means of the <code>SlingMainServlet</code>. This servlet is registered with the OSGi Http Service and provides a custom <code>HttpContext</code> whose <code>handleSecurity</code> method is implemented by the <code>AuthenticationSupport</code> service.</p>
+<p>When the request hits the <code>service</code> method of the Sling Main Servlet, the resource resolver provided by the <code>AuthenticationSupport</code> service is retrieved from the request attributes and used as the resource resolver for the request.</p>
+<p>That's all there is for the Sling Engine to do with respect to authentication.</p>
+<h2 id="sling-commons-auth">Sling Commons Auth</h2>
+<p>The support for authenticating client requests is implemented in the Sling Commons Auth bundle. As such this bundle provides three areas of support</p>
+<ul>
+<li><code>AuthenticationHandler</code> service interface. This is implemented by services providing functionality to extract credentials from HTTP requests.</li>
+<li><code>Authenticator</code> service interface. This is implemented by the <code>SlingAuthenticator</code> class in the Commons Auth bundle and provides applications with entry points to login and logout.</li>
+<li><code>AuthenticationSupport</code> service interface. This is implemented by the <code>SlingAuthenticator</code> class in the Commons Auth bundle and allows applications registering with the OSGi HTTP Service to make use of the Sling authentication infrastructure.</li>
+</ul>
+<h2 id="jcr-repository">JCR Repository</h2>
+<p>The actual process of logging into the repository and provided a <code>Session</code> is implementation dependent. In the case of Jackrabbit extensibility is provided by configuration of the Jackrabbit repository by means of an interface and two helper classes:</p>
+<ul>
+<li><code>LoginModule</code> -- The interface to be implemented to provide login processing plugins</li>
+<li><code>AbstractLoginModule</code> -- A an abstract base class implementation of the <code>LoginModule</code> interface.</li>
+<li><code>DefaultLoginModule</code> -- The default implementation of the <code>AbstractLoginModule</code> provided by Jackabbit. This login module takes <code>SimpleCredentials</code> and uses the repository to lookup the users, validate the credentials and providing the <code>Principal</code> representing the user towards the repository.</li>
+</ul>
+<p>The Sling Jackrabbit Embedded Repository bundle provides additional plugin interfaces to extend the login process dynamically using OSGi services. To this avail the bundle configures a <code>LoginModule</code> with the provided default Jackrabbit configuration supporting these plugins:</p>
+<ul>
+<li><code>LoginModulePlugin</code> -- The main service interface. Plugins must implement this interface to be able to extend the login process. See for example the <a href="">Sling OpenID authentication handler</a>, which implements this interface to support OpenID authentication.</li>
+<li><code>AuthenticationPlugin</code> -- Helper interface for the <code>LoginModulePlugin</code>.</li>
+</ul>
+<h2 id="sling-applications">Sling Applications</h2>
+<p>Sling Applications requiring authenticed requests should not care about how authentication is implemented. To support such functionality the <code>Authenticator</code> service is provided with two methods:</p>
+<ul>
+<li>
+<p><code>login</code> -- allows the application to ensure requests are authenticated. This involves selecting an <code>AuthenticationHandler</code> to request credentials for authentication.</p>
+</li>
+<li>
+<p><code>logout</code> -- allows the application to forget about any authentication. This involves selecting an <code>AuthenticationHandler</code> to forget about credentials in the request.</p>
+</li>
+</ul>
+<p>Sling Applications should never directly use any knowledge of any authentication handler or directly call into an authentication handler. This will certainly break the application and cause unexpected behaviour.</p>
+<p>{info}
+If you want to know whether a request is authenticated or not, you can inspect the result of the <code>HttpServletRequest.getAuthType</code> method: If this method returns <code>null</code> the request is not authenticated.
+{info}</p>
+      <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+        Rev. 1341361 by fmeschbe on Tue, 22 May 2012 08:54:04 +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/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html Tue May 22 09:41:22 2012
@@ -0,0 +1,126 @@
+<!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 - AuthenticationHandler</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 &amp; 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>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/the-sling-engine.html">The Sling Engine</a>&nbsp;&raquo&nbsp;<a href="/documentation/the-sling-engine/authentication.html">Authentication</a>
+      </div>
+      <h1>Authentication - AuthenticationHandler</h1>
+      <p>The <code>AuthenticationHandler</code> interface defines the service API which may be implemented by authentication handlers registered as OSGi services.</p>
+<p><code>AuthenticationHandler</code> services have a single required service registration property which is used to identify requests to which the <code>AuthenticationHandler</code> service is applicable:</p>
+<p>| <code>path</code> | One or more (array or vector) string values indicating the request URLs to which the <code>AuthenticationHandler</code> is applicable. |
+| <code>authtype</code> | The authentication type implemented by this handler. This is a string value property and should be the same as will be used as the authentication type of the <code>AuthenticationInfo</code> object provided by the <code>extractCredentials</code> method. If this property is set, the <code>requestCredentials</code> method of the authentication handler is only called if the <code>sling:authRequestLogin</code> request parameter is either not set or is set to the same value as the <code>authtype</code> of the handler. This property is optional. If not set, the <code>requestCredentials</code> method is always called regardless of the value of the <code>sling:authRequestLogin</code> request parameter. |</p>
+<p>Each path may be an absolute URL, an URL with just the host/port and path or just a plain absolute path:</p>
+<p>| URL part | Scheme | Host/Port | Path |
+| Absolute URL | must match | must match | request URL path is prefixed with the path |
+| Host/Port with Path | ignored | must match | request URL path is prefixed with the path |
+| Path | ignored | ignored | request URL path is prefixed with the path |</p>
+<p>When looking for an <code>AuthenticationHandler</code> the authentication handler is selected whose path is the longest match on the request URL. If the service is registered with Scheme and Host/Port, these must exactly match for the service to be eligible. If multiple <code>AuthenticationHandler</code> services are registered with the same length matching path, the handler with the higher service ranking is selected{footnote}Service ranking is defined by the OSGi Core Specification as follows: <em>If multiple qualifying service interfaces exist, a service with the highest <code>service.ranking</code> number, or when equal to the lowest <code>service.id</code>, determines which service object is returned by the Framework</em>.{footnote}.</p>
+<p>The value of <code>path</code> service registration property value triggering the call to any of the <code>AuthenticationHandler</code> methods is available as the <code>path</code> request attribute (for the time of the method call only). If the service is registered with multiple path values, the value of the <code>path</code> request attribute may be used to implement specific handling.</p>
+<h3 id="implementations-provided-by-sling">Implementations provided by Sling</h3>
+<ul>
+<li><a href="/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html">Form Based AuthenticationHandler</a></li>
+<li><a href="/documentation/the-sling-engine/authentication/authentication-authenticationhandler/openid-authenticationhandler.html">OpenID AuthenticationHandler</a></li>
+</ul>
+<h3 id="sample-implementations">Sample implementations</h3>
+<h4 id="http-basic-authentication-handler">HTTP Basic Authentication Handler</h4>
+<ul>
+<li><code>extractCredentials</code> -- Get user name and password from the <code>Authorization</code> HTTP header</li>
+<li><code>requestCredentials</code> -- Send a 401/UNAUTHORIZED status with <code>WWW-Authenticate</code> response header setting the Realm</li>
+<li><code>dropCredentials</code> -- Send a 401/UNAUTHORIZED status with <code>WWW-Authenticate</code> response header setting the Realm</li>
+</ul>
+<p>Interestingly the <code>dropCredentials</code> method is implemented in the same way as the <code>requestCredentials</code> method. The reason for this is, that HTTP Basic authentication does not have a notion of login and logout. Rather the request is accompanied with an <code>Authorization</code> header or not. The contents of this header is usually cached by the client browser. So logout is actually simulated by sending a 401/UNAUTHORIZED status thus causing the client browser to clear the cache and ask for user name and password.</p>
+<h4 id="form-based-authentication-handler">Form Based Authentication Handler</h4>
+<ul>
+<li><code>extractCredentials</code> -- Get user name and password with the help of a special cookie (note, that of course the cookie should not contain this data, but refer to it in an internal store of the authentication handler). If the cookie is not set, check for specific login parameters to setup the cookie.</li>
+<li><code>requestCredentials</code> -- Send the login form for the user to provide the login parameters.</li>
+<li><code>dropCredentials</code> -- Clear the authentication cookie and internal store.</li>
+</ul>
+<p>///Footnotes Go Here///</p>
+      <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+        Rev. 1341361 by fmeschbe on Tue, 22 May 2012 08:54:04 +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/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html Tue May 22 09:41:22 2012
@@ -0,0 +1,255 @@
+<!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 - Form Based AuthenticationHandler</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 &amp; 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>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/the-sling-engine.html">The Sling Engine</a>&nbsp;&raquo&nbsp;<a href="/documentation/the-sling-engine/authentication.html">Authentication</a>&nbsp;&raquo&nbsp;<a href="/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html">Authentication - AuthenticationHandler</a>
+      </div>
+      <h1>Form Based AuthenticationHandler</h1>
+      <div class="toc">
+<ul>
+<li><a href="#authenticationhandler-implementation">AuthenticationHandler implementation</a></li>
+<li><a href="#authenticationfeedbackhandler-implementation">AuthenticationFeedbackHandler implementation</a></li>
+<li><a href="#phase-1-form-submission">Phase 1: Form Submission</a></li>
+<li><a href="#phase-2-authenticated-requests">Phase 2: Authenticated Requests</a></li>
+<li><a href="#configuration">Configuration</a></li>
+<li><a href="#security-considerations">Security Considerations</a></li>
+</ul>
+</div>
+<p>The Form Based AuthenticationHandler has two authentication phases: The first phase is presenting a login form to the user and passing the entered user name and password to the server. The second phase is storing successful authentication in a Cookie or an HTTP Session.</p>
+<p>The implementation of the Form Based Authentication Handler follows the guidelines of the Servlet API 2.4 specification for <em>Form Based Authentication</em> in section SRV.12.5.3. Specifically the following requirements are implemented:</p>
+<ul>
+<li>For the initial form submission, the request URL must end with <code>/j*security*check</code> and the user name and password names must be <code>j*username</code> and <code>j*password</code>, resp.</li>
+<li>The authentication type as returned by <code>HttpServletRequest.getAuthType()</code> is set to <code>HttpServletRequest.FORM_AUTH</code>.</li>
+</ul>
+<p>The Form Based Authentication Handler is maintained in the <a href="">Sling SVN</a></p>
+<h3 id="authenticationhandler-implementation">AuthenticationHandler implementation</h3>
+<ul>
+<li><code>extractCredentials</code> -- Prepares credentials for the form entered data or from the Cookie or HTTP Session attribute. Returns <code>null</code> if neither data is provided in the request</li>
+<li><code>requestCredentials</code> -- Redirects the client (browser) to the login form</li>
+<li><code>dropCredentials</code> -- Remove the Cookie or remove the HTTP Session attribute</li>
+</ul>
+<h3 id="authenticationfeedbackhandler-implementation">AuthenticationFeedbackHandler implementation</h3>
+<ul>
+<li><code>authenticationFailed</code> -- Remove the Cookie or remove the HTTP Session attribute</li>
+<li><code>authenticationSucceeded</code> -- Set (or update) the Cookie or HTTP Session attribute</li>
+</ul>
+<h3 id="phase-1-form-submission">Phase 1: Form Submission</h3>
+<p>The login form submitted in phase 1 to validate the user name and password must be provided in an HTTP <code>POST</code> request to an URL whose last segment is <code>j*security*check</code>. The request is ignored as a form submission if either the method is not <code>POST</code> or the last segment is no <code>j*security*check</code>.</p>
+<p>The form is rendered by redirecting the client to the URL indicated by the <code>form.login.form</code> configuration parameter. This redirection request may accompanyied by the following parameters:</p>
+<ul>
+<li><code>resource</code> -- The resource to which the user should be redirected after successful login. This request parameter should be submitted back to the server as the <code>resource</code> parameter.</li>
+<li><code>j*reason</code> -- This parameter indicates the reason for rendering the login form. If this parameter is set, it is set to <code>INVALID*CREDENTIALS</code> indicating a previous form submission presented invalid username and password or <code>TIMEOUT</code> indicating a login session has timed out. The login form servlet/script can present the user with an appropriate message.</li>
+</ul>
+<p>The Form Based Authentication Handlers supports the following request parameters submitted by the HTML form:</p>
+<ul>
+<li><code>j_username</code> -- Name of the user to authenticate</li>
+<li><code>j_password</code> -- Password to authenticate the user</li>
+<li><code>j_validate</code> -- Flag indicating whether to just validate the credentials</li>
+<li><code>resource</code> -- The location to go to on successful login</li>
+<li><code>sling.auth.redirect</code> -- The location to redirect to on successful login</li>
+</ul>
+<p>The <code>j*username</code> and <code>j*password</code> parameters are used to create a JCR <code>SimpleCredentials</code> object to log into the JCR Repository.</p>
+<p>The <code>j_validate</code> parameter may be used to implement login form submission using AJAX. If this parameter is set to <code>true</code> (case-insensitive) the credentials are used to login and after success or failure to return a status code:</p>
+<table>
+<thead>
+<tr>
+<th>Status</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>200 OK</code></td>
+<td>Authentication succeeded; credentials are valid for login; the Cookie or HTTP Session attribute is now set</td>
+</tr>
+<tr>
+<td><code>403 FORBIDDEN</code></td>
+<td>Authentication failed; credentials are invalid for login; the Cookie or HTTP Session attribute is not set (if it was set, it is now cleared)</td>
+</tr>
+</tbody>
+</table>
+<p>If the <code>j_validate</code> parameter is not set or is set to any value other than <code>true</code>, the request processing depends on authentication success or failure:</p>
+<table>
+<thead>
+<tr>
+<th>Authentication</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Success</td>
+<td>Client is redirected to the authenticated resource; the Cookie or HTTP Session attribute is now set.</td>
+</tr>
+<tr>
+<td>Failure</td>
+<td>The request is redirected to the login form again; the Cookie or HTTP Session attribute is not set (if it was set, it is now cleared)</td>
+</tr>
+</tbody>
+</table>
+<p>The <code>resource</code> and <code>sling.auth.redirect</code> parameters provide similar functionality but with differing historical backgrounds. The <code>resource</code> parameter is based on the <code>resource</code> request attribute which is set by the login servlet to indicate the original target resource the client desired when it was forced to authenticate. The <code>sling.auth.redirect</code> parameter can be used by clients (applications like cURL or plain HTML forms) to request being redirected after successful login. If both parameters are set, the <code>sling.auth.redirect</code> parameter takes precedence.</p>
+<p>The Form Based Authentication Handler contains a <a href="">default form servlet</a> and [HTML form template from|http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/form/src/main/resources/org/apache/sling/auth/form/impl/login.html].</p>
+<h3 id="phase-2-authenticated-requests">Phase 2: Authenticated Requests</h3>
+<p>After the successful authentication of the user in phase 1, the authentication state is stored in a Cookie or an HTTP Session. The stored value is a security token with the following contents:</p>
+<div class="codehilite"><pre><span class="n">HmacSHA1</span><span class="p">(</span><span class="n">securetoken</span><span class="p">,</span> <span class="sr">&lt;securetokennumber&gt;&lt;expirytime&gt;</span><span class="nv">@</span><span class="err">&lt;</span><span class="nv">userID</span><span class="o">&gt;</span><span class="p">)</span><span class="nv">@</span><span class="err">&lt;</span><span class="nv">securetokennumber</span><span class="o">&gt;</span><span class="sr">&lt;expirytime&gt;</span><span class="nv">@</span><span class="err">&lt;</span><span class="nv">userID</span><span class="o">&gt;</span>
+</pre></div>
+
+
+<p>The <code>securetoken</code> and <code>securetokennumber</code> are related in that an table of secure tokens is maintained where the <code>securetoken</code> is an entry in the table and the <code>securetokennumber</code> is the index in of the token in the table.</p>
+<p>The secure tokens are refreshed periodically causing the authentication state stored in the Cookie or the HTTP Session to be updated peridocally. This periodic update has two advantages:</p>
+<ul>
+<li>Login sessions time out after some period of inactivity: If a request is handled for an authentication state whose expiry time has passed, the request is considered unauthenticated.</li>
+<li>If a Cookie would be stolen or an HTTP Session be hijacked, the authentication state expires within a reasonable amount of time to try to prevent stealing the authentication.</li>
+</ul>
+<p>The authentication state may be transmitted with a Cookie which is configured as follows:</p>
+<ul>
+<li><em>Cookie Path</em> -- Set to the servlet context path</li>
+<li><em>Domain</em> -- See below</li>
+<li><em>Age</em> -- Set to -1 to indicate a session Cookie</li>
+<li><em>Secure</em> -- Set to the value returned by the <code>ServletRequest.isSecure()</code> method</li>
+</ul>
+<p>If the authentication state is kept in an HTTP Session the setup of the session ID cookie is maintained by the servlet container and is outside of the control of the Form Based AuthenticationHandler.</p>
+<h3 id="configuration">Configuration</h3>
+<p>The Form Based Authentication Handler is configured with configuration provided by the OSGi Configuration Admin Service using the <code>org.apache.sling.formauth.FormAuthenticationHandler</code> service PID.</p>
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>form.login.form</code></td>
+<td><code>/system/sling/form/login</code></td>
+<td>The URL (without any context path prefix) to redirect the client to to present the login form.</td>
+</tr>
+<tr>
+<td><code>form.auth.storage</code></td>
+<td><code>cookie</code></td>
+<td>The type of storage used to provide the authentication state. Valid values are <code>cookie</code> and <code>session</code>. The default value also applies if any setting other than the supported values is configured.</td>
+</tr>
+<tr>
+<td><code>form.auth.name</code></td>
+<td><code>sling.formauth</code></td>
+<td>The name of the Cookie or HTTP Session attribute providing the authentication state.</td>
+</tr>
+<tr>
+<td><code>form.auth.timeout</code></td>
+<td><code>30</code></td>
+<td>The number of minutes after which a login session times out. This value is used as the expiry time set in the authentication data.</td>
+</tr>
+<tr>
+<td><code>form.credentials.name</code></td>
+<td><code>sling.formauth</code></td>
+<td>The name of the <code>SimpleCredentials</code> attribute used to provide the authentication data to the <code>LoginModulePlugin</code>.</td>
+</tr>
+<tr>
+<td><code>form.token.file</code></td>
+<td><code>cookie-tokens.bin</code></td>
+<td>The name of the file used to persist the security tokens.</td>
+</tr>
+<tr>
+<td><code>form.default.cookie.domain</code></td>
+<td></td>
+<td>The domain on which cookies will be set, unless overridden in the <code>AuthenticationInfo</code> object.</td>
+</tr>
+</tbody>
+</table>
+<p><em>Note:</em> The <code>form.token.file</code> parameter currently refers to a file stored in the file system. If the path is a relative path, the file is either stored in the Authentication Handler bundle private data area or -- if not possible -- below the location indicated by the <code>sling.home</code> framework property or -- if <code>sling.home</code> is not set -- the current working directory. In the future this file may be store in the JCR Repository to support clustering scenarios.</p>
+<h3 id="security-considerations">Security Considerations</h3>
+<p>Form Based Authentication has some limitations in terms of security:</p>
+<ol>
+<li>User name and password are transmitted in plain text in the initial form submission.</li>
+<li>The Cookie used to provide the authentication state or the HTTP Session ID may be stolen.</li>
+</ol>
+<p>To prevent eavesdroppers from sniffing the credentials or stealing the Cookie a secure transport layer should be used such as TLS/SSL, VPN or IPSec.</p>
+      <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+        Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +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>



Mime
View raw message