incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r1328899 [2/8] - in /sling/site/trunk: content/ templates/
Date Sun, 22 Apr 2012 16:52:16 GMT
Added: sling/site/trunk/content/authentication---actors.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/authentication---actors.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/authentication---actors.mdtext (added)
+++ sling/site/trunk/content/authentication---actors.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,118 @@
+Title: Authentication - Actors
+<a name="Authentication-Actors-Actors"></a>
+# Actors
+
+{excerpt}The authentication process involves a number of actors
+contributing to the concepts, the API and the particular
+implementations.{excerpt}
+
+
+<a name="Authentication-Actors-OSGiHttpServiceSpecification"></a>
+## OSGi Http Service Specification
+
+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 *HttpContext* may be provided,
+which allows for additional support.
+
+The main method of interest to the authentication process is the
+*handleSecurity* 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.
+
+The Sling Commons Auth bundle provides the *AuthenticationSupport*
+service which may be used to the implement the
+*HttpContext.handleSecurity* method.
+
+
+<a name="Authentication-Actors-SlingEngine"></a>
+## Sling Engine
+
+The Sling Engine implements the main entry point into the Sling system by
+means of the *SlingMainServlet*. This servlet is registered with the OSGi
+Http Service and provides a custom *HttpContext* whose *handleSecurity*
+method is implemented by the *AuthenticationSupport* service.
+
+When the request hits the *service* method of the Sling Main Servlet, the
+resource resolver provided by the *AuthenticationSupport* service is
+retrieved from the request attributes and used as the resource resolver for
+the request.
+
+That's all there is for the Sling Engine to do with respect to
+authentication.
+
+
+<a name="Authentication-Actors-SlingCommonsAuth"></a>
+## Sling Commons Auth
+
+The support for authenticating client requests is implemented in the Sling
+Commons Auth bundle. As such this bundle provides three areas of support
+
+ * *AuthenticationHandler* service interface. This is implemented by
+services providing functionality to extract credentials from HTTP requests.
+ * *Authenticator* service interface. This is implemented by the
+*SlingAuthenticator* class in the Commons Auth bundle and provides
+applications with entry points to login and logout.
+ * *AuthenticationSupport* service interface. This is implemented by the
+*SlingAuthenticator* class in the Commons Auth bundle and allows
+applications registering with the OSGi HTTP Service to make use of the
+Sling authentication infrastructure.
+
+
+<a name="Authentication-Actors-JCRRepository"></a>
+## JCR Repository
+
+The actual process of logging into the repository and provided a
+*Session* 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:
+
+  * *LoginModule* -- The interface to be implemented to provide login
+processing plugins
+  * *AbstractLoginModule* -- A an abstract base class implementation of
+the *LoginModule* interface.
+  * *DefaultLoginModule* -- The default implementation of the
+*AbstractLoginModule* provided by Jackabbit. This login module takes
+*SimpleCredentials* and uses the repository to lookup the users, validate
+the credentials and providing the *Principal* representing the user
+towards the repository.
+
+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 *LoginModule* with the provided
+default Jackrabbit configuration supporting these plugins:
+
+  * *LoginModulePlugin* -- The main service interface. Plugins must
+implement this interface to be able to extend the login process. See for
+example the [Sling OpenID authentication handler](http://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/openidauth/)
+, which implements this interface to support OpenID authentication.
+  * *AuthenticationPlugin* -- Helper interface for the
+*LoginModulePlugin*.
+
+
+<a name="Authentication-Actors-SlingApplications"></a>
+## Sling Applications
+
+Sling Applications requiring authenticed requests should not care about how
+authentication is implemented. To support such functionality the
+*Authenticator* service is provided with two methods:
+
+  * *login* -- allows the application to ensure requests are
+authenticated. This involves selecting an *AuthenticationHandler* to
+request credentials for authentication.
+
+  * *logout* -- allows the application to forget about any
+authentication. This involves selecting an *AuthenticationHandler* to
+forget about credentials in the request.
+
+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.
+
+{info}
+If you want to know whether a request is authenticated or not, you can
+inspect the result of the *HttpServletRequest.getAuthType* method: If
+this method returns *null* the request is not authenticated.
+{info}

Added: sling/site/trunk/content/authentication---authenticationhandler.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/authentication---authenticationhandler.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/authentication---authenticationhandler.mdtext (added)
+++ sling/site/trunk/content/authentication---authenticationhandler.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,102 @@
+Title: Authentication - AuthenticationHandler
+<a name="Authentication-AuthenticationHandler-AuthenticationHandler"></a>
+# AuthenticationHandler
+
+{excerpt}The *AuthenticationHandler* interface defines the service API
+which may be implemented by authentication handlers registered as OSGi
+services.{excerpt}
+
+*AuthenticationHandler* services have a single required service
+registration property which is used to identify requests to which the
+*AuthenticationHandler* service is applicable:
+
+<table>
+<tr><td> *path* </td><td> One or more (array or vector) string values indicating the
+request URLs to which the *AuthenticationHandler* is applicable. </td></tr>
+<tr><td> *authtype* </td><td> 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 *AuthenticationInfo* object provided by the
+*extractCredentials* method. If this property is set, the
+*requestCredentials* method of the authentication handler is only called
+if the *sling:authRequestLogin* request parameter is either not set or is
+set to the same value as the *authtype* of the handler. This property is
+optional. If not set, the *requestCredentials* method is always called
+regardless of the value of the *sling:authRequestLogin* request
+parameter. </td></tr>
+</table>
+
+Each path may be an absolute URL, an URL with just the host/port and path
+or just a plain absolute path:
+
+<table>
+<tr><td> URL part </td><td> Scheme </td><td> Host/Port </td><td> Path </td></tr>
+<tr><td> Absolute URL </td><td> must match </td><td> must match </td><td> request URL path is prefixed
+with the path </td></tr>
+<tr><td> Host/Port with Path </td><td> ignored </td><td> must match </td><td> request URL path is prefixed
+with the path </td></tr>
+<tr><td> Path </td><td> ignored </td><td> ignored </td><td> request URL path is prefixed with the path </td></tr>
+</table>
+
+When looking for an *AuthenticationHandler* 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 *AuthenticationHandler* 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: _If multiple qualifying service interfaces
+exist, a service with the highest *service.ranking* number, or when equal
+to the lowest *service.id*, determines which service object is returned
+by the Framework_.{footnote}.
+
+The value of *path* service registration property value triggering the
+call to any of the *AuthenticationHandler* methods is available as the
+*path* request attribute (for the time of the method call only). If the
+service is registered with multiple path values, the value of the *path*
+request attribute may be used to implement specific handling.
+
+
+<a name="Authentication-AuthenticationHandler-ImplementationsprovidedbySling"></a>
+### Implementations provided by Sling
+
+* [Form Based AuthenticationHandler](form-based-authenticationhandler.html)
+* [OpenID AuthenticationHandler](openid-authenticationhandler.html)
+
+<a name="Authentication-AuthenticationHandler-Sampleimplementations"></a>
+### Sample implementations
+
+
+<a name="Authentication-AuthenticationHandler-HTTPBasicAuthenticationHandler"></a>
+#### HTTP Basic Authentication Handler
+
+* *extractCredentials* -- Get user name and password from the
+*Authorization* HTTP header
+* *requestCredentials* -- Send a 401/UNAUTHORIZED status with
+*WWW-Authenticate* response header setting the Realm
+* *dropCredentials* -- Send a 401/UNAUTHORIZED status with
+*WWW-Authenticate* response header setting the Realm
+
+Interestingly the *dropCredentials* method is implemented in the same way
+as the *requestCredentials* 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 *Authorization* 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.
+
+
+<a name="Authentication-AuthenticationHandler-FormBasedAuthenticationHandler"></a>
+#### Form Based Authentication Handler
+
+
+* *extractCredentials* -- 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.
+* *requestCredentials* -- Send the login form for the user to provide the
+login parameters.
+* *dropCredentials* -- Clear the authentication cookie and internal
+store.
+
+
+{display-footnotes} 

Added: sling/site/trunk/content/authentication---framework.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/authentication---framework.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/authentication---framework.mdtext (added)
+++ sling/site/trunk/content/authentication---framework.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,243 @@
+Title: Authentication - Framework
+<a name="Authentication-Framework-Framework"></a>
+# Framework
+
+{excerpt}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.{excerpt}
+
+This support encompasses three parts:
+
+  * The *AuthenticationSupport* service provided by the
+*SlingAuthenticator* class. This service can be used by implementations
+of the OSGi *HttpContext* interface to delegate authentication.
+  * The *Authenticator* service also provided by the
+*SlingAuthenticator* class. This service may be used by Sling
+Applications to help clients login and logout.
+  * The *AuthenticationHandler* service interface. These services may be
+implemented by extensions to support various ways for transporting
+credentials from clients to the Sling server.
+
+This page describes how the *SlingAuthenticator* class provides the
+*AuthenticationSupport* and  *Authenticator* services. For a
+description of the *AuthenticationHandler* service interface and the
+interaction between the *SlingAuthenticator* and the
+*AuthenticationHandler* services refer to the [AuthenticationHandler](authentication---authenticationhandler.html)
+ page.
+
+The *SlingAuthenticator* class is an internal class of the
+*org.apache.sling.commons.auth* bundle and implements the
+*Authenticator* and *AuthenticationSupport* services.
+
+
+<a name="Authentication-Framework-AuthenticationSupport"></a>
+## AuthenticationSupport
+
+The *AuthenticationSupport* service interface defines a single method:
+*handleSecurity*. This method is intended to be called by the
+*handleSecurity* method of any *HttpContext* implementation wishing to
+make use of the Sling Authentication Framework.
+
+The Sling Authenticator implementation selects an *AuthenticationHandler*
+service appropriate for the request and calls the
+*AuthenticationHandler.extractCredentials* 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 *login*
+method.
+
+
+The implementation follows this algorithm:
+
+1. Select one or more *AuthenticationHandler* for the request according
+to the request URL's scheme and authorization part.
+1. Call the *extractCredentials* 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.
+1. The first handler returning a non-*null* *AuthenticationInfo*
+result "wins" and the result is used for authentication.
+1. If any *AuthenticationInfoPostProcessor* services are registered, the
+*AuthenticationInfo* object is passed to their *postProcess()* method.
+1. If no handler returns a non-*null* result, the request may be handled
+anonymously. In these cases, an empty *AuthenticationInfo* object is
+passed to any *AuthenticationInfoPostProcessor* services.
+1. (Try to) log into the repository either with the provided credentials
+or anonymously.
+1. If there were credentials provided and the login was successful, a
+login event is posted *if* the *AuthenticationInfo* object contains a
+non-null object with the key *$$auth.info.login$$*
+(*AuthConstants.AUTH_INFO_LOGIN*). This event is posted with the topic
+*org/apache/sling/auth/core/Authenticator/LOGIN*. (added in Sling Auth
+Core 1.1.0)
+1. Set request attributes listed below.
+
+Extracting the credentials and trying to login to the repository may yield
+the following results:
+
+<table>
+<tr><td> Credentials </td><td> Login </td><td> Consequence </td></tr>
+<tr><td> present </td><td> successfull </td><td> Continue with an authenticated request </td></tr>
+<tr><td> present </td><td> failed </td><td> Select *AuthenticationHandler* and call
+*requestCredentials* method </td></tr>
+<tr><td> missing </td><td> anonymous allowed </td><td> Continue with a non authenticated request
+using anonymous access to the repository </td></tr>
+<tr><td> missing </td><td> anonymous forbidden </td><td> Select *AuthenticationHandler* and call
+*requestCredentials* method </td></tr>
+</table>
+
+{note}
+Only one *AuthenticationHandler* 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
+*AuthenticationHandler* is consulted.
+{note}
+
+
+<a name="Authentication-Framework-RequestAttributesonSuccessfulLogin"></a>
+#### Request Attributes on Successful Login
+
+The *handleSecurity* method gets credentials from the
+*AuthenticationHandler* and logs into the JCR repository using those
+credentials. If the login is successful, the *SlingAuthenticator* sets
+the following request attributes:
+
+<table>
+<tr><th> Attribute </th><th> Description </th></tr>
+<tr><td> *org.osgi.service.http.authentication.remote.user* </td><td> The user ID of the
+JCR Session. This attribute is used by the HTTP Service implementation to
+implement the *HttpServletRequest.getRemoteUser* method. </td></tr>
+<tr><td> *org.osgi.service.http.authentication.type* </td><td> The authentication type
+defined by the *AuthenticationHandler*. This attribute is used by the
+HTTP Service implementation to implement the
+*HttpServletRequest.getAuthType* method. </td></tr>
+<tr><td> *org.apache.sling.commons.auth.ResourceResolver* </td><td> The
+*ResourceResolver* created from the credentials and the logged in JCR
+Session. This attribute may be used by servlets to access the repository.
+Namely the *SlingMainServlet* uses this request attribute to provide the
+*ResourceResolver* to handle the request. </td></tr>
+<tr><td> *javax.jcr.Session* </td><td> The JCR Session. This attribute is for backwards
+compatibility only. *Its use is deprecated and the attribute will be
+removed in future versions*. </td></tr>
+<tr><td> *org.apache.sling.commons.auth.spi.AuthenticationInfo* </td><td> The
+*AuthenticationInfo* object produced from the *AuthenticationHandler*.
+</td></tr>
+</table>
+
+*NOTE*: Do _NOT_ use the *javax.jcr.Session* request attribute in your
+Sling applications. This attribute must be considered implementation
+specific to convey the JCR Session to the *SlingMainServlet*. 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:
+
+
+    Session session = request.getResourceResolver().adaptTo(Session.class);
+
+
+
+<a name="Authentication-Framework-AnonymousLogin"></a>
+#### Anonymous Login
+
+The *SlingAuthenticator* provides high level of control with respect to
+allowing anonymous requests or requiring authentication up front:
+
+* Global setting of whether anonymous requests are allowed or not. This is
+the value of the _Allow Anonymous Access_ (*auth.annonymous*) property of
+the *SlingAuthenticator* configuration. This property is supported for
+backwards compatibility and defaults to *true* (allowing anonymous
+access).
+* Specific configuration per URL. The _Authentication Requirements_
+(*sling.auth.requirements*) property of the *SlingAuthenticator*
+configuration may provide a list of URLs for which authentication may be
+required or not: Any entry prefixed with a dash *-* defines a subtree for
+which authentication is not required. Any entry not prefixed with a dash or
+prefixed with a plus *+* defines a subtree for which authentication is
+required up front and thus anonymous access is not allowed. This list is
+empty by default.
+* Any OSGi service may provide a *sling.auth.requirements* registration
+property which is used to dynamically extend the authentication
+requirements from the _Authentication Requirements_ configuration. This may
+for example be set by *AuthenticationHandler* 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
+_Authentication Requirements_ configuration property.
+
+The URLs set on the _Authentication Requirements_ configuration property or
+the *sling.auth.requirements* service registration property can be
+absolute paths or URLs like the *path* service registration property of
+*AuthenticationHandler* services. This allows the limitation of this
+setup to certain requests by scheme and/or virtual host address.
+
+
+*Examples*
+
+* The *LoginServlet* contained in the Commons Auth bundle registers
+itself with the service registration property {{sling.auth.requirements =
+"-/system/sling/login"}} to ensure the servlet can be accessed without
+requiring authentication.
+
+* An authentication handler may register itself with the service
+registration property {{sling.auth.requirements =
+"-/apps/sample/loginform"}} to ensure the login form can be rendered
+without requiring authentication.
+
+
+
+<a name="Authentication-Framework-Authenticatorimplementation"></a>
+## Authenticator implementation
+
+The implementation of the *Authenticator* interface is similar for both
+methods:
+
+**login**
+
+1. Select one or more *AuthenticationHandler* for the request according
+to the request URL's scheme and authorization part.
+1. Call the *requestCredentials* 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.
+1. As soon as the first handlers returns *true*, the process ends and it
+is assumed credentials have been requested from the client.
+
+The *login* method has three possible exit states:
+
+<table>
+<tr><th> Exit State </th><th> Description </th></tr>
+<tr><td> Normal </td><td> An *AuthenticationHandler* could be selected to which the
+login request could be forwarded. </td></tr>
+<tr><td> *NoAuthenticationHandlerException* </td><td> No *AuthenticationHandler* 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> *IllegalStateException* </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>
+</table>
+
+
+**logout**
+1. Select one or more *AuthenticationHandler* for the request according
+to the request URL's scheme and authorization part.
+1. Call the *dropCredentials* 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.
+
+Unlike for the *login* method in the *logout* method case all
+*AuthenticationHandler* services selected in the first step are called.
+If none can be selected or none can actually handle the *dropCredentials*
+request, the *logout* silently returns.
+

Added: sling/site/trunk/content/authentication---tasks.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/authentication---tasks.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/authentication---tasks.mdtext (added)
+++ sling/site/trunk/content/authentication---tasks.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,36 @@
+Title: Authentication - Tasks
+<a name="Authentication-Tasks-Tasks"></a>
+# Tasks
+
+{excerpt}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.{excerpt}
+
+<a name="Authentication-Tasks-ExtractCredentialsfromtheRequest"></a>
+## Extract Credentials from the Request
+
+ * Implemented and controlled by the Sling Commons Auth bundle
+ * Takes *HttpServletRequest*
+ * Provides credentials for futher processing (basically JCR
+*Credentials* and Workspace name)
+ * Extensible with the help of *AuthenticationHandler* services
+
+
+<a name="Authentication-Tasks-LogintotheJCRRepository"></a>
+## Login to the JCR Repository
+
+ * Implemented and controlled by the JCR Repository
+ * Takes JCR *Credentials* and Workspace name
+ * Provides a JCR *Session*
+ * Implementation dependent process. Jackrabbit provides extensibility
+based on *LoginModules*; Sling's Embedded Jackrabbit Repository bundle
+provides extensibility with *LoginModulePlugin* services.
+
+Currently the credentials are always verified by trying to login to the JCR
+repository. Once an [ResourceResolverFactory](http://cwiki.apache.org/SLING/add-resourceresolverfactory-service-interface.html)
+ API has been added, the process of validating the credentials and logging
+in is actualy replaced by a process of requesting a *ResourceResolver*
+from the *ResourceResolverFactory*. 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.

Added: sling/site/trunk/content/authentication.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/authentication.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/authentication.mdtext (added)
+++ sling/site/trunk/content/authentication.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,63 @@
+Title: Authentication
+<a name="Authentication-Authentication"></a>
+# Authentication
+
+{excerpt:hidden=true}
+How requests are authenticated.
+{excerpt}
+
+This section describes the framework provided by Sling to authenticate HTTP
+requests.
+
+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
+*SlingMainServlet* class in the Sling Engine bundle -- with an OSGi
+*HttpService*. This registration is accompanyied with an implementation
+instance of the OSGi *HttpContext* interface, which defines a method to
+authenticate requests: *handleSecurity*.
+
+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 *service* method.
+
+{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 *handleSecurity*
+method of the *HttpContext* object with which the servlet or resource has
+been registered. This method returns *true* if the request should be
+serviced. If this method returns *false* the HTTP Service implementation
+terminates the request sending back any response which has been prepared by
+the *handleSecurity* method. Note, that the *handleSecurity* method
+must prepare the failure response sent to the client, the HTTP Service adds
+nothing here. If the *handleSecurity* method is successful, it must add
+two (or three) request attributes described below.
+1. When the *handleSecurity* method returns *true* the HTTP Service
+either calls the *Servlet.service* method or sends back the requested
+resource depending on whether a servlet or a resource has been selected in
+the first step.
+{column}
+{section}
+
+The important thing to note here is, that at the time the
+*handleSecurity* method is called, the *SlingMainServlet* is not yet in
+control of the request. So any functionality added by the
+*SlingMainServlet*, notably the *SlingHttpServletRequest* and
+*SlingHttpServletResponse* objects are not available to the
+implementation of the *handleSecurity* method.
+
+The following pages describe the full details of request authentication in
+Sling in full detail:
+
+* [Tasks](authentication---tasks.html)
+: {excerpt-include:Authentication - Tasks|nopanel=true} 
+* [Actors](authentication---actors.html)
+: {excerpt-include:Authentication - Actors|nopanel=true} 
+* [Framework](authentication---framework.html)
+: {excerpt-include:Authentication - Framework|nopanel=true} 
+* [AuthenticationHandler](authentication---authenticationhandler.html)
+: {excerpt-include:Authentication - AuthenticationHandler|nopanel=true} 

Added: sling/site/trunk/content/bundles.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/bundles.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/bundles.mdtext (added)
+++ sling/site/trunk/content/bundles.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,38 @@
+Title: Bundles
+<a name="Bundles-Bundles"></a>
+# Bundles
+
+<a name="Bundles-Content"></a>
+## Content
+
+    * [Content Loading (jcr.contentloader)](content-loading-(jcr.contentloader).html)
+    * [Internationalization Support (i18n)](internationalization-support-(i18n).html)
+    * [Manipulating Content - The SlingPostServlet (servlets.post)](manipulating-content---the-slingpostservlet-(servlets.post).html)
+
+<a name="Bundles-ResourceProviders"></a>
+## Resource Providers
+
+    * [Accessing Filesystem Resources (extensions.fsresource)](accessing-filesystem-resources-(extensions.fsresource).html)
+    * [Bundle Resources (extensions.bundleresource)](bundle-resources-(extensions.bundleresource).html)
+
+<a name="Bundles-Users,Groups,Access,Permissions"></a>
+## Users, Groups, Access, Permissions
+
+    * [Managing users and groups (jackrabbit.usermanager)](managing-users-and-groups-(jackrabbit.usermanager).html)
+    * [Managing permissions (jackrabbit.accessmanager)](managing-permissions-(jackrabbit.accessmanager).html)
+
+<a name="Bundles-Installer"></a>
+## Installer
+    * [OSGi Installer](osgi-installer.html)
+    * [JCR Installer Provider](jcr-installer-provider.html)
+
+<a name="Bundles-Misc"></a>
+## Misc
+    * [Commons Thread Pools](slingxsite:apache-sling-commons-thread-pool.html)
+    * [Commons HTML Utilities](commons-html-utilities.html)
+    * [MIME Type Support (commons.mime)](mime-type-support-(commons.mime).html)
+    * [Output Rewriting Pipelines (org.apache.sling.rewriter)](output-rewriting-pipelines-(org.apache.sling.rewriter).html)
+    * [Sling Settings (org.apache.sling.settings)](sling-settings-(org.apache.sling.settings).html)
+    * [Scheduler Service (commons scheduler)](scheduler-service-(commons-scheduler).html)
+    * [Web Console Extensions (org.apache.sling.extensions.webconsolebranding, org.apache.sling.extensions.webconsolesecurityprovider)](web-console-extensions.html)
+

Added: sling/site/trunk/content/client-request-logging.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/client-request-logging.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/client-request-logging.mdtext (added)
+++ sling/site/trunk/content/client-request-logging.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,215 @@
+Title: Client Request Logging
+<a name="ClientRequestLogging-ClientRequestLogging"></a>
+# Client Request Logging
+
+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 *access.log* and *request.log* files.
+In addition more logging can be configured by providing OSGi Configuration
+Admin configuration.
+
+<a name="ClientRequestLogging-Traditionalaccess.logandrequest.logFiles"></a>
+## Traditional access.log and request.log Files
+
+In the Web Console configure the _Apache Sling Request Logger_
+(PID=*org.apache.sling.engine.impl.log.RequestLogger*) configuration.
+
+In the Sling Web Console locate the Configuration page
+(*/system/console/configMgr*) and click on the *+* (plus) symbol on the
+_Apache Sling Customizable Request Data Logger_ line. This opens a dialog
+to enter the configuration whose properties can be configured as follows:
+
+<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 {{%t \[%R](%r.html)
+ \-> %m %U%q %H}} and request exit is logged with the format {{%\{end}t
+\[%R] <\- %s %\{Content-Type}o %Dms}} (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 {{%h %l %u
+%t "%r" %>s %b "%\{Referer}i" "%\{User-Agent}i"}} (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>
+</table>
+
+
+<a name="ClientRequestLogging-LogOutput"></a>
+#### Log Output
+
+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:
+
+<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>
+</table>
+
+*Note:* If logging to a file, this file is not rotated and/or limited by
+size. To get log file rotation use the _Logger Name_ logging type. See [#Rotating Logger Files](#rotating-logger-files.html)
+ below for information on how logging information can be written to rotated
+and/or size limited files.
+
+
+<a name="ClientRequestLogging-Additionalper-requestLoggers"></a>
+### Additional per-request Loggers
+
+In the Web Console create _Apache Sling Customizable Request Data Logger_
+(Factory PID=*org.apache.sling.engine.impl.log.RequestLoggerService*)
+configuration.
+
+In the Sling Web Console locate the Configuration page
+(*/system/console/configMgr*) and click on the *+* (plus) symbol on the
+_Apache Sling Customizable Request Data Logger_ line. This opens a dialog
+to enter the configuration whose properties can be configured as follows:
+
+<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>
+</table>
+
+
+
+<a name="ClientRequestLogging-LogFormatSpecification"></a>
+#### Log Format Specification
+
+The log format specification follows the [definition of the *format* argument for the *LogFormat* and *CustomLog* directives of Apache httpd](http://httpd.apache.org/docs/current/mod/mod_log_config.html)
+:
+
+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:
+
+<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>
+</table>
+
+
+*Modifiers*
+
+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.
+
+The Apache httpd modifiers "<" and ">"	are not supported by Sling and
+currently ignored.
+
+
+*Some Notes*
+
+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).
+
+
+<a name="ClientRequestLogging-RotatingLoggerFiles"></a>
+#### Rotating Logger Files
+
+If you want to write the request (and access) logging information into a
+rotated file, you should configure as follows:
+
+1. Configure the Log Type to be a _Logger Name_ and some usefull Logger
+name. For example *clientlog.request*.
+1. Create an _Apache Sling Logging Logger Configuration_ for this Logger
+name according to [Logging Configuration](logging#logger-configuration.html)
+ with the following setup:
+  ** Allow message at INFO (Information) level to be logged which is the
+level used by the request loggers
+  ** Define the appropriate log file name, for example
+*logs/client.request.log*
+  ** Use only *\{5*} as the message format because request logger
+messages are generally already fully formated with required timestamp etc.
+  ** Add any Logger names used for the client request log configuration,
+*clientlog.request* in the example above, to the Logger field. By
+clicking on the *+* (plus) button you may add more than a single logger
+name whose messages are written to this file.
+1. Optionally, you may create an _Apache Sling Logging Writer
+Configuration_ for the log file defined in the previous step to better
+control rotation setup. See [Log Writer Configuration](logging#log-writer-configuration.html)
+ for full details.

Added: sling/site/trunk/content/commons-html-utilities.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/commons-html-utilities.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/commons-html-utilities.mdtext (added)
+++ sling/site/trunk/content/commons-html-utilities.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,7 @@
+Title: Commons HTML Utilities
+<a name="CommonsHTMLUtilities-CommonsHTMLUtilities(org.apache.sling.commons.html)"></a>
+# Commons HTML Utilities (org.apache.sling.commons.html)
+
+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.

Added: sling/site/trunk/content/configuration.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/configuration.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/configuration.mdtext (added)
+++ sling/site/trunk/content/configuration.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,376 @@
+Title: Configuration
+<a name="Configuration-ConfigurationSupport"></a>
+# Configuration Support
+
+
+<a name="Configuration-Introduction"></a>
+## Introduction
+
+Configuration in Sling is aligned with respective support by the OSGi
+specification:
+
+   * Framework and Java system properties are available through the
+*BundleContext.getProperty(String)* method. These properties are provided
+in Sling through the Sling launcher.
+   * Bundle Header values are available through the *Bundle.getHeaders()*
+and *Bundle.getHeaders(String)* methods. These header values are set by
+the bundle developer in the *META-INF/MANIFEST.MF* file. In fact, all
+main manifest attributes are available through these methods.
+   * Components managed by the Service Component Runtime and declared in
+component descriptor files listed in the *Service-Component* manifest
+header access configuration properties through the
+*ComponentContext.getProperties()* method. These properties have three
+sources:
+      *# Configuration specified specifically for factory components
+      *# Properties retrieved from the Configuration Admin Service
+      *# Properties set in the component descriptor
+   * Configuration properties provided to *ManagedService* and
+*ManagedServiceFactory* instances by the Configuration Admin Service.
+
+For the discussion to follow we differentiate between intial configuration
+provided by Framework and system properties and managed configuration
+provided by the Configuration Admin Service.
+
+Components managed by the Service Component Runtime are generally
+configured (as listed above) through the descriptor properties and
+configuration set by Configuration Admin Service configuration. The
+descriptor property values may be seen as configuration default values set
+by the component developer, which may be overwritten by user configuration
+through the Configuration Admin Service. Components may but are not
+required to make use of Framework properties by accessing the
+*BundleContext* through the *ComponentContext* given to the
+*activate(ComponentContext)* method of the component.
+
+
+
+<a name="Configuration-InitialConfiguration"></a>
+## Initial Configuration
+
+The lifecycle of the OSGi framework implemented by an instance of the
+*org.apache.felix.framework.Felix* class is managed by the Sling launcher
+class *org.apache.sling.launcher.Sling*. This class is used by the
+standalone main class (*org.apache.sling.launcher.main.Main*) and the
+Sling Servlet (*org.apache.sling.launcher.servlet.SlingServlet*) to
+control the lifecycle.
+
+The Sling launcher is responsible to provide the Framework properties to
+the OSGi framework. The properties are prepared as a
+*java.util.Map<String, String>* instance as follows (later steps may
+overwrite properties defined in earlier steps) :
+
+1. Load core properties from the embedded *sling.properties* file.
+1. Resolve any property file inclusions. This is mainly used to resolve
+the correct JRE package definitions for the JRE version used.
+1. Overwrite with any properties provided by the main class or the Sling
+Servlet.
+1. Make sure the *sling.home* property is set defining a sensible
+default value if missing
+1. Load the contents of the *$\{sling.home}/sling.properties* file
+1. Overwrite properties with Java system properties. This step only
+considers system properties of the same names as properties already
+existing. That is, the system properties are not just copied into the
+properties here. Additionally this step my be omitted if the
+*sling.ignoreSystemProperties* property is set to *true*.
+1. Resolve any property file inclusions. This may be used to provide more
+configurability depending on the integration.
+1. Handle OSGi boot delegation support (see below).
+1. Resolve property references of the form *$\{propName*}
+1. For each property value starting with *ontext:/* do the following,
+assuming the value to be an URL with scheme *context:*:
+1. * Copy the application resource to *$\{sling.home*} preserving the
+URL path unless such a file already exists.
+1. * Replace the property value with the path to the newly created
+file. The path has the form *$\{sling.home}/relpath*.
+1. Store the properties as *$\{sling.home}/sling.properties* to be
+re-used on next startup
+1. Setup Bundle auto installation for the Felix Framework
+
+Using file system copies of the initial configuration and referred files,
+it is easy to modify this configuration without the need to unpack and
+repackage the web application archive.
+
+The only property really required is actually the *sling.home* property,
+which defines the file system location where runtime files will be placed.
+The default if this property is missing will be _sling_ in the current
+working directory as defined the *user.dir* system property.
+
+
+
+<a name="Configuration-StandaloneApplication"></a>
+### Standalone Application
+
+When launching Sling as a standalone application the *sling-app.jar* file
+is used. This is an executable JAR File. The *sling.properties* file as
+well as the *sling_install.properties* and JRE specific properties files
+are located at the root of the JAR file hierarchy.
+
+The standalone application currently sets properties for the third step of
+the configuration setup to ensure the HTTP Servlet integration is using the
+Apache Felix _http.jetty_ bundle. Additionally system properties may be set
+using the *-D* command line switch of the Java binary.
+
+In addition the following command line arguments are accepted:
+
+<table>
+<tr><th> Argument </th><th> Sling property </th><th> Description </th></tr>
+<tr><td> *-l loglevel* </td><td> *org.apache.sling.osgi.log.level* </td><td> The initial
+loglevel (0..4, FATAL, ERROR, WARN, INFO, DEBUG) </td></tr>
+<tr><td> *-f logfile* </td><td> *org.apache.sling.osgi.log.file* </td><td> The log file, "-"
+for stdout </td></tr>
+<tr><td> *-c slinghome* </td><td> *sling.home* </td><td> the sling context directory </td></tr>
+<tr><td> *-a address* </td><td> -- </td><td> the interfact to bind to (use 0.0.0.0 for any) (not
+supported yet) </td></tr>
+<tr><td> *-p port* </td><td> *org.osgi.service.http.port* </td><td> the port to listen to
+(default 8080) </td></tr>
+<tr><td> *-h* </td><td> -- </td><td> Prints a simple usage message and exits. </td></tr>
+</table>
+
+The standalone application exits with status code 0 (zero) if Sling
+terminates normally, that is if the OSGi framework is stopped or if just
+the usage note has been displayed. If any error occurrs during command line
+parsing, the cause is printed to the error output and the application
+exists with status code 1 (one). If the OSGi framework fails to start, the
+cause is printed to the error output and the application exists with status
+code 2.
+
+
+<a name="Configuration-WebApplication"></a>
+### Web Application
+
+When launching Sling as a web application using the *sling-servlet.war*
+or any derived Web Application archive file, the *sling.properties* file
+is located in the *WEB-INF* folder along with the
+*sling_install.properties* and JRE specific properties files.
+
+The Sling Servlet uses the Servlet Context and Servlet *init-param*
+configurations to prepare the properties for the third step of the
+configuration setup.
+
+If the OSGi framework fails to startup for any reason a
+*javax.servlet.UnavailableException*.
+
+
+
+<a name="Configuration-PropertyFileInclusions"></a>
+### Property File Inclusions
+
+Twice in the configuration setup (second and seventh step) any property
+file inclusions will be handled. Property files may be included by defining
+one or more properties containing a comma-separated list of properties
+files to include. Property file inclusion looks at the *sling.include*
+property and any other property whose prefix is *sling.include.*. When
+such properties exist, the files listed in those properties are included.
+
+The order of handling the property file inclusion properties is defined as
+natural sort order of the actual property names. So the properties of the
+files listed in the *sling.include.first* property will be loaded before
+the files listed in the *sling.include.second* but after the files listed
+in the *sling.include.a* property.
+
+Any file which does not exist is silently ignored.
+
+The names of the files are resolved as follows:
+
+1. If a resource exists at the same location as the initial
+*sling.properties* file packaged with the application, that resource is
+used
+1. If the name is a relative file name, it is looked for in the
+*sling.home* directory
+1. If the name is an absolute file name, it is used as is
+
+*Example*
+
+The packaged *sling.properties* file contains the following properties
+file inclusion setting:
+
+
+    sling.include.jre = jre-${java.specification.version}.properties
+
+
+This is used to include the JRE package list to be made visible inside the
+OSGi framework.
+
+
+
+<a name="Configuration-OSGiBootDelegationSupport"></a>
+### OSGi Boot Delegation Support
+
+Some packages may have to be shared between bundles in an OSGi framework
+and the rest of Java VM in which the framework has been launched. This is
+especially true for OSGi framework instances launched in embedding such as
+Servlet Containers. In the case of a Sling Application accessing a JCR
+Repository launched in a different Web Application, this mainly concerns an
+API packages as well as the JNDI Initial Factory package(s).
+
+To cope with this sharing issue, the OSGi core specification defines two
+properties, which may list packages to be used from the environment:
+
+
+* **org.osgi.framework.system.packages** - This property lists package
+names which are added to the list of exported packages of the system bundle
+of the OSGi framework. These packages are used in the resolution process
+just as any package listed in an *Export-Package* bundle manifest header.
+* **org.osgi.framework.bootdelegation** -  This property lists packages,
+which are always used from the environment. As such, these packages will
+never be looked up in package wirings as are packages imported by listing
+them in the *Import-Package* bundle manifest header.
+
+
+Sometimes, especially in the Servlet Container case, it is important to use
+the shared classes from the container and not resolve using standard OSGi
+resolution. In such cases, the packages of these shared classes must be
+listed in the *org.osgi.framework.bootdelegation* property. Sling
+provides a mechanism to extend the default setting of the
+*org.osgi.framework.bootdelegation* property by adding properties
+prefixed with *sling.bootdelegation.*. The value of each of these
+prefixed properties is conditionally appended to the
+*org.osgi.framework.bootdelegation* property. _Conditionally_ means, that
+the property name may contain the fully qualified name of a class, which is
+checked to see whether to add the property value or not.
+
+_Examples_
+
+<table>
+<tr><td> *sling.bootdelegation.simple = com.some.package* </td><td> This setting
+unconditionally adds the *com.some.package* package to the
+*org.osgi.framework.bootdelegation* property </th></tr>
+<tr><td> *sling.bootdelegation.class.com.some.other.Main = com.some.other* </td><td>
+This setting checks whether the *com.some.other.Main* class is known. If
+so, the *com.some.other* package is added to the
+*org.osgi.framework.bootdelegation* property. Otherwise the
+*com.some.other* package is not added - and therefore must be exported by
+a bundle if required for use inside the framework. </td></tr>
+</table>
+
+
+*Note* Even though packages listed in the
+*org.osgi.framework.bootdelegation* property will always be loaded from
+the environment, any bundles using these packages must still import them
+(through *Import-Package* or *DynamicImport-Package*) and the bundles
+must resolve for being usable.
+
+
+
+<a name="Configuration-OSGiSystemPackagesSupport"></a>
+### OSGi System Packages Support
+
+As listed in the above section on OSGi Boot Delegation Support, the
+*org.osgi.framework.system.packages* property may be used to extend the
+export list of the system bundle. Similar to the support for extending the
+boot delegation packages list, Sling supports extending the system packages
+list. The mechanism to extend the default setting of the
+*org.osgi.framework.system.packages* property by adding properties
+prefixed with *sling.system.packages.*. The value of each of these
+prefixed properties is conditionally appended to the
+*org.osgi.framework.system.packages* property. _Conditionally_ means,
+that the property name may contain the fully qualified name of a class,
+which is checked to see whether to add the property value or not.
+
+_Examples_
+
+<table>
+<tr><td> *sling.system.packages.simple = com.some.package* </td><td> This setting
+unconditionally adds the *com.some.package* package to the
+*org.osgi.framework.system.packages* property </th></tr>
+<tr><td> *sling.system.packages.class.com.some.other.Main = com.some.other* </td><td>
+This setting checks whether the *com.some.other.Main* class is known. If
+so, the *com.some.other* package is added to the
+*org.osgi.framework.system.packages* property. Otherwise the
+*com.some.other* package is not added - and therefore must be exported by
+a bundle if required for use inside the framework. </td></tr>
+</table>
+
+
+*Note* Packages listed in the *org.osgi.framework.system.packages*
+required by any bundles must be imported by those bundles by listing them
+in the *Import-Package* or *DynamicImport-Package* manifest header.
+
+
+
+<a name="Configuration-Recommendationsforpropertynames"></a>
+## Recommendations for property names
+
+The following system property names are reserved:
+
+   * Names starting with *org.osgi.* are reserved for OSGi defined
+Framework properties
+   * Names starting with *org.apache.felix.* are reserved for the Felix
+Framework
+   * Names starting with *sling.* and *org.apache.sling.* are reserved
+for Sling
+
+To prevent property name collisions, I suggest the following convention:
+
+   * Use fully qualified property names for initial configuration through
+Framework properties
+   * Use unqualified property names for configuration through the
+Configuration Admin Service
+
+
+<a name="Configuration-WellKnownProperties"></a>
+## Well Known Properties
+
+The following table is a collection of well known property names from
+different parts of Project Sling.
+
+<table>
+<tr><th> Property </th><th> Description </th></tr>
+<tr><td> *sling.home* </td><td> Defines the file system location where Project Sling
+will write copies of the initial configuration. This property should also
+be used to define other local file system locations such as the directory
+to use for the Apache Felix Bundle Cache (*$\{sling.home}/felix* by
+default). If this property is not set it defaults to
+*$\{user.dir}/sling*. </td></tr>
+<tr><td> *sling.home.url* </td><td> Contains the Sling directory set in the
+*sling.home* property as a valid URL. This property may be used in
+situations where the Sling directory is required as an URL. This property
+is automatically set by the Sling application and may not be modified by
+configuration files. </td></tr>
+<tr><td> *sling.ignoreSystemProperties* </td><td> Whether to overwrite any configuration
+properties with Java system properties or not. By default this property is
+set to *true* by the Sling Servlet but not set by the Sling main class.
+The reason to set this by default in the Sling Servlet is to not induce
+values from the environment, which may not be appropriate in the Web
+Application case. </td></tr>
+<tr><td> *obr.repository.url* </td><td> A comma-separated list of OSGi Bundle Repository
+URLs. See _Important Properties_ on the page [Initial Provisioning and Startup](launch-sling.html)
+. </td></tr>
+<tr><td> *sling.install.bundles* </td><td> A comma-separated list of start level
+numbers. See _Important Properties_ on the page [Initial Provisioning and Startup](launch-sling.html)
+. </td></tr>
+<tr><td> *sling.install.<n>* </td><td> A comma-separated list of bundle specifications.
+See _Important Properties_ on the page [Initial Provisioning and Startup](launch-sling.html)
+. </td></tr>
+<tr><td> *org.apache.sling.osgi.log.** </td><td> Properties providing initial
+configuration to the Sling Log Service. See 'Important Properties' on the
+page [Initial Provisioning and Startup](launch-sling.html)
+. </td></tr>
+</table>
+
+
+
+<a name="Configuration-ConfigurationAdminService"></a>
+## Configuration Admin Service
+
+Configuration of the system entities, such as services and components, by
+the system administrator is supported the Configuration Admin Service. The
+Configuration Admin Service acts as the center for the management of the
+configuration data, to which GUI-based tools will connect to retrieve and
+update configuration data. The Configuration Admin Service is responsible
+for persisting the configuration data and for providing configuration
+consumers with the configuration data. Specifically services registered
+with the *ManagedService* or *ManagedServiceFactory* interfaces are
+updated with the configuration upon updated. The Service Component Runtime
+on the other hand recognizes updated configuration and provides it to the
+managed components as defined in the OSGi Declarative Services
+Specification.
+
+By default the Configuration Admin Service is installed when Sling is
+started for the first time. This service is used by the Service Component
+Runtime launching the OSGi components declared in the bundles with
+configuration values. The Sling Management Console provides a simple GUI to
+manage these configuration elements on the 'Configuration' page.
+
+For more information on the Configuration Admin Service refer to the OSGi
+Configuration Admin Service Specification in the OSGi Service Platform
+Service Compendium book.

Added: sling/site/trunk/content/contributing.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/contributing.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/contributing.mdtext (added)
+++ sling/site/trunk/content/contributing.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,35 @@
+Title: Contributing
+<a name="Contributing-Contributing"></a>
+# Contributing
+
+See [SLINGxSITE:Project Information](slingxsite:project-information.html)
+ for details about the tools mentioned below.
+
+Apache Sling is a volunteer effort, so there is always plenty of work that
+needs to be accomplished. If you want to help support Sling, this page is
+intended as a starting point for specific contribution ideas. To further
+understand how the Sling community operates, refer to the Community Roles
+and Processes document and/or join the mailing lists.
+
+The Sling project organizes its "to do" list using the JIRA issue tracking
+system. Specific items from Sling's JIRA issue tracking system are
+highlighted on this page, but are not limited to it. The purpose of the
+list here is to highlight issues that are either more important or serve as
+good entry points for new contributors.
+
+It is important to point out that you do not need to be a programmer to
+contribute to Sling. As such, we will break out the list of issues below
+for non-programmers and programmers.
+
+<a name="Contributing-Non-Programmers"></a>
+## Non-Programmers
+
+    * Improve web site or documentation (e.g., create/propose FAQ entries).
+There is no specific JIRA issue for this task, but any contributions could
+be posted as new JIRA issues for the Documentation component.
+
+<a name="Contributing-Programmers"></a>
+## Programmers
+
+    * Implement support for various rendering technologies in Sling.
+Examples coming to mind are JSF and Wicket.

Added: sling/site/trunk/content/default-mapping-and-rendering.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/default-mapping-and-rendering.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/default-mapping-and-rendering.mdtext (added)
+++ sling/site/trunk/content/default-mapping-and-rendering.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,4 @@
+Title: Default Mapping and Rendering
+This page contained obsolete content, moved it to
+http://cwiki.apache.org/confluence/display/SLING/Default+Mapping+and+Rendering+%28OBSOLETE%29
+in case it is useful to someone.

Added: sling/site/trunk/content/dependency-management.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/dependency-management.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/dependency-management.mdtext (added)
+++ sling/site/trunk/content/dependency-management.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,108 @@
+Title: Dependency Management
+<a name="DependencyManagement-DependencyManagement"></a>
+# Dependency Management 
+
+{excerpt}This page is about how we do and don't do dependency management in
+the Sling project.{excerpt}
+
+{toc:minLevel=2}
+
+<a name="DependencyManagement-Introduction"></a>
+## Introduction
+
+Maven provides projects with a nice feature called dependency management.
+In Sling we currently use this feature to declare the non-Sling
+dependencies of modules in the parent POM.
+
+After working with this some time and trying to upgrade various
+dependencies we came to the conclusion, that using Maven dependency
+management is not going to work out in the Sling scenario.
+
+Why ? Maven's dependency management is aimed at traditional applicaitons,
+which are glued together statically during the build process. For this
+environment, dependency management is a great thing, since it guarantees a
+consistent application setup.
+
+In a dynamic application setup as provided by an OSGi framework the static
+dependency management of Maven does not help. Actually it even causes
+problematic results with respect to backwards compatibility when using the
+Maven Bundle plugin.
+
+Why's that ? The Maven Bundle plugin is constructs the bundle manifest and
+will generally automatically create the Import-Package header. If the
+providing library (from maven's dependency list) has *Export-Package*
+headers with version numbers, the Maven Bundle plugin will insert the
+respective version numbers for the *Import-Package* header. This makes
+perfect sense, because it is expected, that the artifact required at least
+the given package version.
+
+When using Maven dependency management, upgrading any dependencies in the
+parent POM may automatically increse the version numbers in the
+*Import-Package* headers and hence may cause any such bundle to fail
+resolution if deployed - even though the bundle did not change and does not
+really require a new version of the dependency.
+
+So, in the case of OSGi deployment, Maven's dependency management actually
+interferes with the OSGi framework dependency management.
+
+As a consequence, I suggest we drop dependency management in the parent pom
+(almost) completely and state the followin.
+
+
+<a name="DependencyManagement-DependencyManagement"></a>
+## Dependency Management
+
+
+The parent pom only does dependency management for build time dependencies
+and a very limited number of API dependencies used Sling wide. These
+dependencies are:
+
+   * All plugin dependencies. That is *PluginManagement* is still used.
+Maven plugins are actualy build time dependencies and therefore have no
+influence on the actual deployment.
+   * Dependencies on commonly used testing environment helpers. Test helper
+classes are also build time dependencies used to run the unit and
+integration tests. As such, they may well be managed.
+   * Sling makes a small number of assumptions about the environment, which
+we codify in the dependency management: The minimum version number of the
+OSGi specificaiton used, the servlet API version and the JCR API version.
+
+The *<DependencyManagement>* element currently contains the following
+managed dependencies:
+
+<table>
+<tr><th> Group ID </th><th> Artifact ID </th><th> Version </th><th> Scope </th></tr>
+<tr><td> org.apache.felix </td><td> org.osgi.core </td><td> 1.2.0 </td><td> provided </td></tr>
+<tr><td> org.apache.felix </td><td> org.osgi.compendium </td><td> 1.2.0 </td><td> provided </td></tr>
+<tr><td> javax.servlet </td><td> servlet-api </td><td> 2.4 </td><td> provided </td></tr>
+<tr><td> javax.jcr </td><td> jcr </td><td> 1.0 </td><td> provided </td></tr>
+<tr><td> org.slf4j </td><td> slf4j-api </td><td> 1.5.2 </td><td> provided </td></tr>
+<tr><td> junit </td><td> junit </td><td> 4.3 </td><td> test </td></tr>
+<tr><td> org.jmock </td><td> jmock-junit4 </td><td> 2.2.0 </td><td> test </td></tr>
+<tr><td> org.slf4j </td><td> slf4j-simple </td><td> 1.5.2 </td><td> test </td></tr>
+</table>
+
+
+All dependencies per module are fully described in terms of version, scope,
+and classifier by the respective project.
+
+The version of the module dependency should be selected according to the
+following rule: The lowest version providing the functionality required by
+the module (or bundle). By required functionality we bascially mean
+provided API.
+
+Generally there is a constant flow of releases of dependent libraries. In
+general this should not cause the dependency version number of a using
+module to be increased. There is one exception though: If the fixed library
+version contains a bug fix, which has an influence on the operation of the
+module, an increase in the version number is indicated and should also be
+applied.
+
+
+<a name="DependencyManagement-References"></a>
+## References
+
+* [Dependency ManagementLink to this message](http://markmail.org/message/5qpmsukdk4mdacdy)
+ -- Discussion thread about reducing Maven 2 *DependencyManagement*
+* [SLING-811](https://issues.apache.org/jira/browse/SLING-811)
+ -- The actual issue governing the changes to the project descriptors

Added: sling/site/trunk/content/development.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/development.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/development.mdtext (added)
+++ sling/site/trunk/content/development.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,47 @@
+Title: Development
+<a name="Development-Development"></a>
+# Development
+
+Welcome to the wonderful world of extending Sling. Refer to these pages to
+find out how we envision the extension of Sling and how to do it.
+
+
+<a name="Development-UsingSlingasyourDevelopmentFramework"></a>
+## Using Sling as your Development Framework
+
+Look here for more information on developper support when your are using
+Sling to build your own applications.
+
+    * [Getting and Building Sling](getting-and-building-sling.html)
+    * [Embedding Sling](embedding-sling.html)
+    * [Logging](logging.html)
+    * [Client Request Logging](client-request-logging.html)
+    * [Monitoring Requests](monitoring-requests.html)
+    * [Repository Based Development](repository-based-development.html)
+    * [Sling Testing Tools](sling-testing-tools.html)
+
+
+<a name="Development-Maven2stuff"></a>
+## Maven 2 stuff
+
+Sling is using Apache Maven as it build system. Over time we have created a
+number of Maven 2 Plugins and gathered a whole range of knowledge about
+using Maven.
+
+    * [Maven Tips & Tricks](maventipsandtricks.html)
+    * [Maven Sling Plugin](sling.html)
+    * [Maven JspC Plugin](jspc.html)
+    * [Maven Launchpad Plugin](maven-launchpad-plugin.html)
+    * [Maven Archetypes](maven-archetypes.html)
+
+
+<a name="Development-SlingDevelopment"></a>
+### Sling Development
+
+Last but not least, here is some more information on how we ourselves are
+working on Sling
+
+    * [Dependency Management](dependency-management.html)
+    * [Version Policy](version-policy.html)
+    * [Issue Tracker](issue-tracker.html)
+    * [Release Management](release-management.html)

Added: sling/site/trunk/content/discover-sling-in-15-minutes.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/discover-sling-in-15-minutes.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/discover-sling-in-15-minutes.mdtext (added)
+++ sling/site/trunk/content/discover-sling-in-15-minutes.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,310 @@
+Title: Discover Sling in 15 minutes
+<a name="DiscoverSlingin15minutes-DiscoverSlingin15minutes-theSlingLaunchpad"></a>
+# Discover Sling in 15 minutes - the Sling Launchpad
+
+The Sling Launchpad is a ready-to-run Sling configuration, providing an
+embedded JCR content repository and web server, a selection of Sling
+components, documentation and examples. The Launchpad makes it easy to get
+started with Sling and to develop script-based applications.
+
+This page will help you get started with the Launchpad. Fifteen minutes
+should be enough to get an overview of what Sling does.
+
+While simple to run and understand, the Launchpad is a full-featured
+instance of Sling, an example configuration that we have created with the
+most common modules and configurations. The full functionality of Sling is
+available by loading additional Sling (or custom) OSGi bundles as needed,
+using the Launchpad's web-based OSGi management console.
+
+<a name="DiscoverSlingin15minutes-SeeAlso"></a>
+## See Also
+
+
+Example applications and mini-applications for Sling can be found under
+http://svn.apache.org/repos/asf/sling/trunk/samples/ (each application has
+a *README.txt* file, see these for more details).
+
+Once you grok the basic examples of this page, we recommend studying the
+_espblog_ and _webloader_ samples for more complete examples. The
+_javashell_ sample is useful to play with JCR java code (or any java code,
+for that matter) interactively.
+
+<a name="DiscoverSlingin15minutes-Prerequisites"></a>
+## Prerequisites
+
+We'll start with the self-runnable jar from the Sling distribution, you
+only need a Java 5 JDK. Download the latest release from the Sling [Downloads](downloads.html)
+ page or by clicking this link: [org.apache.sling.launchpad-6-standalone.jar|http://www.apache.org/dyn/closer.cgi/sling/org.apache.sling.launchpad-6-standalone.jar]
+. Alternatively you can deploy the [Sling Web application|http://www.apache.org/dyn/closer.cgi/sling/org.apache.sling.launchpad-6.war]
+ into any decent Servlet Container such as Jetty or Tomcat or you can [build the current source yourself|Getting and Building Sling]
+.
+
+To show the simplicity of the REST-style approach taken by Sling the
+examples below will be using [cURL](http://curl.haxx.se/)
+. Any HTTP client would do, but cURL is the easiest to document in a
+reproducible way.
+
+A WebDAV client makes editing server-side scripts much more convenient, but
+to make our examples easy to reproduce, we're using cURL below to create
+and update files in the JCR repository, via the Sling WebDAV server.
+
+
+<a name="DiscoverSlingin15minutes-StarttheLaunchpad"></a>
+## Start the Launchpad
+
+After downloading the Sling Launchpad self-runnable jar just start it as
+follows:
+
+
+    $ java -jar org.apache.sling.launchpad-6-standalone.jar
+
+
+This starts the Sling embedded Web Server on port 8080 and writes
+application files into the *sling* folder found in the current working
+directory.
+
+Once started, look at [http://localhost:8080/system/console/bundles](http://localhost:8080/system/console/bundles)
+ with your browser. Use _admin_ with password _admin_ if Sling asks you for
+a login. Sling then displays the _Felix Web Management Console_ page.
+
+
+On the bundles page, all bundles should be marked _Active_. They're all [OSGi](http://www.osgi.org/)
+ bundles powered by [Apache Felix|http://felix.apache.org]
+, but that doesn't really matter to us right now.
+
+{tip:title=Log files}
+If things go wrong, have a look at the *sling/logs/error.log* log file \-
+that's where Sling writes any error messages.
+{tip}
+
+<a name="DiscoverSlingin15minutes-Createsomecontent"></a>
+## Create some content
+
+Until we have ready-to-test forms, you can create content with cURL, or you
+can create an HTML form that posts to the specified URL.
+
+To create a content node (nodes are a [JCR](http://jackrabbit.apache.org/)
+ concept, a unit of storage) with cURL, use:
+
+
+    curl -u admin:admin -F"sling:resourceType=foo/bar" -F"title=some title"
+http://localhost:8080/content/mynode
+
+
+The resulting node can be seen at [http://localhost:8080/content/mynode.html](http://localhost:8080/content/mynode.html)
+, or as json format under [http://localhost:8080/content/mynode.json|http://localhost:8080/content/mynode.json]
+. Lets try with cURL:
+
+
+    $ curl http://localhost:8080/content/mynode.json
+    {"title":"some
+title","sling:resourceType":"foo/bar","jcr:primaryType":"nt:unstructured"}
+
+
+This returns the properties of the */content/mynode* in JSON format as we
+have created it above. The additional property *jcr:primaryType* is a
+special JCR property indicating the JCR primary node type.
+
+{tip:title=Monitoring requests}
+Sling provides a simple tool (an OSGi console plugin) to monitor HTTP
+requests, which helps understand how things work internally. See the [Monitoring Requests](monitoring-requests.html)
+ page for details.
+{tip}
+
+<a name="DiscoverSlingin15minutes-Renderyourcontentusingserver-sidejavascript(ESP)"></a>
+## Render your content using server-side javascript (ESP)
+
+Sling uses scripts or servlets to render and process content.
+
+Several scripting languages are available as additional Sling modules
+(packaged as OSGi _bundles_ that can be installed via the Sling management
+console), but the launchpad currently includes the ESP (server-side
+ECMAscript), JSP (Java Server Pages), and Groovy language modules by
+default.
+
+To select a script, Sling uses the node's _sling:resourceType_ property, if
+it is set.
+
+That is the case in our example, so the following script will be used by
+Sling to render the node in HTML, if the script is found at
+_/apps/foo/bar/html.esp_ in the repository.
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>html.esp</B></DIV><DIV class="codeContent panelContent">
+    <html>
+      <body>
+        <h1><%= currentNode.title %></h1>
+      </body>
+    </html>
+
+
+To select the script, Sling:
+* looks under _/apps_
+* and appends the _sling:resourceType_ value of our node ( which is
+_foo/bar_ ) 
+* and appends _html.esp_, as the extension of our URL is _html_ and the
+language of our script is _esp_.
+
+Store this script under _/apps/foo/bar/html.esp_, either using a WebDAV
+client (connected to [http://admin:admin@localhost:8080/](http://admin:admin@localhost:8080/)
+), or using cURL as shown here, after creating the _html.esp_ script in the
+current directory on your system:
+
+
+    curl -X MKCOL -u admin:admin http://localhost:8080/apps/foo
+    curl -X MKCOL -u admin:admin http://localhost:8080/apps/foo/bar
+
+
+create a local file _html.esp_ and copy above content.
+
+
+    curl -u admin:admin -T html.esp http://localhost:8080/apps/foo/bar/html.esp
+
+
+The HTML rendering of your node, at [http://localhost:8080/content/mynode.html](http://localhost:8080/content/mynode.html)
+, is now created by this ESP script. You should see the node's title alone
+as an <h1> element in that page.
+
+A script named _POST.esp_ instead of _html.esp_ would be called for a POST
+request, _DELETE.esp_ for DELETE, _xml.esp_ for a GET request with a _.xml_
+extension, etc. See [URL to Script Resolution](http://cwiki.apache.org/SLING/url-to-script-resolution.html)
+ on the Sling wiki for more info.
+
+Servlets can also be easily "wired" to handle specific resource types,
+extensions, etc., in the simplest case by using SCR annotations in the
+servlet source code. Servlets and scripts are interchangeable when it comes
+to processing Sling requests.
+
+
+<a name="DiscoverSlingin15minutes-Whatnext?"></a>
+## What next?
+
+These simple examples show how Sling uses scripts to work with JCR data,
+based on _sling:resourceType_ or node types.
+
+There's much more to Sling of course - you'll find some additional simple
+examples below, and above in the _see also_ section.
+
+We are working on debugging features to help trace the way Sling processes
+requests. Have a look at [SLING-3](https://issues.apache.org/jira/browse/SLING-3)
+ to see what's possible already.
+
+
+<a name="DiscoverSlingin15minutes-Additionalexamples"></a>
+# Additional examples
+
+<a name="DiscoverSlingin15minutes-LetSlinggeneratethepathofanewlycreatednode."></a>
+## Let Sling generate the path of a newly created node.
+
+To create a node with a unique path at a given location, end the URL of the
+POST request with _/_.
+
+In this case, the Sling response redirects to the URL of the created node.
+
+Start by creating a new _/blog_ folder:
+
+
+    curl -X POST -u admin:admin "http://localhost:8080/content/blog"
+
+
+And create a node with a Sling-generated name under it:
+
+
+    curl -D - -u admin:admin -F"title=Adventures with Sling"
+"http://localhost:8080/content/blog/"
+
+
+Using cURL's _\-D_ option shows the full HTTP response, which includes a
+_Location_ header to indicate where the new node was created:
+
+
+    Location: /blog/adventures_with_slin
+
+
+The actual node name might not be _adventures_with_slin_ \- depending on
+existing content in your repository, Sling will find a unique name for this
+new node, based on several well-know property values like title,
+description, etc. which are used for this if provided.
+
+So, in our case, our new node can be displayed in HTML via the [http://localhost:8080/blog/adventures_with_slin.html](http://localhost:8080/blog/adventures_with_slin.html)
+ URL.
+
+Note that we didn't set a _sling:resourceType_ property on our node, so if
+you want to render that node with a script, you'll have to store the script
+under _/apps/nt/unstructured/html.esp_.
+
+
+<a name="DiscoverSlingin15minutes-Addapageheaderwithsling.include"></a>
+## Add a page header with sling.include
+
+The _sling.include_ function can be called from scripts to include the
+rendered result of another node.
+
+In this example, we create a node at _/content/header_, rendered with a
+logo using an _html.esp_ script, then use that header at the top of the
+_html.esp_ script that we created previously for the _foo/bar_ resource
+type.
+
+Start by checking that [http://localhost:8080/content/mynode.html](http://localhost:8080/content/mynode.html)
+ is rendered using the _html.esp_ script created above.
+
+Create this script and name it _header.esp_:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>header.esp</B></DIV><DIV class="codeContent panelContent">
+    <div>
+      <p style="color:blue;">
+        <img src="/images/sling.jpg" align="right"/>
+        <%= currentNode.headline %>
+      </p>
+    </div>
+
+
+Upload it so that it is used to render resources having
+_sling:resourceType=foo/header_:
+
+
+    curl -X MKCOL -u admin:admin http://localhost:8080/apps/foo/header/
+    curl -u admin:admin -T header.esp
+http://localhost:8080/apps/foo/header/html.esp
+
+
+Create the header node:
+
+
+    curl -u admin:admin -F"sling:resourceType=foo/header" -F"headline=Hello,
+Sling world" http://localhost:8080/content/header
+
+
+Upload the logo that the script uses (using sling.jpg or another logo in
+the current directory):
+
+
+    curl -X MKCOL -u admin:admin http://localhost:8080/images/
+    curl -u admin:admin -T sling.jpg http://localhost:8080/images/sling.jpg
+
+
+And check that the header is rendered with the logo at [http://localhost:8080/content/header.html](http://localhost:8080/content/header.html)
+.
+
+Now, update the html.esp script that we created for our first example
+above, to include the header:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>html.esp</B></DIV><DIV class="codeContent panelContent">
+    <html>
+      <body>
+        <div id="header">
+          <% sling.include("/content/header"); %>
+        </div>
+        <h1><%= currentNode.title %></h1>
+      </body>
+    </html>
+
+
+And upload it again to replace the previous version:
+
+
+    curl -u admin:admin -T html.esp http://localhost:8080/apps/foo/bar/html.esp
+
+
+The [http://localhost:8080/content/mynode.html](http://localhost:8080/content/mynode.html)
+, once refreshed, now shows the blue headline and logo, and this layout
+also applies to any node created with _sling:resourceType=foo/bar_.



Mime
View raw message