http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/documentation/the-sling-engine/filters.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/filters.html b/documentation/the-sling-engine/filters.html index 4832c93..b2a0e22 100644 --- a/documentation/the-sling-engine/filters.html +++ b/documentation/the-sling-engine/filters.html @@ -2,29 +2,29 @@ <head> <meta charset="utf-8"/> <title>Apache Sling on JBake</title> - <link rel="stylesheet" href="/res/css/site.css"/> - <link rel="stylesheet" href="/res/css/codehilite.css"/> + <link rel="stylesheet" href="/ng/res/css/site.css"/> + <link rel="icon" href="/ng/res/favicon.ico"/> <div class="title"> <div class="logo"> <a href="http://sling.apache.org";> - <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/> + <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/> </a> </div><div class="header"> <a href="http://www.apache.org";> - <img border="0" alt="Apache" src="/res/logos/apache.png"/> + <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/> </a> </div> </div> </head><body> <div class="menu"> - <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/";>License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling";>Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a><br/><a href="https://donate.apache.org/";>Donate!</a><br/><a href="http://www.apache.org/foun dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong> + <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p ><strong>Project info</strong><br/><a >href="/ng/downloads.cgi">Downloads</a><br/><a >href="http://www.apache.org/licenses/";>License</a><br/><a >href="/ng/contributing.html">Contributing</a><br/><a >href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a >href="/ng/project-information.html">Project Information</a><br/><a >href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a >href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a >href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a > href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a >href="git://git.apache.org/sling.git">Git</a><br/><a >href="https://github.com/apache/sling";>Github >Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a >href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a >href="http://www.apache.org/foundation/sponsorship.html";>Become a >Sponsor</a><br/><a href="https://donate.apache. org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong> </div> <div class="main"> <div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Servlet Filter Support</h1></header><p>Sling supports filter processing by applying filter chains to the requests before actually dispatching to the servlet or script for processing. Filters to be used in such filter processing are plain OSGi services of type <code>javax.servlet.Filter</code> which of course means that the services implement this interface.</p> <div class="note"> See <a href="https://issues.apache.org/jira/browse/SLING-1213";>SLING-1213</a>, <a href="https://issues.apache.org/jira/browse/SLING-1734";>SLING-1734</a>, and <a href="http://markmail.org/message/quxhm7d5s6u66crr";>Registering filters with Sling</a> -for more details. The + for more details. The <a href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/src/main/java/org/apache/sling/launchpad/testservices/filters/NoPropertyFilter.java";>NoPropertyFilter</a> from our integration tests shows an example Sling Filter. </div> @@ -98,40 +98,76 @@ from our integration tests shows an example Sling Filter. <h2>Filter Processing</h2> <p>Filter processing is part of the Sling request processing, which may be sketched as follows:</p> <ul> - <li><em>Request Level</em>:</li> - <li>Authentication</li> - <li>Resource Resolution</li> - <li>Servlet/Script Resolution</li> - <li>Request Level Filter Processing</li> + <li><em>Request Level</em>: + <ul> + <li>Authentication</li> + <li>Resource Resolution</li> + <li>Servlet/Script Resolution</li> + <li>Request Level Filter Processing</li> + </ul> + </li> </ul> <p>The first step of request processing is the <em>Request Level</em> processing which is concerned with resolving the resource, finding the appropriate servlet and calling into the request level filter chain. The next step is the <em>Component Level</em> processing, calling into the component level filters before finally calling the servlet or script:</p> <ul> - <li><em>Component Level</em>:</li> - <li>Component Level Filter Processing</li> - <li>Call Servlet or Script</li> + <li><em>Component Level</em>: + <ul> + <li>Component Level Filter Processing</li> + <li>Call Servlet or Script</li> + </ul> + </li> </ul> <p>When a servlet or script is including or forwarding to another resource for processing through the <code>RequestDispatcher</code> (or any JSP tag or other language feature ultimately using a <code>RequestDispatcher</code>) the following <em>Dispatch</em> processing takes place:</p> <ul> - <li><em>Dispatch</em>:</li> - <li>Resolve the resource to dispatch to if not already defined when getting the <code>RequestDispatcher</code></li> - <li>Servlet/Script resolution</li> - <li>Call include or forward filters depending on the kind of dispatch</li> - <li>Call Servlet or Script</li> + <li><em>Dispatch</em>: + <ul> + <li>Resolve the resource to dispatch to if not already defined when getting the <code>RequestDispatcher</code></li> + <li>Servlet/Script resolution</li> + <li>Call include or forward filters depending on the kind of dispatch</li> + <li>Call Servlet or Script</li> + </ul> + </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> <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> <p>The request traces provided at <code>/system/console/requests</code> contain information about filter execution, as in this example:</p> -<p>0 (2010-09-08 15:22:38) TIMER_START{Request Processing} ... 0 (2010-09-08 15:22:38) LOG Method=GET, PathInfo=/some/path.html 3 (2010-09-08 15:22:38) LOG Applying request filters 3 (2010-09-08 15:22:38) LOG Calling filter: org.apache.sling.bgservlets.impl.BackgroundServletStarterFilter 3 (2010-09-08 15:22:38) LOG Calling filter: org.apache.sling.portal.container.internal.request.PortalFilter 3 (2010-09-08 15:22:38) LOG Calling filter: org.apache.sling.rewriter.impl.RewriterFilter 3 (2010-09-08 15:22:38) LOG Calling filter: org.apache.sling.i18n.impl.I18NFilter 3 (2010-09-08 15:22:38) LOG Calling filter: org.apache.sling.engine.impl.debug.RequestProgressTrackerLogFilter 3 (2010-09-08 15:22:38) LOG Applying inner filters 3 (2010-09-08 15:22:38) TIMER_START{/some/script.jsp#0} ... 8 (2010-09-08 15:22:38) TIMER_END{8,Request Processing} Request Processing</p> +<pre><code>0 (2010-09-08 15:22:38) TIMER_START{Request Processing} +... +0 (2010-09-08 15:22:38) LOG Method=GET, PathInfo=/some/path.html +3 (2010-09-08 15:22:38) LOG Applying request filters +3 (2010-09-08 15:22:38) LOG Calling filter: org.apache.sling.bgservlets.impl.BackgroundServletStarterFilter +3 (2010-09-08 15:22:38) LOG Calling filter: org.apache.sling.portal.container.internal.request.PortalFilter +3 (2010-09-08 15:22:38) LOG Calling filter: org.apache.sling.rewriter.impl.RewriterFilter +3 (2010-09-08 15:22:38) LOG Calling filter: org.apache.sling.i18n.impl.I18NFilter +3 (2010-09-08 15:22:38) LOG Calling filter: org.apache.sling.engine.impl.debug.RequestProgressTrackerLogFilter +3 (2010-09-08 15:22:38) LOG Applying inner filters +3 (2010-09-08 15:22:38) TIMER_START{/some/script.jsp#0} +... +8 (2010-09-08 15:22:38) TIMER_END{8,Request Processing} Request Processing +</code></pre> <h3>Config Status plugin</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> -<p>Current Apache Sling Servlet Filter Configuration</p> -<p>Request Filters: -2147483648 : class org.apache.sling.bgservlets.impl.BackgroundServletStarterFilter (2547) -3000 : class org.apache.sling.portal.container.internal.request.PortalFilter (2562) -2500 : class org.apache.sling.rewriter.impl.RewriterFilter (3365) -700 : class org.apache.sling.i18n.impl.I18NFilter (2334) 0 : class org.apache.sling.engine.impl.debug.RequestProgressTrackerLogFilter (2402)</p> -<h2>Error Filters:</h2> -<p>Include Filters:</p> -<p>Forward Filters: 1000 : class some.package.DebugFilter (2449)</p> -<p>Component Filters: -200 : class some.package.SomeComponentFilter (2583)</p> +<pre><code>Current Apache Sling Servlet Filter Configuration + +Request Filters: +-2147483648 : class org.apache.sling.bgservlets.impl.BackgroundServletStarterFilter (2547) +-3000 : class org.apache.sling.portal.container.internal.request.PortalFilter (2562) +-2500 : class org.apache.sling.rewriter.impl.RewriterFilter (3365) +-700 : class org.apache.sling.i18n.impl.I18NFilter (2334) +0 : class org.apache.sling.engine.impl.debug.RequestProgressTrackerLogFilter (2402) + +Error Filters: +--- + +Include Filters: + +Forward Filters: +1000 : class some.package.DebugFilter (2449) + +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> <p>Up to and including Sling Engine 2.1.0 support for Servlet Filters has been as follows:</p>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/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 81531ee..89b8e26 100644 --- a/documentation/the-sling-engine/mappings-for-resource-resolution.html +++ b/documentation/the-sling-engine/mappings-for-resource-resolution.html @@ -2,22 +2,22 @@ <head> <meta charset="utf-8"/> <title>Apache Sling on JBake</title> - <link rel="stylesheet" href="/res/css/site.css"/> - <link rel="stylesheet" href="/res/css/codehilite.css"/> + <link rel="stylesheet" href="/ng/res/css/site.css"/> + <link rel="icon" href="/ng/res/favicon.ico"/> <div class="title"> <div class="logo"> <a href="http://sling.apache.org";> - <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/> + <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/> </a> </div><div class="header"> <a href="http://www.apache.org";> - <img border="0" alt="Apache" src="/res/logos/apache.png"/> + <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/> </a> </div> </div> </head><body> <div class="menu"> - <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/";>License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling";>Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a><br/><a href="https://donate.apache.org/";>Donate!</a><br/><a href="http://www.apache.org/foun dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong> + <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p ><strong>Project info</strong><br/><a >href="/ng/downloads.cgi">Downloads</a><br/><a >href="http://www.apache.org/licenses/";>License</a><br/><a >href="/ng/contributing.html">Contributing</a><br/><a >href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a >href="/ng/project-information.html">Project Information</a><br/><a >href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a >href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a >href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a > href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a >href="git://git.apache.org/sling.git">Git</a><br/><a >href="https://github.com/apache/sling";>Github >Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a >href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a >href="http://www.apache.org/foundation/sponsorship.html";>Become a >Sponsor</a><br/><a href="https://donate.apache. org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong> </div> <div class="main"> <div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Mappings for Resource Resolution</h1></header><p>[TOC]</p> <h2>Configuration</h2> @@ -25,7 +25,7 @@ <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 <a href="/documentation/bundles/sling-settings-org-apache-sling-settings.html">run mode specific</a> by having a unique path per [run mode specific OSGi configuration]({{ refs./jcr-installer-provider.path }}).</p> <p>When dealing with the new resource resolution we have a number of properties influencing the process:</p> <ul> - <li><code>sling:match</code> – This property when set on a node in the <code>/etc/map</code> tree (see below) defines a partial regular expression which is used instead of the node's name to match the incoming request. This property is only needed if the regular expression includes characters which are not valid JCR name characters. The list of invalid characters for JCR names is: <code>/, :, [, ], *, ', ", , |</code> and any whitespace except blank space. In addition a name without a name space may not be <code>.</code> or <code>..</code> and a blank space is only allowed inside the name.</li> + <li><code>sling:match</code> – This property when set on a node in the <code>/etc/map</code> tree (see below) defines a partial regular expression which is used instead of the node's name to match the incoming request. This property is only needed if the regular expression includes characters which are not valid JCR name characters. The list of invalid characters for JCR names is: <code>/, :, [, ], *, ', ", \, |</code> and any whitespace except blank space. In addition a name without a name space may not be <code>.</code> or <code>..</code> and a blank space is only allowed inside the name.</li> <li><code>sling:redirect</code> – This property when set on a node in the <code>/etc/map</code> tree (see below) causes a redirect response to be sent to the client, which causes the client to send in a new request with the modified location. The value of this property is applied to the actual request and sent back as the value of <code>Location</code> response header.</li> <li><code>sling:status</code> – This property defines the HTTP status code sent to the client with the <code>sling:redirect</code> response. If this property is not set, it defaults to 302 (Found). Other status codes supported are 300 (Multiple Choices), 301 (Moved Permanently), 303 (See Other), and 307 (Temporary Redirect).</li> <li><code>sling:internalRedirect</code> – This property when set on a node in the <code>/etc/map</code> tree (see below) causes the current path to be modified internally to continue with resource resolution. This is a multi-value property, i.e. multiple paths can be given here, which are tried one after another until one resolved to a resource.</li> @@ -52,14 +52,35 @@ <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> +<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> <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> <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> -<p>/etc/map +-- http +-- example.com.80 | +-- sling:redirect = "http://www.example.com/"; +-- www.example.com.80 | +-- sling:internalRedirect = "/example" +-- any_example.com.80 | +-- sling:match = ".+.example.com.80" | +-- sling:redirect = "http://www.example.com/"; +-- localhost_any | +-- sling:match = "localhost.d*" | +-- sling:internalRedirect = "/content" | +-- cgi-bin | | +-- sling:internalRedirect = "/scripts" | +-- gateway | | +-- sling:internalRedirect = "http://gbiv.com"; | +-- (stories) | +-- sling:internalRedirect = "/anecdotes/$1" +-- regexmap +-- sling:match = "$1.example.com/$2" +-- sling:internalRedirect = "/content/([^/]+)/(.*)"</p> +<pre><code>/etc/map + +-- http + +-- example.com.80 + | +-- sling:redirect = "http://www.example.com/" + +-- www.example.com.80 + | +-- sling:internalRedirect = "/example" + +-- any_example.com.80 + | +-- sling:match = ".+\.example\.com\.80" + | +-- sling:redirect = "http://www.example.com/" + +-- localhost_any + | +-- sling:match = "localhost\.\d*" + | +-- sling:internalRedirect = "/content" + | +-- cgi-bin + | | +-- sling:internalRedirect = "/scripts" + | +-- gateway + | | +-- sling:internalRedirect = "http://gbiv.com" + | +-- (stories) + | +-- sling:internalRedirect = "/anecdotes/$1" + +-- regexmap + +-- sling:match = "$1.example.com/$2" + +-- sling:internalRedirect = "/content/([^/]+)/(.*)" +</code></pre> <p>This would define the following mapping entries:</p> <table> <thead> @@ -90,25 +111,25 @@ <td>Redirect all requests to sub domains to www. The actual regular expression for the host.port segment is taken from the <code>sling:match</code> property. </td> </tr> <tr> - <td>http/localhost.d* </td> + <td>http/localhost.\d* </td> <td>/content </td> <td>yes </td> <td>Prefix the URI paths with <code>/content</code> for requests to localhost, regardless of actual port the request was received on. This entry only applies if the URI path does not start with <code>/cgi-bin</code>, <code>gateway</code> or <code>stories</code> because there are longer match entries. The actual regular expression for the host.port segment is taken from the <code>sling:match</code> property. </td> </tr> <tr> - <td>http/localhost.d*/cgi-bin </td> + <td>http/localhost.\d*/cgi-bin </td> <td>/scripts </td> <td>yes </td> <td>Replace the <code>/cgi-bin</code> prefix in the URI path with <code>/scripts</code> for requests to localhost, regardless of actual port the request was received on. </td> </tr> <tr> - <td>http/localhost.d*/gateway </td> + <td>http/localhost.\d*/gateway </td> <td>http://gbiv.com </td> <td>yes </td> <td>Replace the <code>/gateway</code> prefix in the URI path with <code>http://gbiv.com</code> for requests to localhost, regardless of actual port the request was received on. </td> </tr> <tr> - <td>http/localhost.d*/(stories) </td> + <td>http/localhost.\d*/(stories) </td> <td>/anecdotes/stories </td> <td>yes </td> <td>Prepend the URI paths starting with <code>/stories</code> with <code>/anecdotes</code> for requests to localhost, regardless of actual port the request was received on. </td> @@ -116,17 +137,35 @@ </tbody> </table> <h3>Regular Expression Matching</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>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> -<h1>!java</h1> -<p>String path = request.getScheme + "/" + request.getServerName() + "." + request.getServerPort() + "/" + request.getPathInfo(); String result = null; for (MapEntry entry: mapEntries) { Matcher matcher = entry.pattern.matcher(path); if (matcher.find()) { StringBuffer buf = new StringBuffer(); matcher.appendReplacement(buf, entry.getRedirect()); matcher.appendTail(buf); result = buf.toString(); break; } }</p> +<pre><code>#!java +String path = request.getScheme + "/" + request.getServerName() + + "." + request.getServerPort() + "/" + request.getPathInfo(); +String result = null; +for (MapEntry entry: mapEntries) { + Matcher matcher = entry.pattern.matcher(path); + if (matcher.find()) { + StringBuffer buf = new StringBuffer(); + matcher.appendReplacement(buf, entry.getRedirect()); + matcher.appendTail(buf); + result = buf.toString(); + break; + } +} +</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> -<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> -<p>/etc/map +-- http +-- example.com.80 | +-- sling:internalRedirect = "/content/([^/]+)/home/(.*)" | +-- sling:match = "$1/index/$2"</p> +<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> +<pre><code>/etc/map + +-- http + +-- example.com.80 + | +-- sling:internalRedirect = "/content/([^/]+)/home/(.*)" + | +-- sling:match = "$1/index/$2" +</code></pre> <p>leads to the following entry being used in the reverse mapping table:</p> <table> <thead> @@ -145,14 +184,19 @@ <h3>Redirection Values</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> -<h1>!java</h1> -<p>String path = ....; String result = path; do { result = applyMapEntries(result); } while (isURL(result));</p> +<pre><code>#!java +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> <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> - <li>Check whether the path addresses a so called Star Resource. A Star Resource is a resource whose path ends with or contains <code>/*</code>. Such resources are used by the <code>SlingPostServlet</code> to create new content below an existing resource. If the path after Root Level Mapping is absolute, it is made absolute by prepending the first search path entry.</li> + <li>Check whether the path addresses a so called Star Resource. A Star Resource is a resource whose path ends with or contains <code>/\*</code>. Such resources are used by the <code>SlingPostServlet</code> to create new content below an existing resource. If the path after Root Level Mapping is absolute, it is made absolute by prepending the first search path entry.</li> <li>Check whether the path exists in the repository. if the path is absolute, it is tried directly. Otherwise the search path entries are prepended to the path until a resource is found or the search path is exhausted without finding a resource.</li> <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> @@ -160,8 +204,31 @@ <h3>Drilling Down the Resource Tree</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> -<h1>!java</h1> -<p>String path = ...; // the absolute path Resource current = getResource("/"); String[] segments = path.split("/"); for (String segment: segments) { Resource child = getResource(current, segment); if (child == null) { Iterator<Resource> children = listChildren(current); current = null; while (children.hasNext()) { child = children.next(); if (segment.equals(getSlingAlias(child))) { current = child; break; } } if (current == null) { // fail break; } } else { current = child; } }</p> +<pre><code>#!java +String path = ...; // the absolute path +Resource current = getResource("/"); +String[] segments = path.split("/"); +for (String segment: segments) { + Resource child = getResource(current, segment); + if (child == null) { + Iterator<Resource> children = listChildren(current); + current = null; + while (children.hasNext()) { + child = children.next(); + if (segment.equals(getSlingAlias(child))) { + current = child; + break; + } + } + if (current == null) { + // fail + break; + } + } else { + current = child; + } +} +</code></pre> <h2>Rebuild The Vanity Bloom Filter</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> http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/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 565a0c8..12413d5 100644 --- a/documentation/the-sling-engine/request-listeners.html +++ b/documentation/the-sling-engine/request-listeners.html @@ -2,29 +2,42 @@ <head> <meta charset="utf-8"/> <title>Apache Sling on JBake</title> - <link rel="stylesheet" href="/res/css/site.css"/> - <link rel="stylesheet" href="/res/css/codehilite.css"/> + <link rel="stylesheet" href="/ng/res/css/site.css"/> + <link rel="icon" href="/ng/res/favicon.ico"/> <div class="title"> <div class="logo"> <a href="http://sling.apache.org";> - <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/> + <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/> </a> </div><div class="header"> <a href="http://www.apache.org";> - <img border="0" alt="Apache" src="/res/logos/apache.png"/> + <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/> </a> </div> </div> </head><body> <div class="menu"> - <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/";>License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling";>Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a><br/><a href="https://donate.apache.org/";>Donate!</a><br/><a href="http://www.apache.org/foun dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong> + <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p ><strong>Project info</strong><br/><a >href="/ng/downloads.cgi">Downloads</a><br/><a >href="http://www.apache.org/licenses/";>License</a><br/><a >href="/ng/contributing.html">Contributing</a><br/><a >href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a >href="/ng/project-information.html">Project Information</a><br/><a >href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a >href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a >href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a > href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a >href="git://git.apache.org/sling.git">Git</a><br/><a >href="https://github.com/apache/sling";>Github >Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a >href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a >href="http://www.apache.org/foundation/sponsorship.html";>Become a >Sponsor</a><br/><a href="https://donate.apache. org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong> </div> <div class="main"> <div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Request Listeners</h1></header><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> -<h1>!java</h1> -<p>public interface SlingRequestListener {</p> -<p>static final String SERVICE_NAME = "org.apache.sling.api.request.SlingRequestListener";</p> -<p>/** * This method is called from the Sling application for every * <code>EventType</code> appearing during the dispatching of * a Sling request * * @param sre the object representing the event * * @see org.apache.sling.api.request.SlingRequestEvent.EventType */ public void onEvent( SlingRequestEvent sre ); }</p> -<p>There are no special properties to set.</p> +<pre><code>#!java +public interface SlingRequestListener { + + static final String SERVICE_NAME = "org.apache.sling.api.request.SlingRequestListener"; + + /** + * This method is called from the Sling application for every + * <code>EventType</code> appearing during the dispatching of + * a Sling request + * + * @param sre the object representing the event + * + * @see org.apache.sling.api.request.SlingRequestEvent.EventType + */ + public void onEvent( SlingRequestEvent sre ); +} +</code></pre> +<p>There are no special properties to set. </p> <h2>Supported types of events</h2> <p>At the moment you will get two different types of <code>SlingRequestEvent</code>:</p> <table> http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/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 429690c..2cedd02 100644 --- a/documentation/the-sling-engine/request-parameters.html +++ b/documentation/the-sling-engine/request-parameters.html @@ -2,22 +2,22 @@ <head> <meta charset="utf-8"/> <title>Apache Sling on JBake</title> - <link rel="stylesheet" href="/res/css/site.css"/> - <link rel="stylesheet" href="/res/css/codehilite.css"/> + <link rel="stylesheet" href="/ng/res/css/site.css"/> + <link rel="icon" href="/ng/res/favicon.ico"/> <div class="title"> <div class="logo"> <a href="http://sling.apache.org";> - <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/> + <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/> </a> </div><div class="header"> <a href="http://www.apache.org";> - <img border="0" alt="Apache" src="/res/logos/apache.png"/> + <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/> </a> </div> </div> </head><body> <div class="menu"> - <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/";>License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling";>Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a><br/><a href="https://donate.apache.org/";>Donate!</a><br/><a href="http://www.apache.org/foun dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong> + <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p ><strong>Project info</strong><br/><a >href="/ng/downloads.cgi">Downloads</a><br/><a >href="http://www.apache.org/licenses/";>License</a><br/><a >href="/ng/contributing.html">Contributing</a><br/><a >href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a >href="/ng/project-information.html">Project Information</a><br/><a >href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a >href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a >href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a > href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a >href="git://git.apache.org/sling.git">Git</a><br/><a >href="https://github.com/apache/sling";>Github >Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a >href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a >href="http://www.apache.org/foundation/sponsorship.html";>Become a >Sponsor</a><br/><a href="https://donate.apache. org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong> </div> <div class="main"> <div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Request Parameter Handling in Sling</h1></header><p>Excerpt: Explains how Sling provides request parameters to the <code>Component</code>.</p> <h2>Servlet API</h2> @@ -60,7 +60,7 @@ </tr> </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> +<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> <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> @@ -141,7 +141,7 @@ <li>If the parameter is an uploaded file, the file name is re-encoded on the fly when accessed</li> </ul> <div class="info"> -Up to and including Sling Engine 2.2.2 request parameters are always decoded with ISO-8859-1 encoding if the <code>_charset_</code> request parameter is missing. As of Sling Engine 2.2.4 the <code>_charset_</code> request parameter is optional. As of this version the Sling Main Servlet supports a configuration setting which allows to change the default character encoding used if the <code>_charset_</code> request parameter is missing. +Up to and including Sling Engine 2.2.2 request parameters are always decoded with ISO-8859-1 encoding if the <code>_charset_</code> request parameter is missing. As of Sling Engine 2.2.4 the <code>_charset_</code> request parameter is optional. As of this version the Sling Main Servlet supports a configuration setting which allows to change the default character encoding used if the <code>_charset_</code> request parameter is missing. To enable this functionality set the <code>sling.default.parameter.encoding</code> parameter of the Sling Main Servlet (PID <code>org.apache.sling.engine.impl.SlingMainServlet</code>) configuration (for Sling Engine < 2.3.0) or the same parameter of the Sling Request Parameter Handling (PID <code>org.apache.sling.engine.parameters</code>) configuration (for Sling Engine >= 2.3.0 ) to the desired encoding, which of course must be supported by the actual Java Platform. </div></section></div></div> <div class="footer"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/documentation/the-sling-engine/resources.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/resources.html b/documentation/the-sling-engine/resources.html index 425124b..01daaad 100644 --- a/documentation/the-sling-engine/resources.html +++ b/documentation/the-sling-engine/resources.html @@ -2,22 +2,22 @@ <head> <meta charset="utf-8"/> <title>Apache Sling on JBake</title> - <link rel="stylesheet" href="/res/css/site.css"/> - <link rel="stylesheet" href="/res/css/codehilite.css"/> + <link rel="stylesheet" href="/ng/res/css/site.css"/> + <link rel="icon" href="/ng/res/favicon.ico"/> <div class="title"> <div class="logo"> <a href="http://sling.apache.org";> - <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/> + <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/> </a> </div><div class="header"> <a href="http://www.apache.org";> - <img border="0" alt="Apache" src="/res/logos/apache.png"/> + <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/> </a> </div> </div> </head><body> <div class="menu"> - <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/";>License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling";>Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a><br/><a href="https://donate.apache.org/";>Donate!</a><br/><a href="http://www.apache.org/foun dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong> + <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p ><strong>Project info</strong><br/><a >href="/ng/downloads.cgi">Downloads</a><br/><a >href="http://www.apache.org/licenses/";>License</a><br/><a >href="/ng/contributing.html">Contributing</a><br/><a >href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a >href="/ng/project-information.html">Project Information</a><br/><a >href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a >href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a >href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a > href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a >href="git://git.apache.org/sling.git">Git</a><br/><a >href="https://github.com/apache/sling";>Github >Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a >href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a >href="http://www.apache.org/foundation/sponsorship.html";>Become a >Sponsor</a><br/><a href="https://donate.apache. org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong> </div> <div class="main"> <div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Resources</h1></header><p>[TOC]</p> <h2>What is a Resource</h2> @@ -111,7 +111,7 @@ <li>Call <code>HttpServletRequest.getScheme(), .getServerName(), getServerPort</code> to get an absolute path out of the request URL: [scheme]({{ refs.scheme.path }})/[host].[port][path] (<code>resolve(HttpServletRequest, String)</code> method only, which)</li> <li>Check whether any virtual path matches the absolute path. If such a match exists, the next step is entered with the match.</li> <li>Apply a list of mappings in order to create a mapped path. The first mapped path resolving to a Resource is assumed success and the Resource found is returned.</li> - <li>If no mapping created a mapped path addressing an existing Resource, the method fails and returns a <code>NonExistingResource</code> (for the <code>resolve(String)</code> and <code>resolve(HttpServletRequest,String)</code>) or null (for the <code>getResource(String path)</code> and <code>getResource(Resource base, String path)</code> methods).</li> + <li>If no mapping created a mapped path addressing an existing Resource, the method fails and returns a <code>NonExistingResource</code> (for the<br/><code>resolve(String)</code> and <code>resolve(HttpServletRequest,String)</code>) or null (for the <code>getResource(String path)</code> and <code>getResource(Resource base, String path)</code> methods).</li> </ol> <p>The virtual path mapping may be used to create shortcut URLs for otherwise long and complicated URLs. An example of such an URL might be the main administrative page of a CMS system. So, administrators may access the root of the web application and directed to the main administrative page.</p> <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> @@ -144,12 +144,12 @@ <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> <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>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> <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> -<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>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> <p>The merged resource provider exposes a view on merged resources from multiple locations.</p> http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/documentation/the-sling-engine/service-authentication.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/service-authentication.html b/documentation/the-sling-engine/service-authentication.html index 5e8b503..8feae50 100644 --- a/documentation/the-sling-engine/service-authentication.html +++ b/documentation/the-sling-engine/service-authentication.html @@ -2,22 +2,22 @@ <head> <meta charset="utf-8"/> <title>Apache Sling on JBake</title> - <link rel="stylesheet" href="/res/css/site.css"/> - <link rel="stylesheet" href="/res/css/codehilite.css"/> + <link rel="stylesheet" href="/ng/res/css/site.css"/> + <link rel="icon" href="/ng/res/favicon.ico"/> <div class="title"> <div class="logo"> <a href="http://sling.apache.org";> - <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/> + <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/> </a> </div><div class="header"> <a href="http://www.apache.org";> - <img border="0" alt="Apache" src="/res/logos/apache.png"/> + <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/> </a> </div> </div> </head><body> <div class="menu"> - <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/";>License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling";>Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a><br/><a href="https://donate.apache.org/";>Donate!</a><br/><a href="http://www.apache.org/foun dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong> + <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p ><strong>Project info</strong><br/><a >href="/ng/downloads.cgi">Downloads</a><br/><a >href="http://www.apache.org/licenses/";>License</a><br/><a >href="/ng/contributing.html">Contributing</a><br/><a >href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a >href="/ng/project-information.html">Project Information</a><br/><a >href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a >href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a >href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a > href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a >href="git://git.apache.org/sling.git">Git</a><br/><a >href="https://github.com/apache/sling";>Github >Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a >href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a >href="http://www.apache.org/foundation/sponsorship.html";>Become a >Sponsor</a><br/><a href="https://donate.apache. org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong> </div> <div class="main"> <div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Service Authentication</h1></header><p>Excerpt: Introduce new service level authentication to replace <code>loginAdministrative</code></p> <p>[TOC]</p> @@ -37,8 +37,9 @@ <p>A Service may be comprised of multiple parts, so each part of the service may be further identified by a <em>Subservice Name</em>. This Subservice Name is optional, though. Examples of <em>Subservice Name</em> are names for subsystems in a Message Transfer System such as accepting messages, queueing messages, delivering messages.</p> <p>Ultimately, the combination of the <em>Service Name</em> and <em>Subservice Name</em> defines the <em>Service ID</em>. It is the <em>Service ID</em> which is finally mapped to a Resource Resolver and/or JCR Repository user ID for authentication.</p> <p>Thus the actual service identification (service ID) is defined as:</p> -<h1>!text</h1> -<p>service-id = service-name [ ":" subservice-name ] .</p> +<pre><code>#!text +service-id = service-name [ ":" subservice-name ] . +</code></pre> <p>The <code>service-name</code> is the symbolic name of the bundle providing the service.</p> <h3>Example: Tenant Administration</h3> <p>Tenant Administration mostly deals with creating and managing groups and some other user administration tasks. Instead of just using an administrative session for Tenant administration this feature could define itself as being the <code>tenant-admin</code> service and leverage a properly configured Tenant Administration account.</p> @@ -51,14 +52,15 @@ </ul> <p>You could conceive that all these functions serve different purposes and thus should have different access rights to the repository to persist messages while they are being processed.</p> <p>Using the Service Authentication framework, the Mail Transfer System would be consituting the <code>mta</code> service. The sub systems would be called <code>smtp</code>, <code>queue</code>, and <code>deliver</code>.</p> -<p>Thus the SMTP server daemon would be represented by a user for the <code>mta:smtp</code> Service. queueing with <code>mta:queue</code>, and delivery with <code>mta:deliver</code>.</p> +<p>Thus the SMTP server daemon would be represented by a user for the <code>mta:smtp</code> Service. queueing with <code>mta:queue</code>, and delivery with <code>mta:deliver</code>. </p> <h2>Implementation</h2> <p>The implementation in Sling of the <em>Service Authentication</em> concept described above consists of three parts:</p> <h3><code>ServiceUserMapper</code></h3> <p>The first part is a new OSGi Service <code>ServiceUserMapper</code>. The <code>ServiceUserMapper</code> service allows for mapping <em>Service IDs</em> comprised of the <em>Service Names</em> defined by the providing bundles and optional <em>Subservice Name</em> to ResourceResolver and/or JCR Repository user IDs. This mapping is configurable such that system administrators are in full control of assigning users to services.</p> <p>The <code>ServiceUserMapper</code> defines the following API:</p> -<h1>!java</h1> -<p>String getServiceUserID(Bundle bundle, String subServiceName);</p> +<pre><code>#!java +String getServiceUserID(Bundle bundle, String subServiceName); +</code></pre> <p>The implementation uses two fallbacks in case no mapping can be found for the given subServiceName</p> <ol> <li>Use user mapping for the serviceName only (not considering subServiceName)</li> @@ -67,23 +69,39 @@ <p>In addition a service named <code>ServiceUserMapped</code> is registered for each bundle and subservice name for which a service user mapping is configured (<a href="https://issues.apache.org/jira/browse/SLING-4312";>SLING-4312</a>). By explicitly defining a (static) reference towards <code>ServiceUserMapped</code> one can defer starting the service until that service user mapping is available.</p> <h3><code>ResourceResolverFactory</code></h3> <p>The second part is support for service access to the Resource Tree. To this avail, the <code>ResourceResolverFactory</code> service is enhanced with a new factory method</p> -<h1>!java</h1> -<p>ResourceResolver getServiceResourceResolver(Map<String, Object> authenticationInfo) throws LoginException;</p> +<pre><code>#!java +ResourceResolver getServiceResourceResolver(Map<String, Object> authenticationInfo) + throws LoginException; +</code></pre> <p>This method allows for access to the resource tree for services where the service bundle is the bundle actually using the <code>ResourceResolverFactory</code> service. The optional Subservice Name may be provided as an entry in the <code>authenticationInfo</code> map.</p> <p>In addition to having new API on the <code>ResourceResolverFactory</code> service to be used by services, the <code>ResourceProviderFactory</code> service is updated with support for Service Authentication: Now new API is required, though but additional properties are defined to convey the service to authenticate for.</p> <p>The default implementation leverages <code>ServiceUserMapper.getServiceUserID()</code> to resolve the right user id and throws a <code>LoginException</code> in case no mapping has been setup (and none of the fallbacks returned a user id != <code>null</code> either).</p> <h3><code>SlingRepository</code></h3> <p>The third part is an extension to the <code>SlingRepository</code>service interface to support JCR Repository access for services:</p> -<h1>!java</h1> -<p>Session loginService(String subServiceName, String workspace) throws LoginException, RepositoryException;</p> +<pre><code>#!java +Session loginService(String subServiceName, String workspace) + throws LoginException, RepositoryException; +</code></pre> <p>This method allows for access to the JCR Repository for services where the service bundle is the bundle actually using the <code>SlingRepository</code> service. The additional Subservice Name may be provided with the <code>subServiceName</code> parameter.</p> <h2>Configuration</h2> <h3>Service User Mappings</h3> <p>For each service/subservice name combination an according mapping needs to be provided. The mapping binds a service name/subservice name to a JCR system user. This is configured through an OSGi configuration for the factory configuration with PID <code>org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended</code> <a href="https://issues.apache.org/jira/browse/SLING-3578";>SLING-3578</a>. There you can set one configuration property named <code>user.mapping</code> getting a String array as value where each entry must stick to the following format:</p> -<p><service-name>[:<subservice-name>]=<authorizable id of a JCR system user>]</p> +<pre><code><service-name>[:<subservice-name>]=<authorizable id of a JCR system user>] +</code></pre> <p>The according user must exist at the point in time where <code>ResourceResolverFactory.getServiceResourceResolver(...)</code> or <code>SlingRepository.loginService(...)</code> is called. If you rely on one of those methods in your <code>activate</code> method of an OSGi component you should make sure that you defer starting your OSGi component until the according service user mapping is in place. For that you can reference the OSGi service <code>ServiceUserMapped</code> (<a href="https://issues.apache.org/jira/browse/SLING-4312";>SLING-4312</a>), optionally with a target filter on property <code>subServiceName</code> (in case such a subservice name is used). The service <code>ServiceUserMapped</code> does not expose any methods but is only a marker interface exclusively used to defer starting of other OSGi components. However this waits only for the mapping configuration to be available, it does not wait for the service user itself to be available.</p> <p>Example OSGi DS Component</p> -<p>:::java @Component( reference = { // this waits with the activation of this component until a service user mapping with the service name = current bundle's id and the sub service name 'my-subservice-name' is available. // you can leave out "target" if the sub service name is not used. // Please note that this only waits for the mapping to be available, it does not wait for the service user itself to be available! @Reference(name ="scriptsServiceUser", target="(subServiceName=my-subservice-name)", service=ServiceUserMapped.class) } ) class MyComponent { }</p> +<pre><code>:::java +@Component( + reference = { + // this waits with the activation of this component until a service user mapping with the service name = current bundle's id and the sub service name 'my-subservice-name' is available. + // you can leave out "target" if the sub service name is not used. + // Please note that this only waits for the mapping to be available, it does not wait for the service user itself to be available! + @Reference(name ="scriptsServiceUser", target="(subServiceName=my-subservice-name)", service=ServiceUserMapped.class) + } +) +class MyComponent { +} +</code></pre> <p>There is a default mapping applied if no OSGi configuration is available for the mapping. The default is: "serviceuser--" + bundleId [ + "--" + subservice-name]. Please note, that these default mappings are not represented as a ServiceUserMapped service and therefore the above mentioned reference does not work.</p> <h2>Deprecation of administrative authentication</h2> <p>Originally the <code>ResourceResolverFactory.getAdministrativeResourceResolver</code> and <code>SlingRepository.loginAdministrative</code> methods have been defined to provide access to the resource tree and JCR Repository. These methods proved to be inappropriate because they allow for much too broad access.</p> @@ -97,8 +115,13 @@ <p>The implementations we have in Sling's bundle will remain implemented in the near future. But there will be a configuration switch to disable support for these methods: If the method is disabled, a <code>LoginException</code> is always thrown from these methods. The JavaDoc of the methods is extended with this information.</p> <h3>Whitelisting bundles for administrative login</h3> <p>In order to be able to manage few (hopefully legit) uses of the above deprecated methods, a whitelisting mechanism was introduced with <a href="https://issues.apache.org/jira/browse/SLING-5135";>SLING-5153</a> (*JCR Base 2.4.2*).</p> -<p>The recommended way to whitelist a bundle for administrative login is via a <em>whitelist fragment configuration</em>. It can be created as an OSGi factory configuration with the factoryPID <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment</code>. E.g. a typical configuration file might be called <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment-myapp.config</code> and could look as follows:</p> -<p>whitelist.name="myapp" whitelist.bundles=[ "com.myapp.core", "com.myapp.commons" ]</p> +<p>The recommended way to whitelist a bundle for administrative login is via a <em>whitelist fragment configuration</em>. It can be created as an OSGi factory configuration with the factoryPID <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment</code>. E.g. a typical configuration file might be called <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment-myapp.config</code> and could look as follows: </p> +<pre><code>whitelist.name="myapp" +whitelist.bundles=[ + "com.myapp.core", + "com.myapp.commons" +] +</code></pre> <table> <thead> <tr> @@ -128,7 +151,9 @@ <p>Furthermore, there is a global configuration with PID <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist</code>, which should only be used in exceptional cases. It has a switch to turn administrative login on globally (<code>whitelist.bypass</code>) and it allows supplying a regular expression to whitelist matching bundle symbolic names (<code>whitelist.bundles.regexp</code>).</p> <p>The regular expression is most useful for running PaxExam based tests, where bundle symbolic names follow a set pattern but have randomly generated parts.</p> <p>Example: to whitelist all bundles generated by PaxExam a configuration file named <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist.config</code> might look as follows:</p> -<p>whitelist.bypass=B"false" whitelist.bundles.regexp="^PAXEXAM.*$"</p> +<pre><code>whitelist.bypass=B"false" +whitelist.bundles.regexp="^PAXEXAM.*$" +</code></pre> <p>The configuration PID is <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist</code>. It supports the following configuration properties.</p> <table> <thead>
