You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bu...@apache.org on 2015/09/22 12:23:33 UTC
svn commit: r966334 [8/11] - in /websites/staging/sling/trunk/content: ./
documentation/ documentation/bundles/ documentation/bundles/scripting/
documentation/development/ documentation/getting-started/
documentation/legacy/ documentation/the-sling-eng...
Modified: websites/staging/sling/trunk/content/documentation/the-sling-engine/mappings-for-resource-resolution.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/mappings-for-resource-resolution.html (original)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/mappings-for-resource-resolution.html Tue Sep 22 10:23:16 2015
@@ -18,11 +18,11 @@
limitations under the License.
-->
<head>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Apache Sling - Mappings for Resource Resolution</title>
<link rel="icon" href="/res/favicon.ico">
<link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
<link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
- <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
</head>
<body>
<div class="title">
@@ -39,7 +39,18 @@
</div>
<div class="menu">
- <p><strong><a href="/documentation.html">Documentation</a></strong> <br />
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<p><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 />
@@ -90,8 +101,19 @@
<h1>Mappings for Resource Resolution</h1>
- <h2 id="configuration">Configuration</h2>
-<h3 id="properties">Properties</h3>
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<h2 id="configuration">Configuration<a class="headerlink" href="#configuration" title="Permanent link">¶</a></h2>
+<h3 id="properties">Properties<a class="headerlink" href="#properties" title="Permanent link">¶</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.</p>
<p>When dealing with the new resource resolution we have a number of properties influencing the process:</p>
<ul>
@@ -101,7 +123,7 @@
<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.</li>
<li><code>sling:alias</code> – The property may be set on any resource to indicate an alias name for the resource. For example the resource <code>/content/visitors</code> may have the <code>sling:alias</code> property set to <code>besucher</code> allowing the resource to be addressed in an URL as <code>/content/besucher</code>.</li>
</ul>
-<h3 id="node-types">Node Types</h3>
+<h3 id="node-types">Node Types<a class="headerlink" href="#node-types" title="Permanent link">¶</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>
@@ -109,15 +131,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 id="namespace-mangling">Namespace Mangling</h2>
+<h2 id="namespace-mangling">Namespace Mangling<a class="headerlink" href="#namespace-mangling" title="Permanent link">¶</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>}<em>. The prefix</em> <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 id="root-level-mappings">Root Level Mappings</h2>
+<h2 id="root-level-mappings">Root Level Mappings<a class="headerlink" href="#root-level-mappings" title="Permanent link">¶</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 as <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 id="mapping-entry-specification">Mapping Entry Specification</h3>
+<h3 id="mapping-entry-specification">Mapping Entry Specification<a class="headerlink" href="#mapping-entry-specification" title="Permanent link">¶</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>
@@ -146,7 +168,7 @@
<p>This would define the following mapping entries:</p>
-<table>
+<table class="table">
<thead>
<tr>
<th>Regular Expression</th>
@@ -200,7 +222,7 @@
</tr>
</tbody>
</table>
-<h3 id="regular-expression-matching">Regular Expression matching</h3>
+<h3 id="regular-expression-matching">Regular Expression matching<a class="headerlink" href="#regular-expression-matching" title="Permanent link">¶</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>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
@@ -233,7 +255,7 @@
<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 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>
-<h3 id="redirection-values">Redirection Values</h3>
+<h3 id="redirection-values">Redirection Values<a class="headerlink" href="#redirection-values" title="Permanent link">¶</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>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre>1
@@ -249,7 +271,7 @@
</td></tr></table>
<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 id="resource-tree-access">Resource Tree Access</h2>
+<h2 id="resource-tree-access">Resource Tree Access<a class="headerlink" href="#resource-tree-access" title="Permanent link">¶</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>
@@ -258,7 +280,7 @@
<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 id="drilling-down-the-resource-tree">Drilling Down the Resource Tree</h3>
+<h3 id="drilling-down-the-resource-tree">Drilling Down the Resource Tree<a class="headerlink" href="#drilling-down-the-resource-tree" title="Permanent link">¶</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>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
@@ -309,7 +331,7 @@
</pre></div>
</td></tr></table>
-<h2 id="rebuild-the-vanity-bloom-filter">Rebuild The Vanity Bloom Filter</h2>
+<h2 id="rebuild-the-vanity-bloom-filter">Rebuild The Vanity Bloom Filter<a class="headerlink" href="#rebuild-the-vanity-bloom-filter" title="Permanent link">¶</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>
Modified: websites/staging/sling/trunk/content/documentation/the-sling-engine/request-listeners.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/request-listeners.html (original)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/request-listeners.html Tue Sep 22 10:23:16 2015
@@ -18,11 +18,11 @@
limitations under the License.
-->
<head>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Apache Sling - Request Listeners</title>
<link rel="icon" href="/res/favicon.ico">
<link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
<link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
- <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
</head>
<body>
<div class="title">
@@ -39,7 +39,18 @@
</div>
<div class="menu">
- <p><strong><a href="/documentation.html">Documentation</a></strong> <br />
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<p><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 />
@@ -90,7 +101,18 @@
<h1>Request Listeners</h1>
- <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>
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<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>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
@@ -124,9 +146,9 @@
</td></tr></table>
<p>There are no special properties to set. </p>
-<h2 id="supported-types-of-events">Supported types of events</h2>
+<h2 id="supported-types-of-events">Supported types of events<a class="headerlink" href="#supported-types-of-events" title="Permanent link">¶</a></h2>
<p>At the moment you will get two different types of <code>SlingRequestEvent</code>:</p>
-<table>
+<table class="table">
<thead>
<tr>
<th>events types (<code>SlingRequestEvent.EventType</code>)</th>
Modified: websites/staging/sling/trunk/content/documentation/the-sling-engine/request-parameters.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/request-parameters.html (original)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/request-parameters.html Tue Sep 22 10:23:16 2015
@@ -18,11 +18,11 @@
limitations under the License.
-->
<head>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Apache Sling - Request Parameter Handling in Sling</title>
<link rel="icon" href="/res/favicon.ico">
<link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
<link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
- <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
</head>
<body>
<div class="title">
@@ -39,7 +39,18 @@
</div>
<div class="menu">
- <p><strong><a href="/documentation.html">Documentation</a></strong> <br />
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<p><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 />
@@ -90,9 +101,20 @@
<h1>Request Parameter Handling in Sling</h1>
- <h2 id="servlet-api">Servlet API</h2>
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<h2 id="servlet-api">Servlet API<a class="headerlink" href="#servlet-api" title="Permanent link">¶</a></h2>
<p>The Servlet API specification provides the following methods to access the parameters of a request</p>
-<table>
+<table class="table">
<thead>
<tr>
<th>Method</th>
@@ -123,9 +145,9 @@
</tbody>
</table>
<p>As a special restriction only two kinds of parameters are supported: (1) Query String parameters and (2) parameters contained in the request data of content type <code>application/x-www-form-encoded</code>. That is file uploads using request data of type <code>multipart/form-data</code> are not directly supported by the servlet specification. Finally 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 id="sling-api">Sling API</h2>
+<h2 id="sling-api">Sling API<a class="headerlink" href="#sling-api" title="Permanent link">¶</a></h2>
<p>To overcome these 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>
+<table class="table">
<thead>
<tr>
<th>Type</th>
@@ -148,7 +170,7 @@
</tbody>
</table>
<p>To accomodate this new interface as well as to provide easy access in the traditional way the <code>SlingHttpServletRequest</code> interface adds following methods to the standard Servlet API parameter access methods:</p>
-<table>
+<table class="table">
<thead>
<tr>
<th>Method</th>
@@ -177,7 +199,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>
-<h2 id="character-encoding">Character Encoding</h2>
+<h2 id="character-encoding">Character Encoding<a class="headerlink" href="#character-encoding" title="Permanent link">¶</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>
Modified: websites/staging/sling/trunk/content/documentation/the-sling-engine/resources.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/resources.html (original)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/resources.html Tue Sep 22 10:23:16 2015
@@ -18,11 +18,11 @@
limitations under the License.
-->
<head>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Apache Sling - Resources</title>
<link rel="icon" href="/res/favicon.ico">
<link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
<link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
- <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
</head>
<body>
<div class="title">
@@ -39,7 +39,18 @@
</div>
<div class="menu">
- <p><strong><a href="/documentation.html">Documentation</a></strong> <br />
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<p><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 />
@@ -90,7 +101,18 @@
<h1>Resources</h1>
- <div class="toc">
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<div class="toc">
<ul>
<li><a href="#what-is-a-resource">What is a Resource</a><ul>
<li><a href="#resource-properties">Resource Properties</a></li>
@@ -116,11 +138,11 @@
<li><a href="#wrapdecorate-resources">Wrap/Decorate Resources</a></li>
</ul>
</div>
-<h2 id="what-is-a-resource">What is a Resource</h2>
+<h2 id="what-is-a-resource">What is a Resource<a class="headerlink" href="#what-is-a-resource" title="Permanent link">¶</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 id="resource-properties">Resource Properties</h3>
+<h3 id="resource-properties">Resource Properties<a class="headerlink" href="#resource-properties" title="Permanent link">¶</a></h3>
<p>Resources have a number of essentiall properties:</p>
-<table>
+<table class="table">
<thead>
<tr>
<th>Property</th>
@@ -155,10 +177,10 @@
</tbody>
</table>
<p>For a complete description of the <code>Resource</code> interface, please refer to the <a href="http://sling.apache.org/apidocs/sling6/org/apache/sling/api/resource/Resource.html" title="Resource">link text</a> JavaDoc.</p>
-<h3 id="resource-types">Resource Types</h3>
+<h3 id="resource-types">Resource Types<a class="headerlink" href="#resource-types" title="Permanent link">¶</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>
+<table class="table">
<thead>
<tr>
<th>Provider</th>
@@ -190,10 +212,10 @@ implementations provided by Sling, the a
</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 id="adapters">Adapters</h3>
+<h3 id="adapters">Adapters<a class="headerlink" href="#adapters" title="Permanent link">¶</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/sling6/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 id="how-to-get-a-resource">How to get a Resource</h2>
+<h2 id="how-to-get-a-resource">How to get a Resource<a class="headerlink" href="#how-to-get-a-resource" title="Permanent link">¶</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>
@@ -201,7 +223,7 @@ implementations provided by Sling, the a
<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 id="absolute-path-mapping">Absolute Path Mapping</h3>
+<h3 id="absolute-path-mapping">Absolute Path Mapping<a class="headerlink" href="#absolute-path-mapping" title="Permanent link">¶</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>
@@ -215,11 +237,11 @@ and <code>getResource(Resource base, Str
<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>
<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>
-<h3 id="relative-path-resolution">Relative Path Resolution</h3>
+<h3 id="relative-path-resolution">Relative Path Resolution<a class="headerlink" href="#relative-path-resolution" title="Permanent link">¶</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 <em>[</em> <code>*/apps{*}{</code>}<em>,</em> <code>*/libs{*</code>} <em>]()</em> 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 id="querying-resources">Querying Resources</h3>
+<h3 id="querying-resources">Querying Resources<a class="headerlink" href="#querying-resources" title="Permanent link">¶</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>
@@ -228,7 +250,7 @@ and <code>getResource(Resource base, Str
</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 id="providing-resources">Providing Resources</h2>
+<h2 id="providing-resources">Providing Resources<a class="headerlink" href="#providing-resources" title="Permanent link">¶</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>
@@ -238,25 +260,25 @@ and <code>getResource(Resource base, Str
<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 id="jcr-based-resources">JCR-based Resources</h3>
+<h3 id="jcr-based-resources">JCR-based Resources<a class="headerlink" href="#jcr-based-resources" title="Permanent link">¶</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 id="bundle-based-resources">Bundle-based Resources</h3>
+<h3 id="bundle-based-resources">Bundle-based Resources<a class="headerlink" href="#bundle-based-resources" title="Permanent link">¶</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 id="servlet-resources">Servlet Resources</h3>
+<h3 id="servlet-resources">Servlet Resources<a class="headerlink" href="#servlet-resources" title="Permanent link">¶</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 id="file-system-resources">File System Resources</h3>
+<h3 id="file-system-resources">File System Resources<a class="headerlink" href="#file-system-resources" title="Permanent link">¶</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 id="custom-resource-providers">Custom Resource providers</h3>
+<h3 id="custom-resource-providers">Custom Resource providers<a class="headerlink" href="#custom-resource-providers" title="Permanent link">¶</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="http://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 id="writeable-resources">Writeable Resources</h2>
+<h2 id="writeable-resources">Writeable Resources<a class="headerlink" href="#writeable-resources" title="Permanent link">¶</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.</p>
-<h2 id="wrapdecorate-resources">Wrap/Decorate Resources</h2>
+<h2 id="wrapdecorate-resources">Wrap/Decorate Resources<a class="headerlink" href="#wrapdecorate-resources" title="Permanent link">¶</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>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
Rev. 1624417 by fmeschbe on Thu, 11 Sep 2014 22:50:12 +0000
Modified: websites/staging/sling/trunk/content/documentation/the-sling-engine/service-authentication.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/service-authentication.html (original)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/service-authentication.html Tue Sep 22 10:23:16 2015
@@ -18,11 +18,11 @@
limitations under the License.
-->
<head>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Apache Sling - Service Authentication</title>
<link rel="icon" href="/res/favicon.ico">
<link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
<link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
- <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
</head>
<body>
<div class="title">
@@ -39,7 +39,18 @@
</div>
<div class="menu">
- <p><strong><a href="/documentation.html">Documentation</a></strong> <br />
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<p><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 />
@@ -90,7 +101,18 @@
<h1>Service Authentication</h1>
- <div class="toc">
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<div class="toc">
<ul>
<li><a href="#problem">Problem</a></li>
<li><a href="#concept">Concept</a><ul>
@@ -107,7 +129,7 @@
<li><a href="#deprecation-of-administrative-authentication">Deprecation of administrative authentication</a></li>
</ul>
</div>
-<h2 id="problem">Problem</h2>
+<h2 id="problem">Problem<a class="headerlink" href="#problem" title="Permanent link">¶</a></h2>
<p>To access the data storage in the Resource Tree and/or the JCR Repository
authentication is required to properly setup access control and guard
sensitive data from unauthorized access. For regular request processing
@@ -131,7 +153,7 @@ configured for service level access (as
<li>Allow administrators to configure the assignment of service users to
services</li>
</ul>
-<h2 id="concept">Concept</h2>
+<h2 id="concept">Concept<a class="headerlink" href="#concept" title="Permanent link">¶</a></h2>
<p>A <em>Service</em> is a piece or collection of functionality. Examples of services
are the Sling queuing system, Tenant Administration, or some Message Transfer
System. Each service is identified by a unique <em>Service Name</em>. Since a
@@ -151,13 +173,13 @@ a Resource Resolver and/or JCR Repositor
</td></tr></table>
<p>The <code>service-name</code> is the symbolic name of the bundle providing the service.</p>
-<h3 id="example-tenant-administration">Example: Tenant Administration</h3>
+<h3 id="example-tenant-administration">Example: Tenant Administration<a class="headerlink" href="#example-tenant-administration" title="Permanent link">¶</a></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>
-<h3 id="example-mail-transfer-system">Example: Mail Transfer System</h3>
+<h3 id="example-mail-transfer-system">Example: Mail Transfer System<a class="headerlink" href="#example-mail-transfer-system" title="Permanent link">¶</a></h3>
<p>Consider a Mail Transfer System which may be comprised of the following
sub systems:</p>
<ul>
@@ -173,10 +195,10 @@ would be consituting the <code>mta</code
<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>
-<h2 id="implementation">Implementation</h2>
+<h2 id="implementation">Implementation<a class="headerlink" href="#implementation" title="Permanent link">¶</a></h2>
<p>The implementation in Sling of the <em>Service Authentication</em> concept
described above consists of three parts:</p>
-<h3 id="serviceusermapper"><code>ServiceUserMapper</code></h3>
+<h3 id="serviceusermapper"><code>ServiceUserMapper</code><a class="headerlink" href="#serviceusermapper" title="Permanent link">¶</a></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>
@@ -187,7 +209,7 @@ such that system administrators are in f
</pre></div>
</td></tr></table>
-<h3 id="resourceresolverfactory"><code>ResourceResolverFactory</code></h3>
+<h3 id="resourceresolverfactory"><code>ResourceResolverFactory</code><a class="headerlink" href="#resourceresolverfactory" title="Permanent link">¶</a></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>
@@ -206,7 +228,7 @@ be used by services, the <code>ResourceP
with support for Service Authentication: Now new API is required, though
but additional properties are defined to convey the service to authenticate
for.</p>
-<h3 id="slingrepository"><code>SlingRepository</code></h3>
+<h3 id="slingrepository"><code>SlingRepository</code><a class="headerlink" href="#slingrepository" title="Permanent link">¶</a></h3>
<p>The third part is an extension to the <code>SlingRepository</code>service interface
to support JCR Repository access for services:</p>
<table class="codehilitetable"><tr><td class="linenos"><div class="linenodiv"><pre>1
@@ -219,7 +241,7 @@ to support JCR Repository access for ser
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 id="deprecation-of-administrative-authentication">Deprecation of administrative authentication</h2>
+<h2 id="deprecation-of-administrative-authentication">Deprecation of administrative authentication<a class="headerlink" href="#deprecation-of-administrative-authentication" title="Permanent link">¶</a></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
Modified: websites/staging/sling/trunk/content/documentation/the-sling-engine/servlets.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/servlets.html (original)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/servlets.html Tue Sep 22 10:23:16 2015
@@ -18,11 +18,11 @@
limitations under the License.
-->
<head>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Apache Sling - Servlets and Scripts</title>
<link rel="icon" href="/res/favicon.ico">
<link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
<link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
- <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
</head>
<body>
<div class="title">
@@ -39,7 +39,18 @@
</div>
<div class="menu">
- <p><strong><a href="/documentation.html">Documentation</a></strong> <br />
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<p><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 />
@@ -90,7 +101,18 @@
<h1>Servlets and Scripts</h1>
- <div class="toc">
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<div class="toc">
<ul>
<li><a href="#servlet-registration">Servlet Registration</a><ul>
<li><a href="#registering-a-servlet-using-java-annotations">Registering a Servlet using Java Annotations</a></li>
@@ -108,9 +130,9 @@
</div>
<p>See also <a href="/documentation/the-sling-engine/url-to-script-resolution.html">URL to Script Resolution</a> which explains how Sling maps URLs
to a script or and servlet.</p>
-<h2 id="servlet-registration">Servlet Registration</h2>
+<h2 id="servlet-registration">Servlet Registration<a class="headerlink" href="#servlet-registration" title="Permanent link">¶</a></h2>
<p>Servlets can be registered as OSGi services. The following service reference properties are defined for Servlets defined as OSGi services of type <code>javax.servlet.Servlet</code>:</p>
-<table>
+<table class="table">
<thead>
<tr>
<th>Name</th>
@@ -148,7 +170,7 @@ to a script or and servlet.</p>
<p>For a Servlet registered as an OSGi service to be used by the Sling Servlet Resolver, either or both of the <code>sling.servlet.paths</code> or the <code>sling.servlet.resourceTypes</code> service reference properties must be set. If neither is set, the Servlet service is ignored.</p>
<p>Each path to be used for registration - either from the <code>sling.servlet.paths</code> property or constructed from the other <code>sling.servlet.\*</code> properties - must be absolute. Any relative path is made absolute by prefixing it with a root path. This prefix may be set with the <code>sling.servlet.prefix</code> service registration property. If this property is not set, the first entry in the <code>ResourceResolver</code> search path for the <code>ResourceResolver.getResource(String)</code> method is used as the prefix. If this entry cannot be derived, a simpe slash - <code>/</code> - is used as the prefix.</p>
<p>If <code>sling.servlet.methods</code> is not specified, the servlet is only registered for handling GET requests. Make sure to list all methods you want to be handled by this servlet.</p>
-<h4 id="registering-a-servlet-using-java-annotations">Registering a Servlet using Java Annotations</h4>
+<h4 id="registering-a-servlet-using-java-annotations">Registering a Servlet using Java Annotations<a class="headerlink" href="#registering-a-servlet-using-java-annotations" title="Permanent link">¶</a></h4>
<p>If you are working with the default Apache Sling development stack you can use Java Annotations from <a href="http://felix.apache.org/documentation/subprojects/apache-felix-maven-scr-plugin.html">Apache Felix Maven SCR Plugin</a> to register your Sling
servlets and describe their binding details.</p>
<p>There are two ways of doing this, either with a Sling-specific @SlingServlet annotation or with the more generic maven-scr-plugin annotations:</p>
@@ -193,11 +215,11 @@ servlets and describe their binding deta
</li>
</ol>
-<h3 id="automated-tests">Automated tests</h3>
+<h3 id="automated-tests">Automated tests<a class="headerlink" href="#automated-tests" title="Permanent link">¶</a></h3>
<p>The <a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/">launchpad/test-services</a> module contains test servlets that use various combinations of the above properties.</p>
<p>The <a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/">launchpad/integration-tests</a> module contains a number of tests (like the [ExtensionServletTest|http://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/servlets/resolution/ExtensionServletTest.java] for example) that verify the results.</p>
<p>Such tests run as part of our continuous integration process, to demonstrate and verify the behavior of the various servlet registration mechanisms, in a way that's guaranteed to be in sync with the actual Sling core code. If you have an idea for additional tests, make sure to let us know!</p>
-<h3 id="example-registration-by-path">Example: Registration by Path</h3>
+<h3 id="example-registration-by-path">Example: Registration by Path<a class="headerlink" href="#example-registration-by-path" title="Permanent link">¶</a></h3>
<div class="codehilite"><pre><span class="n">sling</span><span class="p">.</span><span class="n">servlet</span><span class="p">.</span><span class="n">paths</span> <span class="p">=</span> <span class="o">\</span><span class="p">[</span> "<span class="o">/</span><span class="n">libs</span><span class="o">/</span><span class="n">sling</span><span class="o">/</span><span class="n">sample</span><span class="o">/</span><span class="n">html</span>"<span class="p">,</span> "<span class="o">/</span><span class="n">libs</span><span class="o">/</span><span class="n">sling</span><span class="o">/</span><span class="n">sample</span><span class="o">/</span><span class="n">txt</span>" <span class="o">\</span><span class="p">]</span>
<span class="n">sling</span><span class="p">.</span><span class="n">servlet</span><span class="p">.</span><span class="n">resourceTypes</span> <span class="p">=</span> <span class="o">\</span><span class="p">[</span> "<span class="n">sling</span><span class="o">/</span><span class="n">unused</span>" <span class="o">\</span><span class="p">]</span>
<span class="n">sling</span><span class="p">.</span><span class="n">servlet</span><span class="p">.</span><span class="n">selectors</span> <span class="p">=</span> <span class="o">\</span><span class="p">[</span> "<span class="n">img</span>" <span class="o">\</span><span class="p">]</span>
@@ -211,7 +233,7 @@ servlets and describe their binding deta
<li><code>/libs/sling/sample/txt</code></li>
</ul>
<p>The registration properties <code>sling.servlet.resourceTypes</code>, <code>sling.servlet.selectors</code> and <code>sling.servlet.extensions</code> <em>are ignored</em> because the <code>sling.servlet.paths</code> property is set.</p>
-<h3 id="example-registration-by-resource-type-etc">Example: Registration by Resource Type etc.</h3>
+<h3 id="example-registration-by-resource-type-etc">Example: Registration by Resource Type etc.<a class="headerlink" href="#example-registration-by-resource-type-etc" title="Permanent link">¶</a></h3>
<div class="codehilite"><pre><span class="n">sling</span><span class="p">.</span><span class="n">servlet</span><span class="p">.</span><span class="n">resourceTypes</span> <span class="p">=</span> <span class="o">\</span><span class="p">[</span> "<span class="n">sling</span><span class="o">/</span><span class="n">unused</span>" <span class="o">\</span><span class="p">]</span>
<span class="n">sling</span><span class="p">.</span><span class="n">servlet</span><span class="p">.</span><span class="n">selectors</span> <span class="p">=</span> <span class="o">\</span><span class="p">[</span> "<span class="n">img</span>"<span class="p">,</span> "<span class="n">tab</span>" <span class="o">\</span><span class="p">]</span>
<span class="n">sling</span><span class="p">.</span><span class="n">servlet</span><span class="p">.</span><span class="n">extensions</span> <span class="p">=</span> <span class="o">\</span><span class="p">[</span> "<span class="n">html</span>"<span class="p">,</span> "<span class="n">txt</span>"<span class="p">,</span> "<span class="n">json</span>" <span class="o">\</span><span class="p">]</span>
@@ -228,7 +250,7 @@ servlets and describe their binding deta
<li><code>{*}prefix*/sling/unused/tab/json</code></li>
</ul>
<p>As explained the Servlet is registered for each permutation of the resource types, selectors and extension. See above For an explanation of how <code>{*}prefix{*</code>} is defined.</p>
-<h3 id="servlet-lifecycle-issues">Servlet Lifecycle Issues</h3>
+<h3 id="servlet-lifecycle-issues">Servlet Lifecycle Issues<a class="headerlink" href="#servlet-lifecycle-issues" title="Permanent link">¶</a></h3>
<p>The Servlet API specification states the following with respect to the life
cycle of Servlets:</p>
<blockquote>
@@ -247,11 +269,11 @@ once in the life time of the Servlet obj
<p>The provider of the Servlet service on the other can cope with this
situation by making sure to drop the servlet instance once it is destroyed.
The mechanism helping the provider here is the OSGi Service Factory.</p>
-<h2 id="scripts-are-servlets">Scripts are Servlets</h2>
+<h2 id="scripts-are-servlets">Scripts are Servlets<a class="headerlink" href="#scripts-are-servlets" title="Permanent link">¶</a></h2>
<p>The Sling API defines a <code>SlingScript</code> interface which is used to represent (executable) scripts inside of Sling. This interface is implemented in the <code>scripting/core</code> bundle in the <code>DefaultSlingScript</code> class which also implements the <code>javax.servlet.Servlet</code>.</p>
<p>To further simplify the access to scripts from the Resource tree, the <code>scripting/core</code> bundle registers an <code>AdapterFactory</code> to adapt Resources to Scripts and Servlets (the <code>SlingScriptAdapterFactory</code>). In fact the adapter factory returns instances of the <code>DefaultSlingScript</code> class for both Scripts and Servlets.</p>
<p>From the perspective of the Servlet resolver, scripts and servlets are handled exactly the same. In fact, internally, Sling only handles with Servlets, whereas scripts are packed inside a Servlet wrapping and representing the script.</p>
-<h2 id="default-servlets">Default Servlet(s)</h2>
+<h2 id="default-servlets">Default Servlet(s)<a class="headerlink" href="#default-servlets" title="Permanent link">¶</a></h2>
<p>As explained in the Resolution Process section above, a default Servlet is selected if no servlet (or script) for the current resource type can be found. To make the provisioning of a default Servlet as versatile as provisioning per resource type Servlets (or scripts), the default Servlet is selected with just a special resource type <code>sling/servlet/default</code>.</p>
<p>The actual Servlet or Script called as the default Servlet is resolved exactly the same way as for any resource type. That is, also for the default Servlet selection, the request selectors and extension or method are considered. Also, the Servlet may be a Servlet registered as an OSGi service or it may be a Script stored in the repository or provided by any bundle.</p>
<p>Finally, if not even a registered default Servlet may be resolved for the request, because none has been registered, the <code>servlets/resolver</code> bundle provides a fall back the <code>DefaultServlet</code> with the following functionality:</p>
@@ -259,11 +281,11 @@ The mechanism helping the provider here
<li>If an <code>NonExistingResource</code> was created for the request the <code>DefaultServlet</code> sends a 404 (Not Found)</li>
<li>Otherwise the <code>DefaultServlet</code> sends a 500 (Internal Server Error), because normally at least a <code>NonExistingResource</code> should be created</li>
</ul>
-<h2 id="optingservlet-interface">OptingServlet interface</h2>
+<h2 id="optingservlet-interface">OptingServlet interface<a class="headerlink" href="#optingservlet-interface" title="Permanent link">¶</a></h2>
<p>If a registered servlet implements the OptingServlet interface, Sling uses that servlet's <code>accepts(SlingHttpServletRequest request)</code> method to refine the servlet resolution process.</p>
<p>In this case, the servlet is only selected for processing the current request if its <code>accept</code> method returns true.</p>
<p>While an opting servlet seems to be a nice way of picking the right servlet to process the request, the use of an opting servlet is not recommended: the main reason is that it complicates the request processing, makes it less transparent what is going on during a request and prevents optimizations like caching the script resolution in an optimal manner. The other static options are usually sufficient for all use cases.</p>
-<h2 id="error-handler-servlets-or-scripts">Error Handler Servlet(s) or Scripts</h2>
+<h2 id="error-handler-servlets-or-scripts">Error Handler Servlet(s) or Scripts<a class="headerlink" href="#error-handler-servlets-or-scripts" title="Permanent link">¶</a></h2>
<p>Error handling support is now described on the <a href="/documentation/the-sling-engine/errorhandling.html">Errorhandling</a> page.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
Rev. 1678488 by cziegeler on Sat, 9 May 2015 12:43:11 +0000
Modified: websites/staging/sling/trunk/content/documentation/the-sling-engine/sling-api-crud-support.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/sling-api-crud-support.html (original)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/sling-api-crud-support.html Tue Sep 22 10:23:16 2015
@@ -18,11 +18,11 @@
limitations under the License.
-->
<head>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Apache Sling - Sling API CRUD Support</title>
<link rel="icon" href="/res/favicon.ico">
<link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
<link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
- <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
</head>
<body>
<div class="title">
@@ -39,7 +39,18 @@
</div>
<div class="menu">
- <p><strong><a href="/documentation.html">Documentation</a></strong> <br />
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<p><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 />
@@ -90,7 +101,18 @@
<h1>Sling API CRUD Support</h1>
- <div class="toc">
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<div class="toc">
<ul>
<li><a href="#apache-sling-api-support">Apache Sling API Support</a></li>
<li><a href="#comparing-sling-api-crud-to-sling-post-servlet">Comparing Sling API CRUD to Sling Post Servlet</a><ul>
@@ -106,7 +128,7 @@
<li><a href="#value-class-support">Value Class Support</a></li>
</ul>
</div>
-<h2 id="apache-sling-api-support">Apache Sling API Support</h2>
+<h2 id="apache-sling-api-support">Apache Sling API Support<a class="headerlink" href="#apache-sling-api-support" title="Permanent link">¶</a></h2>
<p>As of version 2.3.0, the Sling API provides full Create Read Update Delete (CRUD) features. CRUD support is provided by the addition of the following methods to the ResourceResolver:</p>
<ul>
<li><a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#delete-org.apache.sling.api.resource.Resource-">void delete(Resource resource) throws PersistenceException</a></li>
@@ -117,9 +139,9 @@
<li><a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#refresh--">void refresh()</a></li>
</ul>
<p>Which provide the ability to create and delete resources as well as the addition of the ModifiableValueMap interface which is similar to the ValueMap interface, but allows for updating properties on a resource.</p>
-<h2 id="comparing-sling-api-crud-to-sling-post-servlet">Comparing Sling API CRUD to Sling Post Servlet</h2>
+<h2 id="comparing-sling-api-crud-to-sling-post-servlet">Comparing Sling API CRUD to Sling Post Servlet<a class="headerlink" href="#comparing-sling-api-crud-to-sling-post-servlet" title="Permanent link">¶</a></h2>
<p>Here are some examples of common operations performed using the Sling Post Servlet and Sling API CRUD support. Note, the examples are derived from the <a href="http://dev.day.com/content/ddc/blog/2008/07/cheatsheet/_jcr_content/images/cheatsheet/back.png">SlingPostServlet Cheatsheet</a>.</p>
-<h3 id="updating-a-property">Updating a Property</h3>
+<h3 id="updating-a-property">Updating a Property<a class="headerlink" href="#updating-a-property" title="Permanent link">¶</a></h3>
<p>Update /myresource, setting the title and body:</p>
<p><strong>Sling Post Servlet</strong></p>
<div class="codehilite"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/myresource"</span> <span class="na">method=</span><span class="s">"POST"</span><span class="nt">></span>
@@ -138,7 +160,7 @@
</pre></div>
-<h3 id="create-new-resource">Create New Resource</h3>
+<h3 id="create-new-resource">Create New Resource<a class="headerlink" href="#create-new-resource" title="Permanent link">¶</a></h3>
<p>Create a new resource below /myresource</p>
<p><strong>Sling Post Servlet</strong></p>
<div class="codehilite"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/myresource/"</span> <span class="na">method=</span><span class="s">"POST"</span><span class="nt">></span>
@@ -157,7 +179,7 @@
</pre></div>
-<h3 id="remove-a-property">Remove a Property</h3>
+<h3 id="remove-a-property">Remove a Property<a class="headerlink" href="#remove-a-property" title="Permanent link">¶</a></h3>
<p>Remove the property title</p>
<p><strong>Sling Post Servlet</strong></p>
<div class="codehilite"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/myresource"</span> <span class="na">method=</span><span class="s">"POST"</span><span class="nt">></span>
@@ -174,7 +196,7 @@
</pre></div>
-<h3 id="copy-a-resource">Copy a Resource</h3>
+<h3 id="copy-a-resource">Copy a Resource<a class="headerlink" href="#copy-a-resource" title="Permanent link">¶</a></h3>
<p>Copy the resource /myresource to /myresource2</p>
<p><strong>Sling Post Servlet</strong></p>
<div class="codehilite"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/myresource"</span> <span class="na">method=</span><span class="s">"POST"</span><span class="nt">></span>
@@ -192,7 +214,7 @@
</pre></div>
-<h3 id="move-a-resource">Move a Resource</h3>
+<h3 id="move-a-resource">Move a Resource<a class="headerlink" href="#move-a-resource" title="Permanent link">¶</a></h3>
<p>Move the resource /myresource2 to /myresource3</p>
<p><strong>Sling Post Servlet</strong></p>
<div class="codehilite"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/myresource2"</span> <span class="na">method=</span><span class="s">"POST"</span><span class="nt">></span>
@@ -211,7 +233,7 @@
</pre></div>
-<h3 id="setting-non-string-value">Setting non-String Value</h3>
+<h3 id="setting-non-string-value">Setting non-String Value<a class="headerlink" href="#setting-non-string-value" title="Permanent link">¶</a></h3>
<p>Set the property date to a particular date</p>
<p><strong>Sling Post Servlet</strong></p>
<div class="codehilite"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/myresource3"</span> <span class="na">method=</span><span class="s">"POST"</span><span class="nt">></span>
@@ -230,7 +252,7 @@
</pre></div>
-<h3 id="delete-a-resource">Delete a Resource</h3>
+<h3 id="delete-a-resource">Delete a Resource<a class="headerlink" href="#delete-a-resource" title="Permanent link">¶</a></h3>
<p>Delete the resource /myresource</p>
<p><strong>Sling Post Servlet</strong></p>
<div class="codehilite"><pre><span class="nt"><form</span> <span class="na">action=</span><span class="s">"/myresource"</span> <span class="na">method=</span><span class="s">"POST"</span><span class="nt">></span>
@@ -246,7 +268,7 @@
</pre></div>
-<h2 id="value-class-support">Value Class Support</h2>
+<h2 id="value-class-support">Value Class Support<a class="headerlink" href="#value-class-support" title="Permanent link">¶</a></h2>
<div class="info">
Please note, this information is specific to the Sling JCR Resource implementation provided by the Apache Sling project. Other implementations may have different value class support.
</div>
Modified: websites/staging/sling/trunk/content/documentation/the-sling-engine/sling-properties.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/sling-properties.html (original)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/sling-properties.html Tue Sep 22 10:23:16 2015
@@ -18,11 +18,11 @@
limitations under the License.
-->
<head>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Apache Sling - Well-known Sling Properties</title>
<link rel="icon" href="/res/favicon.ico">
<link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
<link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
- <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
</head>
<body>
<div class="title">
@@ -39,7 +39,18 @@
</div>
<div class="menu">
- <p><strong><a href="/documentation.html">Documentation</a></strong> <br />
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<p><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 />
@@ -90,7 +101,18 @@
<h1>Well-known Sling Properties</h1>
- <p>This table lists properties which have known functionality in the OSGi and Sling frameworks.</p>
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<p>This table lists properties which have known functionality in the OSGi and Sling frameworks.</p>
<p>With the exception of the Sling setup properties (<code>sling.home</code>, <code>sling.launchpad</code>, and <code>sling.properties</code>) all properties can be set on the command line using the <code>-D</code> command line option or in the <code>sling.properties</code> file. Properties defined on the command line or in the <code>web.xml</code> file always overwrite properties in the <code>sling.properties</code> file.</p>
<div class="toc">
<ul>
@@ -100,8 +122,8 @@
<li><a href="#http-service-properties">Http Service Properties</a></li>
</ul>
</div>
-<h2 id="sling-setup-properties">Sling Setup Properties</h2>
-<table>
+<h2 id="sling-setup-properties">Sling Setup Properties<a class="headerlink" href="#sling-setup-properties" title="Permanent link">¶</a></h2>
+<table class="table">
<thead>
<tr>
<th>Property</th>
@@ -127,8 +149,8 @@
</tr>
</tbody>
</table>
-<h2 id="server-control-port-properties">Server Control Port Properties</h2>
-<table>
+<h2 id="server-control-port-properties">Server Control Port Properties<a class="headerlink" href="#server-control-port-properties" title="Permanent link">¶</a></h2>
+<table class="table">
<thead>
<tr>
<th>Property</th>
@@ -149,9 +171,9 @@
</tr>
</tbody>
</table>
-<h2 id="logging-configuration">Logging Configuration</h2>
+<h2 id="logging-configuration">Logging Configuration<a class="headerlink" href="#logging-configuration" title="Permanent link">¶</a></h2>
<p>Logging configuration defined by these properties sets up initial configuration for the Sling Commons Log bundle. This configuration is used as long as there is no configuration from the Configuration Admin Service for the service PID <code>org.apache.sling.commons.log.LogManager</code>.</p>
-<table>
+<table class="table">
<thead>
<tr>
<th>Property</th>
@@ -193,8 +215,8 @@
</tbody>
</table>
<p>See <a href="http://sling.apache.org/site/logging.html">Logging</a> for full information on configuring the Sling Logging system.</p>
-<h2 id="http-service-properties">Http Service Properties</h2>
-<table>
+<h2 id="http-service-properties">Http Service Properties<a class="headerlink" href="#http-service-properties" title="Permanent link">¶</a></h2>
+<table class="table">
<thead>
<tr>
<th>Property</th>