http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/authentication/authentication-actors.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/authentication/authentication-actors.html b/documentation/the-sling-engine/authentication/authentication-actors.html index 594ccf4..e8035bb 100644 --- a/documentation/the-sling-engine/authentication/authentication-actors.html +++ b/documentation/the-sling-engine/authentication/authentication-actors.html @@ -73,22 +73,22 @@ <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a> » <a href="/ng/documentation/the-sling-engine/authentication.html">Authentication</a> » </div> <h1> Authentication - Actors </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>The authentication process involves a number of actors contributing to the concepts, the API and the particular implementations.</p> -<h2>OSGi Http Service Specification</h2> +<h2><a href="#osgi-http-service-specification" name="osgi-http-service-specification">OSGi Http Service Specification</a></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 Auth Core bundle provides the <code>AuthenticationSupport</code> service which may be used to the implement the <code>HttpContext.handleSecurity</code> method.</p> -<h2>Sling Engine</h2> +<h2><a href="#sling-engine" name="sling-engine">Sling Engine</a></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>Sling Auth Core</h2> +<h2><a href="#sling-auth-core" name="sling-auth-core">Sling Auth Core</a></h2> <p>The support for authenticating client requests is implemented in the Sling Auth Core 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 Sling Auth Core 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 Sling Auth Core bundle and allows applications registering with the OSGi HTTP Service to make use of the Sling authentication infrastructure.</li> </ul> -<h2>JCR Repository</h2> +<h2><a href="#jcr-repository" name="jcr-repository">JCR Repository</a></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> @@ -100,7 +100,7 @@ <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="http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/openid/";>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>Sling Applications</h2> +<h2><a href="#sling-applications" name="sling-applications">Sling Applications</a></h2> <p>Sling Applications requiring authenticated 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>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html b/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html index 8856ca4..69f3e5a 100644 --- a/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html +++ b/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html @@ -126,20 +126,20 @@ <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[^ranking].</p> <p>[^ranking]: 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>.</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>Implementations provided by Sling</h3> +<h3><a href="#implementations-provided-by-sling" name="implementations-provided-by-sling">Implementations provided by Sling</a></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>Sample implementations</h3> -<h4>HTTP Basic Authentication Handler</h4> +<h3><a href="#sample-implementations" name="sample-implementations">Sample implementations</a></h3> +<h4><a href="#http-basic-authentication-handler" name="http-basic-authentication-handler">HTTP Basic Authentication Handler</a></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>Form Based Authentication Handler</h4> +<h4><a href="#form-based-authentication-handler" name="form-based-authentication-handler">Form Based Authentication Handler</a></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> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html b/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html index 413f870..238cb4f 100644 --- a/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html +++ b/documentation/the-sling-engine/authentication/authentication-authenticationhandler/form-based-authenticationhandler.html @@ -81,18 +81,18 @@ <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="http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/form";>Sling SVN</a></p> -<h3>AuthenticationHandler implementation</h3> +<h3><a href="#authenticationhandler-implementation" name="authenticationhandler-implementation">AuthenticationHandler implementation</a></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>AuthenticationFeedbackHandler implementation</h3> +<h3><a href="#authenticationfeedbackhandler-implementation" name="authenticationfeedbackhandler-implementation">AuthenticationFeedbackHandler implementation</a></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>Phase 1: Form Submission</h3> +<h3><a href="#phase-1-form-submission" name="phase-1-form-submission">Phase 1: Form Submission</a></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> @@ -148,7 +148,7 @@ </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="http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/form/src/main/java/org/apache/sling/auth/form/impl/AuthenticationFormServlet.java";>default form servlet</a> and <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/form/src/main/resources/org/apache/sling/auth/form/impl/login.html";>HTML form template</a>.</p> -<h3>Phase 2: Authenticated Requests</h3> +<h3><a href="#phase-2-authenticated-requests" name="phase-2-authenticated-requests">Phase 2: Authenticated Requests</a></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> <pre><code>HmacSHA1(securetoken, <securetokennumber><expirytime>@<userID>)@<securetokennumber><expirytime>@<userID> </code></pre> @@ -166,7 +166,7 @@ <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>Configuration</h3> +<h3><a href="#configuration" name="configuration">Configuration</a></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> @@ -215,7 +215,7 @@ </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>Security Considerations</h3> +<h3><a href="#security-considerations" name="security-considerations">Security Considerations</a></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> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/authentication/authentication-authenticationhandler/openid-authenticationhandler.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/authentication/authentication-authenticationhandler/openid-authenticationhandler.html b/documentation/the-sling-engine/authentication/authentication-authenticationhandler/openid-authenticationhandler.html index d3a3d4e..d3427d5 100644 --- a/documentation/the-sling-engine/authentication/authentication-authenticationhandler/openid-authenticationhandler.html +++ b/documentation/the-sling-engine/authentication/authentication-authenticationhandler/openid-authenticationhandler.html @@ -78,10 +78,10 @@ <p>Since generally an OpenID identity is an URL and URLs may not be used as JCR user names, an association mechanism is used by the OpenID authentication handler to associate an OpenID identity with an existing JCR user: The OpenID identity URL is set as the value of a JCR user property. When a user authenticates with his OpenID identity the matching user searched for by looking for a match in this property.</p> <p><em>NOTE:</em> This association currently only works with Jackrabbit (or Jackrabbit based repositories) because user management is not part of the JCR 2 specification and the OpenID authentication handler uses the Jackrabbit <code>UserManager</code> to find users by a user property value.</p> <p>The OpenID Authentication Handler is maintained in the <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/openid/";>Sling SVN</a></p> -<h3>Credentials Extraction</h3> +<h3><a href="#credentials-extraction" name="credentials-extraction">Credentials Extraction</a></h3> <p>Theoretically each request with the <code>openid_identifier</code> request parameter set may initiate an OpenID authentication process which involves resolving the OpenID provider for the identifier and subsequently authentication with the provider authorizing the Sling instance to use the OpenID identity.</p> <p>This initiation, though, is not possible if the request already contains a valid and validated OpenID identifier either set as a request attribute or set in the HTTP Session or the OpenID cookie. In these situations, the current association of a client with an OpenID identity must first be removed by logging out, e.g. by requesting <code>/system/sling/logout.html</code> which causes the current OpenID user data to be removed by either removing it from the HTTP Session or by clearing the OpenID cookie.</p> -<h3>Phase 1: Form Submission</h3> +<h3><a href="#phase-1-form-submission" name="phase-1-form-submission">Phase 1: Form Submission</a></h3> <p>Requesting an OpenID identifier is initiated by the Sling Authenticator deciding, that authentication is actually required to process a request and the OpenID Authentication Handler being selected to request credentials with.</p> <p>In this case the OpenID authenticator causes a form to be rendered by redirecting the client to the URL indicated by the <code>form.login.form</code> configuration parameter. This redirection request may accompanied by the following parameters:</p> <table> @@ -113,7 +113,7 @@ <li><code>resource</code> -- The <code>resource</code> request parameter should be sent back to ensure the user is finally redirected to requested target resource after successful authentication. If this request parameter is not set, or is set to an empty string, it is assumed to be the request context root path.</li> </ul> <p>The OpenID Authentication Handler provides a default login form registered at <code>/system/sling/openid/login</code>.</p> -<h3>Configuration</h3> +<h3><a href="#configuration" name="configuration">Configuration</a></h3> <p>The OpenID AuthenticationHandler is configured with configuration provided by the OSGi Configuration Admin Service using the <code>org.apache.sling.openidauth.OpenIdAuthenticationHandler</code> service PID.</p> <table> <thead> @@ -125,8 +125,8 @@ </thead> </table> <p>| <code>path</code> | -- | Repository path for which this authentication handler should be used by Sling. If this is empty, the authentication handler will be disabled. | | <code>openid.login.form</code> | <code>/system/sling/openid/login</code> | This should provide a way to capture the user's OpenID identifier. This is not the OpenID Provider's login page, however, it does not have to be a local URL. If it is a local Sling URL, it must be accessible by the anonymous user. The user is HTTP Redirect'ed to this URL. This page should POST back the user's OpenID identifier (as named by the "OpenID identifier form field" property) to the originally requested URL set in the "resource" request parameter. | | <code>openid.login.identifier</code> | <code>openid_identifier</code> | The name of the form parameter that provides the user's OpenID identifier. By convention this is <code>openid_identifier</code>. Only change this if you have a very good reason to do so. | | <code>openid.extern al.url.prefix</code> | -- | The prefix of URLs generated for the <code>ReturnTo</code> and <code>TrustRoot</code> properties of the OpenID request to the OpenID provider. Thus this URL prefix should bring back the authenticated user to this Sling instance. Configuring this property is usually necessary when running Sling behind a proxy (like Apache) since proxy mapping is not performed on the OpenID ReturnTo and TrustRoot URLs as they are sent to the OpenID Provider as form parameters. If this property is empty, the URLs are generated using the hostname found in the original request.| | <code>openid.use.cookie</code> | <code>true</code> | Whether to use a regular Cookie or an HTTP Session to cache the OpenID authentication details. By default a regular cookie is used to prevent use of HTTP Sessions. | | <code>openid.cookie.domain</code> | -- | Domain of cookie used to persist authentication. This defaults to the host name of the Sling server but may be set to a different value to sh are the cookie amongst a server farm or if the server is running behind a proxy. Only used if 'Use Cookie' is checked. | | <code>openid.cookie.name</code> | <code>sling.openid</code> | Name of cookie used to persist authentication. Only used if 'Use Cookie' is checked. | | <code>openid.cookie.secret.key</code> | <code>secret</code> | Secret key used to create a signature of the cookie value to prevent tampering. Only used if 'Use Cookie' is true. | | <code>openid.user.attr</code> | <code>openid.user</code> | Name of the JCR SimpleCredentials attribute to to set with the OpenID User data. This attribute is used by the OpenID LoginModule to validate the OpenID user authentication data. | | <code>openid.property.identity</code> | <code>openid.identity</code> | The name of the JCR User attribute listing one or more OpenID Identity URLs with which a user is associated. The property may be a multi- or single-valued. To resolve a JCR user ID from an OpenID identity a user is searched who l ists the identity in this property. |</p> -<h3>AuthenticationHandler implementation</h3> -<h4>extractCredentials</h4> +<h3><a href="#authenticationhandler-implementation" name="authenticationhandler-implementation">AuthenticationHandler implementation</a></h3> +<h4><a href="#extractcredentials" name="extractcredentials">extractCredentials</a></h4> <p>To extract authentication information from the request, the Sling OpenID Authentication handler considers the following information in order:</p> <ol> <li>The OpenID credentials cookie or OpenID User data in the HTTP Session (depending on the <code>openid.use.cookie</code> configuration)</li> @@ -136,7 +136,7 @@ <p>If the existing credentials fail to validate, authentication failure is assumed and the credentials are removed from the request, either by clearing the OpenID cookie or by removing the OpenID User data from the HTTP Session.</p> <p>If no OpenID credentials are found in the request, the request parameter is considered and if set is used to resolve the actual OpenID identity of the user. This involves redirecting the client to the OpenID provider resolved from the OpenID identifier supplied.</p> <p>If the supplied OpenID identifier fails to resolve to an OpenID provider or if the identifier fails to be resolved to a validated OpenID identity, authentication fails.</p> -<h4>requestCredentials</h4> +<h4><a href="#requestcredentials" name="requestcredentials">requestCredentials</a></h4> <p>If the <code>sling:authRequestLogin</code> parameter is set to a value other than <code>OpenID</code> this method immediately returns <code>false</code>.</p> <p>If the parameter is not set or is set to <code>OpenID</code> this method continues with first invalidating any cached OpenID credentials (same as <code>dropCredentials</code> does) and then redirecting the client to the login form configured with the <code>openid.login.form</code> configuration property. The redirect is provided with up to three request parameters:</p> <table> @@ -161,20 +161,20 @@ </tr> </tbody> </table> -<h4>dropCredentials</h4> +<h4><a href="#dropcredentials" name="dropcredentials">dropCredentials</a></h4> <p>Invalidates the OpenID identity currently stored with the request. This means to either remove the OpenID cookie or to remove the OpenID information from the HTTP Session. This method does not write to the response (except setting the <code>Set-Cookie</code> header to remove the OpenID cookie if required) and does not commit the response.</p> -<h3>AuthenticationFeedbackHandler implementation</h3> -<h4>authenticationFailed</h4> +<h3><a href="#authenticationfeedbackhandler-implementation" name="authenticationfeedbackhandler-implementation">AuthenticationFeedbackHandler implementation</a></h3> +<h4><a href="#authenticationfailed" name="authenticationfailed">authenticationFailed</a></h4> <p>This method is called, if the Credentials provided by the Authentication Handler could not be validated by the Jackrabbit authentication infrastructure. One cause may be that the integration with Jackrabbit has not been completed (see <em>Integration with Jackrabbit</em> below). Another, more probably cause, is that the validated OpenID identifier cannot be associated with an existing JCR user.</p> <p>The OpenID Authentication Handler implementation of the <code>authenticationFailed</code> method sets the <code>j_reason</code> request attribute to <code>OpenIDFailure.REPOSITORY</code> and sets the <code>j_openid_identity</code> request attribute to the OpenID identity of the authenticated user.</p> <p>A login form provider may wish to act upon this situation and provide a login form to the user to allow to his OpenID identity with an existing JCR user.</p> <p>In addition, the current OpenID identity is invalidated thus the cached OpenID information is removed from the HTTP Session or the OpenID cookie is cleaned. This will allow the user to present a different OpenID identifier to retry or it will require the OpenID identity to be revalidated with the OpenID provider if the identity is associated with a JCR user.</p> -<h4>authenticationSucceeded</h4> +<h4><a href="#authenticationsucceeded" name="authenticationsucceeded">authenticationSucceeded</a></h4> <p>The OpenID Authentication Handler implementation of the <code>authenticationSucceeded</code> method just calls the <code>DefaultAuthenticationFeedbackHandler.handleRedirect</code> method to redirect the user to the initially requested location.</p> -<h3>Integration with Jackrabbit</h3> +<h3><a href="#integration-with-jackrabbit" name="integration-with-jackrabbit">Integration with Jackrabbit</a></h3> <p>The OpenID authentication handler can be integrated in two ways into the Jackrabbit authentication mechanism which is based on JAAS <code>LoginModule</code>. One integration is by means of a <code>LoginModulePlugin</code> which plugs into the extensible <code>LoginModule</code> architecture supported by the Sling Jackrabbit Embedded Repository bundle.</p> <p>The other integration option is the <code>trusted_credentials_attribute</code> mechanism supported by the Jackrabbit <code>DefaultLoginModule</code>. By setting the <code>trusted_credentials_attribute</code> parameter of the Jackrabbit <code>DefaultLoginModule</code> and the <code>openid.user.attr</code> configuration property of the OpenID Authentication Handler to the same value, the existence of an attribute of that name in the <code>SimpleCredentials</code> instance provided to the <code>Repository.login</code> method signals pre-authenticated credentials, which need not be further checked by the <code>DefaultLoginModule</code>.</p> -<h3>Security Considerations</h3> +<h3><a href="#security-considerations" name="security-considerations">Security Considerations</a></h3> <p>OpenIDAuthentication 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> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/authentication/authentication-framework.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/authentication/authentication-framework.html b/documentation/the-sling-engine/authentication/authentication-framework.html index c7169bd..b8ce347 100644 --- a/documentation/the-sling-engine/authentication/authentication-framework.html +++ b/documentation/the-sling-engine/authentication/authentication-framework.html @@ -81,7 +81,7 @@ </ul> <p>This page describes how the <code>SlingAuthenticator</code> class provides the <code>AuthenticationSupport</code> and <code>Authenticator</code> services. For a description of the <code>AuthenticationHandler</code> service interface and the interaction between the <code>SlingAuthenticator</code> and the <code>AuthenticationHandler</code> services refer to the <a href="/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html">AuthenticationHandler</a> page.</p> <p>The <code>SlingAuthenticator</code> class is an internal class of the <code>org.apache.sling.auth.core</code> bundle and implements the <code>Authenticator</code> and <code>AuthenticationSupport</code> services.</p> -<h2>AuthenticationSupport</h2> +<h2><a href="#authenticationsupport" name="authenticationsupport">AuthenticationSupport</a></h2> <p>The <code>AuthenticationSupport</code> service interface defines a single method: <code>handleSecurity</code>. This method is intended to be called by the <code>handleSecurity</code> method of any <code>HttpContext</code> implementation wishing to make use of the Sling Authentication Framework.</p> <p>The Sling Authenticator implementation selects an <code>AuthenticationHandler</code> service appropriate for the request and calls the <code>AuthenticationHandler.extractCredentials</code> method to extract the credentials from the request. If no credentials could be extracted, the Sling Authenticator either admits the request as an anonymous request or requests authentication from the client by calling its own <code>login</code> method.</p> <p>The implementation follows this algorithm:</p> @@ -130,7 +130,7 @@ <div class="note"> Only one <code>AuthenticationHandler</code> is able to provide credentials for a given request. If the credentials provided by the handler cannot be used to login to the repository, authentication fails and no further <code>AuthenticationHandler</code> is consulted. </div> -<h4>Request Attributes on Successful Login</h4> +<h4><a href="#request-attributes-on-successful-login" name="request-attributes-on-successful-login">Request Attributes on Successful Login</a></h4> <p>The <code>handleSecurity</code> method gets credentials from the <code>AuthenticationHandler</code> and logs into the JCR repository using those credentials. If the login is successful, the <code>SlingAuthenticator</code> sets the following request attributes:</p> <table> <thead> @@ -165,7 +165,7 @@ <p><strong>NOTE</strong>: Do <em>NOT</em> use the <code>javax.jcr.Session</code> request attribute in your Sling applications. This attribute must be considered implementation specific to convey the JCR Session to the <code>SlingMainServlet</code>. In future versions of the Sling Auth Core bundle, this request attribute will not be present anymore. To get the JCR Session for the current request adapt the request's resource resolver to a JCR Session:</p> <pre><code>Session session = request.getResourceResolver().adaptTo(Session.class); </code></pre> -<h4>Anonymous Login</h4> +<h4><a href="#anonymous-login" name="anonymous-login">Anonymous Login</a></h4> <p>The <code>SlingAuthenticator</code> provides high level of control with respect to allowing anonymous requests or requiring authentication up front:</p> <ul> <li>Global setting of whether anonymous requests are allowed or not. This is the boolean value of the <em>Allow Anonymous Access</em> (<code>auth.annonymous</code>) property of the <code>SlingAuthenticator</code> configuration. This property is supported for backwards compatibility and defaults to <code>true</code> (allowing anonymous access). Setting it to <code>true</code> is a shortcut for setting <code>sling.auth.requirements</code> to <code>-/</code>.</li> @@ -189,7 +189,7 @@ <ul> <li>An authentication handler may register itself with the service registration property <code>sling.auth.requirements = "-/apps/sample/loginform"</code> to ensure the login form can be rendered without requiring authentication.</li> </ul> -<h2>Authenticator implementation</h2> +<h2><a href="#authenticator-implementation" name="authenticator-implementation">Authenticator implementation</a></h2> <p>The implementation of the <code>Authenticator</code> interface is similar for both methods:</p> <p><strong><code>login</code></strong></p> <ol> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/authentication/authentication-tasks.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/authentication/authentication-tasks.html b/documentation/the-sling-engine/authentication/authentication-tasks.html index ecdfe7b..fe32868 100644 --- a/documentation/the-sling-engine/authentication/authentication-tasks.html +++ b/documentation/the-sling-engine/authentication/authentication-tasks.html @@ -73,14 +73,14 @@ <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a> » <a href="/ng/documentation/the-sling-engine/authentication.html">Authentication</a> » </div> <h1> Authentication - Tasks </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>Authentication of HTTP Requests is generally a two-step process: First the credentials must be extracted from the request and second the credentials must be validated. In the case of Sling this means acquiring a JCR Session.</p> -<h2>Extract Credentials from the Request</h2> +<h2><a href="#extract-credentials-from-the-request" name="extract-credentials-from-the-request">Extract Credentials from the Request</a></h2> <ul> <li>Implemented and controlled by the Sling Auth Core bundle</li> <li>Takes <code>HttpServletRequest</code></li> <li>Provides credentials for futher processing (basically JCR <code>Credentials</code> and Workspace name)</li> <li>Extensible with the help of <code>AuthenticationHandler</code> services</li> </ul> -<h2>Login to the JCR Repository</h2> +<h2><a href="#login-to-the-jcr-repository" name="login-to-the-jcr-repository">Login to the JCR Repository</a></h2> <ul> <li>Implemented and controlled by the JCR Repository</li> <li>Takes JCR <code>Credentials</code> and Workspace name</li> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/dispatching-requests.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/dispatching-requests.html b/documentation/the-sling-engine/dispatching-requests.html index d61c6cd..bb4760f 100644 --- a/documentation/the-sling-engine/dispatching-requests.html +++ b/documentation/the-sling-engine/dispatching-requests.html @@ -72,7 +72,7 @@ </div> <div class="main"> <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a> » </div> <h1> Dispatching Requests - </h1><div class="row"><div class="small-12 columns"><section class="wrap"><h2>Main process</h2> + </h1><div class="row"><div class="small-12 columns"><section class="wrap"><h2><a href="#main-process" name="main-process">Main process</a></h2> <p>The following steps should give you an overview how a request is processed in Sling. Details can be found under provided links.</p> <ol> <li> @@ -111,7 +111,7 @@ <li> <p>After having called the component level filters, the request servlet or script is finally called to process the request.</p></li> </ol> -<h2>Include/Forward</h2> +<h2><a href="#include-forward" name="include-forward">Include/Forward</a></h2> <p>If a servlet or script is including another resource for processing through the <code>RequestDispatcher.include</code> or <code>RequestDispatcher.forward</code> (or any JSP or feature of another scripting language which relies on one of this two methods) the following processing takes place:</p> <ol> <li> @@ -126,7 +126,7 @@ <p>The servlet or script is called to process the request.</p></li> </ol> <p>Note that these steps are processed for every include or forward call.</p> -<h2>Included Request Attributes</h2> +<h2><a href="#included-request-attributes" name="included-request-attributes">Included Request Attributes</a></h2> <p>When servlet or script is called as a result of <code>RequestDispatcher.include</code> the following request attributes are set:</p> <table> <thead> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/errorhandling.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/errorhandling.html b/documentation/the-sling-engine/errorhandling.html index 96cc4b0..16ddbc8 100644 --- a/documentation/the-sling-engine/errorhandling.html +++ b/documentation/the-sling-engine/errorhandling.html @@ -78,7 +78,7 @@ <p>The <a href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/servlets/resolver/errorhandler/ErrorHandlingTest.java";>ErrorHandlingTest</a> in our integration tests suite provides working examples of various error handling scenarios.</p> <p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>Resetting the Response</h2> +<h2><a href="#resetting-the-response" name="resetting-the-response">Resetting the Response</a></h2> <p>Errorhandler scripts and servlets are script with the current response. Before setting the status and writing to the response such handlers should do the following:</p> <ul> <li>Check whether the response has been committed or not</li> @@ -96,7 +96,7 @@ </ul> </li> </ul> -<h2>HTTP Status Codes</h2> +<h2><a href="#http-status-codes" name="http-status-codes">HTTP Status Codes</a></h2> <p>The Sling engine implements the <code>HttpServletResponse.sendError</code> methods by calling the <code>ErrorHandler.handleError(int status, String message, SlingHttpServletRequest request, SlingHttpServletResponse response)</code> method.</p> <p>The Servlet Resolver bundle implementation looks up a script to handle the status code as follows:</p> <ul> @@ -108,11 +108,11 @@ <li>An application provider my provide a default handler for the 404/NOT FOUND status. This script might be located in <code>/libs/sling/servlet/errorhandler/404.jsp</code>.</li> <li>An programmer might provide a handler for the 403/FORBIDDEN status in <code>/apps/sling/servlet/errorhandler/403.esp</code>.</li> </ul> -<h2>Uncaught Throwables</h2> +<h2><a href="#uncaught-throwables" name="uncaught-throwables">Uncaught Throwables</a></h2> <p>To handle uncaught Throwables the simple name (<code>Class.getSimpleName()</code>) of the <code>Throwable</code> class is used as request extension. Similarly to the Java try-catch clauses the class hierarchy is supported. That is to handle an uncaught <code>FileNotFoundException</code>, the names <code>FileNotFoundException</code>, <code>IOException</code>, <code>Exception</code>, <code>Throwable</code> are checked for a Servlet and the first one found is then used. Again, the Serlvet may be a Servlet registered as an OSGi service or may be a plain script stored in the JCR repository or provided through some custom Resource provider.</p> <p><strong>Example:</strong> To register a catch-all handler for any uncaught Throwables you might create a script <code>/apps/sling/servlet/errorhandler/Throwable.esp</code>.</p> <p><strong>Note:</strong> If no script or servlet to handle an uncaught <code>Throwable</code> is registered, the default handler kicks in, which sends back a 500/INTERNAL SERVER ERROR response containing the <code>Throwable</code> and the stack trace. This response is <strong>not</strong> handled by the HTTP Status Code handling described above because the response status is sent using <code>HttpServletResponse.setStatus(int, String)</code>. To prevent this default response you have to implement a catch-all handler for the <code>Throwable</code> class as shown in the example.</p> -<h2>Default Handler</h2> +<h2><a href="#default-handler" name="default-handler">Default Handler</a></h2> <p>The Sling Servlet Resolver bundle provides a default error handler servlet which is used if the algorithms described above do not resolve to a handler script or servlet. The provided error handler servlet does the following:</p> <ul> <li>Print a descriptive message, which is the <code>javax.servlet.error.message</code> request attribute by default</li> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/filters.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/filters.html b/documentation/the-sling-engine/filters.html index 7699524..ee9b4e3 100644 --- a/documentation/the-sling-engine/filters.html +++ b/documentation/the-sling-engine/filters.html @@ -116,7 +116,7 @@ from our integration tests shows an example Sling Filter. </tr> </tbody> </table> -<h2>Filter Chains</h2> +<h2><a href="#filter-chains" name="filter-chains">Filter Chains</a></h2> <p>Sling maintains five filter chains: request level, component level, include filters, forward filters and error filters. Except for the component level filter these filter chains correspond to the filter <code><dispatcher></code> configurations as defined for Servlet API 2.5 web applications (see section SRV.6.2.5 Filters and the RequestDispatcher).</p> <p>The following table summarizes when each of the filter chains is called and what value must be defined in the <code>sling.filter.scope</code> property to have a filter added to the respective chain:</p> <table> @@ -156,7 +156,7 @@ from our integration tests shows an example Sling Filter. </tbody> </table> <p>Note on <code>INCLUDE</code> and <code>FORWARD</code> with respect to JSP tags: These filters are also called if the respective including (e.g. <code><jsp:include></code> or <code><sling:include></code>) or forwarding (e.g. <code><jsp:forward></code> or <code><sling:forward></code>) ultimately calls the <code>RequestDispatcher</code>.</p> -<h2>Filter Processing</h2> +<h2><a href="#filter-processing" name="filter-processing">Filter Processing</a></h2> <p>Filter processing is part of the Sling request processing, which may be sketched as follows:</p> <ul> <li><em>Request Level</em>: @@ -189,9 +189,9 @@ from our integration tests shows an example Sling Filter. </li> </ul> <p>As a consequence, request level filters will be called at most once during request processing (they may not be called at all if a filter earlier in the filter chain decides to terminate the request) while the component level, include, and forward filters may be called multiple times while processing a request.</p> -<h2>Troubleshooting</h2> +<h2><a href="#troubleshooting" name="troubleshooting">Troubleshooting</a></h2> <p>Apart form the logs which tell you when filters are executed, two Sling plugins provide information about filters in the OSGi console.</p> -<h3>Recent Requests plugin</h3> +<h3><a href="#recent-requests-plugin" name="recent-requests-plugin">Recent Requests plugin</a></h3> <p>The request traces provided at <code>/system/console/requests</code> contain information about filter execution, as in this example:</p> <pre><code>0 (2010-09-08 15:22:38) TIMER_START{Request Processing} ... @@ -207,7 +207,7 @@ from our integration tests shows an example Sling Filter. ... 8 (2010-09-08 15:22:38) TIMER_END{8,Request Processing} Request Processing </code></pre> -<h3>Config Status plugin</h3> +<h3><a href="#config-status-plugin" name="config-status-plugin">Config Status plugin</a></h3> <p>The configuration status page at <code>/system/console/config</code> includes the current list of active filters in its <em>Servlet Filters</em> category, as in this example:</p> <pre><code>Current Apache Sling Servlet Filter Configuration @@ -230,7 +230,7 @@ Component Filters: -200 : class some.package.SomeComponentFilter (2583) </code></pre> <p>The first numbers on those lines are the filter priorities, and the last number in parentheses is the OSGi service ID.</p> -<h2>Support in Sling Engine 2.1.0</h2> +<h2><a href="#support-in-sling-engine-2-1-0" name="support-in-sling-engine-2-1-0">Support in Sling Engine 2.1.0</a></h2> <p>Up to and including Sling Engine 2.1.0 support for Servlet Filters has been as follows:</p> <ul> <li>Any <code>javax.servlet.Filter</code> service is accepted as a filter for Sling unless the <code>pattern</code> property used by the <a href="http://felix.apache.org/site/apache-felix-http-service.html#ApacheFelixHTTPService-UsingtheWhiteboard";>Apache Felix HttpService whiteboard support</a> is set in the service registration properties.</li> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/mappings-for-resource-resolution.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/mappings-for-resource-resolution.html b/documentation/the-sling-engine/mappings-for-resource-resolution.html index d8b9568..f6cccfc 100644 --- a/documentation/the-sling-engine/mappings-for-resource-resolution.html +++ b/documentation/the-sling-engine/mappings-for-resource-resolution.html @@ -74,8 +74,8 @@ Mappings for Resource Resolution </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>Configuration</h2> -<h3>Properties</h3> +<h2><a href="#configuration" name="configuration">Configuration</a></h2> +<h3><a href="#properties" name="properties">Properties</a></h3> <p>The mapping of request URLs to resources is mainly configured in a configuration tree which is (by default) located below <code>/etc/map</code>. The actual location can be configured with the <code>resource.resolver.map.location</code> property of the <code>org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl</code> configuration. That way you can even make it run mode specific, by taking advantage of the Sling OSGi Installer's run mode awareness.</p> <p>When dealing with the new resource resolution we have a number of properties influencing the process:</p> <ul> @@ -93,7 +93,7 @@ <li>An ACE with allow <code>jcr:read</code> in <code>/content</code> for <code>testuser</code></li> </ul> <p>If the <code>sling:alias</code> property (e.g. <code>myalias</code>) is set directly in <code>/content</code>, the User <code>testuser</code> will not be able to address the resource <code>/content</code> in an URL as <code>/myalias</code>. Instead if the <code>sling:alias</code> property is set in any resource under <code>/content</code> (e.g. <code>/content/visitors</code>) the <code>sling:alias</code> feature will work as usual.</p> -<h3>Node Types</h3> +<h3><a href="#node-types" name="node-types">Node Types</a></h3> <p>To ease with the definition of redirects and aliases, the following node types are defined:</p> <ul> <li><code>sling:ResourceAlias</code> – This mixin node type defines the <code>sling:alias</code> property and may be attached to any node, which does not otherwise allow setting a property named <code>sling:alias</code></li> @@ -101,15 +101,15 @@ <li><code>sling:Mapping</code> – Primary node type which may be used to easily construct entries in the <code>/etc/map</code> tree. The node type extends the <code>sling:MappingSpec</code> mixin node type to allow setting the required matching and redirection. In addition the <code>sling:Resource</code> mixin node type is extended to allow setting a resource type and the <code>nt:hierarchyNode</code> node type is extended to allow locating nodes of this node type below <code>nt:folder</code> nodes.</li> </ul> <p>Note, that these node types only help setting the properties. The implementation itself only cares for the properties and their values and not for any of these node types.</p> -<h2>Namespace Mangling</h2> +<h2><a href="#namespace-mangling" name="namespace-mangling">Namespace Mangling</a></h2> <p>There are systems accessing Sling, which have a hard time handling URLs containing colons – <code>:</code> – in the path part correctly. Since URLs produced and supported by Sling may contain colons because JCR Item based resources may be namespaced (e.g. <code>jcr:content</code>), a special namespace mangling feature is built into the <code>ResourceResolver.resolve</code> and <code>ResourceResolver(map)</code> methods.</p> <p>Namespace mangling operates such, that any namespace prefix identified in resource path to be mapped as an URL in the <code>map</code> methods is modified such that the prefix is enclosed in underscores and the colon removed.</p> <p><em>Example</em>: The path <code>/content/*a*sample/jcr:content/jcr:data.png</code> is modified by namespace mangling in the <code>map</code> method to get at <code>/content/*a*sample/*jcr*content/*jcr*data.png</code>.</p> <p>Conversely the <code>resolve</code> methods must undo such namespace mangling to get back at the resource path. This is simple done by modifying any path such that segments starting with an underscore enclosed prefix are changed by removing the underscores and adding a colon after the prefix. There is one catch, tough: Due to the way the SlingPostServlets automatically generates names, there may be cases where the actual name would be matching this mechanism. Therefore only prefixes are modified which are actually namespace prefixes.</p> <p><em>Example</em>: The path <code>/content/*a*sample/*jcr*content/*jcr*data.png{*</code>} <em>is modified by namespace mangling in the</em> <code>{*}resolve{*</code>} <em>method to get</em> <code>*/content/*a*sample/jcr:content/jcr:data.png{*}{</code>}*. The prefix* <code>*\*a{*}{</code>}<code>{</code>} is not modified because there is no registered namespace with prefix <code>a</code>. On the other hand the prefix <code>{*}jcr{*</code>} is modified because there is of course a registered namespace with prefix <code>jcr</code>.</p> -<h2>Root Level Mappings</h2> +<h2><a href="#root-level-mappings" name="root-level-mappings">Root Level Mappings</a></h2> <p>Root Level Mappings apply to the request at large including the scheme, host, port and uri path. To accomplish this a path is constructed from the request lik this <code>{scheme}/{host}.{port}/{uri_path}</code>. This string is then matched against mapping entries below <code>/etc/map</code> which are structured in the content analogously. The longest matching entry string is used and the replacement, that is the redirection property, is applied.</p> -<h3>Mapping Entry Specification</h3> +<h3><a href="#mapping-entry-specification" name="mapping-entry-specification">Mapping Entry Specification</a></h3> <p>Each entry in the mapping table is a regular expression, which is constructed from the resource path below <code>/etc/map</code>. If any resource along the path has a <code>sling:match</code> property, the respective value is used in the corresponding segment instead of the resource name. Only resources either having a <code>sling:redirect</code> or <code>sling:internalRedirect</code> property are used as table entries. Other resources in the tree are just used to build the mapping structure.</p> <p><em>Example</em></p> <p>Consider the following content</p> @@ -190,11 +190,10 @@ </tr> </tbody> </table> -<h3>Regular Expression Matching</h3> +<h3><a href="#regular-expression-matching" name="regular-expression-matching">Regular Expression Matching</a></h3> <p>As said above the mapping entries are regular expressions which are matched against path. As such these regular expressions may also contain capturing groups as shown in the example above: <code>http/localhost\.\d*/(stories)</code>. After matching the path against the regular expression, the replacement pattern is applied which allows references back to the capturing groups.</p> <p>To illustrate the matching and replacement is applied according to the following pseudo code:</p> -<pre><code>#!java -String path = request.getScheme + "/" + request.getServerName() +<pre><code><!-- TODO syntax marker (#!java) disabled -->String path = request.getScheme + "/" + request.getServerName() + "." + request.getServerPort() + "/" + request.getPathInfo(); String result = null; for (MapEntry entry: mapEntries) { @@ -210,7 +209,7 @@ for (MapEntry entry: mapEntries) { </code></pre> <p>At the end of the loop, <code>result</code> contains the mapped path or <code>null</code> if no entry matches the request <code>path</code>.</p> <p><strong>NOTE:</strong> Since the entries in the <code>/etc/map</code> are also used to reverse map any resource paths to URLs, using regular expressions with wildcards in the Root Level Mappings prevent the respective entries from being used for reverse mappings. Therefor, it is strongly recommended to not use regular expression matching, unless you have a strong need.</p> -<h4>Regular Expressions for Reverse Mappings</h4> +<h4><a href="#regular-expressions-for-reverse-mappings" name="regular-expressions-for-reverse-mappings">Regular Expressions for Reverse Mappings</a></h4> <p>By default using regular expressions with wildcards will prevent to use the mapping entry for reverse mappings (see above). </p> <p>There is one exception though: If there is a <code>sling:internalRedirect</code> property containing a regular expression the map entry will be <em>exclusively used for reverse mappings</em> (i.e. used only for <code>ResourceResolver.map(...)</code>) (see also <a href="https://issues.apache.org/jira/browse/SLING-2560";>SLING-2560</a>). The same resource may carry a <code>sling:match</code> property with wildcards and groups referring to the groups being defined in the <code>sling:internalRedirect</code> property. </p> <p>This example </p> @@ -235,18 +234,17 @@ for (MapEntry entry: mapEntries) { </tr> </tbody> </table> -<h3>Redirection Values</h3> +<h3><a href="#redirection-values" name="redirection-values">Redirection Values</a></h3> <p>The result of matching the request path and getting the redirection is either a path into the resource tree or another URL. If the result is an URL, it is converted into a path again and matched against the mapping entries. This may be taking place repeatedly until an absolute or relative path into the resource tree results.</p> <p>The following pseudo code summarizes this behaviour:</p> -<pre><code>#!java -String path = ....; +<pre><code><!-- TODO syntax marker (#!java) disabled -->String path = ....; String result = path; do { result = applyMapEntries(result); } while (isURL(result)); </code></pre> <p>As soon as the result of applying the map entries is an absolute or relative path (or no more map entries match), Root Level Mapping terminates and the next step in resource resolution, resource tree access, takes place.</p> -<h2>Resource Tree Access</h2> +<h2><a href="#resource-tree-access" name="resource-tree-access">Resource Tree Access</a></h2> <p>The result of Root Level Mapping is an absolute or relative path to a resource. If the path is relative – e.g. <code>myproject/docroot/sample.gif</code> – the resource resolver search path (<code>ResourceResolver.getSearchPath()</code> is used to build absolute paths and resolve the resource. In this case the first resource found is used. If the result of Root Level Mapping is an absolute path, the path is used as is.</p> <p>Accessing the resource tree after applying the Root Level Mappings has four options:</p> <ul> @@ -255,11 +253,10 @@ do { <li>Drill down the resource tree starting from the root, optionally using the search path until a resource is found.</li> <li>If no resource can be resolved, a Missing Resource is returned.</li> </ul> -<h3>Drilling Down the Resource Tree</h3> +<h3><a href="#drilling-down-the-resource-tree" name="drilling-down-the-resource-tree">Drilling Down the Resource Tree</a></h3> <p>Drilling down the resource tree starts at the root and for each segment in the path checks whether a child resource of the given name exists or not. If not, a child resource is looked up, which has a <code>sling:alias</code> property whose value matches the given name. If neither exists, the search is terminated and the resource cannot be resolved.</p> <p>The following pseudo code shows this algorithm assuming the path is absolute:</p> -<pre><code>#!java -String path = ...; // the absolute path +<pre><code><!-- TODO syntax marker (#!java) disabled -->String path = ...; // the absolute path Resource current = getResource("/"); String[] segments = path.split("/"); for (String segment: segments) { @@ -283,7 +280,7 @@ for (String segment: segments) { } } </code></pre> -<h2>Rebuild The Vanity Bloom Filter</h2> +<h2><a href="#rebuild-the-vanity-bloom-filter" name="rebuild-the-vanity-bloom-filter">Rebuild The Vanity Bloom Filter</a></h2> <p><a href="https://issues.apache.org/jira/browse/SLING-4216";>SLING-4216</a> introduced the usage of a bloom filter in order to resolve long startup time with many vanityPath entries. The bloom filter is handled automatically by the Sling framework. In some cases though, as changing the maximum number of vanity bloom filter bytes, a rebuild of the vanity bloom filter is needed.</p> <p>In order to rebuild vanity bloom filter:</p> <ul> @@ -293,7 +290,7 @@ for (String segment: segments) { <li>delete the vanityBloomFilter.txt file</li> <li>start Apache Sling (this might take few minutes, depending on how many vanity path entries are present)</li> </ul> -<h2>Debugging Issues</h2> +<h2><a href="#debugging-issues" name="debugging-issues">Debugging Issues</a></h2> <p>Use the Felix Web Console Plugin provided at <code>/system/console/jcrresolver</code> to inspect both the mapping and the resolver map entries. Also you can check what either <code>ResourceResolver.map(...)</code> or <code>ResourceResolver.resolve(...)</code> would return for a given URL/path.</p></section></div></div> <div class="footer"> <div class="trademarkFooter"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/request-listeners.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/request-listeners.html b/documentation/the-sling-engine/request-listeners.html index 78811f3..7b897d3 100644 --- a/documentation/the-sling-engine/request-listeners.html +++ b/documentation/the-sling-engine/request-listeners.html @@ -73,8 +73,7 @@ <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a> » </div> <h1> Request Listeners </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>Sling provides the possibility to "listen" to a request processed by the Sling Engine (<code>SlingMainServlet</code>). To get notified you implement the service interface <code>org.apache.sling.api.request.SlingRequestListener</code>.</p> -<pre><code>#!java -public interface SlingRequestListener { +<pre><code><!-- TODO syntax marker (#!java) disabled -->public interface SlingRequestListener { static final String SERVICE_NAME = "org.apache.sling.api.request.SlingRequestListener"; @@ -91,7 +90,7 @@ public interface SlingRequestListener { } </code></pre> <p>There are no special properties to set. </p> -<h2>Supported types of events</h2> +<h2><a href="#supported-types-of-events" name="supported-types-of-events">Supported types of events</a></h2> <p>At the moment you will get two different types of <code>SlingRequestEvent</code>:</p> <table> <thead> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/request-parameters.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/request-parameters.html b/documentation/the-sling-engine/request-parameters.html index 7577b90..1863eb8 100644 --- a/documentation/the-sling-engine/request-parameters.html +++ b/documentation/the-sling-engine/request-parameters.html @@ -72,7 +72,7 @@ </div> <div class="main"> <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a> » </div> <h1> Request Parameter Handling in Sling - </h1><div class="row"><div class="small-12 columns"><section class="wrap"><h2>Servlet API</h2> + </h1><div class="row"><div class="small-12 columns"><section class="wrap"><h2><a href="#servlet-api" name="servlet-api">Servlet API</a></h2> <p>The Servlet API specification provides the following methods to access the parameters of a request</p> <table> <thead> @@ -113,7 +113,7 @@ </tbody> </table> <p>The actual encoding of the parameters is all but safe because the encoding of URLs is not very well defined and browsers do not set the character encoding when sending post data. Fortunately, they use the same character encoding for sending back form content as was used by the server to send the form. </p> -<h2>Sling API</h2> +<h2><a href="#sling-api" name="sling-api">Sling API</a></h2> <p>To overcome the restrictions and to provide uniform access to request parameters the Sling API in addition to the Servlet API methods to access parameters provides an abstraction of parameters which is applicable to all parameters sent by clients, the <code>RequestParameter</code> interface. Through this interface, each parameter may be analyzed for these topics:</p> <table> <thead> @@ -167,7 +167,7 @@ <li>After the servlet container provided parameters are parameters extracted from the request in case <code>multipart/form-data</code> POST requests. The order of these parameters is preserved as they are submitted in the request. This conforms to HTML 4.01 spec on forms submitted with multipart/form-data encoding: <em>A "multipart/form-data" message contains a series of parts, each representing a successful control. The parts are sent to the processing agent in the same order the corresponding controls appear in the document stream. Part boundaries should not occur in any of the data; how this is done lies outside the scope of this specification</em> (<a href="http://www.w3.org/TR/html401/interact/forms.html";>17.13.4 Form content types</a>)</li> </ul> <p>Be warned: Only rely on request parameter ordering <code>multipart/form-data</code> POST requests without a query part in the request URL.</p> -<h3>Effects of Sling on Servlet API parameter methods</h3> +<h3><a href="#effects-of-sling-on-servlet-api-parameter-methods" name="effects-of-sling-on-servlet-api-parameter-methods">Effects of Sling on Servlet API parameter methods</a></h3> <p>From within Sling servlets/scripts you can no longer rely on the original semantics of the Servlet API methods for dealing with parameters as</p> <ul> <li><code>ServletRequest.getParameter(String)</code></li> @@ -179,7 +179,7 @@ </ul> <p>internally use the Sling parameter support (and therefore have the same implications on e.g. encoding). You should preferably use the Sling methods <code>getRequestParameter*</code> instead.</p> <p>Calling <code>ServletRequest.getInputStream()</code> is not supported, nor relying on some 3rd party libraries which are internally using that method like <a href="https://commons.apache.org/proper/commons-fileupload/";>Apache Commons Fileupload</a>. This is because the Sling parameter support needs exclusive access to the request's input stream.</p> -<h2>Character Encoding</h2> +<h2><a href="#character-encoding" name="character-encoding">Character Encoding</a></h2> <p>Traditionally, the encoding of parameters, especially in text area input forms, has been a big issue. To solve this issue Sling introduces the following convention:</p> <ul> <li>All forms should contain a hidden field of the name <code>_charset_</code> containing the actual encoding used to send the form from the server to the client</li> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/resources.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/resources.html b/documentation/the-sling-engine/resources.html index 94a1dba..541f613 100644 --- a/documentation/the-sling-engine/resources.html +++ b/documentation/the-sling-engine/resources.html @@ -74,9 +74,9 @@ Resources </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>What is a Resource</h2> +<h2><a href="#what-is-a-resource" name="what-is-a-resource">What is a Resource</a></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. By doing this Sling fits very well in the paradigma of the REST architecture.</p> -<h3>Resource Properties</h3> +<h3><a href="#resource-properties" name="resource-properties">Resource Properties</a></h3> <p>Resources have a number of essentiall properties:</p> <table> <thead> @@ -113,7 +113,7 @@ </tbody> </table> <p>For a complete description of the <code>Resource</code> interface, please refer to the <a href="http://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/Resource.html"; title="Resource">link text</a> JavaDoc.</p> -<h3>Resource Types</h3> +<h3><a href="#resource-types" name="resource-types">Resource Types</a></h3> <p>The exact method of setting the resource type for a Resource depends on the actual Resource Provider. For the four main Resource Provider implementations provided by Sling, the assignments are as follows:</p> <table> <thead> @@ -147,10 +147,10 @@ </tbody> </table> <p>Resource Types form a type hierarchy much like Java classes form a type hierarchy. Each resource type has a resource super type, either explicitly defined as for example for JCR or Servlet Resources or implicitly. The implicit Resource Super Type is at the same time the root Resource Type much like the <code>java.lang.Object</code> class is called <code>sling/servlet/default</code> (for historical reasons). The <code>sling/servlet/default</code> Resource Type is the only type without a super type.</p> -<h3>Adapters</h3> +<h3><a href="#adapters" name="adapters">Adapters</a></h3> <p>The object types to which Resources may be adapted depend mostly depends on the Resource Provider providing the resource. For example all JCR node based resources always adapt to <code>javax.jcr.Node</code> objects.</p> <p>If the actual Resource object class implementation extends from the <code>SlingAdaptable</code> class, then in addition all <code>AdapterFactory</code> services adapting <code>Resource</code> objects are considered when trying to adapt the Resource. In general Resource Providers are recommended to have their Resource implementation extend from <a href="http://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/AbstractResource.html"; title="AbstractResource">link text</a> which guarantees the Resource implementation to extend from <code>SlingAdaptable</code> and thus supporting Adapter Factories.</p> -<h2>How to get a Resource</h2> +<h2><a href="#how-to-get-a-resource" name="how-to-get-a-resource">How to get a Resource</a></h2> <p>To get at Resources, you need a <code>ResourceResolver</code>. This interface defines four kinds of methods to access resources:</p> <ul> <li>Absolute Path Mapping Resource Resolution: The <code>resolve(HttpServletRequest, String)</code> and <code>resolve(String)</code> methods are called to apply some implementation specific path matching algorithm to find a Resource. These methods are mainly used to map external paths - such as path components of request URLs - to Resources. To support creating external paths usable in an URL a third method <code>map(String)</code> is defined, which allows for round-tripping.</li> @@ -158,7 +158,7 @@ <li>Resource Enumeration: To enumerate resources and thus iterate the resource tree, the <code>listChildren(Resource)</code> method may be used. This method returns an <code>Iterator<Resource></code> listing all resources whose path prefix is the path of the given Resource. This method will of course also cross boundaries of registered <code>ResourceProvider</code> instances to enable iterating the complete resource tree.</li> <li>Resource Querying: Querying resources is currently only supported for JCR Resources through the <code>findResources(String query, String language)</code> and <code>queryResources(String query, String language)</code> methods. For more information see the section on <a href="#querying-resources">Querying Resources</a> below.</li> </ul> -<h3>Absolute Path Mapping</h3> +<h3><a href="#absolute-path-mapping" name="absolute-path-mapping">Absolute Path Mapping</a></h3> <p>As has been said, the absolute path mapping methods <code>resolve(HttpServletRequest, String)</code> and <code>resolve(String)</code> apply some implementation specific path matching algorithm to find a Resource. The difference between the two methods is that the former may take more properties of the <code>HttpServletRequest</code> into account when resolving the Resoure, while the latter just has an absolute path to work on.</p> <p>The general algorithm of the two methods is as follows:</p> <ol> @@ -171,11 +171,11 @@ <p>The path mapping functionality may be used to hide internal resource organization from the request URL space. For example to better control the structure of your repository, you might decide to store all accessible data inside a <code>/content</code> subtree. To hide this fact from the users, a mapping may be defined to prefix all incoming paths with <code>/content</code> to get at the actual Resource.</p> <p>The <code>map(String)</code> applies the path mapping algorithm in the reverse order. That is, first the path mappings are reversed and then any virtual mappings are checked. So, a path <code>/content/sample</code> might be mapped <code>/sample</code> to revers the <code>/content</code> prefixing. Or the main administrative page - say <code>/system/admin/main.html</code> - may be mapped to the virtual URL <code>/</code>.</p> <p>More details on mappings can be found at <a href="/documentation/the-sling-engine/mappings-for-resource-resolution.html">Mappings for Resource Resolution</a>.</p> -<h3>Relative Path Resolution</h3> +<h3><a href="#relative-path-resolution" name="relative-path-resolution">Relative Path Resolution</a></h3> <p>Sometimes it is required to resolve relative paths to Resources. An example of such a use case is Script and Servlet resolution which starts with a relative path consisting of the Resource type, optional selectors and the request extension or method name. By scanning a search path for these relative paths a system provided Resource may be overwritten with some user defined implementation.</p> <p>Consider for example, the system would provide a Servlet to render Resources of type <code>nt:file</code>. This Servlet would be registered under the path <code>/libs/nt/file/html</code>. For a certain web application, this default HTML rendering might not be appropriate, so a Script is created as <code>/apps/nt/file/html.jsp</code> with a customized HTML rendering. By defining the search path to be <code>[/apps,/libs]</code> the Servlet resolver would call the <code>ResourceResolver.getResource(String)</code> method with the relative path <code>nt/file/html</code> and be provided with the first matching resource - <code>/apps/nt/file/html.jsp</code> in this example.</p> <p>Of course the search path is not used for absolute path arguments.</p> -<h3>Querying Resources</h3> +<h3><a href="#querying-resources" name="querying-resources">Querying Resources</a></h3> <p>For convenience the <code>ResourceResolver</code> provides two Resource querying methods <code>findResources</code> and <code>queryResources</code> both methods take as arguments a JCR query string and a query language name. These parameters match the parameter definition of the <code>QueryManager.createQuery(String statement, String language)</code> method of the JCR API.</p> <p>The return value of these two methods differ in the use case:</p> <ul> @@ -184,7 +184,7 @@ </ul> <p>These methods are convenience methods to more easily post queries to the repository and to handle results in very straight forward way using only standard Java functionality.</p> <p>Please note, that Resource querying is currently only supported for repository based Resources. These query methods are not reflected in the <code>ResourceProvider</code> interface used to inject non-repository Resources into the Resource tree.</p> -<h2>Providing Resources</h2> +<h2><a href="#providing-resources" name="providing-resources">Providing Resources</a></h2> <p>The virtual Resource tree to which the the Resource accessor methods <code>resolve</code> and <code>getResource</code> provide access is implemented by a collection of registered <code>ResourceProvider</code> instances. The main Resource provider is of course the repository based <code>JcrResourceProvider</code> which supports Node and Property based resources. This Resource provider is always available in Sling. Further Resource providers may or may not exist.</p> <p>Each Resource provider is registered as an OSGi service with a required service registration property <code>provider.roots</code>. This is a multi-value String property listing the absolute paths Resource tree entries serving as roots to provided subtrees. For example, if a Resource provider is registered with the service registration property <code>provider.roots</code> set to <em>/some/root</em>, all paths starting with <code>/some/root</code> are first looked up in the given Resource Provider.</p> <p>When looking up a Resource in the registered Resource providers, the <code>ResourceResolver</code> applies a longest prefix matching algorithm to find the best match. For example consider three Resource provider registered as follows:</p> @@ -194,35 +194,35 @@ <li>Resource provider R2 as <code>/some/path</code></li> </ul> <p>When accessing a Resource with path <code>/some/path/resource</code> the Resource provider <em>R2</em> is first asked. If that cannot provide the resource, Resource provider <em>R1</em> is asked and finally the JCR Resource provider is asked. The first Resource provider having a Resource with the requested path will be used.</p> -<h3>JCR-based Resources</h3> +<h3><a href="#jcr-based-resources" name="jcr-based-resources">JCR-based Resources</a></h3> <p>JCR-based Resources are provided with the default <code>JcrResourceProvider</code>. This Resource provider is always available and is always asked last. That is Resources provided by other Resource providers may never be overruled by repository based Resources.</p> -<h3>Bundle-based Resources</h3> +<h3><a href="#bundle-based-resources" name="bundle-based-resources">Bundle-based Resources</a></h3> <p>Resources may by provided by OSGi bundles. Providing bundles have a Bundle manifest header <code>Sling-Bundle-Resources</code> containing a list of absolute paths provided by the bundle. The path are separated by comma or whitespace (SP, TAB, VTAB, CR, LF).</p> <p>The <code>BundleResourceProvider</code> supporting bundle-based Resources provides directories as Resources of type <code>nt:folder</code> and files as Resources of type <code>nt:file</code>. This matches the default primary node types intended to be used for directories and files in JCR repositories. </p> <p>For details see <a href="/documentation/bundles/bundle-resources-extensions-bundleresource.html">Bundle Resource.</a></p> -<h3>Servlet Resources</h3> +<h3><a href="#servlet-resources" name="servlet-resources">Servlet Resources</a></h3> <p>Servlet Resources are registered by the Servlet Resolver bundle for Servlets registered as OSGi services. See <a href="/documentation/the-sling-engine/servlets.html">Servlet Resolution</a> for information on how Servlet Resources are provided.</p> -<h3>File System Resources</h3> +<h3><a href="#file-system-resources" name="file-system-resources">File System Resources</a></h3> <p>The Filesystem Resource Provider provides access to the operating system's filesystem through the Sling ResourceResolver. Multiple locations may be mapped into the resource tree by configuring the filesystem location and the resource tree root path for each location to be mapped. </p> <p>For details see <a href="/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html">File System Resources</a>.</p> -<h3>Merged Resources</h3> +<h3><a href="#merged-resources" name="merged-resources">Merged Resources</a></h3> <p>The merged resource provider exposes a view on merged resources from multiple locations.</p> <p>For details see <a href="/documentation/bundles/resource-merger.html">Resource Merger</a>.</p> -<h3>Custom Resource providers</h3> +<h3><a href="#custom-resource-providers" name="custom-resource-providers">Custom Resource providers</a></h3> <p>Custom ResourceProvider services can be used to integrate your own custom resources in the Sling resource tree.</p> <p>For a simple example of that, see the <a href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/src/main/java/org/apache/sling/launchpad/testservices/resourceprovider/";>PlanetResourceProvider</a> used in our integration tests.</p> -<h2>Writeable Resources</h2> +<h2><a href="#writeable-resources" name="writeable-resources">Writeable Resources</a></h2> <p>Sling now supports full CRUD functionality on Resources, without necessarily having to go through the JCR API.</p> <p>The advantage is that this works for any ResourceProvider that supports the required operations.</p> <p>See the testSimpleCRUD method in <a href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/src/main/java/org/apache/sling/launchpad/testservices/serversidetests/WriteableResourcesTest.java";>WriteableResourcesTest</a> for a basic example of how that works. More details can be found at <a href="/documentation/the-sling-engine/sling-api-crud-support.html">Sling API CRUD Support</a>.</p> -<h2>Resource Observation</h2> +<h2><a href="#resource-observation" name="resource-observation">Resource Observation</a></h2> <p>To be notified whenever certain resources or their properties have been modified/added/removed there are different possibilities</p> -<h3>Resource Observation API (ResourceChangeListener)</h3> +<h3><a href="#resource-observation-api-resourcechangelistener-" name="resource-observation-api-resourcechangelistener-">Resource Observation API (ResourceChangeListener)</a></h3> <p><em>This API is only available since Sling API 2.11.0 (<a href="https://issues.apache.org/jira/browse/SLING-4751";>SLING-4751</a>).</em></p> <p>Register an OSGi service for <a href="https://svn.apache.org/repos/asf/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChangeListener.java";><code>org.apache.sling.api.resource.observation.ResourceChangeListener</code></a> or <a href="https://svn.apache.org/repos/asf/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ExternalResourceChangeListener.java";><code>org.apache.sling.api.resource.observation.ExternalResourceChangeListener</code></a> to be notified about changes. Certain properties can be used to restrict subscription to only a subset of events.</p> -<h3>OSGi Event Admin</h3> +<h3><a href="#osgi-event-admin" name="osgi-event-admin">OSGi Event Admin</a></h3> <p>Resource events are sent out via the OSGi Event Admin. You can subscribe to those event by registering an OSGi service for <a href="https://osgi.org/javadoc/r6/cmpn/org/osgi/service/event/EventHandler.html";><code>org.osgi.service.event.EventHandler</code></a>. Several properties should be used to restrict the subscription to only the relevant event. The event topics which are used for resources are listed as constants in <a href="http://sling.apache.org/apidocs/sling8/org/apache/sling/api/SlingConstants.html";><code>org.apache.sling.api.SlingConstants</code></a> starting with the prefix <code>TOPIC_</code>.</p> -<h2>Wrap/Decorate Resources</h2> +<h2><a href="#wrap-decorate-resources" name="wrap-decorate-resources">Wrap/Decorate Resources</a></h2> <p>The Sling API provides an easy way to wrap or decorate a resource before returning. Details see <a href="/documentation/the-sling-engine/wrap-or-decorate-resources.html">Wrap or Decorate Resources</a>.</p></section></div></div> <div class="footer"> <div class="trademarkFooter">
