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 2012/05/22 11:41:27 UTC
svn commit: r818667 [13/18] - in /websites/staging/sling/trunk/content: ./
authentication/ documentation/ documentation/bundles/
documentation/development/ documentation/getting-started/
documentation/the-sling-engine/ documentation/the-sling-engine/au...
Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/request-parameters.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/request-parameters.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/request-parameters.html Tue May 22 09:41:22 2012
@@ -0,0 +1,135 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - Request Parameter Handling in Sling</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/the-sling-engine.html">The Sling Engine</a>
+ </div>
+ <h1>Request Parameter Handling in Sling</h1>
+ <h2 id="servlet-api">Servlet API</h2>
+<p>The Servlet API specification provides the following methods to access the parameters of a request</p>
+<p>| <code>HttpServletRequest.getQueryString()</code> | Returns the query part of the request URL |
+| <code>ServletRequest.getParameter(String)</code> | Returns the (first) named parameter |
+| <code>ServletRequest.getParameterValues(String)</code> | Returns all parameters of that name |
+| <code>ServletRequest.getParameterMap()</code> | Returns all parameters as a map of <code>String[]()</code> |
+| <code>ServletRequest.getParameterNames()</code> | Returns an enumeration of the names of the parameters |</p>
+<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>
+<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>
+<p>| Raw Content | Byte array and <code>InputStream</code> representation of the request parameter values. You will generally use the <code>InputStream</code> to handle uploaded files. |
+| String Content | Access the values as strings is some given encoding (see below) or by requesting the conversion using an explicit encoding. |
+| File Uploads | Find out whether a parameter is a file upload, get the size in bytes of the parameter value and client side file name as sent by the browser. |</p>
+<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>
+<p>| <code>getRequestParameter(String)</code> | Returns the (first) named parameter as a <code>RequestParameter</code> instance |
+| <code>getRequestParameters(String)</code> | Returns the named parameter as an array of <code>RequestParameter</code> instances |
+| <code>getRequestParameterMap()</code> | Returns <code>RequestParameterMap</code> being a map of <code>RequestParameter</code> arrays indexed by parameter names |</p>
+<p>All parameters are handled the same, that is all methods give access to the same parameters regardless of whether the parameters were transmitted in the request query, as part of form encoded data or as part of a <code>multipart/form-data</code> request.</p>
+<p>As of Sling Engine 2.1.0 the order or request parameters in the <code>getRequestParameterMap()</code>, <code>getParameterMap()</code>, and <code>getParameterNams()</code> is preserved as follows:</p>
+<ul>
+<li>The first entries are the parameters reported by the servlet container. The order of these parameters amongst each other is not defined. The <code>SlingHttpServletRequest</code> provides them in the same order as provided by the servlet container.</li>
+<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="">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>
+<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>
+<li>All forms should be sent with <em>UTF-8</em> character encoding</li>
+</ul>
+<p>The first rule is essential as it helps decoding the form input correctly. The second rule is not actually a very hard requirement but to enable support for all (or most) character sets used, using <em>UTF-8</em> is one of the best choices anyway.</p>
+<p>When Sling is now receiving a request and is asked for the parameters, the parameters are parsed in two phases: The first phase just parses the raw input data using an identity transformation of bytes to characters. This identity transformation happens to generate strings as the original data was generated with <code>ISO-8859-1</code> encoding. The second phase locates the <code>\*charset\*</code> parameter and fixes the character encodings of the parameters as follows:</p>
+<ul>
+<li>All names of the parameters are re-encoded</li>
+<li>The parameter values are re-encoded, unless the parameter value is an uploaded file. Actually the parameter (not the files of course) are internally as <code>byte[]()</code> where the conversion to a string is done on the fly (and yes, the conversion using the <code>\*charset\*</code> character encoding is of course cached for performance reasons)</li>
+<li>If the parameter is an uploaded file, the file name is re-encoded on the fly when accessed</li>
+</ul>
+<p>{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. 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 to the desired encoding, which of course must be supported by the actual Java Platform.
+{info}</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/resources.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/resources.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/resources.html Tue May 22 09:41:22 2012
@@ -0,0 +1,166 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - Resources</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/the-sling-engine.html">The Sling Engine</a>
+ </div>
+ <h1>Resources</h1>
+ <div class="toc">
+<ul>
+<li><a href="#what-is-a-resource">What is a Resource</a></li>
+<li><a href="#how-to-get-a-resource">How to get a Resource</a><ul>
+<li><a href="#absolute-path-mapping">Absolute Path Mapping</a></li>
+<li><a href="#relative-path-resolution">Relative Path Resolution</a></li>
+<li><a href="#querying-resources">Querying Resources</a></li>
+</ul>
+</li>
+<li><a href="#providing-resources">Providing Resources</a><ul>
+<li><a href="#jcr-based-resources">JCR-based Resources</a></li>
+<li><a href="#bundle-based-resources">Bundle-based Resources</a></li>
+<li><a href="#servlet-resources">Servlet Resources</a></li>
+<li><a href="#file-system-resources">File System Resources</a></li>
+</ul>
+</li>
+<li><a href="#wrapdecorate-resources">Wrap/Decorate Resources</a></li>
+</ul>
+</div>
+<h2 id="what-is-a-resource">What is a Resource</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>
+<h2 id="how-to-get-a-resource">How to get a Resource</h2>
+<p>To get at Resources, you need a <code>ResourceResolver</code>. This interface defines four kinds of methods to access resources:
+<em> 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.
+</em> Absolute or Relative Path Resolution (including search path): The <code>getResource(String path)</code> and <code>getResource(Resource base, String path)</code> methods may be used to access a resource with an absolute path directly. If it can't be found the path is assumed to be relative and the search path retrieved from <code>getSearchPath()</code> is used to retrieve the resource. This mechanism is similar to resolving a programm with the <code>PATH</code> environment variable in your favourite operating system.
+<em> 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.
+</em> 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</a> below.</p>
+<h3 id="absolute-path-mapping">Absolute Path Mapping</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:
+1. Call <code>HttpServletRequest.getScheme(), .getServerName(), getServerPort</code> to get an absolute path out of the request URL: [scheme]()/[host].[port][path] (<code>resolve(HttpServletRequest, String)</code> method only, which)
+1. Check whether any virtual path matches the absolute path. If such a match exists, the next step is entered with the match.
+1. 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.
+1. If no mapping created a mapped path addressing an existing Resource, the method fails and returns:</p>
+<ul>
+<li>The <code>resolve(String)</code> and <code>resolve(HttpServletRequest,String)</code> methods return a <code>NonExistingResource</code></li>
+<li>The <code>getResource(String path)</code> and <code>getResource(Resource base, String path)</code> methods return null</li>
+</ul>
+<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>
+<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>
+<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:
+<em> <code>findResources</code> returns an <code>Iteratory<Resource></code> of all Resources matching the query. This method is comparable to calling <code>getNodes()</code> on the <code>QueryResult</code> returned from executing the JCR query.
+</em> <code>queryResources</code> returns an <code>Iterator<Map<String, Object>></code>. Each entry in the iterator is a <code>Map<String, Object</code> representing a JCR result <code>Row</code> in the <code>RowIterator</code> returned from executing the JCR query. The map is indexed by the column name and the value of each entry is the value of the named column as a Java Object.</p>
+<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>
+<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:
+<em> JCR Resource provider as <code>/</code>
+</em> Resource provider R1 as <code>/some</code>
+* Resource provider R2 as <code>/some/path</code></p>
+<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>
+<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>
+<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. For details see <a href="">Bundle Resource.</a></p>
+<h3 id="servlet-resources">Servlet Resources</h3>
+<p>Servlet Resources are registered by the Servlet Resolver bundle for Servlets registered as OSGi services. See <a href="">Servlet Resolution</a> for information on how Servlet Resources are provided.</p>
+<h3 id="file-system-resources">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. For details see <a href="">File System Resources</a>.</p>
+<h2 id="wrapdecorate-resources">Wrap/Decorate Resources</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. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/servlets.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/servlets.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/servlets.html Tue May 22 09:41:22 2012
@@ -0,0 +1,195 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - Servlets and Scripts</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/the-sling-engine.html">The Sling Engine</a>
+ </div>
+ <h1>Servlets and Scripts</h1>
+ <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>
+<thead>
+<tr>
+<th>Name</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>sling.servlet.paths</code></td>
+<td>A list of absolute paths under which the servlet is accessible as a Resource. The property value must either be a single String, an array of Strings or a Vector of Strings.</td>
+</tr>
+<tr>
+<td>A servlet using this property might be ignored unless its path is included in the <em>Execution Paths</em> (<code>servletresolver.paths</code>) configuration setting of the <code>SlingServletResolver</code> service.</td>
+<td></td>
+</tr>
+<tr>
+<td>Creating a resource at the desired path, with a resource type that maps to a servlet, provides the same result in most cases while taking advantage of more Sling built-in features.</td>
+<td></td>
+</tr>
+<tr>
+<td><code>sling.servlet.resourceTypes</code></td>
+<td>The resource type(s) supported by the servlet. The property value must either be a single String, an array of Strings or a Vector of Strings. This property is ignored if the <code>sling.servlet.paths</code> property is set.</td>
+</tr>
+<tr>
+<td><code>sling.servlet.selectors</code></td>
+<td>The request URL selectors supported by the servlet. The selectors must be configured as they would be specified in the URL that is as a list of dot-separated strings such as <em>print.a4</em>. The property value must either be a single String, an array of Strings or a Vector of Strings. This property is ignored if the <code>sling.servlet.paths</code> property is set.</td>
+</tr>
+<tr>
+<td><code>sling.servlet.extensions</code></td>
+<td>The request URL extensions supported by the servlet for requests. The property value must either be a single String, an array of Strings or a Vector of Strings. This property is ignored if the <code>sling.servlet.paths</code> property is set.</td>
+</tr>
+<tr>
+<td><code>sling.servlet.methods</code></td>
+<td>The request methods supported by the servlet. The property value must either be a single String, an array of Strings or a Vector of Strings. This property is ignored if the <code>sling.servlet.paths</code> property is set. If this property is missing, the value defaults to GET, regardless of which methods are actually implemented/handled by the servlet.</td>
+</tr>
+<tr>
+<td><code>sling.servlet.prefix</code></td>
+<td>The prefix or numeric index to make relative paths absolute. If the value of this property is a number (int), it defines the index of the search path entries from the resource resolver to be used as the prefix. The defined search path is used as a prefix to mount this servlet. The number can be -1 which always points to the last search entry. If the specified value is higher than than the highest index of the search paths, the last entry is used. The index starts with 0. If the value of this property is a string and parseable as a number, the value is treated as if it would be a number. If the value of this property is a string starting with "/", this value is applied as a prefix, regardless of the configured search paths! If the value is anything else, it is ignored. If this property is not specified, it defaults to the default configuration of the sling servlet resolver.</td>
+</tr>
+</tbody>
+</table>
+<p>A <code>SlingServletResolver</code> listens for <code>Servlet{</code>}services and - given the correct service registration properties - provides the servlets as resources in the (virtual) resource tree. Such servlets are provided as <code>ServletResource</code> instances which adapt to the <code>javax.servlet.Servlet</code> class.</p>
+<p>For a Servlet registered as an OSGi service to be used by the Sling Servlet Resolver, the 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>
+<h3 id="automated-tests">Automated tests</h3>
+<p>The <a href="">launchpad/test-services</a> module contains test servlets that use various combinations of the above properties. </p>
+<p>The <a href="">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>
+<div class="codehilite"><pre><span class="n">sling</span><span class="o">.</span><span class="n">servlet</span><span class="o">.</span><span class="n">paths</span> <span class="o">=</span> <span class="o">\</span><span class="p">[</span> <span class="s">"/libs/sling/sample/html"</span><span class="p">,</span> <span class="s">"/libs/sling/sample/txt"</span> <span class="o">\</span><span class="p">]</span>
+<span class="n">sling</span><span class="o">.</span><span class="n">servlet</span><span class="o">.</span><span class="n">resourceTypes</span> <span class="o">=</span> <span class="o">\</span><span class="p">[</span> <span class="s">"sling/unused"</span> <span class="o">\</span><span class="p">]</span>
+<span class="n">sling</span><span class="o">.</span><span class="n">servlet</span><span class="o">.</span><span class="n">selectors</span> <span class="o">=</span> <span class="o">\</span><span class="p">[</span> <span class="s">"img"</span> <span class="o">\</span><span class="p">]</span>
+<span class="n">sling</span><span class="o">.</span><span class="n">servlet</span><span class="o">.</span><span class="n">extensions</span> <span class="o">=</span> <span class="o">\</span><span class="p">[</span> <span class="s">"html"</span><span class="p">,</span> <span class="s">"txt"</span><span class="p">,</span> <span class="s">"json"</span> <span class="o">\</span><span class="p">]</span>
+</pre></div>
+
+
+<p>A Servlet service registered with these properties is registered under the following paths:</p>
+<ul>
+<li><code>/libs/sling/sample/html</code></li>
+<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>
+<div class="codehilite"><pre><span class="n">sling</span><span class="o">.</span><span class="n">servlet</span><span class="o">.</span><span class="n">resourceTypes</span> <span class="o">=</span> <span class="o">\</span><span class="p">[</span> <span class="s">"sling/unused"</span> <span class="o">\</span><span class="p">]</span>
+<span class="n">sling</span><span class="o">.</span><span class="n">servlet</span><span class="o">.</span><span class="n">selectors</span> <span class="o">=</span> <span class="o">\</span><span class="p">[</span> <span class="s">"img"</span><span class="p">,</span> <span class="s">"tab"</span> <span class="o">\</span><span class="p">]</span>
+<span class="n">sling</span><span class="o">.</span><span class="n">servlet</span><span class="o">.</span><span class="n">extensions</span> <span class="o">=</span> <span class="o">\</span><span class="p">[</span> <span class="s">"html"</span><span class="p">,</span> <span class="s">"txt"</span><span class="p">,</span> <span class="s">"json"</span> <span class="o">\</span><span class="p">]</span>
+</pre></div>
+
+
+<p>A Servlet service registered with these properties is registered under the following paths:</p>
+<ul>
+<li><code>{*}prefix*/sling/unused/img/html</code></li>
+<li><code>{*}prefix*/sling/unused/img/txt</code></li>
+<li><code>{*}prefix*/sling/unused/img/json</code></li>
+<li><code>{*}prefix*/sling/unused/tab/html</code></li>
+<li><code>{*}prefix*/sling/unused/tab/txt</code></li>
+<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>
+<h2 id="scripts-are-servlets">Scripts are Servlets</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></h2>
+<h2 id="default-servlets">Default Servlet(s)</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>
+<ul>
+<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>
+<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>
+<h2 id="error-handler-servlets-or-scripts">Error Handler Servlet(s) or Scripts</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. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/sling-properties.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/sling-properties.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/sling-properties.html Tue May 22 09:41:22 2012
@@ -0,0 +1,225 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - Well-known Sling Properties</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/the-sling-engine.html">The Sling Engine</a>
+ </div>
+ <h1>Well-known Sling Properties</h1>
+ <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>
+<li><a href="#sling-setup-properties">Sling Setup Properties</a></li>
+<li><a href="#server-control-port-properties">Server Control Port Properties</a></li>
+<li><a href="#logging-configuration">Logging Configuration</a></li>
+<li><a href="#http-service-properties">Http Service Properties</a></li>
+</ul>
+</div>
+<h2 id="sling-setup-properties">Sling Setup Properties</h2>
+<table>
+<thead>
+<tr>
+<th>Property</th>
+<th>Default Value</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>sling.home</code></td>
+<td><code>sling</code></td>
+<td>Path to the main Sling Directory; relative path is resolved against current working directory as defined in the <code>user.dir</code> system property. Can also be set with the <code>-c</code> command line option.</td>
+</tr>
+<tr>
+<td><code>sling.launchpad</code></td>
+<td><code>${sling.home}</code></td>
+<td>Location for the Sling launchpad JAR file and the startup folder containing bundles to be installed by the Bootstrap Installer. Can also be set with the <code>-i</code> command line option.</td>
+</tr>
+<tr>
+<td><code>sling.properties</code></td>
+<td><code>${sling.home}/sling.properties</code></td>
+<td>Path to the <code>sling.properties</code> file; relative path is resolved against <code>${sling.home}</code></td>
+</tr>
+</tbody>
+</table>
+<h2 id="server-control-port-properties">Server Control Port Properties</h2>
+<table>
+<thead>
+<tr>
+<th>Property</th>
+<th>Default Value</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>sling.control.socket</code></td>
+<td><code>127.0.0.1:0</code></td>
+<td>Specification of the control port. Can also be set with the <code>-j</code> command line option. This property is only used by the Standalone Sling Application.</td>
+</tr>
+<tr>
+<td><code>sling.control.action</code></td>
+<td>--</td>
+<td>Action to execute. This is the same as specifying <code>start</code>, <code>status</code>, or <code>stop</code> on the command line. This property is only used by the Standalone Sling Application.</td>
+</tr>
+</tbody>
+</table>
+<h2 id="logging-configuration">Logging Configuration</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>
+<thead>
+<tr>
+<th>Property</th>
+<th>Default Value</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>org.apache.sling.commons.log.level</code></td>
+<td><code>INFO</code></td>
+<td>Sets the initial logging level of the root logger. This may be any of the defined logging levels <code>DEBUG</code>, <code>INFO</code>, <code>WARN</code>, or <code>ERROR</code>. This property can also be set with the <code>-l</code> command line option.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.commons.log.file</code></td>
+<td><code>${sling.home}/logs/error.log</code></td>
+<td>Sets the log file to which log messages are written. If this property is empty or missing, log messages are written to System.out. This property can also be set with the <code>-f</code> command line option.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.commons.log.file.number</code></td>
+<td><code>5</code></td>
+<td>The number of rotated files to keep.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.commons.log.file.size</code></td>
+<td><code>'.'yyyy-MM-dd</code></td>
+<td>Defines how the log file is rotated (by schedule or by size) and when to rotate. See the section <a href="http://sling.apache.org/site/logging.html#Logging-LogFileRotation">Log File Rotation</a> for full details on log file rotation.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.commons.log.pattern</code></td>
+<td><code>{0,date,dd.MM.yyyy HH:mm:ss.SSS} *{4}* [{2}] {3} {5}</code></td>
+<td>The MessageFormat pattern to use for formatting log messages with the root logger.</td>
+</tr>
+<tr>
+<td>org.apache.sling.commons.log.julenabled</td>
+<td><code>false</code></td>
+<td>Enables the java.util.logging support.</td>
+</tr>
+</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>
+<thead>
+<tr>
+<th>Property</th>
+<th>Default Value</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>org.apache.felix.http.context_path</code></td>
+<td><code>/</code></td>
+<td>The servlet context path for the Http Service of the embedded servlet container. This property requires support by the Http Service bundle.</td>
+</tr>
+<tr>
+<td><code>org.apache.felix.http.host</code></td>
+<td><code>0.0.0.0</code></td>
+<td>The host interface to bind the HTTP Server to. This property requires support by the Http Service bundle.</td>
+</tr>
+<tr>
+<td><code>org.osgi.service.http.port</code></td>
+<td>8080</td>
+<td>The port to listen on for HTTP requests. This property requires support by the Http Service bundle.</td>
+</tr>
+</tbody>
+</table>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1340579 by fmeschbe on Sat, 19 May 2012 22:10:45 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/the-sling-launchpad.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/the-sling-launchpad.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/the-sling-launchpad.html Tue May 22 09:41:22 2012
@@ -0,0 +1,350 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - The Sling Launchpad</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/the-sling-engine.html">The Sling Engine</a>
+ </div>
+ <h1>The Sling Launchpad</h1>
+ <div class="toc">
+<ul>
+<li><a href="#sling-home">Sling Home</a></li>
+<li><a href="#command-line-options">Command Line Options</a><ul>
+<li><a href="#control-port">Control Port</a></li>
+</ul>
+</li>
+<li><a href="#servlet-parameters">Servlet Parameters</a></li>
+<li><a href="#slingproperties">sling.properties</a></li>
+<li><a href="#components">Components</a><ul>
+<li><a href="#launchpad-base">Launchpad Base</a></li>
+<li><a href="#launchpad-bundles">Launchpad Bundles</a></li>
+<li><a href="#launchpad-app-and-launchpad-webapp">Launchpad App and Launchpad WebApp</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<p>This tries to explain how exactly the Sling Launchpad works, what constitutes the Sling Launchpad and how you can use the Sling Launchpad to custom create you Sling launchers. For a view behind the scenes of the Sling Launchpad Base module (the actual launcher) you might want to refer to the <a href="/documentation/development/embedding-sling.html">Embedding Sling</a> page.</p>
+<h2 id="sling-home">Sling Home</h2>
+<p>Since Sling requires some space on the filesystem to store various files Sling has to know where this filesystem space is located.</p>
+<p>The following is a list of uses for the Sling Home directory:</p>
+<ul>
+<li><code>sling.properties</code> -- The main configuration file used by Sling to launch the framework. It mainly contains OSGi framework configuration and initial configuration for some bundles. This file is read on each startup of <em>Launcher JAR</em>. That is, changes to this file require a restart of the <em>Launcher JAR</em>.</li>
+<li><code>org.apache.sling.launchpad.base.jar</code> -- This is the <em>Launcher JAR</em> file used by the Standalone Application or the Web Application to start the OSGi Framework. This file is initially placed when first starting Sling and may later be updated by updating the system bundle with a new <em>Launcher JAR</em>.</li>
+<li><code>felix</code> -- The directory into which the Apache Felix Framework places the bundles, which have been installed into the system. This does generally not need to be touched.</li>
+<li><code>config</code> -- The directory into which the Apache Felix Configuration Admin Service stores the configurationes. Do not change any files in this directory, since changes will not generally be picked up.</li>
+<li><code>jackrabbit</code> -- The directory in which the Apache Jackrabbit JCR repository is started. Amongst other things this also contains the Jackrabbit configuration file <code>repository.xml</code>. You may modify this file, but don't forget to restart the Embedded Jackrabbit Repository bundle after doing this.</li>
+<li><code>logs</code> -- Contains the log files generated by Sling. By default this contains the error.log and its rotated generations.</li>
+</ul>
+<h2 id="command-line-options">Command Line Options</h2>
+<p>The Java Standalone Application supports a number of command line options, which influence the operation of the launch process.</p>
+<table>
+<thead>
+<tr>
+<th>Option</th>
+<th>Argument</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>start</code></td>
+<td>--</td>
+<td>Open a TCP/IP server socket when starting Sling. Uses option <code>-j</code> to define the local socket address.</td>
+</tr>
+<tr>
+<td><code>status</code></td>
+<td>--</td>
+<td>Check whether a (remote) Sling application is running. Uses option <code>-j</code> to define the address of the Sling instance to check. Note, that the Sling application terminates after checking for the (remote) Sling status.</td>
+</tr>
+<tr>
+<td><code>stop</code></td>
+<td>--</td>
+<td>Stop a (remote) Sling application is running. Uses option <code>-j</code> to define the address of the Sling instance to stop. Note, that the Sling application terminates after stopping the (remote) Sling instance.</td>
+</tr>
+<tr>
+<td><code>-j</code></td>
+<td><a href=""> host ":" </a> port</td>
+<td>The socket address to listen on for control connections (<code>start</code> or to use as the remote endpoint for the control connection (<code>status</code> and <code>stop</code>. If this parameter has no arguments or is not specified, the address defaults to any free port on localhost/127.0.0.1. If only the port is specified localhost/127.0.0.1 is used as the host part of the address.</td>
+</tr>
+<tr>
+<td><code>-c</code></td>
+<td>slinghome</td>
+<td>The directory in which Sling locates its initial configuration file <code>sling.properties</code> and where files of Sling itself such as the Apache Felix bundle archive or the JCR repository files are stored. This defaults to the <code>sling</code> folder in the current working directory. This is the value which is commonly refered to as <code>$\{sling.home}.</code></td>
+</tr>
+<tr>
+<td><code>-i</code></td>
+<td>launchpadhome</td>
+<td>The launchpad directory. If not set, this is the same as <code>$\{sling.home}.</code> (since Sling Launchpad 2.4.0)</td>
+</tr>
+<tr>
+<td><code>-l</code></td>
+<td>loglevel</td>
+<td>Sets the initial loglevel as an integer in the range 0 to 4 or as one of the well known level strings <code>ERROR</code>, <code>WARN</code>, <code>INFO</code>, or <code>DEBUG</code>. This option overwrites the <code>org.apache.sling.osg.log.level</code> setting the <code>sling.properties</code> file. The default is <code>INFO</code>.</td>
+</tr>
+<tr>
+<td><code>-f</code></td>
+<td>logfile</td>
+<td>The log file to use or <code>-</code> to log to standard out. This option overwrites the <code>org.apache.sling.osg.log.file</code> setting in the <code>sling.properties</code> file. The default is <code>$\{sling.home}/logs/error.log</code>.</td>
+</tr>
+<tr>
+<td><code>-a</code></td>
+<td>address</td>
+<td>The interfact to bind to (use 0.0.0.0 for any). This option overwrites the <code>org.apache.felix.http.host</code> setting in the <code>sling.properties</code> file and requires the embedded Http Service implementation to honor this property. (supported since Sling Launchpad 2.4.0)</td>
+</tr>
+<tr>
+<td><code>-p</code></td>
+<td>port</td>
+<td>The port to listen (default 8080) to handle HTTP requests. This option overwrites the <code>org.osgi.service.http.port</code> setting in the <code>sling.properties</code> file.</td>
+</tr>
+<tr>
+<td><code>-r</code></td>
+<td>path</td>
+<td>The root servlet context path for the Http Service (default is /). This option overwrites the <code>org.apache.felix.http.context_path</code> setting in the <code>sling.properties</code> file and requires the embedded Http Service implementation to honor this property. (since Sling Launchpad 2.4.0)</td>
+</tr>
+<tr>
+<td><code>-D</code></td>
+<td>n=v</td>
+<td>Sets the property <code>n</code> to the value <code>v</code>. This option can be added repeatedly setting additional properties. Any property set in this manner overwrites same named properties in the <code>sling.properties</code> file. (since Sling Launchpad 2.4.0)</td>
+</tr>
+<tr>
+<td><code>-h</code></td>
+<td>--</td>
+<td>Prints a simple usage message listing all available command line options.</td>
+</tr>
+</tbody>
+</table>
+<p>The Sling Standalone application looks for a definition of the <code>sling.home</code> setting in the following locations in order of precendence:</p>
+<ol>
+<li>The <code>-c</code> command line option</li>
+<li>The <code>sling.home</code> system property</li>
+<li>The <code>SLING_HOME</code> environment variable</li>
+<li>If none of the above resolves to a non-null value, the default value of <code>sling</code> is assumed</li>
+</ol>
+<h3 id="control-port">Control Port</h3>
+<p>When starting the Sling Standalone Application with the <code>start</code> command line option, a TCP port is opened. The interface and port is configurable with the <code>-j</code> command line option. The address of the interface and the actual port used are written to the <code>$\{sling.home}/conf/controlport</code> file. So technically the <code>-j</code> option is not required for the <code>status</code> and <code>stop</code> operations because the port information is just read from this file.</p>
+<p>Note that using a control connection for the Sling Standalone Application presents a potential security issue. For this reason the following defaults apply:</p>
+<ul>
+<li>The server side socket for a running Sling Standalone Application is only created if the application is started with the <code>start</code> command line option. If this option is omitted -- the default -- the server side socket is not created and the Sling Standalone Application instance cannot be remotely controlled.</li>
+<li>The default host name for the socket is localhost/127.0.0.1 meaning that the socket is only accessible from the same system as the Sling Standalone Application is running on.</li>
+<li>In addition to the IP address and port on which the control port is listening a nonce is written to the <code>controlport</code> file. Any interaction with the server on the control port must include this none.</li>
+</ul>
+<p>Suggestions:
+<em> Do not allow the control port to be opened on an externally visible interface. Using the localhost/127.0.0.1 is just sufficient.
+</em> Make sure only legitimate users have access to the installation folder of Sling (<code>$\{sling.home})</code>.</p>
+<h2 id="servlet-parameters">Servlet Parameters</h2>
+<p>The Web Application does not require specific servlet parameters. Those which are specified are used to overwrite any properties with the same name from the <code>sling.properties</code> file. One exception to this rule is the <code>sling.home</code> parameter, which is used to set the value of the <code>sling.home</code> property. If no parameter with this name is defined the Sling home directory is derived from the context path at which the Sling Web Application is registered.</p>
+<p>The <code>sling.home</code> folders for Sling Web Applications without the <code>sling.home</code> servlet parameter are all located in the <code>sling</code> folder in the current working directory as reported by the <code>user.dir</code> system property. The name of the actual directory is derived from the Web Application Context Path by replacing all slash characters <code>/</code> by underscore characters <code>\*</code>. For the root context a single underscore character <code>\*</code> is used.</p>
+<p>Examples:</p>
+<table>
+<thead>
+<tr>
+<th>Servlet Context</th>
+<th>Default <code>sling.home</code></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><em>root</em></td>
+<td><code>sling/\_</code></td>
+</tr>
+<tr>
+<td><code>/sling</code></td>
+<td><code>sling/\_sling</code></td>
+</tr>
+<tr>
+<td><code>/sling/instance1</code></td>
+<td><code>sling/\*sling\*instance1</code></td>
+</tr>
+</tbody>
+</table>
+<p>Starting with Launchpad Base 2.2.2 the fixed prefix <code>sling</code> is configurable with the <code>sling.home.prefix</code> system property. If this property is set the value used as the prefix.</p>
+<p>Examples: Assume the <code>sling.home.prefix</code> system property is set to <code>/var/sling</code></p>
+<table>
+<thead>
+<tr>
+<th>Servlet Context</th>
+<th>Default <code>sling.home</code></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><em>root</em></td>
+<td><code>/var/sling/\_</code></td>
+</tr>
+<tr>
+<td><code>/sling</code></td>
+<td><code>/var/sling/\_sling</code></td>
+</tr>
+<tr>
+<td><code>/sling/instance1</code></td>
+<td><code>/var/sling/\*sling\*instance1</code></td>
+</tr>
+</tbody>
+</table>
+<h2 id="slingproperties">sling.properties</h2>
+<p>The <code>sling.properties</code> file contains the initial setup of the Sling Application and the OSGi framework. Some of the parameters are required and should not be modified without a very good reason. Some parameters may be freely modified to your needs. Please see the inlined comment in the <code>sling.properties</code> file installed when Sling is first started.</p>
+<p>One thing to note is, that the <code>sling.properties</code> file is a simple Java Properties file with support for property references. That is, the value of properties may refer other property values by means of the well known <code>$\{name</code>} notation. Such property references may even be cascaded as in</p>
+<div class="codehilite"><pre>java.packages=<span class="cp">${</span><span class="n">jre</span><span class="o">-</span><span class="err">$</span><span class="p">{</span><span class="n">java</span><span class="o">.</span><span class="n">specification</span><span class="o">.</span><span class="n">version</span><span class="cp">}</span>}
+</pre></div>
+
+
+<h2 id="components">Components</h2>
+<p>The Sling Launchapd consists of <em>Launchbad Base</em> project and three additional projects which ultimately create a Standalone Java Application and a Web Appliction with standard parts of Sling.</p>
+<h3 id="launchpad-base">Launchpad Base</h3>
+<p>The <em>Launchpad Base</em> projects creates the following artifacts, which are required in actual setups to get a Sling application:</p>
+<ul>
+<li>
+<p><em>Launcher JAR</em> -- The primary artifact of the Base project contains the actual support to launch the Apache Felix OSGi Framework and install bundles, which are packaged with the application. It also contains the Apache Felix Framework together with the OSGi R4.1 Core and Compendium libraries as well as the Equinox HttpService bridge and the Servlet API.</p>
+</li>
+<li>
+<p><em>App JAR</em> -- The secondary artifact with classifier <em>app</em> is a minimal Standalone Java Application which may be started by simply typing</p>
+<p>$ java -jar org.apache.sling.launchpad.base-app.jar</p>
+</li>
+<li>
+<p><em>Web App Archive</em> -- The secondary artifact with classifier <em>webapp</em> is a minimal Web Application, which may simply be deployed into your favirourite servlet container, provided it supports at least Servlet API 2.4.</p>
+</li>
+<li>
+<p><em>Source JAR</em> -- The secondary artifact with the classifier <em>sources</em> is simple the source of the <em>Launchpad Base</em> project.</p>
+</li>
+</ul>
+<p>To build a very basic Sling launcher, the <em>Launchpad Base</em> is actually all you need. But to really glue this together and get a usable system, some more work is required. Lets see how the additionaly projects <em>Launchpad Bundles</em>, <em>Launchpad App</em>, and <em>Launchpad WebApp</em> get to that.</p>
+<h3 id="launchpad-bundles">Launchpad Bundles</h3>
+<p>The second project we want to look at is the <em>Launchpad Bundles</em> project. This is a very simple project in that it only collects together a number of OSGi bundles, which will make up the final application. The bundles are stored in a (big) Java Archive in folders whose path is formed with <code>resources/9</code> where <code>9</code> is a start level which is assigned to the bundles as they are installed. The special start level <code>0</code> instructs the installer to not actually assign a specific start level to the bundles contained in that folder.</p>
+<p>Currently the following start level assignement is used by the <em>Launchpad Bundles</em> project:</p>
+<table>
+<thead>
+<tr>
+<th>Start Level</th>
+<th>Bundle Group</th>
+<th>Bundle(s)</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>1</td>
+<td>Basic bundles required for the correct operation of Sling</td>
+<td>org.apache.sling.commons.log</td>
+</tr>
+<tr>
+<td>5</td>
+<td>Apache Felix Web Console</td>
+<td>org.apache.felix.bundlerepository, org.apache.felix.webconsole, org.apache.sling.extensions.threaddump</td>
+</tr>
+<tr>
+<td>10</td>
+<td>OSGi Compendium Service Implementations</td>
+<td>org.apache.felix.configadmin, org.apache.felix.eventadmin, org.apache.felix.metatype, org.apache.felix.scr</td>
+</tr>
+<tr>
+<td>15</td>
+<td>JCR Repository (Jackrabbit)</td>
+<td>commons-collections, commons-io-1.4.jar</td>
+</tr>
+<tr>
+<td>commons-lang, jackrabbit-api, jackrabbit-jcr-commons, org.apache.sling.commons.mime, org.apache.sling.commons.osgi, org.apache.sling.jcr.api, org.apache.sling.jcr.base, org.apache.sling.jcr.jackrabbit.server, org.apache.sling.jcr.webdav</td>
+<td></td>
+<td></td>
+</tr>
+<tr>
+<td>0</td>
+<td>Actual Sling Application bundles</td>
+<td>org.apache.sling.adapter, org.apache.sling.api, org.apache.sling.bundleresource.impl, org.apache.sling.commons.json, org.apache.sling.engine, org.apache.sling.extensions.apt.parser, org.apache.sling.extensions.apt.servlet, org.apache.sling.httpauth, org.apache.sling.jcr.classloader, org.apache.sling.jcr.contentloader, org.apache.sling.jcr.ocm, org.apache.sling.jcr.resource, org.apache.sling.launchpad.content, org.apache.sling.samples.path-based.rtp, org.apache.sling.scripting.api, org.apache.sling.scripting.core, org.apache.sling.scripting.javascript, org.apache.sling.scripting.jsp, org.apache.sling.scripting.jsp.taglib, org.apache.sling.servlets.get, org.apache.sling.servlets.post, org.apache.sling.servlets.resolver</td>
+</tr>
+</tbody>
+</table>
+<h3 id="launchpad-app-and-launchpad-webapp">Launchpad App and Launchpad WebApp</h3>
+<p>The <em>Launchpad App</em> and <em>Launchpad WebApp</em> bundles are actually projects which just glue together artifacts from the Launchpad projects. There is nothing special about them. Here's what is done:</p>
+<ul>
+<li>Take the appropriate secondary artifact from the <em>Launchpad Base</em> project: <em>app</em> for the Standalone Java Application or <em>webapp</em> for the Web Application and unpack</li>
+<li>Take the <em>Launchpad Base</em> primary artifact and place it under the name <code>org.apache.sling.launchpad.base.jar</code> into the <code>resources</code> folder</li>
+<li>Take the <em>Launchpad Bundles</em> artifact and unpack it</li>
+<li>Finally pack all together into a single big JAR or WAR file</li>
+</ul>
+<p>That's it. The resulting artifact may be directly used to launch the Standalone Java Application or may directly be deployed into any Servlet API 2.4 (or later) compliant servlet container.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/documentation/the-sling-engine/url-decomposition.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/the-sling-engine/url-decomposition.html (added)
+++ websites/staging/sling/trunk/content/documentation/the-sling-engine/url-decomposition.html Tue May 22 09:41:22 2012
@@ -0,0 +1,225 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - URL decomposition</title>
+ <link rel="stylesheet" href="/css/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/the-sling-engine.html">The Sling Engine</a>
+ </div>
+ <h1>URL decomposition</h1>
+ <p>During the <em>Resource Resolution</em> step, the client request URL is decomposed into the following parts:</p>
+<ol>
+<li><em>Resource Path</em> - The longest substring of the request URL such that the resource path is either the complete request URL or the next character in the request URL after the resource path is a dot (<code>.</code>).</li>
+<li><em>Selectors</em> - If the first character in the request URL after the resource path is a dot, the string after the dot up to but not including the last dot before the next slash character or the end of the request URL. If the resource path spans the complete request URL no seletors exist. If only one dot follows the resource path before the end of the request URL or the next slash, also no selectors exist.</li>
+<li><em>Extension</em> - The string after the last dot after the resource path in the request URL but before the end of the request URL or the next slash after the resource path in the request URL. </li>
+<li><em>Suffix Path</em> - If the request URL contains a slash character after the resource path and optional selectors and extension, the path starting with the slash up to the end of the request URL is the suffix path. Otherwise, the suffix path is empty. Note, that after the resource path at least a dot must be in the URL to let Sling detect the resource path.</li>
+</ol>
+<p>There's a cheat sheet on Day's dev page under <a href="">http://dev.day.com/content/docs/en/cq/current/developing/sling_cheatsheet.html</a> available to get you familiar with the URL decomposition of Sling.</p>
+<p><em>Examples</em>: Assume there is a Resource at <code>/a/b</code>, which has no children.</p>
+<table>
+<thead>
+<tr>
+<th>URI</th>
+<th>Resource Path</th>
+<th>Selectors</th>
+<th>Extension</th>
+<th>Suffix</th>
+<th>Resource Found</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>/a/b</td>
+<td>/a/b</td>
+<td>null</td>
+<td>null</td>
+<td>null</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>/a/b.html</td>
+<td>/a/b</td>
+<td>null</td>
+<td>html</td>
+<td>null</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>/a/b.s1.html</td>
+<td>/a/b</td>
+<td>s1</td>
+<td>html</td>
+<td>null</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>/a/b.s1.s2.html</td>
+<td>/a/b</td>
+<td>s1.s2</td>
+<td>html</td>
+<td>null</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>/a/b/c/d</td>
+<td>/a/b/c/d</td>
+<td>null</td>
+<td>null</td>
+<td>null</td>
+<td>no!</td>
+</tr>
+<tr>
+<td>/a/b./c/d</td>
+<td>/a/b</td>
+<td>null</td>
+<td>null</td>
+<td>/c/d</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>/a/b.html/c/d</td>
+<td>/a/b</td>
+<td>null</td>
+<td>html</td>
+<td>/c/d</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>/a/b.s1.html/c/d</td>
+<td>/a/b</td>
+<td>s1</td>
+<td>html</td>
+<td>/c/d</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>/a/b.s1.s2.html/c/d</td>
+<td>/a/b</td>
+<td>s1.s2</td>
+<td>html</td>
+<td>/c/d</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>/a/b/c/d.s.txt</td>
+<td>/a/b/c/d</td>
+<td>s</td>
+<td>txt</td>
+<td>null</td>
+<td>no!</td>
+</tr>
+<tr>
+<td>/a/b.html/c/d.s.txt</td>
+<td>/a/b</td>
+<td>null</td>
+<td>html</td>
+<td>/c/d.s.txt</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>/a/b.s1.html/c/d.s.txt</td>
+<td>/a/b</td>
+<td>s1</td>
+<td>html</td>
+<td>/c/d.s.txt</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>/a/b.s1.s2.html/c/d.s.txt</td>
+<td>/a/b</td>
+<td>s1.s2</td>
+<td>html</td>
+<td>/c/d.s.txt</td>
+<td>yes</td>
+</tr>
+</tbody>
+</table>
+<p>{info:title=Automated tests and examples}
+The <a href="">SlingRequestPathInfoTest</a> demonstrates and tests this decomposition. Feel free to suggest additional tests that help clarify how this works!
+{info}</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>