You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bd...@apache.org on 2017/06/19 12:41:42 UTC
[36/53] sling-site git commit: asf-site branch created for published
content
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/resources.html
----------------------------------------------------------------------
diff --git a/documentation/the-sling-engine/resources.html b/documentation/the-sling-engine/resources.html
new file mode 100644
index 0000000..425124b
--- /dev/null
+++ b/documentation/the-sling-engine/resources.html
@@ -0,0 +1,183 @@
+<!DOCTYPE html><html lang="en">
+ <head>
+<meta charset="utf-8"/>
+ <title>Apache Sling on JBake</title>
+ <link rel="stylesheet" href="/res/css/site.css"/>
+ <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ </a>
+ </div><div class="header">
+ <a href="http://www.apache.org">
+ <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ </a>
+ </div>
+ </div>
+ </head><body>
+<div class="menu">
+ <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html">Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a><br/><a href="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Resources</h1></header><p>[TOC]</p>
+<h2>What is a Resource</h2>
+<p>The Resource is one of the central parts of Sling. Extending from JCR's <em>Everything is Content</em>, Sling assumes <em>Everthing is a Resource</em>. Thus Sling is maintaining a virtual tree of resources, which is a merger of the actual contents in the JCR Repository and resources provided by so called resource providers. By doing this Sling fits very well in the paradigma of the REST architecture.</p>
+<h3>Resource Properties</h3>
+<p>Resources have a number of essentiall properties:</p>
+<table>
+ <thead>
+ <tr>
+ <th>Property </th>
+ <th>Description </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Path </td>
+ <td>Resources are part of a Resource Tree. As such each Resource has a path which is formed by concatenating the names of all Resources along the root to the Resource separated by a slash. Ok, really, this is much like a URL path or a file system path where the slash (<code>/</code>) is the separator character. </td>
+ </tr>
+ <tr>
+ <td>Name </td>
+ <td>The name of the Resource is the last element (or segment) in the path. </td>
+ </tr>
+ <tr>
+ <td>Resource Type </td>
+ <td>Each resource has a resource type which is used by the Servlet and Script resolver to find the appropriate Servlet or Script to handle the request for the Resource. </td>
+ </tr>
+ <tr>
+ <td>Resource Super Type </td>
+ <td>The (optional explicit) super type of the Resource. See the section <em>Resource Types</em> below for more details. </td>
+ </tr>
+ <tr>
+ <td>Adapters </td>
+ <td>Resources are always <code>Adaptable</code> and therefore can be adapted to a different view. See the section <em>Resource Adapters</em> below for more details. </td>
+ </tr>
+ <tr>
+ <td>Metadata </td>
+ <td>Resources in general support <a href="http://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/ResourceMetadata.html" title="ResourceMetadata">link text</a> providing access to values such as the length of a binary resource (which can be streamed) or the Resource's content type. </td>
+ </tr>
+ </tbody>
+</table>
+<p>For a complete description of the <code>Resource</code> interface, please refer to the <a href="http://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/Resource.html" title="Resource">link text</a> JavaDoc.</p>
+<h3>Resource Types</h3>
+<p>The exact method of setting the resource type for a Resource depends on the actual Resource Provider. For the four main Resource Provider implementations provided by Sling, the assignments are as follows:</p>
+<table>
+ <thead>
+ <tr>
+ <th>Provider </th>
+ <th>Resource Type </th>
+ <th>Resource Super Type </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>JCR </td>
+ <td>The value of the <code>sling:resourceType</code> property or the primary node type if the property is not set (a namespace separator colon is replaced by a slash, e.g. the <code>nt:file</code> primary node type is mapped to the <code>nt/file</code> resource type </td>
+ <td>The value of the <code>sling:resourceSuperType</code> of the Resource node or resource super type of the resource pointed to by the resource type (when accessed with <code>ResourceResolver.getResource(String)</code> </td>
+ </tr>
+ <tr>
+ <td>File System </td>
+ <td>File based resources are of type <code>nt/file</code>; folder based resources are of type <code>nt/folder</code> corresponding to the respective JCR primary node type </td>
+ <td>none </td>
+ </tr>
+ <tr>
+ <td>Bundle </td>
+ <td>File based resources are of type <code>nt/file</code>; folder based resources are of type <code>nt/folder</code> corresponding to the respective JCR primary node type </td>
+ <td>none </td>
+ </tr>
+ <tr>
+ <td>Servlet </td>
+ <td>The absolute path of the resource appended with the suffix <code>.servlet</code> </td>
+ <td><code>sling/bundle/resource</code> </td>
+ </tr>
+ </tbody>
+</table>
+<p>Resource Types form a type hierarchy much like Java classes form a type hierarchy. Each resource type has a resource super type, either explicitly defined as for example for JCR or Servlet Resources or implicitly. The implicit Resource Super Type is at the same time the root Resource Type much like the <code>java.lang.Object</code> class is called <code>sling/servlet/default</code> (for historical reasons). The <code>sling/servlet/default</code> Resource Type is the only type without a super type.</p>
+<h3>Adapters</h3>
+<p>The object types to which Resources may be adapted depend mostly depends on the Resource Provider providing the resource. For example all JCR node based resources always adapt to <code>javax.jcr.Node</code> objects.</p>
+<p>If the actual Resource object class implementation extends from the <code>SlingAdaptable</code> class, then in addition all <code>AdapterFactory</code> services adapting <code>Resource</code> objects are considered when trying to adapt the Resource. In general Resource Providers are recommended to have their Resource implementation extend from <a href="http://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/AbstractResource.html" title="AbstractResource">link text</a> which guarantees the Resource implementation to extend from <code>SlingAdaptable</code> and thus supporting Adapter Factories.</p>
+<h2>How to get a Resource</h2>
+<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>
+ <li>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.</li>
+ <li>Resource Enumeration: To enumerate resources and thus iterate the resource tree, the <code>listChildren(Resource)</code> method may be used. This method returns an <code>Iterator<Resource></code> listing all resources whose path prefix is the path of the given Resource. This method will of course also cross boundaries of registered <code>ResourceProvider</code> instances to enable iterating the complete resource tree.</li>
+ <li>Resource Querying: Querying resources is currently only supported for JCR Resources through the <code>findResources(String query, String language)</code> and <code>queryResources(String query, String language)</code> methods. For more information see the section on <a href="#querying-resources">Querying Resources</a> below.</li>
+</ul>
+<h3>Absolute Path Mapping</h3>
+<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>
+ <li>Call <code>HttpServletRequest.getScheme(), .getServerName(), getServerPort</code> to get an absolute path out of the request URL: [scheme]({{ refs.scheme.path }})/[host].[port][path] (<code>resolve(HttpServletRequest, String)</code> method only, which)</li>
+ <li>Check whether any virtual path matches the absolute path. If such a match exists, the next step is entered with the match.</li>
+ <li>Apply a list of mappings in order to create a mapped path. The first mapped path resolving to a Resource is assumed success and the Resource found is returned.</li>
+ <li>If no mapping created a mapped path addressing an existing Resource, the method fails and returns a <code>NonExistingResource</code> (for the <code>resolve(String)</code> and <code>resolve(HttpServletRequest,String)</code>) or null (for the <code>getResource(String path)</code> and <code>getResource(Resource base, String path)</code> methods).</li>
+</ol>
+<p>The virtual path mapping may be used to create shortcut URLs for otherwise long and complicated URLs. An example of such an URL might be the main administrative page of a CMS system. So, administrators may access the root of the web application and directed to the main administrative page.</p>
+<p>The path mapping functionality may be used to hide internal resource organization from the request URL space. For example to better control the structure of your repository, you might decide to store all accessible data inside a <code>/content</code> subtree. To hide this fact from the users, a mapping may be defined to prefix all incoming paths with <code>/content</code> to get at the actual Resource.</p>
+<p>The <code>map(String)</code> applies the path mapping algorithm in the reverse order. That is, first the path mappings are reversed and then any virtual mappings are checked. So, a path <code>/content/sample</code> might be mapped <code>/sample</code> to revers the <code>/content</code> prefixing. Or the main administrative page - say <code>/system/admin/main.html</code> - may be mapped to the virtual URL <code>/</code>.</p>
+<p>More details on mappings can be found at <a href="/documentation/the-sling-engine/mappings-for-resource-resolution.html">Mappings for Resource Resolution</a>.</p>
+<h3>Relative Path Resolution</h3>
+<p>Sometimes it is required to resolve relative paths to Resources. An example of such a use case is Script and Servlet resolution which starts with a relative path consisting of the Resource type, optional selectors and the request extension or method name. By scanning a search path for these relative paths a system provided Resource may be overwritten with some user defined implementation.</p>
+<p>Consider for example, the system would provide a Servlet to render Resources of type <code>nt:file</code>. This Servlet would be registered under the path <code>/libs/nt/file/html</code>. For a certain web application, this default HTML rendering might not be appropriate, so a Script is created as <code>/apps/nt/file/html.jsp</code> with a customized HTML rendering. By defining the search path to be <code>[/apps,/libs]</code> the Servlet resolver would call the <code>ResourceResolver.getResource(String)</code> method with the relative path <code>nt/file/html</code> and be provided with the first matching resource - <code>/apps/nt/file/html.jsp</code> in this example.</p>
+<p>Of course the search path is not used for absolute path arguments.</p>
+<h3>Querying Resources</h3>
+<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>
+ <li><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.</li>
+ <li><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.</li>
+</ul>
+<p>These methods are convenience methods to more easily post queries to the repository and to handle results in very straight forward way using only standard Java functionality.</p>
+<p>Please note, that Resource querying is currently only supported for repository based Resources. These query methods are not reflected in the <code>ResourceProvider</code> interface used to inject non-repository Resources into the Resource tree.</p>
+<h2>Providing Resources</h2>
+<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>
+<ul>
+ <li>JCR Resource provider as <code>/</code></li>
+ <li>Resource provider R1 as <code>/some</code></li>
+ <li>Resource provider R2 as <code>/some/path</code></li>
+</ul>
+<p>When accessing a Resource with path <code>/some/path/resource</code> the Resource provider <em>R2</em> is first asked. If that cannot provide the resource, Resource provider <em>R1</em> is asked and finally the JCR Resource provider is asked. The first Resource provider having a Resource with the requested path will be used.</p>
+<h3>JCR-based Resources</h3>
+<p>JCR-based Resources are provided with the default <code>JcrResourceProvider</code>. This Resource provider is always available and is always asked last. That is Resources provided by other Resource providers may never be overruled by repository based Resources.</p>
+<h3>Bundle-based Resources</h3>
+<p>Resources may by provided by OSGi bundles. Providing bundles have a Bundle manifest header <code>Sling-Bundle-Resources</code> containing a list of absolute paths provided by the bundle. The path are separated by comma or whitespace (SP, TAB, VTAB, CR, LF).</p>
+<p>The <code>BundleResourceProvider</code> supporting bundle-based Resources provides directories as Resources of type <code>nt:folder</code> and files as Resources of type <code>nt:file</code>. This matches the default primary node types intended to be used for directories and files in JCR repositories.</p>
+<p>For details see <a href="/documentation/bundles/bundle-resources-extensions-bundleresource.html">Bundle Resource.</a></p>
+<h3>Servlet Resources</h3>
+<p>Servlet Resources are registered by the Servlet Resolver bundle for Servlets registered as OSGi services. See <a href="/documentation/the-sling-engine/servlets.html">Servlet Resolution</a> for information on how Servlet Resources are provided.</p>
+<h3>File System Resources</h3>
+<p>The Filesystem Resource Provider provides access to the operating system's filesystem through the Sling ResourceResolver. Multiple locations may be mapped into the resource tree by configuring the filesystem location and the resource tree root path for each location to be mapped.</p>
+<p>For details see <a href="/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html">File System Resources</a>.</p>
+<h3>Merged Resources</h3>
+<p>The merged resource provider exposes a view on merged resources from multiple locations.</p>
+<p>For details see <a href="/documentation/bundles/resource-merger.html">Resource Merger</a>.</p>
+<h3>Custom Resource providers</h3>
+<p>Custom ResourceProvider services can be used to integrate your own custom resources in the Sling resource tree.</p>
+<p>For a simple example of that, see the <a href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/src/main/java/org/apache/sling/launchpad/testservices/resourceprovider/">PlanetResourceProvider</a> used in our integration tests.</p>
+<h2>Writeable Resources</h2>
+<p>Sling now supports full CRUD functionality on Resources, without necessarily having to go through the JCR API.</p>
+<p>The advantage is that this works for any ResourceProvider that supports the required operations.</p>
+<p>See the testSimpleCRUD method in <a href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/src/main/java/org/apache/sling/launchpad/testservices/serversidetests/WriteableResourcesTest.java">WriteableResourcesTest</a> for a basic example of how that works. More details can be found at <a href="/documentation/the-sling-engine/sling-api-crud-support.html">Sling API CRUD Support</a>.</p>
+<h2>Resource Observation</h2>
+<p>To be notified whenever certain resources or their properties have been modified/added/removed there are different possibilities</p>
+<h3>Resource Observation API (ResourceChangeListener)</h3>
+<p><em>This API is only available since Sling API 2.11.0 (<a href="https://issues.apache.org/jira/browse/SLING-4751">SLING-4751</a>).</em></p>
+<p>Register an OSGi service for <a href="https://svn.apache.org/repos/asf/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChangeListener.java"><code>org.apache.sling.api.resource.observation.ResourceChangeListener</code></a> or <a href="https://svn.apache.org/repos/asf/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ExternalResourceChangeListener.java"><code>org.apache.sling.api.resource.observation.ExternalResourceChangeListener</code></a> to be notified about changes. Certain properties can be used to restrict subscription to only a subset of events.</p>
+<h3>OSGi Event Admin</h3>
+<p>Resource events are sent out via the OSGi Event Admin. You can subscribe to those event by registering an OSGi service for <a href="https://osgi.org/javadoc/r6/cmpn/org/osgi/service/event/EventHandler.html"><code>org.osgi.service.event.EventHandler</code></a>. Several properties should be used to restrict the subscription to only the relevant event. The event topics which are used for resources are listed as constants in <a href="http://sling.apache.org/apidocs/sling8/org/apache/sling/api/SlingConstants.html"><code>org.apache.sling.api.SlingConstants</code></a> starting with the prefix <code>TOPIC_</code>.</p>
+<h2>Wrap/Decorate Resources</h2>
+<p>The Sling API provides an easy way to wrap or decorate a resource before returning. Details see <a href="/documentation/the-sling-engine/wrap-or-decorate-resources.html">Wrap or Decorate Resources</a>.</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </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>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/service-authentication.html
----------------------------------------------------------------------
diff --git a/documentation/the-sling-engine/service-authentication.html b/documentation/the-sling-engine/service-authentication.html
new file mode 100644
index 0000000..5e8b503
--- /dev/null
+++ b/documentation/the-sling-engine/service-authentication.html
@@ -0,0 +1,167 @@
+<!DOCTYPE html><html lang="en">
+ <head>
+<meta charset="utf-8"/>
+ <title>Apache Sling on JBake</title>
+ <link rel="stylesheet" href="/res/css/site.css"/>
+ <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ </a>
+ </div><div class="header">
+ <a href="http://www.apache.org">
+ <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ </a>
+ </div>
+ </div>
+ </head><body>
+<div class="menu">
+ <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html">Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a><br/><a href="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Service Authentication</h1></header><p>Excerpt: Introduce new service level authentication to replace <code>loginAdministrative</code></p>
+<p>[TOC]</p>
+<h2>Problem</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 this authentication step is handled by the Sling <a href="/documentation/the-sling-engine/authentication.html">{{ refs.authentication.headers.title }}</a> subsystem.</p>
+<p>On the other hand there are also some background tasks to be executed with access to the resources. Such tasks cannot in general be configured with user names and passwords: Neither hard coding the passwords in the code nor having the passwords in – more or less – plain text in some configuration is considered good practice.</p>
+<p>To solve this problem for services to identify themselves and authenticate with special users properly configured to support those services.</p>
+<p>The solution presented here serves the following goals:</p>
+<ul>
+ <li>Prevent over-use and abuse of administrative ResourceResolvers and/ro JCR Sessions</li>
+ <li>Allow services access to ResourceResolvers and/or JCR Sessions without requiring to hard-code or configure passwords</li>
+ <li>Allow services to use <em>service users</em> which have been specially configured for service level access (as is usually done on unixish systems)</li>
+ <li>Allow administrators to configure the assignment of service users to services</li>
+</ul>
+<h2>Concept</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 service will be implemented in an OSGi bundle (or a collection of OSGi bundles), services are named by the bundles providing them.</p>
+<p>A Service may be comprised of multiple parts, so each part of the service may be further identified by a <em>Subservice Name</em>. This Subservice Name is optional, though. Examples of <em>Subservice Name</em> are names for subsystems in a Message Transfer System such as accepting messages, queueing messages, delivering messages.</p>
+<p>Ultimately, the combination of the <em>Service Name</em> and <em>Subservice Name</em> defines the <em>Service ID</em>. It is the <em>Service ID</em> which is finally mapped to a Resource Resolver and/or JCR Repository user ID for authentication.</p>
+<p>Thus the actual service identification (service ID) is defined as:</p>
+<h1>!text</h1>
+<p>service-id = service-name [ ":" subservice-name ] .</p>
+<p>The <code>service-name</code> is the symbolic name of the bundle providing the service.</p>
+<h3>Example: Tenant Administration</h3>
+<p>Tenant Administration mostly deals with creating and managing groups and some other user administration tasks. Instead of just using an administrative session for Tenant administration this feature could define itself as being the <code>tenant-admin</code> service and leverage a properly configured Tenant Administration account.</p>
+<h3>Example: Mail Transfer System</h3>
+<p>Consider a Mail Transfer System which may be comprised of the following sub systems:</p>
+<ul>
+ <li>Accepting mail for processing — for example the SMTP server daemon</li>
+ <li>Queing and processing the messages</li>
+ <li>Delivering messages to mailboxes</li>
+</ul>
+<p>You could conceive that all these functions serve different purposes and thus should have different access rights to the repository to persist messages while they are being processed.</p>
+<p>Using the Service Authentication framework, the Mail Transfer System would be consituting the <code>mta</code> service. The sub systems would be called <code>smtp</code>, <code>queue</code>, and <code>deliver</code>.</p>
+<p>Thus the SMTP server daemon would be represented by a user for the <code>mta:smtp</code> Service. queueing with <code>mta:queue</code>, and delivery with <code>mta:deliver</code>.</p>
+<h2>Implementation</h2>
+<p>The implementation in Sling of the <em>Service Authentication</em> concept described above consists of three parts:</p>
+<h3><code>ServiceUserMapper</code></h3>
+<p>The first part is a new OSGi Service <code>ServiceUserMapper</code>. The <code>ServiceUserMapper</code> service allows for mapping <em>Service IDs</em> comprised of the <em>Service Names</em> defined by the providing bundles and optional <em>Subservice Name</em> to ResourceResolver and/or JCR Repository user IDs. This mapping is configurable such that system administrators are in full control of assigning users to services.</p>
+<p>The <code>ServiceUserMapper</code> defines the following API:</p>
+<h1>!java</h1>
+<p>String getServiceUserID(Bundle bundle, String subServiceName);</p>
+<p>The implementation uses two fallbacks in case no mapping can be found for the given subServiceName</p>
+<ol>
+ <li>Use user mapping for the serviceName only (not considering subServiceName)</li>
+ <li>Use default user (if one is configured).</li>
+</ol>
+<p>In addition a service named <code>ServiceUserMapped</code> is registered for each bundle and subservice name for which a service user mapping is configured (<a href="https://issues.apache.org/jira/browse/SLING-4312">SLING-4312</a>). By explicitly defining a (static) reference towards <code>ServiceUserMapped</code> one can defer starting the service until that service user mapping is available.</p>
+<h3><code>ResourceResolverFactory</code></h3>
+<p>The second part is support for service access to the Resource Tree. To this avail, the <code>ResourceResolverFactory</code> service is enhanced with a new factory method</p>
+<h1>!java</h1>
+<p>ResourceResolver getServiceResourceResolver(Map<String, Object> authenticationInfo) throws LoginException;</p>
+<p>This method allows for access to the resource tree for services where the service bundle is the bundle actually using the <code>ResourceResolverFactory</code> service. The optional Subservice Name may be provided as an entry in the <code>authenticationInfo</code> map.</p>
+<p>In addition to having new API on the <code>ResourceResolverFactory</code> service to be used by services, the <code>ResourceProviderFactory</code> service is updated with support for Service Authentication: Now new API is required, though but additional properties are defined to convey the service to authenticate for.</p>
+<p>The default implementation leverages <code>ServiceUserMapper.getServiceUserID()</code> to resolve the right user id and throws a <code>LoginException</code> in case no mapping has been setup (and none of the fallbacks returned a user id != <code>null</code> either).</p>
+<h3><code>SlingRepository</code></h3>
+<p>The third part is an extension to the <code>SlingRepository</code>service interface to support JCR Repository access for services:</p>
+<h1>!java</h1>
+<p>Session loginService(String subServiceName, String workspace) throws LoginException, RepositoryException;</p>
+<p>This method allows for access to the JCR Repository for services where the service bundle is the bundle actually using the <code>SlingRepository</code> service. The additional Subservice Name may be provided with the <code>subServiceName</code> parameter.</p>
+<h2>Configuration</h2>
+<h3>Service User Mappings</h3>
+<p>For each service/subservice name combination an according mapping needs to be provided. The mapping binds a service name/subservice name to a JCR system user. This is configured through an OSGi configuration for the factory configuration with PID <code>org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended</code> <a href="https://issues.apache.org/jira/browse/SLING-3578">SLING-3578</a>. There you can set one configuration property named <code>user.mapping</code> getting a String array as value where each entry must stick to the following format:</p>
+<p><service-name>[:<subservice-name>]=<authorizable id of a JCR system user>]</p>
+<p>The according user must exist at the point in time where <code>ResourceResolverFactory.getServiceResourceResolver(...)</code> or <code>SlingRepository.loginService(...)</code> is called. If you rely on one of those methods in your <code>activate</code> method of an OSGi component you should make sure that you defer starting your OSGi component until the according service user mapping is in place. For that you can reference the OSGi service <code>ServiceUserMapped</code> (<a href="https://issues.apache.org/jira/browse/SLING-4312">SLING-4312</a>), optionally with a target filter on property <code>subServiceName</code> (in case such a subservice name is used). The service <code>ServiceUserMapped</code> does not expose any methods but is only a marker interface exclusively used to defer starting of other OSGi components. However this waits only for the mapping configuration to be available, it does not wait for the service user itself to be available.</p>
+<p>Example OSGi DS Component</p>
+<p>:::java @Component( reference = { // this waits with the activation of this component until a service user mapping with the service name = current bundle's id and the sub service name 'my-subservice-name' is available. // you can leave out "target" if the sub service name is not used. // Please note that this only waits for the mapping to be available, it does not wait for the service user itself to be available! @Reference(name ="scriptsServiceUser", target="(subServiceName=my-subservice-name)", service=ServiceUserMapped.class) } ) class MyComponent { }</p>
+<p>There is a default mapping applied if no OSGi configuration is available for the mapping. The default is: "serviceuser--" + bundleId [ + "--" + subservice-name]. Please note, that these default mappings are not represented as a ServiceUserMapped service and therefore the above mentioned reference does not work.</p>
+<h2>Deprecation of administrative authentication</h2>
+<p>Originally the <code>ResourceResolverFactory.getAdministrativeResourceResolver</code> and <code>SlingRepository.loginAdministrative</code> methods have been defined to provide access to the resource tree and JCR Repository. These methods proved to be inappropriate because they allow for much too broad access.</p>
+<p>Consequently these methods are being deprecated and will be removed in future releases of the service implementations.</p>
+<p>The following methods are deprecated:</p>
+<ul>
+ <li><code>ResourceResolverFactory.getAdministrativeResourceResolver</code></li>
+ <li><code>ResourceProviderFactory.getAdministrativeResourceProvider</code></li>
+ <li><code>SlingRepository.loginAdministrative</code></li>
+</ul>
+<p>The implementations we have in Sling's bundle will remain implemented in the near future. But there will be a configuration switch to disable support for these methods: If the method is disabled, a <code>LoginException</code> is always thrown from these methods. The JavaDoc of the methods is extended with this information.</p>
+<h3>Whitelisting bundles for administrative login</h3>
+<p>In order to be able to manage few (hopefully legit) uses of the above deprecated methods, a whitelisting mechanism was introduced with <a href="https://issues.apache.org/jira/browse/SLING-5135">SLING-5153</a> (*JCR Base 2.4.2*).</p>
+<p>The recommended way to whitelist a bundle for administrative login is via a <em>whitelist fragment configuration</em>. It can be created as an OSGi factory configuration with the factoryPID <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment</code>. E.g. a typical configuration file might be called <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment-myapp.config</code> and could look as follows:</p>
+<p>whitelist.name="myapp" whitelist.bundles=[ "com.myapp.core", "com.myapp.commons" ]</p>
+<table>
+ <thead>
+ <tr>
+ <th>Property </th>
+ <th>Type </th>
+ <th>Default </th>
+ <th>Description </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>whitelist.name</code> </td>
+ <td>String </td>
+ <td><code>[unnamed]</code> </td>
+ <td>Purely informational property that allows easy identification of different fragments. </td>
+ </tr>
+ <tr>
+ <td><code>whitelist.bundles</code> </td>
+ <td>String[] </td>
+ <td>[] </td>
+ <td>An array of bundle symbolic names that should be allowed to make use of the administrative login functionality. </td>
+ </tr>
+ </tbody>
+</table>
+<p>All configured whitelist fragments are taken into account. This makes it easy to separate whitelists for different application layers and purposes.</p>
+<p>For example, some Sling bundles need to be whitelisted, which could be done in a whitelist fragment named <code>sling</code>. In addition <code>myapp</code> adds a whitelist fragment called <code>myapp</code>. For integration tests and additional whitelist fragment <code>myapp-integration-testing</code> may be added.</p>
+<p>Furthermore, there is a global configuration with PID <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist</code>, which should only be used in exceptional cases. It has a switch to turn administrative login on globally (<code>whitelist.bypass</code>) and it allows supplying a regular expression to whitelist matching bundle symbolic names (<code>whitelist.bundles.regexp</code>).</p>
+<p>The regular expression is most useful for running PaxExam based tests, where bundle symbolic names follow a set pattern but have randomly generated parts.</p>
+<p>Example: to whitelist all bundles generated by PaxExam a configuration file named <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist.config</code> might look as follows:</p>
+<p>whitelist.bypass=B"false" whitelist.bundles.regexp="^PAXEXAM.*$"</p>
+<p>The configuration PID is <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist</code>. It supports the following configuration properties.</p>
+<table>
+ <thead>
+ <tr>
+ <th>Property </th>
+ <th>Type </th>
+ <th>Default </th>
+ <th>Description </th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>whitelist.bypass</code> </td>
+ <td>Boolean </td>
+ <td>false </td>
+ <td>Allow all bundles to use administrative login. This is <strong>NOT</strong> recommended for production and warnings will be logged. </td>
+ </tr>
+ <tr>
+ <td><code>whitelist.bundles.regexp</code> </td>
+ <td>String </td>
+ <td>"" </td>
+ <td>A regular expression that whitelists all matching bundle symbolic names. This is <strong>NOT</strong> recommended for production and warnings will be logged. </td>
+ </tr>
+ </tbody>
+</table></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </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>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/servlets.html
----------------------------------------------------------------------
diff --git a/documentation/the-sling-engine/servlets.html b/documentation/the-sling-engine/servlets.html
new file mode 100644
index 0000000..0e50baf
--- /dev/null
+++ b/documentation/the-sling-engine/servlets.html
@@ -0,0 +1,156 @@
+<!DOCTYPE html><html lang="en">
+ <head>
+<meta charset="utf-8"/>
+ <title>Apache Sling on JBake</title>
+ <link rel="stylesheet" href="/res/css/site.css"/>
+ <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ </a>
+ </div><div class="header">
+ <a href="http://www.apache.org">
+ <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ </a>
+ </div>
+ </div>
+ </head><body>
+<div class="menu">
+ <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html">Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a><br/><a href="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Servlets and Scripts</h1></header><p>[TOC]</p>
+<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>Servlet Registration</h2>
+<p>Servlets can be registered as OSGi services. The following service reference properties are evaluated for Servlets defined as OSGi services of type <code>javax.servlet.Servlet</code> (all those property names are defined in <code>org.apache.sling.api.servlets.ServletResolverConstants</code> (since API 2.15.2) or <code>org.apache.sling.servlets.resolver.internal.ServletResolverConstants</code> (before API 2.15.2)):</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.<br>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. Either this property or the <code>sling.servlet.resourceTypes</code> property must be set, or the servlet is ignored. If both are set, the servlet is registered using both ways.<br>Binding resources by paths is discouraged, see <a href="#caveats-when-binding-servlets-by-path">caveats when binding servlets by path</a> below. </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. Either this property or the <code>sling.servlet.paths</code> property must be set, or the servlet is ignored. If both are set, the servlet is registered using both ways. </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 only considered for the registration with <code>sling.servlet.resourceTypes</code>. </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 only considered for the registration with <code>sling.servlet.resourceTypes</code>. </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 only considered for the registration with <code>sling.servlet.resourceTypes</code>. If this property is missing, the value defaults to GET and HEAD, 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, either one 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 and HEAD requests. Make sure to list all methods you want to be handled by this servlet.</p>
+<h3>Caveats when binding servlets by path</h3>
+<p>Binding servlets by paths has several disadvantages when compared to binding by resource types, namely:</p>
+<ul>
+ <li>path-bound servlets cannot be access controlled using the default JCR repository ACLs</li>
+ <li>path-bound servlets can only be registered to a path and not a resource type (i.e. no suffix handling)</li>
+ <li>if a path-bound servlet is not active, e.g. if the bundle is missing or not started, a POST might result in unexpected results. usually creating a node at /bin/xyz which subsequently overlays the servlets path binding</li>
+ <li>the mapping is not transparent to a developer looking just at the repository</li>
+</ul>
+<p>Given these drawbacks it is strongly recommended to bind servlets to resource types rather than paths.</p>
+<h3>Registering a Servlet using Java Annotations</h3>
+<p>If you are working with the default Apache Sling development stack you can either use</p>
+<ul>
+ <li><a href="https://osgi.org/javadoc/r6/cmpn/org/osgi/service/component/annotations/package-summary.html">OSGi DS annotations</a> (introduced with DS 1.2/OSGi 5, properly supported since <a href="https://github.com/bndtools/bndtools/wiki/Changes-in-3.0.0">bnd 3.0</a>, being used in <a href="http://felix.apache.org/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html">maven-bundle-plugin 3.0.0</a>) or</li>
+ <li>Generic Felix SCR or Sling-specific <code>@SlingServlet</code> 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:</li>
+</ul>
+<p>The following examples show example code how you can register Servlets with Sling</p>
+<ol>
+ <li>OSGi DS annotations (recommended)</li>
+</ol>
+<p>:::java @Component( service = { Servlet.class }, property = { SLING_SERVLET_RESOURCE_TYPES + "=/apps/my/type" SLING_SERVLET_METHODS + "=GET", SLING_SERVLET_EXTENSIONS + "=html", SLING_SERVLET_SELECTORS + "=hello", } ) public class MyServlet extends SlingSafeMethodsServlet {</p>
+<p>@Override protected void doGet(SlingHttpServletRequest request, SlingHttpServletResponse response) throws ServletException, IOException { ... } }</p>
+<p>Custom OSGi DS annotations (e.g. for Sling servlets) are not yet supported by the OSGi spec (and therefore by bnd), but this is supposed to be fixed with DS 1.4 (OSGi 7), see also <a href="https://issues.apache.org/jira/browse/FELIX-5396">FELIX-5396</a>.</p>
+<ol>
+ <li>The <code>@SlingServlet</code> annotation (evaluated by maven-scr-plugin)</li>
+</ol>
+<p>:::java @SlingServlet( resourceTypes = "/apps/my/type", selectors = "hello", extensions = "html", methods = "GET") public class MyServlet extends SlingSafeMethodsServlet {</p>
+<p>@Override protected void doGet(SlingHttpServletRequest request, SlingHttpServletResponse response) throws ServletException, IOException { ... } }</p>
+<h3>Automated tests</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>Example: Registration by Path</h3>
+<p>sling.servlet.paths = [ "/libs/sling/sample/html", "/libs/sling/sample/txt" ] sling.servlet.selectors = [ "img" ] sling.servlet.extensions = [ "html", "txt", "json" ]</p>
+<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.selectors</code> and <code>sling.servlet.extensions</code> <em>are ignored</em> because the servlet is registered only by path (only <code>sling.servlet.paths</code> property is set).</p>
+<h3>Example: Registration by Resource Type etc.</h3>
+<p>sling.servlet.resourceTypes = [ "sling/unused" ] sling.servlet.selectors = [ "img", "tab" ] sling.servlet.extensions = [ "html", "txt", "json" ]</p>
+<p>A Servlet service registered with these properties is registered for the following resource types:</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 at the explanation of <code>sling.servlet.prefix</code> how <code><prefix></code> is defined.</p>
+<p>It is more common to register for absolute resource types or at least explicitly define <code>sling.servlet.prefix</code> as well, because otherwise you are in most cases not sure under which absolute path the Servlet is registered (and therefore by which other paths it might get overwritten).</p>
+<h3>Servlet Lifecycle Issues</h3>
+<p>The Servlet API specification states the following with respect to the life cycle of Servlets:</p>
+<blockquote>
+ <p>The servlet container calls the init method exactly once after instantiating the servlet.</p>
+</blockquote>
+<p>This works perfectly in a regular servlet container which both instantiates and initializes the servlets. With Sling the tasks of instantiation and initialization are split:</p>
+<ul>
+ <li>The provider of the Servlet service takes care of creating the servlet instance</li>
+ <li>The Sling Servlet Resolver picks up the Servlet services and initializes and destroys them as needed</li>
+</ul>
+<p>So Sling has not way of making sure a Servlet is only initialized and destroyed once in the life time of the Servlet object instance.</p>
+<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>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>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>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>
+<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>Error Handler Servlet(s) or Scripts</h2>
+<p>Error handling support is described on the <a href="/documentation/the-sling-engine/errorhandling.html">Errorhandling</a> page.</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </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>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/sling-api-crud-support.html
----------------------------------------------------------------------
diff --git a/documentation/the-sling-engine/sling-api-crud-support.html b/documentation/the-sling-engine/sling-api-crud-support.html
new file mode 100644
index 0000000..d86f34e
--- /dev/null
+++ b/documentation/the-sling-engine/sling-api-crud-support.html
@@ -0,0 +1,125 @@
+<!DOCTYPE html><html lang="en">
+ <head>
+<meta charset="utf-8"/>
+ <title>Apache Sling on JBake</title>
+ <link rel="stylesheet" href="/res/css/site.css"/>
+ <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ </a>
+ </div><div class="header">
+ <a href="http://www.apache.org">
+ <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ </a>
+ </div>
+ </div>
+ </head><body>
+<div class="menu">
+ <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html">Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a><br/><a href="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Sling API CRUD Support</h1></header><p>[TOC]</p>
+<h2>Apache Sling API Support</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>
+ <li><a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#create-org.apache.sling.api.resource.Resource-java.lang.String-java.util.Map-">Resource create(Resource parent, String name, Map<String, Object> properties) throws PersistenceException</a></li>
+ <li><a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#revert--">void revert()</a></li>
+ <li><a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#commit--">void commit() throws PersistenceException</a></li>
+ <li><a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#hasChanges--">boolean hasChanges()</a></li>
+ <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>Comparing Sling API CRUD to Sling Post Servlet</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>Updating a Property</h3>
+<p>Update /myresource, setting the title and body:</p>
+<p><strong>Sling Post Servlet</strong></p>
+<form action="/myresource" method="POST">
+<input type="text" name="title">
+<textarea name="body">
+</form>
+<p><strong>Sling API CRUD</strong></p>
+<p>Resource myResource = resourceResolver.getResource("/myresource"); ModifiableValueMap properties = myNode.adaptTo(ModifiableValueMap.class); properties.put("title", {TITLE}); properties.put("body", {BODY}); resourceResolver.commit();</p>
+<h3>Create New Resource</h3>
+<p>Create a new resource below /myresource</p>
+<p><strong>Sling Post Servlet</strong></p>
+<form action="/myresource/" method="POST">
+<input type="text" name="dummy">
+</form>
+<p><strong>Sling API CRUD</strong></p>
+<p>Resource myResource = resourceResolver.getResource("/myresource"); Map<String,Object> properties = new HashMap<String,Object>(); properties.put("jcr:primaryType", "nt:unstructured"); properties.put("sling:resourceType", "myapp/components/mytype"); Resource dummy = resourceResolver.create(myResource, "dummy", properties); resourceResolver.commit();</p>
+<h3>Remove a Property</h3>
+<p>Remove the property title</p>
+<p><strong>Sling Post Servlet</strong></p>
+<form action="/myresource" method="POST">
+<input type="hidden" name="title@Delete">
+</form>
+<p><strong>Sling API CRUD</strong></p>
+<p>Resource myResource = resourceResolver.getResource("/myresource"); ModifiableValueMap properties = myResource.adaptTo(ModifiableValueMap.class); properties.remove("title"); resourceResolver.commit();</p>
+<h3>Copy a Resource</h3>
+<p>Copy the resource /myresource to /myresource2</p>
+<p><strong>Sling Post Servlet</strong></p>
+<form action="/myresource" method="POST">
+<input type="hidden" name=":operation" value="copy">
+<input type="hidden" name=":dest" value="/myresource2">
+<input type="hidden" name=":replace" value="true">
+</form>
+<p><strong>Sling API CRUD</strong></p>
+<p>Map<String,Object> properties = myResource.adaptTo(ValueMap.class); Resource myResource2 = resourceResolver.create(null, "myresource2", properties); resourceResolver.commit();</p>
+<h3>Move a Resource</h3>
+<p>Move the resource /myresource2 to /myresource3</p>
+<p><strong>Sling Post Servlet</strong></p>
+<form action="/myresource2" method="POST">
+<input type="hidden" name=":operation" value="move">
+<input type="hidden" name=":dest" value="/myresource3">
+</form>
+<p><strong>Sling API CRUD</strong></p>
+<p>Resource myResource2 = resourceResolver.getResource("/myresource2"); Map<String,Object> properties = myResource2.adaptTo(ValueMap.class); Resource myResource3 = resourceResolver.create(null, "myresource3", properties); resourceResolver.delete(myResource2); resourceResolver.commit();</p>
+<h3>Setting non-String Value</h3>
+<p>Set the property date to a particular date</p>
+<p><strong>Sling Post Servlet</strong></p>
+<form action="/myresource3" method="POST">
+<input type="text" name="date" value="2008-06-13T18:55:00">
+<input type="hidden" name="date@TypeHint" value="Date">
+</form>
+<p><strong>Sling API CRUD</strong></p>
+<p>Resource myResource3 = resourceResolver.getResource("/myresource3"); Calendar calendar = [SOME_DATE]; ModifiableValueMap properties = myResource3.adaptTo(ModifiableValueMap.class); properties.put("date", calendar); resourceResolver.commit();</p>
+<h3>Delete a Resource</h3>
+<p>Delete the resource /myresource</p>
+<p><strong>Sling Post Servlet</strong></p>
+<form action="/myresource" method="POST">
+<input type="hidden" name=":operation" value="delete">
+</form>
+<p><strong>Sling API CRUD</strong></p>
+<p>Resource myResource = resourceResolver.getResource("/myresource"); resourceResolver.delete(myResource); resourceResolver.commit();</p>
+<h2>Value Class Support</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>
+<p>The Classes implementing the following types are supported directly when setting properties:</p>
+<ul>
+ <li><a href="http://docs.oracle.com/javase/8/docs/api/java/util/Calendar.html">Calendar</a></li>
+ <li><a href="http://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html">InputStream</a></li>
+ <li><a href="http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/Node.html">Node</a></li>
+ <li><a href="http://docs.oracle.com/javase/8/docs/api/java/math/BigDecimal.html">BigDecimal</a></li>
+ <li><a href="http://docs.oracle.com/javase/8/docs/api/java/lang/Long.html">Long</a></li>
+ <li><a href="http://docs.oracle.com/javase/8/docs/api/java/lang/Short.html">Short</a></li>
+ <li><a href="http://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html">Integer</a></li>
+ <li><a href="http://docs.oracle.com/javase/8/docs/api/java/lang/Number.html">Number</a></li>
+ <li><a href="http://docs.oracle.com/javase/8/docs/api/java/lang/Boolean.html">Boolean</a></li>
+ <li><a href="http://docs.oracle.com/javase/8/docs/api/java/lang/String.html">String</a></li>
+</ul>
+<p>As well as the corresponding primitive types. Any object which implements the Serializable interface will be serialized and the result of the serialization will be saved as a binary value for the property.</p></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </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>
+
+ </div>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/a6129baf/documentation/the-sling-engine/sling-properties.html
----------------------------------------------------------------------
diff --git a/documentation/the-sling-engine/sling-properties.html b/documentation/the-sling-engine/sling-properties.html
new file mode 100644
index 0000000..0ac338a
--- /dev/null
+++ b/documentation/the-sling-engine/sling-properties.html
@@ -0,0 +1,155 @@
+<!DOCTYPE html><html lang="en">
+ <head>
+<meta charset="utf-8"/>
+ <title>Apache Sling on JBake</title>
+ <link rel="stylesheet" href="/res/css/site.css"/>
+ <link rel="stylesheet" href="/res/css/codehilite.css"/>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org">
+ <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/>
+ </a>
+ </div><div class="header">
+ <a href="http://www.apache.org">
+ <img border="0" alt="Apache" src="/res/logos/apache.png"/>
+ </a>
+ </div>
+ </div>
+ </head><body>
+<div class="menu">
+ <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki">Wiki</a><br/><a href="http://s.apache.org/sling.faq">FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h
ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/">License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk">Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling">Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html">Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a><br/><a href="https://donate.apache.org/">Donate!</a><br/><a href="http://www.apache.org/foun
dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong>
+ </div> <div class="main">
+<div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Well-known Sling Properties</h1></header><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>
+<p>[TOC]</p>
+<h2>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>
+ <td>Launchpad </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>
+ <td>Launchpad </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>
+ <td>Launchpad </td>
+ </tr>
+ </tbody>
+</table>
+<h2>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>
+ <td>Launchpad </td>
+ </tr>
+ </tbody>
+</table>
+<p>| <code>sling.control.action</code> | -- | 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. | Launchpad |</p>
+<h2>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>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></section></div></div>
+<div class="footer">
+ <div class="timestamp">
+ TODO display revision number here
+ </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>
+
+ </div>
+ </body>
+</html>