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:53 UTC
[47/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/bundles/osgi-installer.html
----------------------------------------------------------------------
diff --git a/documentation/bundles/osgi-installer.html b/documentation/bundles/osgi-installer.html
new file mode 100644
index 0000000..cffd0da
--- /dev/null
+++ b/documentation/bundles/osgi-installer.html
@@ -0,0 +1,81 @@
+<!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>OSGi Installer</h1></header><h1>Overview</h1>
+<p>The OSGi installer is a central service for handling installs, updates and uninstall of "artifacts". By default, the installer supports bundles and has an extension for handling configurations for the OSGi configuration admin.</p>
+<p><img src="/documentation/bundles/Slide14.jpg" alt="Apache Sling OSGI Installer Diagram" /></p>
+<p>The OSGi installer itself is "just" the central service managing the tasks and states of the artifacts. The artifacts can be provided through various providers, e.g. through a file system provider reading artifacts from configured directories or the jcr provider reading artifacts from a JCR repository.</p>
+<p>A provider is just scanning for artifacts and their removal. It informs the OSGi installer about new artifacts and removed artifacts. The provider itself has usually no knowledge about the contents of an artifact. It does not know about bundles, configurations etc.</p>
+<p>As the OSGi installer itself is not performing the actual install, update or removal of an artifact, its possible to install transformers and installer factories. A transformer inspects the artifacts and tries to detect its type. By default, detecting of bundles and configurations is supported. The final service is an installer factory creating the actual task, like install this bundle, update that bundle etc.</p>
+<p>It's possible to add own providers, transformers and installer factories to support custom scenarios.</p>
+<h2>API</h2>
+<p>The installer API is defined by the <code>org.apache.sling.installer.api</code> package of the <a href="http://svn.apache.org/repos/asf/sling/trunk/installer/core/">org.apache.sling.installer.core</a> module. The main interface is the <code>OsgiInstaller</code> with which installable resources can be registered.</p>
+<p>The [installer integration tests][1] module can be useful to understand the details of how the installer works.</p>
+<h2>Artifact Handling</h2>
+<p>Once an artifact is detected by a transformer, it gets a unique id. By default a bundle gets the symbolic name as the unique identifier and a configuration the PID. In addition to this id, an artifact gets a priority information from the provider. The priority is used if an artifact with the same id is provided several times from different locations. For example if a file system provider is scanning two directories and an artifact with the same id (like a configuration) is added to both directories, one should have precedence over the other. This is handled by the priority.</p>
+<p>Artifacts with the same unique id are grouped and then sorted by priority and maybe other artifact dependent metadata like the bundle version. Only the first artifact in this sorted group is tried to be applied!</p>
+<h2>Bundle Handling</h2>
+<p>In general, the OSGi installer always tries to install the highest version of a bundle if several bundles with the same symbolic name are provided. In this case higher version wins over priority. If an installed bundle is removed by a provider, for example deleted in the repository, the OSGi installer uninstall the bundle. If a bundle is removed from a provider which is currently not installed, this has no effect at all. If an installed bundle is removed and another version of this bundle is provided (a lower version), than this one is installed instead. This is basically a downgrade of the bundle. If a bundle is installed and a higher version is provided, an upgrade is performed. If an installed bundle is managed via any other OSGi tooling, like uninstalling it through the web console, the OSGi installer does no action at all!</p>
+<p>If a failure occurs during bundle installation or update, the OSGi installer will retry this as soon as another bundle has been installed. The common use case is an application installation with several bundles where one bundle depends on another. As they are installed in arbitrary order, this mechanism ensures that in the end all bundles are properly wired and installed.</p>
+<p>When all artifacts have been processed (either install, update or delete), a package refresh is automatically called.</p>
+<h3>Versions and Snapshots</h3>
+<p>The OSGi installer asumes that a symbolic name and version (not a snapshot version) uniquely identifies a bundle. Obviously this is a common development requirement that a released version of an artifact never changes over time. Therefore, once a bundle with a specific version is installed, it will not be reinstalled if the corresponding artifact changes. For example, if bundle A with version 1.0 is put into the JCR repository, it gets installed. If now this jar in the repository is overwritten either with the same contents or with a different one, and this new artifact has again A as the symbolic name and version set to 1.0, nothing will happen as this exact bundle is already installed.</p>
+<p>During development, SNAPSHOT versions should be used, like 1.0.0-SNAPSHOT (using the Maven convention). If a bundle with a snapshot version is changed, it gets updated by the OSGI installer.</p>
+<h2>Start Level Handling</h2>
+<p>The OSGi installer supports handling of start levels for bundles. If the provided bundle artifacts contain a start level information the bundle is installed with that start level, otherwise the default start level is used. Therefore, for initial provisioning to make use of start levels, the OSGi installer and the corresponding provider (see below) should run at a very low start level, probably at 1. This ensure that the bundles with a start level are started with respect to the start level.</p>
+<p>When an update of bundles is performed through the installer, by default the installer stays in the current start level and updates the bundles. However, if bundles at low start levels are affected, this might result in a lot of churn going on. Therefore, the OSGi installer can be configured to use a more intelligent start level handling:</p>
+<ul>
+ <li>If the framework property "sling.installer.switchstartlevel" is set to "true" and</li>
+ <li>there is no asynchronous install task in the list of tasks to perform, then</li>
+ <li>the start level is set to (the lowest level of the bundles to be updated - 1) - if the start level is lower than the level of the installer itself, the start level of the installer is used.</li>
+ <li>the bundles are updated/installed</li>
+ <li>the start level is increased to the previous level</li>
+</ul>
+<h2>Plugins</h2>
+<h3>Factories</h3>
+<p>An installer factory provides support for a specific artifact type, like a configuration or a deployment package etc.</p>
+<ul>
+ <li><a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a></li>
+ <li><a href="/documentation/bundles/subsystem-installer-factory.html">Subsystem Installer Factory</a></li>
+</ul>
+<h3>Providers</h3>
+<p>A provider provides artifacts, e.g. by scanning a directory or a database etc.</p>
+<ul>
+ <li><a href="/documentation/bundles/file-installer-provider.html">File Installer Provider</a></li>
+ <li><a href="/documentation/bundles/jcr-installer-provider.html">JCR Installer Provider</a></li>
+</ul>
+<h2>Health Check</h2>
+<p>The OSGi installer provides a <a href="/documentation/bundles/sling-health-check-tool.html">Sling Health Check</a> which validates that the processed OSGi installer resources have the correct state (<a href="https://issues.apache.org/jira/browse/SLING-5888">SLING-5888</a>). By default it will only check resources with a URL prefix <code>jcrinstall:/apps/</code>, so only the resources being provided through the <a href="/documentation/bundles/jcr-installer-provider.html">JCR Installer Provider</a> initially located below the repository resource <code>/apps/</code> are considered. The health check will fail in the following cases:</p>
+<h3>Bundles Installation Failure</h3>
+<p>The checked bundle was not installed because it has been installed in a newer version through some other means (e.g. manually through the Felix Web Console or by another provider. For further details please review the OSGi Installer console at <code>/system/console/osgi-installer</code> and check for all bundles with the given symbolic name (=OSGi installers resource id) and the according URL.</p>
+<h3>Configuration Installation Failure</h3>
+<p>The checked configuration was not installed because it has either been overwritten manually in the Felix Web Console or is installed by some non-checked provider (which has a higher priority). To revert manually overwritten configurations just go to <code>/system/console/configMgr</code> and delete the according configuration. That way the OSGi installer should automatically create a new configuration for the same PID based on the configuration provided by some provider with the highest prio. In case another non-checked provider has provided already a configuration you can see from where it has been installed by looking at the OSGi Installer console at <code>/system/console/osgi-installer</code> and look for all configurations with the given PID.</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/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html
----------------------------------------------------------------------
diff --git a/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html b/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html
new file mode 100644
index 0000000..169db1f
--- /dev/null
+++ b/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html
@@ -0,0 +1,86 @@
+<!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>Output Rewriting Pipelines (org.apache.sling.rewriter)</h1></header><p>The Apache Sling Rewriter is a module for rewriting the output generated by a usual Sling rendering process. Some possible use cases include rewriting or checking all links in an HTML page, manipulating the HTML page, or using the generated output as the base for further transformation. An example of further transformation is to use XSLT to transform rendered XML to some output format like HTML or XSL:FO for generating PDF.</p>
+<p>For supporting these use cases, the rewriter uses the concept for a processor. The processor is a component that is injected through a servlet filter into the response. By implementing the <em>Processor</em> interface one is able to rewrite the whole response in one go. A more convenient way of processing the output is by using a so called pipeline; the Apache Sling rewriter basically uses the same concept as the famous Apache Cocoon: an XML based pipeline for further post processing of the output. The pipeline is based on SAX events.</p>
+<h2>SAX Pipelines</h2>
+<p>The rewriter allows to configure a pipeline for post processing of the generated response. Depending on how the pipeline is assembled the rewriting process might buffer the whole output in order to do proper post processing - for example this is required if an HTML response is "transformed" to XHTML or if XSLT is used to process the response.</p>
+<p>As the pipeline is based on SAX events, there needs to be a component that generates these events and sends them through the pipeline. By default the Sling rendering scripts write to an output stream, so there is a need to parse this output and generate the SAX events.</p>
+<p>The first component in the pipeline generating the initial SAX events is called a generator. The generator gets the output from Sling, generates SAX events (XML), and streams these events into the pipeline. The counterpart of the generator is the serializer which builds the end of the pipeline. The serializer collects all incomming SAX events, transforms them into the required response by writing into output stream of the response.</p>
+<p>Between the generator and the serializer so called transformers can be placed in a chain. A transformer receives SAX events from the previous component in the pipeline and sends SAX events to the next component in the pipeline. A transformer can remove events, change events, add events or just pass on the events.</p>
+<p>Sling contains a default pipeline which is executed for all HTML responses: it starts with an HTML generator, parsing the HTML output and sending events into the pipeline. An HTML serializer collects all events and serializes the output.</p>
+<p>The pipelines can be configured in the repository as a child node of <em>/apps/APPNAME/config/rewriter</em> (or <em>/libs/APPNAME/config/rewriter</em>). (In fact the configured search paths of the resource resolver are observed.) Each node can have the following properties:</p>
+<ul>
+ <li>generatorType - the type of the generator (required)</li>
+ <li>transformerTypes (multi value string) - the types of the transformers (optional)</li>
+ <li>serializerType - the type of the serializer (required)</li>
+ <li>paths (multi value string) - the paths this pipeline should run on (content paths)</li>
+ <li>contentTypes (multi value string) - the content types this pipeline should be used for (optional)</li>
+ <li>extensions (multi value string) - the extensions this pipeline should be used for (optional)</li>
+ <li>resourceTypes (multi value string) - the resource types this pipeline should be used for (optional)</li>
+ <li>unwrapResources (boolean) - check resource types of unwrapped resources as well (optional, since 1.1.0)</li>
+ <li>selectors (multi value string) - a set of selectors the pipeline should be used for (optional, since 1.1.0)</li>
+ <li>order (long) - the configurations are sorted by this order, order must be higher or equal to 0. The configuration with the highest order is tried first.</li>
+ <li>enabled (boolean) - Is this configuration active? (default yes)</li>
+</ul>
+<p>As you can see from the configuration there are several possibilities to define when a pipeline should be used for a response, like paths, extensions, content types, or resource types. It is possible to specify several of them at once. In this case all conditions must be met.</p>
+<p>If a component needs a configuration, the configuration is stored in a child node which name is <em>{componentType}-{name}</em>, e.g. to configure the HTML generator (named <em>html-generator</em>), the node should have the name <em>generator-html-generator</em>. In the case that the pipeline contains the same transformer several times, the configuration child node should have the formant <em>{componentType}-{index}</em> where index is the index of the transformer starting with 1. For example if you have a pipeline with the following transformers, xslt, html-cleaner, xslt, link-checker, then the configuration nodes should be named <em>transformer-1</em> (for the first xslt), <em>transformer-html-cleaner</em>, <em>transformer-3</em> (for the second xslt), and <em>transformer-link-checker</em>.</p>
+<h3>Default Pipeline</h3>
+<p>The default pipeline is configured for the <em>text/html</em> mime type and the <em>html</em> extensions and consists of the <em>html-generator</em> as the generator, and the <em>html-serializer</em> for generating the final response. As the HTML generated by Sling is not required to be valid XHTML, the HTML parser is using an HTML parser to create valid SAX events. In order to perform this, the generator needs to buffer the whole response first.</p>
+<h2>Implementing Pipeline Components</h2>
+<p>Each pipeline component type has a corresponding Java interface (Generator, Transformer, and Serializer) together with a factory interface (GeneratorFactory, TransformerFactory, and SerializerFactory). When implementing such a component, both interfaces need to be implemented. The factory has only one method which creates a new instance of that type for the current request. The factory has to be registered as a service. For example if you're using the Maven SCR plugin, it looks like this:</p>
+<p>::java @scr.component metatype="no" @scr.service interface="TransformerFactory" @scr.property value="pipeline.type" value="validator"</p>
+<p>The factory needs to implement the according interface and should be registered as a service for this factory interface (this is a plain service and not a factory service in the OSGi sense). Each factory gets a unique name through the <em>pipeline.type</em> property. The pipeline configuration in the repository just references this unique name (like validator).</p>
+<h2>Extending the Pipeline</h2>
+<p>With the possibilities from above, it is possible to define new pipelines and add custom components to the pipeline. However, in some cases it is required to just add a custom transformer to the existing pipeline. Therefore the rewriting can be configured with pre and post transformers that are simply added to each configured pipeline. This allows a more flexible way of customizing the pipeline without changing/adding a configuration in the repository.</p>
+<p>The approach here is nearly the same. A transformer factory needs to be implemented, but instead of giving this factory a unique name, this factory is marked as a global factory:</p>
+<p>::java @scr.component metatype="no" @scr.service interface="TransformerFactory" @scr.property name="pipeline.mode" value="global" @scr.property name="service.ranking" value="RANKING" type="Integer"</p>
+<p><em>RANKING</em> is an integer value (don't forget the type attribute otherwise the ranking is interpreted as zero!) specifying where to add the transformer in the pipeline. If the value is less than zero the transformer is added at the beginning of the pipeline right after the generator. If the ranking is equal or higher as zero, the transformer is added at the end of the pipeline before the serializer.</p>
+<p>The <em>TransformerFactory</em> interface has just one method which returns a new transformer instance. If you plan to use other services in your transformer you might declare the references on the factory and pass in the instances into the newly created transformer.</p>
+<p>Since the transformer carries information about the current response it is not advisable to reuse the same transformer instance among multiple calls of <code>TransformerFactory.createTransformer</code>.</p>
+<h2>Implementing a Processor</h2>
+<p>A processor must conform to the Java interface <em>org.apache.sling.rewriter.Processor</em>. It gets initializd (method <em>init</em>) with the <em>ProcessingContext</em>. This context contains all necessary information for the current request (especially the output writer to write the rewritten content to). The <em>getWriter</em> method should return a writer where the output is written to. When the output is written or an error occured <em>finished</em> is called.</p>
+<p>Like the pipeline components a processor is generated by a factory which has to be registered as a service factory, like this:</p>
+<p>::java @scr.component metatype="no" @scr.service interface="ProcessorFactory" @scr.property value="pipeline.type" value="uniqueName"</p>
+<h2>Configuring a Processor</h2>
+<p>The processors can be configured in the repository as a child node of <em>/apps/APPNAME/config/rewriter</em> (or libs or any configured search path). Each node can have the following properties:</p>
+<ul>
+ <li>processorType - the type of the processor (required) - this is the part from the scr factory information after the slash (in the example above this is <em>uniqueName</em>)</li>
+ <li>paths (multi value string) - the paths this processor should run on (content paths)</li>
+ <li>contentTypes (multi value string) - the content types this processor should be used for (optional)</li>
+ <li>extensions (multi value string) - the extensions this processor should be used for (optional)</li>
+ <li>resourceTypes (multi value string) - the resource types this processor should be used for (optional)</li>
+ <li>unwrapResources (boolean) - check resource types of unwrapped resources as well (optional, since 1.1.0)</li>
+ <li>selectors (multi value string) - a set of selectors the pipeline should be used for (optional, since 1.1.0)</li>
+ <li>order (long) - the configurations are sorted by this order, order must be higher or equal to 0. The configuration with the highest order is tried first.</li>
+ <li>enabled (boolean) - Is this configuration active? (default yes)</li>
+</ul></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/bundles/rendering-content-default-get-servlets.html
----------------------------------------------------------------------
diff --git a/documentation/bundles/rendering-content-default-get-servlets.html b/documentation/bundles/rendering-content-default-get-servlets.html
new file mode 100644
index 0000000..644c84f
--- /dev/null
+++ b/documentation/bundles/rendering-content-default-get-servlets.html
@@ -0,0 +1,67 @@
+<!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>Rendering Content - Default GET Servlets</h1></header><p>[TOC]</p>
+<div class="note">
+Not all features of the <b>org.apache.sling.servlets.get</b> bundle are described below - this
+page needs more work.
+</div>
+<h1>Default GET and HEAD servlets</h1>
+<p>Sling provides a number of default GET and HEAD servlets, in the <code>org.apache.sling.servlets.get</code> bundle.</p>
+<p>This provides useful functionality out of the box: JSON rendering of content for example, usually does not require custom code.</p>
+<p>This page provides an overview of these default servlets.</p>
+<p>Currently, only the <code>DefaultGetServlet</code> has configuration parameters. Those are found at <code>/system/console/configMgr/org.apache.sling.servlets.get.DefaultGetServlet</code> on a standard Sling setup, and should be self-explaining. One common use is to disable some of the default renderings listed below, as they might not be useful or desired on production systems.</p>
+<h1>Default renderings</h1>
+<h2>Default JSON rendering</h2>
+<p>Adding a .json extension to a request triggers the default Sling GET servlet in JSON mode, unless a more specific servlet or script is provided for the current resource.</p>
+<p>This servlet currently supports the following selectors:</p>
+<ul>
+ <li><code>.tidy</code> causes the JSON output to be formatted</li>
+ <li><code>.harray</code> causes child nodes to be output as arrays instead of objects, to preserve their order (requires <code>org.apache.sling.servlets.get</code> V2.1.10)</li>
+ <li>A numeric value or <code>.infinity</code> as the last selector selects the desired recursion level</li>
+</ul>
+<p>Note that the number of elements is limited by a configurable value, see the <code>DefaultGetServlet</code> configuration for more info.</p>
+<h2>Default HTML rendering</h2>
+<p>In a similar way, adding a <code>.html</code> extension to a request triggers the default Sling GET servlet in HTML mode. That rendering just dumps the current node values in a readable way, but it's only really useful for troubleshooting.</p>
+<h2>Default text rendering</h2>
+<p>A basic text rendering is also provided if the request has a <code>.txt</code> extension, unless more specific servlets or scripts are provided.</p>
+<h2>Default XML rendering</h2>
+<p>Adding a <code>.xml</code> extension triggers the default XML rendering, once again unless a more specific script or servlet is registered for the current resource.</p>
+<p>That XML rendering currently uses the JCR "document view" export functionality directly, so it only supports rendering resources that are backed by JCR nodes.</p>
+<h2>StreamRendererServlet</h2>
+<p>Whenever the request carries the extension <code>.res</code> or no extension at all, the resource's input stream is spooled to the servlet response (leveraging <code>Resource.adaptTo(InputStream.class)</code>). This servlet supports conditional requests (<a href="https://tools.ietf.org/html/rfc7232">RFC 7232</a>) evaluating the resource's modification date from <code>Resource.getResourceMetadata().getModificationTime()</code> and range requests (<a href="https://tools.ietf.org/html/rfc7233">RFC 7233</a>).</p>
+<h2>RedirectServlet</h2>
+<p>The <code>RedirectServlet</code> handles the <code>sling:redirect</code> resource type, using the <code>sling:target</code> property of the resource to define the redirect target, and the <code>sling:status</code> property to define the HTTP status to use (default is 302).</p>
+<p>This is not to be confused with the <code>sling:redirect</code> property used under <code>/etc/map</code>, which is described in <a href="/documentation/the-sling-engine/mappings-for-resource-resolution.html">Mappings for Resource Resolution</a></p>
+<h2>SlingInfoServlet</h2>
+<p>The <code>SlingInfoServlet</code> provides info on the current JCR session, for requests that map to JCR nodes.</p>
+<p>It is available at <code>/system/sling/info.sessionInfo</code> by default, and supports <code>.json</code> and <code>.txt</code> extensions.</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/bundles/repository-initialization.html
----------------------------------------------------------------------
diff --git a/documentation/bundles/repository-initialization.html b/documentation/bundles/repository-initialization.html
new file mode 100644
index 0000000..b39ef69
--- /dev/null
+++ b/documentation/bundles/repository-initialization.html
@@ -0,0 +1,96 @@
+<!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></h1></header><p>The <code>SlingRepositoryInitializer</code> mechanism allows for running code before the <code>SlingRepository</code> service is registered.</p>
+<p>This is useful for initialization and content migration purposes.</p>
+<p>Please be aware of potential clustering and coordination issues when using this mechanism, if your environment lets several Sling instances access the same content repository you'll need to implement a synchronization mechanism for such operations.</p>
+<h2>SlingRepositoryInitializer</h2>
+<p>The <code>SlingRepositoryInitializer</code> is a very simple service interface, available from version 2.4.0 of the <code>org.apache.sling.jcr.api</code> and <code>org.apache.sling.jcr.base</code> bundles.</p>
+<p>public interface SlingRepositoryInitializer { public void processRepository(SlingRepository repo) throws Exception; }</p>
+<p>Services that implement this interface are called when setting up the JCR-based <code>SlingRepository</code> service, before registering it as an OSGi service.</p>
+<p>They are called in increasing order of their <code>service.ranking</code> service property, which needs to be an <code>Integer</code> as usual.</p>
+<p>If any of them throws an Exception, the <code>SlingRepository</code> service is not registered.</p>
+<h2>The 'repoinit' Repository Initialization Language</h2>
+<p>The <code>org.apache.sling.repoinit.parser</code> implements a mini-language meant to create paths, service users and Access Control Lists in a content repository, as well as registering JCR namespaces and node types.</p>
+<p>The language grammar is defined (using the JavaCC compiler-compiler, which has no runtime dependencies) in the <code>RepoInitGrammar.jjt</code> file in that module, and the automated tests provide a number of <a href="https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/repoinit/parser/src/test/resources/testcases">test cases</a> which demonstrate various features.</p>
+<p>The companion <code>org.apache.sling.jcr.repoinit</code> module implements those operations on an Oak JCR repository, using a <code>SlingRepositoryInitializer</code> registered by default with a service ranking of 100. It also provides a <code>JcrRepoInitOpsProcessor</code> service to explicitly apply the output of the repoinit parser to a JCR repository.</p>
+<p>Here's a current example from the test cases mentioned above, that uses all language features as of version 1.0.2 of the parser module.</p>
+<p>The language is self-explaining but please refer to the actual test cases for details that are guaranteed to be up to date, assuming the tests pass.</p>
+<p>create service user user1, u-ser_2 set ACL on /libs,/apps allow jcr:read for user1,u-ser_2</p>
+<p>deny jcr:write for u-ser_2 deny jcr:lockManagement for user1 remove jcr:understand,some:other for u3 end</p>
+<p>create service user bob_the_service</p>
+<p>set ACL on /tmp allow some:otherPrivilege for bob_the_service end</p>
+<h1>Nodetypes inside the path apply to just that path element</h1>
+<p>create path /content/example.com(sling:Folder)</p>
+<h1>A nodetype in front is used as the default for all path elements</h1>
+<p>create path (nt:unstructured) /var</p>
+<p>set ACL for alice, bob,fred</p>
+<h1>remove is currently not supported by the jcr.repoinit module</h1>
+<p>remove * on / allow jcr:read on /content,/var deny jcr:write on /content/example.com deny jcr:all on / nodetypes example:Page end</p>
+<p>set ACL for restrictions_examples deny jcr:modifyProperties on /apps, /content nodetypes sling:Folder, nt:unstructured restriction(rep:itemNames,prop1,prop2) allow jcr:addChildNodes on /apps restriction(rep:ntNames,sling:Folder,nt:unstructured) allow jcr:modifyProperties on /apps restriction(rep:ntNames,sling:Folder,nt:unstructured) restriction(rep:itemNames,prop1,prop2) allow jcr:addChildNodes on /apps,/content restriction(rep:glob,/cat/*,*/cat,*cat/*) end</p>
+<h1>register namespace requires</h1>
+<h1>o.a.s.repoinit.parser 1.0.4</h1>
+<h1>and o.a.s.jcr.repoinit 1.0.2</h1>
+<p>register namespace ( NSprefix ) uri:someURI/v1.42</p>
+<h1>register nodetypes in CND format</h1>
+<h1>(same bundle requirements as register namespaces)</h1>
+<p>#</p>
+<h1>The optional << markers are used when embedding</h1>
+<h1>this in a Sling provisioning model, to avoid syntax errors</h1>
+<p>#</p>
+<h1>The CND instructions are passed as is to the JCR</h1>
+<h1>modules, so the full CND syntax is supported.</h1>
+<p># register nodetypes <<=== << <slingevent='http://sling.apache.org/jcr/event/1.0'> << << [slingevent:Event] > nt:unstructured, nt:hierarchyNode << - slingevent:topic (string) << - slingevent:properties (binary) ===>></p>
+<p>create user demoUser with password {SHA-256} dc460da4ad72c482231e28e688e01f2778a88ce31a08826899d54ef7183998b5</p>
+<p>create service user the-last-one</p>
+<h2>Providing repoinit statements from the Sling provisioning model or other URLs</h2>
+<p>All bundles required for this feature need to be active before the <code>SlingRepository</code> service starts.</p>
+<p>From version 1.0.2 of the <code>org.apache.sling.jcr.repoinit</code> bundle, the <code>o.a.s.jcr.repoinit.RepositoryInitializer</code> component uses an OSGi configuration as shown in this example to define where to read repoinit statements:</p>
+<p>org.apache.sling.jcr.repoinit.impl.RepositoryInitializer references=["model:context:/resources/provisioning/model.txt","model@repoinitTwo:context:/resources/provisioning/model.txt"]</p>
+<p>This example defines two <em>references</em> to URLs that supply repoinit statements. Their syntax is described below.</p>
+<p>By default the <code>RepositoryInitializer</code> uses the first URL shown in the above example, which points to the provisioning model that's embedded by default in the Sling Launchpad runnable jar.</p>
+<p>Note that previous versions of the <code>org.apache.sling.jcr.repoinit</code> bundle used different configuration parameters. From version 1.0.2 on, warnings are logged if those old parameters (_text.url,text.format,model.section.name_) are used.</p>
+<h3>References to Sling Provisioning Model additional sections</h3>
+<p>The <code>slingstart-maven-plugin</code>, from V1.4.2 on, allows for embedding so-called "additional sections" in the Sling provisioning model by starting their name with a colon.</p>
+<p>At runtime this requires the <code>org.apache.sling.provisioning.model</code> bundle, version 1.4.2 or later.</p>
+<p>The <code>o.a.s.jcr.repoinit</code> bundle can use this feature to execute <code>repoinit</code> statements provided by Sling provisioning models, as in this provisioning model example fragment:</p>
+<p>[:repoinit] create path /repoinit/provisioningModelTest</p>
+<p>create service user provisioningModelUser</p>
+<p>To read repoinit statements from such an additional provisioning model section, the <code>RepositoryInitializer</code> configuration shown above uses references like</p>
+<p>model@repoinitTwo:context:/resources/provisioning/model.txt</p>
+<p>Where <em>model</em> means "use the provisioning model format", <em>repoinitTwo</em> is the name of the additional section to read statements from in the provisioning model (without the leading colon) and <em>context:/resources/...</em> is the URL to use to retrieve the provisioning model.</p>
+<p>In this example the URL uses the <em>context</em> scheme defined by the Sling Launchpad, but any scheme can be used provided a suitable URL handler is active.</p>
+<p>The section name in that reference is optional and defaults to <em>repoinit</em>. If it's not specified the <code>@</code> should be omitted as well.</p>
+<h3>References to URLs providing raw repoinit statements</h3>
+<p>Using a <code>RepositoryInitializer</code> reference like in this example, with the <em>raw</em> prefix, means that its content is passed as is to the repoinit parser:</p>
+<p>raw:classpath://some-repoinit-file.txt</p>
+<p>Which points to a <code>classpath:</code> URL to provide the raw repoinit statements in this example, but again any valid URL scheme can be used.</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/bundles/request-analysis.html
----------------------------------------------------------------------
diff --git a/documentation/bundles/request-analysis.html b/documentation/bundles/request-analysis.html
new file mode 100644
index 0000000..75287b2
--- /dev/null
+++ b/documentation/bundles/request-analysis.html
@@ -0,0 +1,68 @@
+<!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>Request Processing Analyzer (reqanalyzer)</h1></header><p>[TOC]</p>
+<h2>Introduction</h2>
+<p>Sling provides a helpful functionality to track progress of requests being processed: The <a href="http://sling.apache.org/apidocs/sling6/org/apache/sling/api/request/RequestProgressTracker.html">RequestProgressTracker</a> which is available through the <a href="http://sling.apache.org/apidocs/sling6/org/apache/sling/api/SlingHttpServletRequest.html#getRequestProgressTracker%28%29">SlingHttpServletRequest</a>.</p>
+<p>This tool provides mechanims to record states of request processing and a simple mechanism to time periods of processing. By default Sling itself uses this tool to track progress through Sling like script resolution and calling scripts.</p>
+<p>Scripts and servlets called during Sling's request processing may themselves use the <code>RequestProgressTracker</code> to log their own processing.</p>
+<p>Usually the data collected by the <code>RequestProgressTracker</code> is just dropped or it may be visible for a certain number of recent requests on the <em>Recent Requests</em> page of the Web Console. When doing load tests, though, this Web Console page is of limited use because a lot more requests are handled than can be displayed in the Web Console.</p>
+<p>This is where the <a href="http://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/reqanalyzer">Request Processing Analyzer</a> comes in handy. When deployed as a bundle it registers as a request level servlet Filter with the Sling Main Servlet. Each request is logged in a special file (currently fixed at <code>${sling.home}/logs/requesttracker.txt</code>) with a header line provding core information on the request:</p>
+<ul>
+ <li>Start time stamp in ms since the Epoch</li>
+ <li>Request processing time in ms</li>
+ <li>Request Method</li>
+ <li>Request URL</li>
+ <li>Response content type (plus character encoding if available)</li>
+ <li>Response Status</li>
+</ul>
+<p>After that first line the complete data from the requests <code>RequestProgressTracker</code> is dumped.</p>
+<h2>Web Console Integration</h2>
+<p>The Request Processing Analyzer is available through the Web Console in the <em>Sling</em> category to</p>
+<ul>
+ <li>Download the <code>requesttracker.txt</code> file as a plain text or ZIP-ed file</li>
+ <li>Launch the Swing-based GUI to analyze the file</li>
+</ul>
+<p>The option to launch the Swing-based GUI is only available if the Sling application is not running in headless mode and if the Web Console is accessed on <em>localhost</em>, that is on the same host as the Sling instance is running.</p>
+<h2>Analyzing the <code>requesttracker.txt</code> file</h2>
+<p>To analyze the <code>requesttracker.txt</code> file the <em>Request Processing Analyzer</em> module can also be used as a standalone Java application. Just start the module using the <code>java</code> command:</p>
+<p>$ java -jar org.apache.sling.reqanalyzer-0.0.1-SNAPSHOT.jar requesttracker.txt</p>
+<p>The command supports two command line arguments:</p>
+<ol>
+ <li>The tracker file (required)</li>
+ <li>The number of requests to load and display from the file. This second option is optional and may be used to limit the request information loaded to the first requests in the file</li>
+</ol>
+<p>After starting and parsing the file, a window is opened showing the core request information in simple table. This table can be sorted by any of the columns by clicking on the column title.</p>
+<p><img src="requesttracker.png" alt="Recorded Requests" /></p>
+<p>Clicking on any row opens a second window displaying the detail request progress information as recorded before with the <code>RequestProgressTracker</code>.</p>
+<p><img src="requesttracker-details.png" alt="Details of a recorded Request" /></p>
+<p>The size, location, and the widths of the table columns are persisted with the Java Preferences API and thus when starting the application again, these settings are preserved.</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/bundles/resource-access-security.html
----------------------------------------------------------------------
diff --git a/documentation/bundles/resource-access-security.html b/documentation/bundles/resource-access-security.html
new file mode 100644
index 0000000..076eedf
--- /dev/null
+++ b/documentation/bundles/resource-access-security.html
@@ -0,0 +1,87 @@
+<!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>Resource Access Security</h1></header><p>Notice: 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.</p>
+<h2>Summary</h2>
+<p>The ResourceAccessSecurity service allows it to restrict access to resources. The access can be granted or denied for read, create, update and delete actions.</p>
+<p>The ResourceAccessSecurity defines a service API which is used in two different context: for securing resource providers which have no own access control and on the application level to further restrict the access to resources in general.</p>
+<p>A resource access security service is registered with the service property “context”. Allowed values are “application” and “provider”. If the value is missing or invalid, the service will be ignored.</p>
+<p>In the context of resource providers, this service might be used for implementations of resource providers where the underlying persistence layer does not implement access control. The goal is to make it easy to implement a lightweight access control for such providers. For example, a JCR resource providers should not use the provider context resource access security - in a JCR context, security is fully delegated to the underlying repository, and mixing security models would be a bad idea.</p>
+<p>In the context of the application, this service might be used to add additional or temporary constraints across the whole resource tree.</p>
+<h2>How to use ResourceAccessSecurity</h2>
+<p>To use the ResourceAccessSecurity service you don’t have to implement the interface ResourceAccessSecurity. Simply add the resourceaccesssecurity bundle to your sling instance. This adds an implementation of the ResourceAccessSecurity service for the provider context (“provider”) and also the application context (“application”).</p>
+<p>Furthermore the implementation of ResourceAccessSecurity defines a service provider interface named ResourceAccessGate. This is the service interface which you can implement and register to control the access to the resources.</p>
+<p>The ResourceAccessGate defines a service API which can be used to make some restrictions to accessing resources. Implementations of this service interface must be registered like ResourceProvider with a path (like provider.roots but with the property name “path”). If different ResourceAccessGate services match a path, not only the ResourceAccessGate with the longest path will be called, but all of them, that's in contrast to the ResourceProvider, but in this case more logical (and secure!). The access gates also must be registered with a context (“application” or “provider”), without a given context, the service will be ignored by ResourceAccessSecurity. The gates will be called in the order of the service ranking. If one of the gates grants access for a given operation access will be granted. An exception are the gates which are registered for “finaloperations”. If such a gate denies resource access no further gate will be asked and access denied (except a gate w
ith higher service ranking has granted access).</p>
+<h3>Service properties</h3>
+<table>
+ <thead>
+ <tr>
+ <th>Property name </th>
+ <th>description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Path </td>
+ <td>regexp to define on which paths the service should be called (default .*)</td>
+ </tr>
+ <tr>
+ <td>operations </td>
+ <td>set of operations on which the service should be called ("read,create,update,delete,execute", default all of them)</td>
+ </tr>
+ <tr>
+ <td>finaloperations </td>
+ <td>set of operations on which the service answer is final and no further service should be called (default none of them), except the GateResult is GateResult.CANT_DECIDE</td>
+ </tr>
+ <tr>
+ <td>context </td>
+ <td>“provider” or “application”. The resource access gate can either have the context “provider”, in this case the gate is only applied to resource providers requesting the security checks. Or the context can be “application”. In this case the access gate is invoked for the whole resource tree. This is indicated by the required service property “context”. If the property is missing or invalid, the service is ignored.</td>
+ </tr>
+ </tbody>
+</table>
+<h3>How to implement ResourceAccessGate</h3>
+<p>The implementation is straightforward. The easiest way is to extend <code>AllowingResourceAccessGate</code> which is exported by the resourceaccesssecurity bundle and does not deny any access. So if you wan’t restrict access on resources for read operations you have to implement to following two methods:</p>
+<p>::java @Override public boolean hasReadRestrictions(final ResourceResolver resourceResolver) { return true; }</p>
+<p>@Override public GateResult canRead(final Resource resource) { GateResult returnValue = GateResult.CANT_DECIDE; if( whatever-condition ) { returnValue = GateResult.GRANTED; } else { returnValue = GateResult.DENIED; }</p>
+<p>return returnValue; }</p>
+<p>And you have to register the ResourceAccessGate with the path where you wan’t to restrict access and the operation property set to “read”. Furthermore you have to decide if the ResourceAccessGate should operate on all resource providers (context=”application”) or only on the resourceproviders flagged with the property useResourceAccessSecurity=true (context=”provider”).</p>
+<p>Tip: We do not recommend to mix up application and provider context in the same application. This can lead to confusing configurations in the ResourceAccessGate implementations.</p>
+<h3>GateResult</h3>
+<p>GateResult does have three states:</p>
+<ul>
+ <li>GateResult.GRANTED</li>
+ <li>GateResult.DENIED</li>
+ <li>GateResult.CANT_DECIDE</li>
+</ul>
+<p>The first two of them are self-explanatory. CANT_DECIDE means that the actual gate neither can grant nor deny the access. If no other gate does return GRANTED or DENIED the access to the resource will be denied for security reasons. CANT-DECIDE comes handy if you declare finaloperations (where no other gate will be called after this gate). If such a gate returns CANT_DECIDE, further gates will be called regardless of the setted finaloperations property.</p>
+<h2>Actual state of ResourceAccessSecurity</h2>
+<p>By now the implementation is complete for securing access on resource level for CRUD operations. It is not yet ready to allow fine granular access rights on values of a resource. So at the moment the <code>canReadValue, canUpdateValue, canDeleteValue</code> and <code>canCreateValue</code> on <code>ResourceAccessGate</code> methods are ignored.</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/bundles/resource-editor.html
----------------------------------------------------------------------
diff --git a/documentation/bundles/resource-editor.html b/documentation/bundles/resource-editor.html
new file mode 100644
index 0000000..abcaacd
--- /dev/null
+++ b/documentation/bundles/resource-editor.html
@@ -0,0 +1,52 @@
+<!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>The Apache Sling Resource Editor</h1></header><p>Notice: 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.</p>
+<p><img src="http://sling.apache.org/documentation/bundles/resource-editor-screenshot.png" alt="alt text" /></p>
+<h1>Features</h1>
+<p>Currently it allows to display the node properties and edit nodes.</p>
+<ul>
+ <li>Node editing includes adding, renaming and deleting nodes.</li>
+ <li>Multi selection of nodes, Keyboard controls for navigation and shortcuts are provided. Click on the info icon in the tree to get detailed information.</li>
+ <li>The node names are HTML and URL encoded.</li>
+ <li>The add node dialog provides you with the allowed node name / node type / resource type options and its combinations to prevent errors soon. Click on the info icon in the dialog to discover more.</li>
+ <li>The nodes are bookmarkable.</li>
+</ul>
+<h1>Status</h1>
+<p>The features for the node tree are finished so far. Now the work on making properties editable begins.</p>
+<h1>Installation</h1>
+<ol>
+ <li>Follow the <a href="http://sling.apache.org/documentation/development/getting-and-building-sling.html">instructions for Getting and Building Sling</a>.</li>
+ <li>The <code>contrib/explorers/resourceeditor/README</code> file in SVN tells you how to install the Resource Editor.</li>
+ <li>Open <code>http://localhost:8080/reseditor/.html</code> in your browser.</li>
+ <li>Enjoy!</li>
+</ol></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/bundles/resource-merger.html
----------------------------------------------------------------------
diff --git a/documentation/bundles/resource-merger.html b/documentation/bundles/resource-merger.html
new file mode 100644
index 0000000..9d50e7b
--- /dev/null
+++ b/documentation/bundles/resource-merger.html
@@ -0,0 +1,142 @@
+<!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>Resource Merger (org.apache.sling.resourcemerger)</h1></header><p>[TOC]</p>
+<h1>Introduction</h1>
+<p><strong>This documentation only applies to versions >= 1.2 (due to major changes done in <a href="https://issues.apache.org/jira/browse/SLING-3423">SLING-3423</a>)</strong></p>
+<p>The Resource Merger bundle provides two resource provider factories</p>
+<ul>
+ <li><code>MergingResourceProvider</code> (only for reading)</li>
+ <li><code>CRUDMergingResourceProvider</code> (for reading and writing)</li>
+</ul>
+<p>Those providers give access to virtual resources which provide a merged view on multiple other resources.</p>
+<p>Each <code>MergedResourcePicker</code> service implementation in the system provides one unique mount point/root path (usually starting with <code>/mnt</code>) exposing a view on merged resources from at least two different locations.</p>
+<p>The exact merging mechanism depends on the resource picker implementation (see below). The order of the merging is important as the overlying resource may overwrite properties/child resources from the underlying resource (but not vice-versa). It is possible to</p>
+<ul>
+ <li>remove existing resource/properties from the underlying resources,</li>
+ <li>modify existing properties/child resources of the underlying resources and</li>
+ <li>add new properties/child resources</li>
+</ul>
+<p>You may use any of the merge properties described below to influence the merging behaviour. All those special properties are not exposed below the mount point.</p>
+<p>The <code>CRUDMergingResourceProvider</code> not only gives read-access to the merged resources but even allows to write. This provider always writes inside the topmost resource path (being returned as last item by the resource picker). Currently both resource pickers shipped with the Sling Resource Merger bundle do not allow to write though. Further details can be found in the description of <a href="https://issues.apache.org/jira/browse/SLING-3909">SLING-3909</a>.</p>
+<h1>Merge Properties</h1>
+<table>
+ <thead>
+ <tr>
+ <th>Property Name </th>
+ <th>Type </th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>sling:hideProperties </td>
+ <td>String[] </td>
+ <td>Hides the properties with the given names. <code>*</code> hides all properties (since version 1.3.2 the wildcard only affects underlying properties and no longer local ones, see also <a href="https://issues.apache.org/jira/browse/SLING-5468">SLING-5468</a>).</td>
+ </tr>
+ <tr>
+ <td>sling:hideChildren</td>
+ <td>String[] </td>
+ <td>Hides the child resources with the given names. <code>*</code> hides all child resources (since version 1.3.2 the wildcard only affects underlying child resources and no longer local ones, see also <a href="https://issues.apache.org/jira/browse/SLING-5468">SLING-5468</a>). If one value starts with <code>!</code> this is a negation (which means the property with the given value should not be hidden). Since by default nothing is hidden the negation is only useful if you specify multiple values for this property. E.g. giving the values <code>[!child1,*]</code> hides all children except for the one with the name <code>child1</code>. If you have a resource name starting with <code>!</code> you must escape it with an additional <code>!</code> in front if you want to reference it in <code>sling:hideChildren</code>, e.g. <code>!!child1</code> means that the resource with the name <code>!child1</code> should be hidden.</td>
+ </tr>
+ <tr>
+ <td>sling:hideResource </td>
+ <td>Boolean </td>
+ <td>If <code>true</code> then the resource with the name which contains this property should not be exposed!</td>
+ </tr>
+ <tr>
+ <td>sling:orderBefore </td>
+ <td>String </td>
+ <td>Contains the name of the preceeding sibling resource. This is influencing the order of resources when calling e.g. <code>Resource.listChildren()</code> or <code>Resource.getChildren()</code> on the merged resource. This is only necessary if the default resource order is not sufficient (see below).</td>
+ </tr>
+ </tbody>
+</table>
+<h1>Child Resource Order</h1>
+<p>For a merged resource the order of its child resources is the following: First the ones from the base resource, then the ones from the overlaying resources. The children only defined by the topmost resource come last.</p>
+<p>In case the same child is defined in more than one resource, its position is taken from the highest overlaying resource (since version 1.3.2, see also <a href="https://issues.apache.org/jira/browse/SLING-4915">SLING-4915</a>). For example:</p>
+<p>base/ +--child1 +--child2 +--child3</p>
+<p>overlay/ +--child4 +--child2 +--child3</p>
+<p>resulting order: child1, child4, child2, child3</p>
+<p>You can overwrite that behaviour by leveraging the <code>sling:orderBefore</code> property.</p>
+<h1>Resource Pickers</h1>
+<h2>Merging Resource Picker (Overlay approach)</h2>
+<table>
+ <thead>
+ <tr>
+ <th>Description </th>
+ <th>Merged Resource Path </th>
+ <th>Merging Order </th>
+ <th>Read-Only </th>
+ <th>Related Ticket</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Merging based on the resource resolver's search path </td>
+ <td><code>/mnt/overlay/<relative resource path></code> </td>
+ <td>Last resource resolver search path first (Order = Descending search paths). </td>
+ <td><code>true</code> </td>
+ <td><a href="http://issues.apache.org/jira/browse/SLING-2986">SLING-2986</a></td>
+ </tr>
+ </tbody>
+</table>
+<p>This picker is thought for globally overlaying content by placing the diff-resource in "/apps" without actually touching anything in "/libs" (since this is only thought for Sling itself). This should be used whenever some deviation of content is desired which is initially shipped with Sling. The client (i.e. the code using the merged resource) does not have to know if there is an overlay in place.</p>
+<h3>Example</h3>
+<p>/libs/sling/example (nt:folder) +-- sling:resourceType = "some/resource/type" +-- child1 (nt:folder) | +-- property1 = "property from /libs/sling/example/child1" +-- child2 (nt:folder) | +-- property1 = "property from /libs/sling/example/child2" +-- child3 (nt:folder) | +-- property1 = "property from /libs/sling/example/child3"</p>
+<p>/apps/sling/example (sling:Folder) +-- property1 = "property added in apps" +-- child1 (nt:folder) | +-- sling:hideResource = true +-- child2 (nt:folder) | +-- property1 = "property from /apps/sling/example/child2" +-- child3 (nt:folder) | +-- property2 = "property from /apps/sling/example/child3"</p>
+<p>/mnt/overlay/sling/example (sling:Folder) +-- sling:resourceType = "some/resource/type" +-- property1 = "property added in apps" +-- child2 (nt:folder) | +-- property1 = "property from /apps/sling/example/child2" +-- child3 (nt:folder) | +-- property1 = "property from /libs/sling/example/child3" | +-- property2 = "property from /apps/sling/example/child3"</p>
+<h2>Overriding Resource Picker (Override approach)</h2>
+<table>
+ <thead>
+ <tr>
+ <th>Description </th>
+ <th>Merged Resource Path </th>
+ <th>Merging Order </th>
+ <th>Read-Only </th>
+ <th>Related Ticket</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Merging based on the <code>sling:resourceSuperType</code> </td>
+ <td><code>/mnt/override/<absolute resource type></code> </td>
+ <td>The topmost resource type (having itself no <code>sling:resourceSuperType</code> defined) is the base. The resources are overlaid in the order from the most generic one to the most specific one (which is the one having the most inheritance levels). </td>
+ <td><code>true</code> </td>
+ <td><a href="https://issues.apache.org/jira/browse/SLING-3657">SLING-3675</a></td>
+ </tr>
+ </tbody>
+</table>
+<p>This picker is thought for extending content of another already existing resource (which should not be modified). The client (i.e. the code using the merged resource) must directly reference the most specific resource type (i.e. it must be aware of the sub resource type).</p>
+<h3>Example</h3>
+<p>/apps/sling/base (nt:folder) +-- child1 (nt:folder) | +-- property1 = "property from /libs/sling/example/child1" +-- child2 (nt:folder) | +-- property1 = "property from /libs/sling/example/child2" +-- child3 (nt:folder) | +-- property1 = "property from /libs/sling/example/child3"</p>
+<p>/apps/sling/example (sling:Folder) +-- sling:resourceSuperType = "/apps/sling/base" +-- property1 = "property added in /apps/sling/example" +-- child1 (nt:folder) | +-- sling:hideResource = true +-- child2 (nt:folder) | +-- property1 = "property from /apps/sling/example/child2" +-- child3 (nt:folder) | +-- property2 = "property from /apps/sling/example/child3"</p>
+<p>/mnt/override/apps/sling/example (sling:Folder) +-- sling:resourceSuperType = "/apps/sling/base" +-- property1 = "property added in /apps/sling/example" +-- child2 (nt:folder) | +-- property1 = "property from /apps/sling/example/child2" +-- child3 (nt:folder) | +-- property1 = "property from /libs/sling/example/child3" | +-- property2 = "property from /apps/sling/example/child3"</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>