You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by gi...@apache.org on 2020/04/27 09:37:18 UTC
[sling-site] branch asf-site updated: Automatic website deployment
from https://builds.apache.org/job/Sling/job/sling-site/job/master/334/
This is an automated email from the ASF dual-hosted git repository.
git-site-role pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 0b1716a Automatic website deployment from https://builds.apache.org/job/Sling/job/sling-site/job/master/334/
0b1716a is described below
commit 0b1716a1b09e5c751ddff5cca8510fd05ef059d2
Author: jenkins <us...@infra.apache.org>
AuthorDate: Mon Apr 27 09:37:12 2020 +0000
Automatic website deployment from https://builds.apache.org/job/Sling/job/sling-site/job/master/334/
---
contributing.html | 25 +-
documentation.html | 43 +-
documentation/apidocs.html | 21 +-
documentation/bundles.html | 131 +-
...filesystem-resources-extensions-fsresource.html | 111 +-
.../bundles/apache-sling-commons-thread-pool.html | 3 +-
.../apache-sling-eventing-and-job-handling.html | 133 +-
...bundle-resources-extensions-bundleresource.html | 29 +-
documentation/bundles/caching-services.html | 6 +-
documentation/bundles/commons-crypto.html | 25 +-
documentation/bundles/commons-html-utilities.html | 3 +-
.../bundles/configuration-installer-factory.html | 115 +-
.../bundles/connection-timeout-agent.html | 47 +-
documentation/bundles/content-distribution.html | 205 +-
.../bundles/content-loading-jcr-contentloader.html | 210 +-
.../bundles/content-package-installer-factory.html | 9 +-
...aware-configuration-default-implementation.html | 55 +-
.../context-aware-configuration-override.html | 25 +-
.../context-aware-configuration-spi.html | 25 +-
.../context-aware-configuration.html | 97 +-
documentation/bundles/datasource-providers.html | 43 +-
documentation/bundles/discovery-api-and-impl.html | 209 +-
documentation/bundles/distribution.html | 195 +-
documentation/bundles/dynamic-includes.html | 85 +-
documentation/bundles/file-installer-provider.html | 51 +-
documentation/bundles/hapi.html | 39 +-
.../bundles/installer-provider-installhook.html | 53 +-
.../bundles/internationalization-support-i18n.html | 105 +-
documentation/bundles/jcr-installer-provider.html | 35 +-
documentation/bundles/log-tracers.html | 113 +-
...aging-permissions-jackrabbit-accessmanager.html | 152 +-
...ng-users-and-groups-jackrabbit-usermanager.html | 475 +--
...content-the-slingpostservlet-servlets-post.html | 706 ++--
documentation/bundles/metrics.html | 53 +-
.../bundles/mime-type-support-commons-mime.html | 68 +-
documentation/bundles/models.html | 438 +--
.../bundles/nosql-resource-providers.html | 31 +-
.../bundles/org-apache-sling-junit-bundles.html | 196 +-
documentation/bundles/osgi-installer.html | 65 +-
...riting-pipelines-org-apache-sling-rewriter.html | 133 +-
.../rendering-content-default-get-servlets.html | 39 +-
.../bundles/repository-initialization.html | 350 +-
documentation/bundles/request-analysis.html | 29 +-
.../bundles/resource-access-security.html | 84 +-
documentation/bundles/resource-editor.html | 29 +-
documentation/bundles/resource-filter.html | 261 +-
documentation/bundles/resource-merger.html | 143 +-
.../scheduler-service-commons-scheduler.html | 87 +-
documentation/bundles/scripting.html | 117 +-
documentation/bundles/scripting/scripting-htl.html | 238 +-
documentation/bundles/scripting/scripting-jsp.html | 565 ++-
.../bundles/scripting/scripting-thymeleaf.html | 55 +-
documentation/bundles/servlet-helpers.html | 9 +-
.../sling-health-check-tool-deprecated.html | 183 +-
documentation/bundles/sling-health-check-tool.html | 45 +-
documentation/bundles/sling-health-checks.html | 52 +-
documentation/bundles/sling-oak-restrictions.html | 203 +-
documentation/bundles/sling-pipes.html | 45 +-
documentation/bundles/sling-pipes/bindings.html | 29 +-
.../bundles/sling-pipes/execution-monitoring.html | 267 +-
documentation/bundles/sling-pipes/logical.html | 49 +-
documentation/bundles/sling-pipes/readers.html | 147 +-
documentation/bundles/sling-pipes/samples.html | 61 +-
documentation/bundles/sling-pipes/writers.html | 81 +-
documentation/bundles/sling-query.html | 57 +-
documentation/bundles/sling-query/basic-ideas.html | 15 +-
documentation/bundles/sling-query/examples.html | 5 +-
.../bundles/sling-query/hierarchy-operators.html | 27 +-
documentation/bundles/sling-query/methods.html | 77 +-
documentation/bundles/sling-query/modifiers.html | 25 +-
documentation/bundles/sling-query/operators.html | 25 +-
documentation/bundles/sling-query/selectors.html | 19 +-
documentation/bundles/sling-query/vs-jcr.html | 47 +-
.../sling-settings-org-apache-sling-settings.html | 110 +-
.../bundles/subsystem-installer-factory.html | 11 +-
documentation/bundles/validation.html | 232 +-
documentation/bundles/web-console-extensions.html | 46 +-
documentation/bundles/xml-support.html | 9 +-
documentation/configuration.html | 231 +-
documentation/development.html | 73 +-
.../development/client-request-logging.html | 361 +-
.../development/dependency-management.html | 104 +-
.../development/deprecating-sling-modules.html | 31 +-
documentation/development/embedding-sling.html | 287 +-
documentation/development/feature-model.html | 3 +-
.../development/getting-and-building-sling.html | 106 +-
documentation/development/hamcrest.html | 9 +-
documentation/development/htl-maven-plugin.html | 3 +-
documentation/development/ide-tooling.html | 123 +-
.../ide-tooling/ide-tooling-incremental-build.html | 17 +-
documentation/development/issue-tracker.html | 147 +-
documentation/development/jcr-mock.html | 35 +-
documentation/development/jspc.html | 3 +-
documentation/development/jsr-305.html | 3 +-
documentation/development/logging.html | 413 +--
documentation/development/maven-archetypes.html | 15 +-
.../development/maven-launchpad-plugin.html | 99 +-
documentation/development/maven-usage.html | 15 +-
documentation/development/maventipsandtricks.html | 17 +-
documentation/development/monitoring-requests.html | 3 +-
documentation/development/null-analysis.html | 41 +-
documentation/development/osgi-mock.html | 67 +-
documentation/development/release-management.html | 429 +--
.../development/repository-based-development.html | 107 +-
.../development/resourceresolver-mock.html | 25 +-
documentation/development/sling-mock.html | 203 +-
documentation/development/sling-testing-tools.html | 65 +-
documentation/development/sling.html | 3 +-
documentation/development/slingstart.html | 361 +-
documentation/development/testing-paxexam.html | 97 +-
documentation/development/version-policy.html | 195 +-
documentation/getting-started.html | 51 +-
.../discover-sling-in-15-minutes.html | 43 +-
documentation/karaf.html | 11 +-
documentation/legacy/logging.html | 221 +-
documentation/pax-exam-utils.html | 3 +-
documentation/the-sling-engine.html | 45 +-
documentation/the-sling-engine/adapters.html | 25 +-
documentation/the-sling-engine/architecture.html | 51 +-
documentation/the-sling-engine/authentication.html | 23 +-
.../authentication/authentication-actors.html | 39 +-
.../authentication-authenticationhandler.html | 86 +-
.../form-based-authenticationhandler.html | 161 +-
.../openid-authenticationhandler.html | 122 +-
.../authentication/authentication-framework.html | 180 +-
.../authentication/authentication-tasks.html | 23 +-
.../default-mapping-and-rendering.html | 3 +-
.../the-sling-engine/dispatching-requests.html | 167 +-
documentation/the-sling-engine/errorhandling.html | 53 +-
documentation/the-sling-engine/featureflags.html | 43 +-
documentation/the-sling-engine/filters.html | 238 +-
.../mappings-for-resource-resolution.html | 161 +-
.../the-sling-engine/request-listeners.html | 56 +-
.../the-sling-engine/request-parameters.html | 143 +-
documentation/the-sling-engine/resources.html | 212 +-
.../the-sling-engine/service-authentication.html | 127 +-
documentation/the-sling-engine/servlets.html | 225 +-
.../the-sling-engine/sling-api-crud-support.html | 59 +-
.../the-sling-engine/sling-properties.html | 151 +-
.../the-sling-engine/the-sling-launchpad.html | 246 +-
.../the-sling-engine/url-decomposition.html | 166 +-
.../the-sling-engine/url-to-script-resolution.html | 79 +-
.../wrap-or-decorate-resources.html | 9 +-
documentation/tutorials-how-tos.html | 15 +-
documentation/tutorials-how-tos/46-line-blog.html | 41 +-
.../getting-resources-and-properties-in-sling.html | 13 +-
.../how-to-manage-events-in-sling.html | 121 +-
.../installing-and-upgrading-bundles.html | 23 +-
.../tutorials-how-tos/jackrabbit-persistence.html | 44 +-
.../testing-sling-based-applications.html | 33 +-
downloads.html | 9 +-
errors/403.html | 7 +-
errors/404.html | 9 +-
guides.html | 3 +-
index.html | 7 +-
links.html | 63 +-
media.html | 3 +-
news.html | 61 +-
news/sling-10-released.html | 36 +-
news/sling-11-released.html | 47 +-
news/sling-ide-tooling-11-released.html | 23 +-
news/sling-ide-tooling-12-released.html | 13 +-
news/sling-launchpad-8-released.html | 31 +-
news/sling-launchpad-9-released.html | 29 +-
old-stuff.html | 3 +-
old-stuff/assembly.html | 75 +-
old-stuff/launch-sling.html | 3 +-
old-stuff/request-processing.html | 56 +-
old-stuff/run-modes-org-apache-sling-runmode.html | 17 +-
old-stuff/scriptengineintegration.html | 19 +-
.../scriptengineintegration/groovy-support.html | 15 +-
.../xslt-processing-pipeline.html | 142 +-
old-stuff/servlet-resolution.html | 113 +-
old-stuff/sling-api.html | 291 +-
project-information.html | 117 +-
...apache-sling-community-roles-and-processes.html | 25 +-
project-information/project-license.html | 3 +-
project-information/project-team.html | 64 +-
project-information/security.html | 15 +-
releases.html | 3857 ++++++++++----------
repolist.html | 3 +-
site-conversion.html | 3 +-
sitemap.html | 2 +-
sitemap.xml | 2 +-
tags/development.html | 2 +-
tags/maven.html | 2 +-
186 files changed, 8691 insertions(+), 12118 deletions(-)
diff --git a/contributing.html b/contributing.html
index d31bb29..def1757 100644
--- a/contributing.html
+++ b/contributing.html
@@ -99,31 +99,32 @@
Contributing
</h1><div class="content is-marginless">
<div class="row"><div><section><p>Thanks for choosing to contribute to Apache Sling! The following are a set of guidelines to follow when contributing to this project.</p>
-<h2><a href="#code-of-conduct" name="code-of-conduct">Code of Conduct</a></h2>
+<h2><a href="#code-of-conduct" id="code-of-conduct">Code of Conduct</a></h2>
<p>Being an Apache project, Apache Sling adheres to the Apache Software Foundation's <a href="https://www.apache.org/foundation/policies/conduct.html">Code of Conduct</a>.</p>
-<h2><a href="#legal" name="legal">Legal</a></h2>
+<h2><a href="#legal" id="legal">Legal</a></h2>
<p>Before contributing to the project, please make sure you understand the <a href="https://www.apache.org/foundation/how-it-works/legal.html">requirements and implications of contributing to the Apache Software Foundation</a>. An <a href="https://www.apache.org/licenses/icla.pdf">Apache iCLA</a> is welcome if you start contributing regularly, and required if you later become a committer.</p>
-<h2><a href="#how-to-contribute" name="how-to-contribute">How to contribute</a></h2>
+<h2><a href="#how-to-contribute" id="how-to-contribute">How to contribute</a></h2>
<p>Apache Sling is a volunteer effort, so there is always plenty of work that needs to be accomplished. If you want to help supporting Apache Sling, this page is intended as a starting point for specific contribution ideas. To further understand how the Sling community operates, refer to the <a href="https://www.apache.org/foundation/how-it-works.html">Community Roles and Processes document</a> and/or join our mailing lists.</p>
<p>See <a href="/project-information.html">Project Information</a> for details about the tools mentioned below.</p>
-<p>The Apache Sling project organizes its "to do" list using the Apache <a href="https://issues.apache.org/jira/browse/SLING">JIRA issue tracking system</a>. No matter if you are a programmer or not, it is probably best to check JIRA first to figure out if the problem you identified is already known. If not, please create a JIRA issue in which you try to describe to the best of your knowledge the bug that you want to fix or the improvement that you would like to contribute. There are man [...]
+<p>The Apache Sling project organizes its "to do" list using the Apache <a href="https://issues.apache.org/jira/browse/SLING">JIRA issue tracking system</a>. No matter if you are a programmer or not, it is probably best to check JIRA first to figure out if the problem you identified is already known. If not, please create a JIRA issue in which you try to describe to the best of your knowledge the bug that you want to fix or the improvement that you would like to contribute. The [...]
<p>If pull requests are familiar to you, the next step is to open one against one of our modules. More details about how the project is structured in terms of repositories can be read on the <a href="/documentation/development/getting-and-building-sling.html">Getting and Building Sling</a> page.</p>
<p>For relatively large contributions (e.g. new modules), we recommend one of the following two approaches:</p>
<ol>
- <li>open a JIRA issue and send a pull request to the <a href="https://github.com/apache/sling-whiteboard/">Apache Sling Whiteboard project</a></li>
- <li>open a JIRA issue and attach your source code to it as a zip or tar archive.</li>
+<li>open a JIRA issue and send a pull request to the <a href="https://github.com/apache/sling-whiteboard/">Apache Sling Whiteboard project</a></li>
+<li>open a JIRA issue and attach your source code to it as a zip or tar archive.</li>
</ol>
<p>For people who are completely new to contributing to an Apache Software Foundation project, the <a href="https://www.apache.org/foundation/getinvolved.html">Get Involved</a> page provides you with enough resources to understand how the foundation works and how its projects are structured - and don't hesitate to ask on our <a href="http://sling.apache.org/project-information.html#mailing-lists">mailing lists</a>!</p>
-<h3><a href="#testing" name="testing">Testing</a></h3>
+<h3><a href="#testing" id="testing">Testing</a></h3>
<p>Each Sling module comes with an automated build, usually based on Apache Maven. Your change should be covered by new unit tests that verify that the changes work as expected.</p>
<p>In case your changes are more far-reaching and the module you are contributing to is part of the <a href="https://github.com/apache/sling-org-apache-sling-starter">Sling Starter</a>, it is a good idea to also run the Sling Starter integration tests. This can be achieved by doing the following:</p>
<ul>
- <li>Check out the <a href="https://github.com/apache/sling-org-apache-sling-starter">Sling Starter</a> and <a href="https://github.com/apache/sling-org-apache-sling-launchpad-testing">Sling Starter Integration Tests</a> projects. This step can be skipped if you have followed the steps to checkout all Sling repositories as documented at <a href="/documentation/development/getting-and-building-sling.html#getting-the-sling-source">Getting and Building Sling</a></li>
- <li>Use the latest version of the bundle(s) you changed in the Sling Starter. Running <code>git grep ${ARTIFACT_ID}</code> will indicate the potential places where you need to make changes</li>
- <li>Run <code>mvn clean install</code> in the Sling Starter checkout. This runs a set of Smoke tests and allows the integration tests to use the version of the starter that you just built</li>
- <li>Run <code>mvn clean install</code> in the Sling Starter Integration Tests checkout</li>
+<li>Check out the <a href="https://github.com/apache/sling-org-apache-sling-starter">Sling Starter</a> and <a href="https://github.com/apache/sling-org-apache-sling-launchpad-testing">Sling Starter Integration Tests</a> projects. This step can be skipped if you have followed the steps to checkout all Sling repositories as documented at <a href="/documentation/development/getting-and-building-sling.html#getting-the-sling-source">Getting and Building Sling</a></li>
+<li>Use the latest version of the bundle(s) you changed in the Sling Starter. Running <code>git grep ${ARTIFACT_ID}</code> will indicate the potential places where you need to make changes</li>
+<li>Run <code>mvn clean install</code> in the Sling Starter checkout. This runs a set of Smoke tests and allows the integration tests to use the version of the starter that you just built</li>
+<li>Run <code>mvn clean install</code> in the Sling Starter Integration Tests checkout</li>
</ul>
-<p>Additionally, and PR you submit will eventually be built by Jenkins, with additional validations on top of the plain Maven build.</p></section></div></div>
+<p>Additionally, and PR you submit will eventually be built by Jenkins, with additional validations on top of the plain Maven build.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation.html b/documentation.html
index 2a22881..4589229 100644
--- a/documentation.html
+++ b/documentation.html
@@ -116,38 +116,39 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h1><a href="#overview" name="overview">Overview</a></h1>
+<h1><a href="#overview" id="overview">Overview</a></h1>
<p>The documentation is split into different parts:</p>
<ul>
- <li><a href="/documentation/getting-started.html">Getting Started</a>, the right place to start!</li>
- <li><a href="/documentation/the-sling-engine.html">The Sling Engine</a>, all about the heart of Sling</li>
- <li><a href="/documentation/development.html">Development</a>, how do I get and develop with Sling</li>
- <li><a href="/documentation/bundles.html">Bundles</a>, which bundle delivers which features to Sling</li>
- <li><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a></li>
- <li><a href="http://cwiki.apache.org/SLING/">Wiki</a></li>
- <li><a href="/documentation/configuration.html">Configuration</a></li>
- <li><a href="http://sling.apache.org/apidocs/sling8/index.html">API Doc</a></li>
+<li><a href="/documentation/getting-started.html">Getting Started</a>, the right place to start!</li>
+<li><a href="/documentation/the-sling-engine.html">The Sling Engine</a>, all about the heart of Sling</li>
+<li><a href="/documentation/development.html">Development</a>, how do I get and develop with Sling</li>
+<li><a href="/documentation/bundles.html">Bundles</a>, which bundle delivers which features to Sling</li>
+<li><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a></li>
+<li><a href="http://cwiki.apache.org/SLING/">Wiki</a></li>
+<li><a href="/documentation/configuration.html">Configuration</a></li>
+<li><a href="http://sling.apache.org/apidocs/sling8/index.html">API Doc</a></li>
</ul>
-<h1><a href="#how-you-can-contribute" name="how-you-can-contribute">How you can contribute</a></h1>
+<h1><a href="#how-you-can-contribute" id="how-you-can-contribute">How you can contribute</a></h1>
<p>We're on the way to improve the documentation, but it's a long way. If you would like to contribute to the documentation you are very welcome. Please directly post your proposals to the <a href="http://cwiki.apache.org/SLING/">public wiki</a> or post your suggestions to the <a href="/project-information.html">mailing list</a>.</p>
-<h1><a href="#how-the-documentation-is-generated" name="how-the-documentation-is-generated">How the documentation is generated</a></h1>
+<h1><a href="#how-the-documentation-is-generated" id="how-the-documentation-is-generated">How the documentation is generated</a></h1>
<p>The basic documentation of Sling is made up of four parts:</p>
<ol>
- <li>The Sling Site at http://sling.apache.org/ (you are here)</li>
- <li>The Public Wiki at http://cwiki.apache.org/SLING</li>
- <li>The JavaDoc</li>
- <li>The Maven plugin documentation</li>
+<li>The Sling Site at http://sling.apache.org/ (you are here)</li>
+<li>The Public Wiki at http://cwiki.apache.org/SLING</li>
+<li>The JavaDoc</li>
+<li>The Maven plugin documentation</li>
</ol>
<p>This page is about how this documentation is maintained and who is allowed to do what.</p>
-<h2><a href="#the-sling-website" name="the-sling-website">The Sling Website</a></h2>
+<h2><a href="#the-sling-website" id="the-sling-website">The Sling Website</a></h2>
<p>The website is built from a dedicated repository as described <a href="/project-information.html#documentation-repository">Project Information</a>.</p>
-<h2><a href="#the-public-wiki" name="the-public-wiki">The Public Wiki</a></h2>
-<p>The public wiki of Sling is available at <a href="http://cwiki.apache.org/SLING">http://cwiki.apache.org/SLING</a> and is maintained in the Confluence space <em>SLING</em>. Everyone can create an account there. To gain edit rights please ask via the <a href="/project-information.html">mailing list</a>. Any of the administrators listed in the <a href="https://cwiki.apache.org/confluence/spaces/viewspacesummary.action?key=SLING&showAllAdmins=true">Space Overview</a> can give you access.</p>
-<h2><a href="#the-javadoc" name="the-javadoc">The JavaDoc</a></h2>
+<h2><a href="#the-public-wiki" id="the-public-wiki">The Public Wiki</a></h2>
+<p>The public wiki of Sling is available at <a href="http://cwiki.apache.org/SLING">http://cwiki.apache.org/SLING</a> and is maintained in the Confluence space <em>SLING</em>. Everyone can create an account there. To gain edit rights please ask via the <a href="/project-information.html">mailing list</a>. Any of the administrators listed in the <a href="https://cwiki.apache.org/confluence/spaces/viewspacesummary.action?key=SLING&showAllAdmins=true">Space Overview</a> can give you acc [...]
+<h2><a href="#the-javadoc" id="the-javadoc">The JavaDoc</a></h2>
<p>With every major release of Sling the JavaDoc of all containing bundles are published below <a href="http://sling.apache.org/apidocs/">http://sling.apache.org/apidocs/</a>. The script for generating this aggregation JavaDoc is in the sling-tooling-release repo, at <a href="https://github.com/apache/sling-tooling-release/blob/master/generate_javadoc_for_release.sh">generate_javadoc_for_release.sh</a>.</p>
<p>In addition every released bundle is released together with its JavaDoc (which is also pushed to Maven Central).</p>
-<h2><a href="#the-maven-plugin-documentation" name="the-maven-plugin-documentation">The Maven Plugin Documentation</a></h2>
-<p>For the most important Maven Plugins the according Maven Sites (generated with the <code>maven-site-plugin</code>) are published at <a href="http://sling.apache.org/components/">http://sling.apache.org/components/</a>. The description on how to publish can be found at <a href="/documentation/development/release-management.html">Release Management</a>.</p></section></div></div>
+<h2><a href="#the-maven-plugin-documentation" id="the-maven-plugin-documentation">The Maven Plugin Documentation</a></h2>
+<p>For the most important Maven Plugins the according Maven Sites (generated with the <code>maven-site-plugin</code>) are published at <a href="http://sling.apache.org/components/">http://sling.apache.org/components/</a>. The description on how to publish can be found at <a href="/documentation/development/release-management.html">Release Management</a>.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/apidocs.html b/documentation/apidocs.html
index a840e8f..65cd39e 100644
--- a/documentation/apidocs.html
+++ b/documentation/apidocs.html
@@ -106,20 +106,21 @@
</div><h1 class="title">
API Docs
</h1><div class="content is-marginless">
-<div class="row"><div><section><h2><a href="#sling-api-documentation" name="sling-api-documentation">Sling API Documentation</a></h2>
+<div class="row"><div><section><h2><a href="#sling-api-documentation" id="sling-api-documentation">Sling API Documentation</a></h2>
<p>Use these links to access the API docs of the various Sling versions:</p>
<ul>
- <li><a href="/apidocs/sling11/index.html">Sling 11</a></li>
- <li><a href="/apidocs/sling10/index.html">Sling 10</a></li>
- <li><a href="/apidocs/sling9/index.html">Sling 9</a></li>
- <li><a href="/apidocs/sling8/index.html">Sling 8</a></li>
- <li><a href="/apidocs/sling7/index.html">Sling 7</a></li>
- <li><a href="/apidocs/sling6/index.html">Sling 6</a></li>
- <li><a href="/apidocs/sling5/index.html">Sling 5</a></li>
+<li><a href="/apidocs/sling11/index.html">Sling 11</a></li>
+<li><a href="/apidocs/sling10/index.html">Sling 10</a></li>
+<li><a href="/apidocs/sling9/index.html">Sling 9</a></li>
+<li><a href="/apidocs/sling8/index.html">Sling 8</a></li>
+<li><a href="/apidocs/sling7/index.html">Sling 7</a></li>
+<li><a href="/apidocs/sling6/index.html">Sling 6</a></li>
+<li><a href="/apidocs/sling5/index.html">Sling 5</a></li>
</ul>
-<p>These apply to the "big" Sling releases, but in between those we often release individual modules, including their version-specific javadocs.</p>
+<p>These apply to the "big" Sling releases, but in between those we often release individual modules, including their version-specific javadocs.</p>
<p><a href="http://www.javadoc.io/">javadocs.io</a> also provides archived javadocs for all Sling modules, and actually for all open source software hosted at Maven Central.</p>
-<p>To get the javadocs of a particular module there, use an URL like <code>http://javadoc.io/doc/{org}/{artifact}/{version}</code>, like for example <a href="http://www.javadoc.io/doc/org.apache.sling/org.apache.sling.api/2.9.0">http://www.javadoc.io/doc/org.apache.sling/org.apache.sling.api/2.9.0</a></p></section></div></div>
+<p>To get the javadocs of a particular module there, use an URL like <code>http://javadoc.io/doc/{org}/{artifact}/{version}</code>, like for example <a href="http://www.javadoc.io/doc/org.apache.sling/org.apache.sling.api/2.9.0">http://www.javadoc.io/doc/org.apache.sling/org.apache.sling.api/2.9.0</a></p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles.html b/documentation/bundles.html
index 72fd57f..af693e9 100644
--- a/documentation/bundles.html
+++ b/documentation/bundles.html
@@ -114,88 +114,89 @@
</li>
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
-<div class="row"><div><section><h2><a href="#bundles-and-git-repositories" name="bundles-and-git-repositories">Bundles and Git repositories</a></h2>
+<div class="row"><div><section><h2><a href="#bundles-and-git-repositories" id="bundles-and-git-repositories">Bundles and Git repositories</a></h2>
<p>This is a manually maintained list of Sling bundles which have their documentation here.</p>
-<p>See also the <a href="/repolist.html">complete list of modules</a> - some of them have their own "local" documentation in their README files instead of here.</p>
-<h2><a href="#content" name="content">Content</a></h2>
+<p>See also the <a href="/repolist.html">complete list of modules</a> - some of them have their own "local" documentation in their README files instead of here.</p>
+<h2><a href="#content" id="content">Content</a></h2>
<ul>
- <li><a href="/documentation/bundles/content-loading-jcr-contentloader.html">Content Loading (jcr.contentloader)</a></li>
- <li><a href="/documentation/bundles/internationalization-support-i18n.html">Internationalization Support (i18n)</a></li>
- <li><a href="/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html">Manipulating Content - The SlingPostServlet (servlets.post)</a></li>
- <li><a href="/documentation/bundles/rendering-content-default-get-servlets.html">Rendering Content - Default GET servlets (servlets.get)</a></li>
- <li><a href="/documentation/bundles/validation.html">Validation</a></li>
- <li><a href="/documentation/bundles/repository-initialization.html">Repository Initialization</a></li>
- <li><a href="/documentation/bundles/distribution.html">Distribution</a></li>
- <li><a href="/documentation/bundles/resource-filter.html">Filtering Resource Streams</a></li>
+<li><a href="/documentation/bundles/content-loading-jcr-contentloader.html">Content Loading (jcr.contentloader)</a></li>
+<li><a href="/documentation/bundles/internationalization-support-i18n.html">Internationalization Support (i18n)</a></li>
+<li><a href="/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html">Manipulating Content - The SlingPostServlet (servlets.post)</a></li>
+<li><a href="/documentation/bundles/rendering-content-default-get-servlets.html">Rendering Content - Default GET servlets (servlets.get)</a></li>
+<li><a href="/documentation/bundles/validation.html">Validation</a></li>
+<li><a href="/documentation/bundles/repository-initialization.html">Repository Initialization</a></li>
+<li><a href="/documentation/bundles/distribution.html">Distribution</a></li>
+<li><a href="/documentation/bundles/resource-filter.html">Filtering Resource Streams</a></li>
</ul>
-<h2><a href="#resource-providers" name="resource-providers">Resource Providers</a></h2>
+<h2><a href="#resource-providers" id="resource-providers">Resource Providers</a></h2>
<ul>
- <li><a href="/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html">Accessing File System Resources (org.apache.sling.fsresource)</a></li>
- <li><a href="/documentation/bundles/bundle-resources-extensions-bundleresource.html">Bundle Resources (org.apache.sling.bundleresource.impl)</a></li>
- <li><a href="/documentation/bundles/nosql-resource-providers.html">NoSQL Resource Providers (org.apache.sling.nosql)</a></li>
- <li><a href="/documentation/bundles/resource-merger.html">Resource Merger (org.apache.sling.resourcemerger)</a></li>
+<li><a href="/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html">Accessing File System Resources (org.apache.sling.fsresource)</a></li>
+<li><a href="/documentation/bundles/bundle-resources-extensions-bundleresource.html">Bundle Resources (org.apache.sling.bundleresource.impl)</a></li>
+<li><a href="/documentation/bundles/nosql-resource-providers.html">NoSQL Resource Providers (org.apache.sling.nosql)</a></li>
+<li><a href="/documentation/bundles/resource-merger.html">Resource Merger (org.apache.sling.resourcemerger)</a></li>
</ul>
-<h2><a href="#users-groups-access-permissions-acls-on-resources" name="users-groups-access-permissions-acls-on-resources">Users, Groups, Access, Permissions, ACLs on Resources</a></h2>
+<h2><a href="#users-groups-access-permissions-acls-on-resources" id="users-groups-access-permissions-acls-on-resources">Users, Groups, Access, Permissions, ACLs on Resources</a></h2>
<ul>
- <li><a href="/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html">Managing users and groups (jackrabbit.usermanager)</a></li>
- <li><a href="/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html">Managing permissions (jackrabbit.accessmanager)</a></li>
- <li><a href="/documentation/bundles/resource-access-security.html">Resource Access Security (resourceaccesssecurity)</a></li>
- <li><a href="/documentation/bundles/sling-oak-restrictions.html">Sling Oak Restrictions (sling-oak-restrictions)</a></li>
+<li><a href="/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html">Managing users and groups (jackrabbit.usermanager)</a></li>
+<li><a href="/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html">Managing permissions (jackrabbit.accessmanager)</a></li>
+<li><a href="/documentation/bundles/resource-access-security.html">Resource Access Security (resourceaccesssecurity)</a></li>
+<li><a href="/documentation/bundles/sling-oak-restrictions.html">Sling Oak Restrictions (sling-oak-restrictions)</a></li>
</ul>
-<h2><a href="#osgi-installer" name="osgi-installer">OSGi Installer</a></h2>
+<h2><a href="#osgi-installer" id="osgi-installer">OSGi Installer</a></h2>
<p>The OSGi installer is a very flexible and powerful service to manage provisioning and updates of an OSGi system. It is independent of Sling and can be extended by several plugins.</p>
<ul>
- <li><a href="/documentation/bundles/osgi-installer.html">OSGi Installer</a></li>
- <li><a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a></li>
- <li><a href="/documentation/bundles/content-package-installer-factory.html">Content Package Installer Factory</a></li>
- <li><a href="/documentation/bundles/subsystem-installer-factory.html">Subsystem Installer Factory (deprecated)</a></li>
- <li><a href="/documentation/bundles/jcr-installer-provider.html">JCR Installer Provider</a></li>
- <li><a href="/documentation/bundles/file-installer-provider.html">File Installer Provider</a></li>
- <li><a href="/documentation/bundles/installer-provider-installhook.html">Vault Package Install Hook</a></li>
+<li><a href="/documentation/bundles/osgi-installer.html">OSGi Installer</a></li>
+<li><a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a></li>
+<li><a href="/documentation/bundles/content-package-installer-factory.html">Content Package Installer Factory</a></li>
+<li><a href="/documentation/bundles/subsystem-installer-factory.html">Subsystem Installer Factory (deprecated)</a></li>
+<li><a href="/documentation/bundles/jcr-installer-provider.html">JCR Installer Provider</a></li>
+<li><a href="/documentation/bundles/file-installer-provider.html">File Installer Provider</a></li>
+<li><a href="/documentation/bundles/installer-provider-installhook.html">Vault Package Install Hook</a></li>
</ul>
-<h2><a href="#development-and-utilities" name="development-and-utilities">Development and Utilities</a></h2>
+<h2><a href="#development-and-utilities" id="development-and-utilities">Development and Utilities</a></h2>
<ul>
- <li><a href="/documentation/bundles/commons-crypto.html">Commons Crypto</a></li>
- <li><a href="/documentation/bundles/apache-sling-commons-thread-pool.html">Commons Thread Pools</a></li>
- <li><a href="/documentation/bundles/commons-html-utilities.html">Commons HTML Utilities</a></li>
- <li><a href="/documentation/bundles/mime-type-support-commons-mime.html">MIME Type Support (commons.mime and commons.contentdetection)</a></li>
- <li><a href="/documentation/bundles/scripting.html">Scripting</a></li>
- <li><a href="/documentation/bundles/sling-settings-org-apache-sling-settings.html">Sling Settings (org.apache.sling.settings)</a></li>
- <li><a href="/documentation/bundles/caching-services.html">Caching Services</a></li>
- <li><a href="/documentation/bundles/models.html">Sling Models</a></li>
- <li><a href="/documentation/pax-exam-utils.html">Sling Pax Exam Utilities</a></li>
- <li><a href="/documentation/bundles/sling-query.html">Sling Query Library</a></li>
- <li><a href="/documentation/bundles/org-apache-sling-junit-bundles.html">Junit Server-Side Tests Support</a></li>
- <li><a href="/documentation/bundles/sling-pipes.html">Sling Pipes</a></li>
- <li><a href="/documentation/bundles/metrics.html">Sling Metrics</a></li>
- <li><a href="/documentation/bundles/servlet-helpers.html">Servlet Helpers</a></li>
- <li><a href="/documentation/bundles/context-aware-configuration/context-aware-configuration.html">Context-Aware Configuration</a></li>
- <li><a href="/documentation/bundles/hapi.html">HApi - Hypermedia API tools</a></li>
- <li><a href="https://github.com/apache/sling-org-apache-sling-capabilities">Capabilities</a></li>
- <li><a href="/documentation/bundles/connection-timeout-agent.html">Connection Timeout Agent</a></li>
+<li><a href="/documentation/bundles/commons-crypto.html">Commons Crypto</a></li>
+<li><a href="/documentation/bundles/apache-sling-commons-thread-pool.html">Commons Thread Pools</a></li>
+<li><a href="/documentation/bundles/commons-html-utilities.html">Commons HTML Utilities</a></li>
+<li><a href="/documentation/bundles/mime-type-support-commons-mime.html">MIME Type Support (commons.mime and commons.contentdetection)</a></li>
+<li><a href="/documentation/bundles/scripting.html">Scripting</a></li>
+<li><a href="/documentation/bundles/sling-settings-org-apache-sling-settings.html">Sling Settings (org.apache.sling.settings)</a></li>
+<li><a href="/documentation/bundles/caching-services.html">Caching Services</a></li>
+<li><a href="/documentation/bundles/models.html">Sling Models</a></li>
+<li><a href="/documentation/pax-exam-utils.html">Sling Pax Exam Utilities</a></li>
+<li><a href="/documentation/bundles/sling-query.html">Sling Query Library</a></li>
+<li><a href="/documentation/bundles/org-apache-sling-junit-bundles.html">Junit Server-Side Tests Support</a></li>
+<li><a href="/documentation/bundles/sling-pipes.html">Sling Pipes</a></li>
+<li><a href="/documentation/bundles/metrics.html">Sling Metrics</a></li>
+<li><a href="/documentation/bundles/servlet-helpers.html">Servlet Helpers</a></li>
+<li><a href="/documentation/bundles/context-aware-configuration/context-aware-configuration.html">Context-Aware Configuration</a></li>
+<li><a href="/documentation/bundles/hapi.html">HApi - Hypermedia API tools</a></li>
+<li><a href="https://github.com/apache/sling-org-apache-sling-capabilities">Capabilities</a></li>
+<li><a href="/documentation/bundles/connection-timeout-agent.html">Connection Timeout Agent</a></li>
</ul>
-<h2><a href="#content-presentation-and-rendering" name="content-presentation-and-rendering">Content Presentation and Rendering</a></h2>
+<h2><a href="#content-presentation-and-rendering" id="content-presentation-and-rendering">Content Presentation and Rendering</a></h2>
<ul>
- <li><a href="/documentation/bundles/scripting.html">Scripting</a> (aka Templating)</li>
- <li><a href="/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html">Output Rewriting Pipelines (org.apache.sling.rewriter)</a></li>
- <li><a href="/documentation/bundles/xml-support.html">XML Support</a></li>
- <li><a href="/documentation/bundles/resource-editor.html">Sling Resource Editor</a></li>
- <li><a href="/documentation/bundles/dynamic-includes.html">Sling Dynamic Include (org.apache.sling.dynamic-include)</a></li>
+<li><a href="/documentation/bundles/scripting.html">Scripting</a> (aka Templating)</li>
+<li><a href="/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html">Output Rewriting Pipelines (org.apache.sling.rewriter)</a></li>
+<li><a href="/documentation/bundles/xml-support.html">XML Support</a></li>
+<li><a href="/documentation/bundles/resource-editor.html">Sling Resource Editor</a></li>
+<li><a href="/documentation/bundles/dynamic-includes.html">Sling Dynamic Include (org.apache.sling.dynamic-include)</a></li>
</ul>
-<h2><a href="#troubleshooting" name="troubleshooting">Troubleshooting</a></h2>
+<h2><a href="#troubleshooting" id="troubleshooting">Troubleshooting</a></h2>
<ul>
- <li><a href="/documentation/bundles/request-analysis.html">Request Processing Analyzer (org.apache.sling.reqanalyzer)</a></li>
- <li><a href="/documentation/bundles/sling-health-check-tool.html">Sling Health Check Tool</a></li>
+<li><a href="/documentation/bundles/request-analysis.html">Request Processing Analyzer (org.apache.sling.reqanalyzer)</a></li>
+<li><a href="/documentation/bundles/sling-health-check-tool.html">Sling Health Check Tool</a></li>
</ul>
-<h2><a href="#misc" name="misc">Misc</a></h2>
+<h2><a href="#misc" id="misc">Misc</a></h2>
<ul>
- <li><a href="/documentation/bundles/apache-sling-eventing-and-job-handling.html">Eventing and Job Handling</a></li>
- <li><a href="/documentation/bundles/scheduler-service-commons-scheduler.html">Scheduler Service (commons scheduler)</a></li>
- <li><a href="/documentation/bundles/web-console-extensions.html">Web Console Extensions (org.apache.sling.extensions.webconsolebranding, org.apache.sling.extensions.webconsolesecurityprovider)</a></li>
- <li><a href="/documentation/bundles/discovery-api-and-impl.html">Discovery API and its Implementations (discovery.api, discovery.impl)</a></li>
- <li><a href="/documentation/bundles/datasource-providers.html">Datasource Provider</a></li>
- <li><a href="/documentation/bundles/log-tracers.html">Log Tracer</a></li>
-</ul></section></div></div>
+<li><a href="/documentation/bundles/apache-sling-eventing-and-job-handling.html">Eventing and Job Handling</a></li>
+<li><a href="/documentation/bundles/scheduler-service-commons-scheduler.html">Scheduler Service (commons scheduler)</a></li>
+<li><a href="/documentation/bundles/web-console-extensions.html">Web Console Extensions (org.apache.sling.extensions.webconsolebranding, org.apache.sling.extensions.webconsolesecurityprovider)</a></li>
+<li><a href="/documentation/bundles/discovery-api-and-impl.html">Discovery API and its Implementations (discovery.api, discovery.impl)</a></li>
+<li><a href="/documentation/bundles/datasource-providers.html">Datasource Provider</a></li>
+<li><a href="/documentation/bundles/log-tracers.html">Log Tracer</a></li>
+</ul>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html b/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html
index 146ebc4..466d6e4 100644
--- a/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html
+++ b/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html
@@ -120,91 +120,59 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h2><a href="#introduction" name="introduction">Introduction</a></h2>
+<h2><a href="#introduction" id="introduction">Introduction</a></h2>
<p>The Apache Sling File System Resource Provider provides access to the operating system's file system through the Sling <code>ResourceResolver</code>. Multiple locations may be mapped into the resource tree by configuring the file system location and the resource tree root path for each location to be mapped. The provider supports mapping folders and files as binaries, and content structures stored in JSON files or FileVault XML format.</p>
<p>To activate this feature, install the <code>org.apache.sling.fsresource</code> bundle. You can get it from the Sling downloads page or from <a href="https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.sling%22%20AND%20a%3A%22org.apache.sling.fsresource%22">Maven Central</a>.</p>
<p>Currently two major versions are maintained - choose the correct version depending on your Sling environment:</p>
<ul>
- <li>fsresource 2.x (<a href="https://github.com/apache/sling-org-apache-sling-fsresource">trunk</a>): compatible with Apache Sling API 2.11 and Apache Sling Resource Resolver 1.5.18 or above.</li>
- <li>fsresource 1.x (<a href="https://github.com/apache/sling-org-apache-sling-fsresource/tree/release/1.x">branch</a>): compatible with Apache Sling API 2.4 and Apache Sling Resource Resolver 1.1.0 or above.</li>
+<li>fsresource 2.x (<a href="https://github.com/apache/sling-org-apache-sling-fsresource">trunk</a>): compatible with Apache Sling API 2.11 and Apache Sling Resource Resolver 1.5.18 or above.</li>
+<li>fsresource 1.x (<a href="https://github.com/apache/sling-org-apache-sling-fsresource/tree/release/1.x">branch</a>): compatible with Apache Sling API 2.4 and Apache Sling Resource Resolver 1.1.0 or above.</li>
</ul>
-<h2><a href="#resource-types" name="resource-types">Resource Types</a></h2>
+<h2><a href="#resource-types" id="resource-types">Resource Types</a></h2>
<p>Files and directories are mapped into the resource tree as regular <code>Resource</code> instances whose resource type depends on the actual nature of the mapped file system resource:</p>
<ul>
- <li>Regular files are assigned the <code>nt:file</code> resource type</li>
- <li>Directories are assigned the <code>nt:folder</code> resource type</li>
+<li>Regular files are assigned the <code>nt:file</code> resource type</li>
+<li>Directories are assigned the <code>nt:folder</code> resource type</li>
</ul>
<p>Content stored in JSON or FileVault XML files are mapped with the resource type stored in the files. If a resource type is missing <code>nt:unstructured</code> is used as fallback.</p>
-<h2><a href="#adapters" name="adapters">Adapters</a></h2>
+<h2><a href="#adapters" id="adapters">Adapters</a></h2>
<p>File system resources extend from Sling's <code>AbstractResource</code> class and thus are adaptable to any type for which an <code>AdapterFactory</code> is registered supporting file system resources. In addition File system Resources support the following adapters natively:</p>
<ul>
- <li><code>java.io.File</code> -- The Java file object providing access to the file system file</li>
- <li><code>java.net.URL</code> -- A valid <code>file://</code> URL to the file. This URL is derived from the <code>java.io.File</code> object by calling the <code>File.toURI().toURL()</code> sequence.</li>
- <li><code>java.io.InputStream</code> -- If the <code>java.io.File</code> can be read from (as per <code>File.canRead()</code> an <code>InputStream</code> to read from the file is returned.</li>
+<li><code>java.io.File</code> -- The Java file object providing access to the file system file</li>
+<li><code>java.net.URL</code> -- A valid <code>file://</code> URL to the file. This URL is derived from the <code>java.io.File</code> object by calling the <code>File.toURI().toURL()</code> sequence.</li>
+<li><code>java.io.InputStream</code> -- If the <code>java.io.File</code> can be read from (as per <code>File.canRead()</code> an <code>InputStream</code> to read from the file is returned.</li>
</ul>
-<h2><a href="#configuration" name="configuration">Configuration</a></h2>
-<p>The File System Resource Provider is configured with OSGi Configuration Admin factory configurtions whose factory PID is <code>org.apache.sling.fsprovider.internal.FsResourceProvider</code>. Configuration can be managed using the OSGi Configuration Admin API, through the Web Console or by any other means supporting Configuration Admin configurations. Each configuration "mounts" a specific file system path into the resource hierarchy.</p>
+<h2><a href="#configuration" id="configuration">Configuration</a></h2>
+<p>The File System Resource Provider is configured with OSGi Configuration Admin factory configurtions whose factory PID is <code>org.apache.sling.fsprovider.internal.FsResourceProvider</code>. Configuration can be managed using the OSGi Configuration Admin API, through the Web Console or by any other means supporting Configuration Admin configurations. Each configuration "mounts" a specific file system path into the resource hierarchy.</p>
<p>Which files are mounted depends on the 'File system layout' configuration parameter:</p>
<ul>
- <li>FILES_FOLDERS (default): Support only files and folders (classic mode).</li>
- <li>INITIAL_CONTENT: Sling-Initial-Content filesystem layout, supports file and folders ant content files in JSON and jcr.xml format.</li>
- <li>FILEVAULT_XML: FileVault XML format (expanded content package).</li>
+<li>FILES_FOLDERS (default): Support only files and folders (classic mode).</li>
+<li>INITIAL_CONTENT: Sling-Initial-Content filesystem layout, supports file and folders ant content files in JSON and jcr.xml format.</li>
+<li>FILEVAULT_XML: FileVault XML format (expanded content package).</li>
</ul>
<p>Configuration parameters for each mapping:</p>
<table>
- <thead>
- <tr>
- <th>Parameter </th>
- <th>Name </th>
- <th>Description </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>File System Root </td>
- <td><code>provider.file</code> </td>
- <td>File system directory mapped to the virtual resource tree. This property must not be an empty string. If the path is relative it is resolved against sling.home or the current working directory. The path may be a file or folder. If the path does not address an existing file or folder, an empty folder is created. </td>
- </tr>
- <tr>
- <td>Provider Root </td>
- <td><code>provider.root</code> (2.x), <code>provider.roots</code> (1.x) </td>
- <td>Location in the virtual resource tree where the file system resources are mapped in. This property must not be an empty string. Only one path is supported. </td>
- </tr>
- <tr>
- <td>File system layout </td>
- <td><code>provider.fs.mode</code> </td>
- <td>File system layout mode for files, folders and content. </td>
- </tr>
- <tr>
- <td>Init. Content Options </td>
- <td><code>provider.initial.content.import.options</code> </td>
- <td>Import options for Sling-Initial-Content file system layout. Supported options: overwrite, ignoreImportProviders. </td>
- </tr>
- <tr>
- <td>FileVault Filter </td>
- <td><code>provider.filevault.filterxml.path</code> </td>
- <td>Path to META-INF/vault/filter.xml when using FileVault XML file system layout. </td>
- </tr>
- <tr>
- <td>Check Interval </td>
- <td><code>provider.checkinterval</code> </td>
- <td>If the interval has a value higher than 100, the provider will check the file system for changes periodically. This interval defines the period in milliseconds (the default is 1000). If a change is detected, resource events are sent through the event admin. </td>
- </tr>
- <tr>
- <td>Cache Size </td>
- <td><code>provider.cache.size</code> </td>
- <td>Max. number of content files cached in memory. </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Parameter </th><th> Name </th><th> Description </th></tr>
+</thead>
+<tbody>
+<tr><td> File System Root </td><td> <code>provider.file</code> </td><td> File system directory mapped to the virtual resource tree. This property must not be an empty string. If the path is relative it is resolved against sling.home or the current working directory. The path may be a file or folder. If the path does not address an existing file or folder, an empty folder is created. </td></tr>
+<tr><td> Provider Root </td><td> <code>provider.root</code> (2.x), <code>provider.roots</code> (1.x) </td><td> Location in the virtual resource tree where the file system resources are mapped in. This property must not be an empty string. Only one path is supported. </td></tr>
+<tr><td> File system layout </td><td> <code>provider.fs.mode</code> </td><td> File system layout mode for files, folders and content. </td></tr>
+<tr><td> Init. Content Options </td><td> <code>provider.initial.content.import.options</code> </td><td> Import options for Sling-Initial-Content file system layout. Supported options: overwrite, ignoreImportProviders. </td></tr>
+<tr><td> FileVault Filter </td><td> <code>provider.filevault.filterxml.path</code> </td><td> Path to META-INF/vault/filter.xml when using FileVault XML file system layout. </td></tr>
+<tr><td> Check Interval </td><td> <code>provider.checkinterval</code> </td><td> If the interval has a value higher than 100, the provider will check the file system for changes periodically. This interval defines the period in milliseconds (the default is 1000). If a change is detected, resource events are sent through the event admin. </td></tr>
+<tr><td> Cache Size </td><td> <code>provider.cache.size</code> </td><td> Max. number of content files cached in memory. </td></tr>
+</tbody>
</table>
-<h3>FILES_FOLDERS file system layout</h3>
+<h3><a href="#files-folders-file-system-layout" id="files-folders-file-system-layout">FILES_FOLDERS file system layout</a></h3>
<p>The mode maps only files and folders. This was the only mode supported in fsresource versions before 1.3.</p>
<p>Notes:</p>
<ul>
- <li>No caching is used for this mode.</li>
- <li>Resource events are sent when file oder folder changes are detected.</li>
+<li>No caching is used for this mode.</li>
+<li>Resource events are sent when file oder folder changes are detected.</li>
</ul>
-<h3>INITIAL_CONTENT file system layout</h3>
+<h3><a href="#initial-content-file-system-layout" id="initial-content-file-system-layout">INITIAL_CONTENT file system layout</a></h3>
<p>The mode maps files and folders, and content files stored in JSON or jcr.xml files. The layout has to match the conventions of the <a href="content-loading-jcr-contentloader.html">Apache Sling JCR Content Loader</a>. The bundle header <code>Sling-Initial-Content</code> defines where and how the content should be loaded to.</p>
<p>This mode is best use together with the <a href="http://sling.apache.org/components/sling-maven-plugin/">Maven Sling Plugin</a>, which automatically creates the appropriate File System Resource Provider configurations for a Maven bundle project containing content structures. For each path an individual configuration is created.</p>
<p>Usage - deploy OSGi bundle from current maven project and register the appropriate OSGi configuration mappings:</p>
@@ -218,11 +186,11 @@
</code></pre>
<p>Notes:</p>
<ul>
- <li>The content of JSON or jcr.xml files is cached in-memory until it changes.</li>
- <li>Resource events are sent when file oder folder changes are detected. When a JSON or jcr.xml file is changed resource events are sent for each resource contained in this file.</li>
- <li>When 'overwrite:=true' is not set for a path in the <code>Sling-Initial-Content</code> header the resource provider falls back to the parent resource provider (e.g. JCR repository) if a requested resource is not find in the file system (version 2.x, with version 1.x this always happens).</li>
+<li>The content of JSON or jcr.xml files is cached in-memory until it changes.</li>
+<li>Resource events are sent when file oder folder changes are detected. When a JSON or jcr.xml file is changed resource events are sent for each resource contained in this file.</li>
+<li>When 'overwrite:=true' is not set for a path in the <code>Sling-Initial-Content</code> header the resource provider falls back to the parent resource provider (e.g. JCR repository) if a requested resource is not find in the file system (version 2.x, with version 1.x this always happens).</li>
</ul>
-<h3>FILEVAULT_XML file system layout</h3>
+<h3><a href="#filevault-xml-file-system-layout" id="filevault-xml-file-system-layout">FILEVAULT_XML file system layout</a></h3>
<p>The mode maps an maven project containing an expanded content package which uses the <a href="http://jackrabbit.apache.org/filevault/vaultfs.html">Jackrabbit FileVault XML layout</a> in the running Sling instance. The existing of a filter file <code>META-INF/vault/filter.xml</code> is mandatory.</p>
<p>This mode is best use together with the <a href="http://sling.apache.org/components/sling-maven-plugin/">Maven Sling Plugin</a>, which automatically creates the appropriate File System Resource Provider configurations. For each path defined in the filter.xml one mapping configuration is created. The include/exclude definitions are respected as well.</p>
<p>Usage - register the appropriate mappings:</p>
@@ -233,10 +201,11 @@
</code></pre>
<p>Notes:</p>
<ul>
- <li>The content of .content.xml files is cached in-memory until it changes.</li>
- <li>Resource events are sent when file oder folder changes are detected. When a JSON or jcr.xml file is changed resource events are sent for each resource contained in this file.</li>
- <li>Content excluded by the filter definition is not mounted by the resource provider, if a resource of the relevant path is requested the resource provider falls back to the parent resource provider (e.g. JCR repository).</li>
-</ul></section></div></div>
+<li>The content of .content.xml files is cached in-memory until it changes.</li>
+<li>Resource events are sent when file oder folder changes are detected. When a JSON or jcr.xml file is changed resource events are sent for each resource contained in this file.</li>
+<li>Content excluded by the filter definition is not mounted by the resource provider, if a resource of the relevant path is requested the resource provider falls back to the parent resource provider (e.g. JCR repository).</li>
+</ul>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/apache-sling-commons-thread-pool.html b/documentation/bundles/apache-sling-commons-thread-pool.html
index 4d67903..24a8f94 100644
--- a/documentation/bundles/apache-sling-commons-thread-pool.html
+++ b/documentation/bundles/apache-sling-commons-thread-pool.html
@@ -121,7 +121,8 @@
<div class="row"><div><section><p>The Apache Sling Commons Thread Pool bundle provides a thread pool services. All thread pools are managed by the <code>org.apache.sling.commons.threads.ThreadPoolManager</code>. This service can be used to get a thread pool.</p>
<p>Thread pools are managed by name - there is a default thread pool and custom thread pools can be generated on demand using a unique name.</p>
<p>The thread pools are actually wrappers around the thread pool support (executer) from the Java library. The advantage of using this thread pool service is, that the pools can be configured and managed through OSGi configurations. In addition the bundle contains a plugin for the Apache Felix Web Console.</p>
-<p>When using the <code>ThreadPoolMananger</code> it is important to release a thread pool using the manager after it has been used.</p></section></div></div>
+<p>When using the <code>ThreadPoolMananger</code> it is important to release a thread pool using the manager after it has been used.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/apache-sling-eventing-and-job-handling.html b/documentation/bundles/apache-sling-eventing-and-job-handling.html
index e187995..8002adc 100644
--- a/documentation/bundles/apache-sling-eventing-and-job-handling.html
+++ b/documentation/bundles/apache-sling-eventing-and-job-handling.html
@@ -118,21 +118,21 @@
</li>
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
-<div class="row"><div><section><h2><a href="#overview" name="overview">Overview</a></h2>
+<div class="row"><div><section><h2><a href="#overview" id="overview">Overview</a></h2>
<p>The Apache Sling Event Support bundle adds additional features to the OSGi Event Admin and for distributed event processing.</p>
<p>The bundle provides the following features</p>
<ul>
- <li><a href="#jobs-guarantee-of-processing">Jobs</a></li>
- <li><a href="#distributed-events">Distributed Events</a></li>
- <li><a href="#sending-scheduled-events">Scheduled Events</a></li>
+<li><a href="#jobs-guarantee-of-processing">Jobs</a></li>
+<li><a href="#distributed-events">Distributed Events</a></li>
+<li><a href="#sending-scheduled-events">Scheduled Events</a></li>
</ul>
<p>To get some hands on code, you can refer to the following tutorials:</p>
<ul>
- <li><a href="/documentation/tutorials-how-tos/how-to-manage-events-in-sling.html">How to Manage Events in Sling</a></li>
- <li><a href="/documentation/bundles/scheduler-service-commons-scheduler.html">Scheduler Service (commons scheduler)</a></li>
+<li><a href="/documentation/tutorials-how-tos/how-to-manage-events-in-sling.html">How to Manage Events in Sling</a></li>
+<li><a href="/documentation/bundles/scheduler-service-commons-scheduler.html">Scheduler Service (commons scheduler)</a></li>
</ul>
-<h2><a href="#jobs-guarantee-of-processing-" name="jobs-guarantee-of-processing-">Jobs (Guarantee of Processing)</a></h2>
-<p>In general, the eventing mechanism (OSGi EventAdmin) has no knowledge about the contents of an event. Therefore, it can't decide if an event is important and should be processed by someone. As the event mechanism is a "fire event and forget about it" algorithm, there is no way for an event admin to tell if someone has really processed the event. Processing of an event could fail, the server or bundle could be stopped etc.</p>
+<h2><a href="#jobs-guarantee-of-processing" id="jobs-guarantee-of-processing">Jobs (Guarantee of Processing)</a></h2>
+<p>In general, the eventing mechanism (OSGi EventAdmin) has no knowledge about the contents of an event. Therefore, it can't decide if an event is important and should be processed by someone. As the event mechanism is a "fire event and forget about it" algorithm, there is no way for an event admin to tell if someone has really processed the event. Processing of an event could fail, the server or bundle could be stopped etc.</p>
<p>On the other hand, there are use cases where the guarantee of processing is a must and usually this comes with the requirement of processing exactly once. Typical examples are sending notification emails (or sms), post processing of content (like thumbnail generation of images or documents), workflow steps etc.</p>
<p>The Sling Event Support adds the notion of a job. A job is a special event that has to be processed exactly once. To be precise, the processing guarantee is at least once. However, the time window for a single job where exactly once can't be guaranteed is very small. It happens if the instance which processes a job crashes after the job processing is finished but before this state is persisted. Therefore a job consumer should be prepared to process a job more than once. Of course, if [...]
<p>The Sling Jobs Processing adds some overhead, so in some cases it might be better to use just the <a href="/documentation/bundles/scheduler-service-commons-scheduler.html">Commons Scheduler Service</a> or the <a href="/documentation/bundles/apache-sling-commons-thread-pool.html">Commons Thread Pool</a> for asynchronous execution of code.</p>
@@ -143,27 +143,27 @@
import org.apache.felix.scr.annotations.Reference;
import java.util.Map;
import java.util.HashMap;
-
+
@Component
public class MyComponent {
-
+
@Reference
private JobManager jobManager;
-
+
public void startJob() {
final Map<String, Object> props = new HashMap<String, Object>();
props.put("item1", "/something");
props.put("count", 5);
-
+
jobManager.addJob("my/special/jobtopic", props);
}
}
</code></pre>
<p>The job topic follows the conventions for the topic of an OSGi event. All objects in the payload must be serializable and publically available (exported by a bundle). This is required as the job is persisted and unmarshalled before processing.</p>
<p>As soon as the method returns from the job manager, the job is persisted and the job manager ensures that this job will be processed exactly once.</p>
-<h3><a href="#jobbuilder" name="jobbuilder">JobBuilder</a></h3>
+<h3><a href="#jobbuilder" id="jobbuilder">JobBuilder</a></h3>
<p>Instead of creating the jobs by calling <code>JobManager.addJob("my/special/jobtopic", props);</code> the <code>JobBuilder</code> can be used, which is retrieved via <code>JobManager.createJob("my/special/jobtopic")</code>. The last method being called on the <code>JobBuilder</code> must be <code>add(...)</code>, which finally adds the job to the queue.</p>
-<h3><a href="#scheduled-jobs" name="scheduled-jobs">Scheduled Jobs</a></h3>
+<h3><a href="#scheduled-jobs" id="scheduled-jobs">Scheduled Jobs</a></h3>
<p>Scheduled Jobs are put in the queue at a specific time (optionally periodically). For that the <code>ScheduleBuilder</code> must be used which is retrieved via <code>JobBuilder.schedule()</code>.</p>
<p>An example code for scheduling a job looks like this:</p>
<pre><code>import org.apache.sling.jobs.JobManager;
@@ -187,7 +187,7 @@ public class MyComponent {
}
</code></pre>
<p>Internally the scheduled Jobs use the <a href="/documentation/bundles/scheduler-service-commons-scheduler.html">Commons Scheduler Service</a>. But in addition they are persisted (by default below <code>/var/eventing/scheduled-jobs</code>) and survive therefore even server restarts. When the scheduled time is reached, the job is automatically added as regular Sling Job through the <code>JobManager</code>.</p>
-<h3><a href="#job-consumers" name="job-consumers">Job Consumers</a></h3>
+<h3><a href="#job-consumers" id="job-consumers">Job Consumers</a></h3>
<p>A job consumer is a service consuming and processing a job. It registers itself as an OSGi service together with a property defining which topics this consumer can process:</p>
<pre><code> import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Service;
@@ -206,8 +206,9 @@ public class MyComponent {
}
</code></pre>
<p>The consumer can either return <em>JobResult.OK</em> indicating that the job has been processed, <em>JobResult.FAILED</em> indicating the processing failed, but can be retried or <em>JobResult.CANCEL</em> the processing has failed permanently.</p>
-<h3><a href="#job-executors" name="job-executors">Job Executors</a></h3>
-<p>If the job consumer needs more features like providing progress information or adding more information of the processing,*JobExecutor* should be implemented.<br/>A job executor is a service processing a job. It registers itself as an OSGi service together with a property defining which topics this consumer can process:</p>
+<h3><a href="#job-executors" id="job-executors">Job Executors</a></h3>
+<p>If the job consumer needs more features like providing progress information or adding more information of the processing,<em>JobExecutor</em> should be implemented.<br />
+A job executor is a service processing a job. It registers itself as an OSGi service together with a property defining which topics this consumer can process:</p>
<pre><code> import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Service;
import org.apache.sling.event.jobs.Job;
@@ -221,109 +222,83 @@ public class MyComponent {
public JobExecutionResult process(final Job job, JobExecutionContext context)
//process the job and return the result
-
+
//initialize job progress with n number of steps
context.getJobContext().initProgress(n, -1);
context.getJobContext().log("Job initialized");
-
+
//increament progress by 2 steps
context.getJobContext().incrementProgressCount(2);
context.getJobContext().log("2 steps completed.");
-
+
//stop processing if job was cancelled
if(context.isStopped()) {
context.getJobContext().log("Job Stopped after 4 steps.");
return context.result().message(resultMessage).cancelled();
}
-
+
//add job log
context.getJobContext().log("Job finished.");
-
+
return context.result().message(resultMessage).succeeded();
}
}
</code></pre>
-<p><em>JobExecutionContext</em> can be used by executor to update job execution progress, add job logs, build a JobExecutionResult and to check if job is still active by jobExecutionContext.isStopped(). The executor can return job result "succeeded" by calling JobExecutionContext.result(successMsg).succeeded(), job result "failed" by calling JobExecutionContext.result(errorMessage).failed() and job result "cancelled" by calling JobExecutionContext.result(message).cancelled(). The <em>Job [...]
-<h3><a href="#job-handling" name="job-handling">Job Handling</a></h3>
+<p><em>JobExecutionContext</em> can be used by executor to update job execution progress, add job logs, build a JobExecutionResult and to check if job is still active by jobExecutionContext.isStopped(). The executor can return job result "succeeded" by calling JobExecutionContext.result(successMsg).succeeded(), job result "failed" by calling JobExecutionContext.result(errorMessage).failed() and job result "cancelled" by calling JobExecutionContext.result(me [...]
+<h3><a href="#job-handling" id="job-handling">Job Handling</a></h3>
<p>New jobs are first persisted in the resource tree (for failover etc.), then the job is distributed to an instance responsible for processing the job and on that instance the job is put into a processing queue. There are different types of queues defining how the jobs are processed (one after the other, in parallel etc.).</p>
<p>For managing queues, the Sling Job Handler uses the OSGi ConfigAdmin - it is possible to configure one or more queue configurations through the ConfigAdmin. One way of creating and configuring such configurations is the Apache Felix WebConsole. If there is no specific queue configuration maintained for the given job topic, the Sling Job Handler falls back to using the <code>Apache Sling Job Default Queue</code> (which can be configured through OSGi as well).</p>
-<h4><a href="#queue-configurations" name="queue-configurations">Queue Configurations</a></h4>
+<h4><a href="#queue-configurations" id="queue-configurations">Queue Configurations</a></h4>
<p>A queue configuration can have the following properties:</p>
<table>
- <thead>
- <tr>
- <th>Property Name </th>
- <th>Description </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>queue.name</code> </td>
- <td>The name of the queue. If matching is used for topics, the value {0} can be used for replacing the matched part. </td>
- </tr>
- <tr>
- <td><code>queue.type</code> </td>
- <td>The type of the queue: ORDERED, UNORDERED, TOPIC_ROUND_ROBIN </td>
- </tr>
- <tr>
- <td><code>queue.topics</code> </td>
- <td>A list of topics processed by this queue. Either the concrete topic is specified or the topic string ends with /* or /. If a star is at the end all topics and sub topics match, with a dot only direct sub topics match. </td>
- </tr>
- <tr>
- <td><code>queue.maxparallel</code> </td>
- <td>How many jobs can be processed in parallel? -1 for number of processors.</td>
- </tr>
- <tr>
- <td><code>queue.retries</code> </td>
- <td>How often the job should be retried in case of failure (i.e. Job did not finish with succeeded or cancelled result). -1 for endless retries. In case of exceptions there is no retry. </td>
- </tr>
- <tr>
- <td><code>queue.retrydelay</code> </td>
- <td>The waiting time in milliseconds between job retries. </td>
- </tr>
- <tr>
- <td><code>queue.priority</code> </td>
- <td>The thread priority: NORM, MIN, or MAX </td>
- </tr>
- <tr>
- <td><code>service.ranking</code> </td>
- <td>A ranking for this configuration.</td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Property Name </th><th> Description </th></tr>
+</thead>
+<tbody>
+<tr><td> <code>queue.name</code> </td><td> The name of the queue. If matching is used for topics, the value {0} can be used for replacing the matched part. </td></tr>
+<tr><td> <code>queue.type</code> </td><td> The type of the queue: ORDERED, UNORDERED, TOPIC_ROUND_ROBIN </td></tr>
+<tr><td> <code>queue.topics</code> </td><td> A list of topics processed by this queue. Either the concrete topic is specified or the topic string ends with /* or /. If a star is at the end all topics and sub topics match, with a dot only direct sub topics match. </td></tr>
+<tr><td> <code>queue.maxparallel</code> </td><td> How many jobs can be processed in parallel? -1 for number of processors.</td></tr>
+<tr><td> <code>queue.retries</code> </td><td> How often the job should be retried in case of failure (i.e. Job did not finish with succeeded or cancelled result). -1 for endless retries. In case of exceptions there is no retry. </td></tr>
+<tr><td> <code>queue.retrydelay</code> </td><td> The waiting time in milliseconds between job retries. </td></tr>
+<tr><td> <code>queue.priority</code> </td><td> The thread priority: NORM, MIN, or MAX </td></tr>
+<tr><td> <code>service.ranking</code> </td><td> A ranking for this configuration.</td></tr>
+</tbody>
</table>
<p>The configurations are processed in order of their service ranking. The first matching queue configuration is used for the job.</p>
-<h4><a href="#ordered-queues" name="ordered-queues">Ordered Queues</a></h4>
+<h4><a href="#ordered-queues" id="ordered-queues">Ordered Queues</a></h4>
<p>An ordered queue processes one job after the other.</p>
-<h4><a href="#unordered-queues-or-parallel-queues-" name="unordered-queues-or-parallel-queues-">Unordered Queues (or Parallel queues)</a></h4>
+<h4><a href="#unordered-queues-or-parallel-queues" id="unordered-queues-or-parallel-queues">Unordered Queues (or Parallel queues)</a></h4>
<p>Unordered queues process jobs in parallel.</p>
-<h4><a href="#topic-round-robin-queues" name="topic-round-robin-queues">Topic-Round-Robin Queues</a></h4>
+<h4><a href="#topic-round-robin-queues" id="topic-round-robin-queues">Topic-Round-Robin Queues</a></h4>
<p>The jobs are processed in parallel. Scheduling of the jobs is based on the topic of the jobs. These are started by doing round-robin on the available topics.</p>
-<h3><a href="#job-distributing" name="job-distributing">Job Distributing</a></h3>
+<h3><a href="#job-distributing" id="job-distributing">Job Distributing</a></h3>
<p>For job distribution (= distributing the processing in a cluster), the job handling uses the topology feature from Sling - each instance in the topology announces the set of topics (consumers) it currently has - and this defines the job capabilities, a mapping from an instance to the topics it can process.</p>
<p>When a job is scheduled, the job manager uses these capabilities to find out the set of instances which is able to process the request. If the queue type is <em>ordered</em> then all jobs are processed by the leader of this set. For parallel queues, the jobs are distributed equally amongst those instance.</p>
<p>Failover is handled by the leader: if an instance dies, the leader will detect this through the topology framework and then redistribute jobs from the dead instance to the available instances. Of course this takes a leader change into account as well. In addition if the job capabilities change and this require a reschedule of jobs, that's done by the leader as well.</p>
-<h3><a href="#job-creation-patterns" name="job-creation-patterns">Job Creation Patterns</a></h3>
+<h3><a href="#job-creation-patterns" id="job-creation-patterns">Job Creation Patterns</a></h3>
<p>The job manager ensures that a job is processed exactly once. However, the client code has to take care that a job is created exactly once. We'll discuss this based on some general usage patterns:</p>
-<h4><a href="#jobs-based-on-user-action" name="jobs-based-on-user-action">Jobs based on user action</a></h4>
+<h4><a href="#jobs-based-on-user-action" id="jobs-based-on-user-action">Jobs based on user action</a></h4>
<p>If a user action results in the creation of a job, the thread processing the user action can directly create the job. This ensures that even in a clustered scenario the job is created only once.</p>
-<h4><a href="#jobs-based-on-observation-events" name="jobs-based-on-observation-events">Jobs based on observation / events</a></h4>
+<h4><a href="#jobs-based-on-observation-events" id="jobs-based-on-observation-events">Jobs based on observation / events</a></h4>
<p>If an observation event or any other OSGi event results in the creation of a job, special care needs to be taken in a clustered installation to avoid the job is created on all cluster instances. The easiest way to avoid this, is to use the topology api and make sure the job is only created on the leader instance.</p>
-<h2><a href="#distributed-events" name="distributed-events">Distributed Events</a></h2>
+<h2><a href="#distributed-events" id="distributed-events">Distributed Events</a></h2>
<p>In addition to the job handling, the Sling Event support adds handling for distributed events. A distributed event is an OSGi event which is sent across JVM boundaries to a different VM. A potential use case is to broadcast information in a clustered environment.</p>
-<h3><a href="#basic-principles" name="basic-principles">Basic Principles</a></h3>
+<h3><a href="#basic-principles" id="basic-principles">Basic Principles</a></h3>
<p>The foundation of the distributed event mechanism is to distribute each event to every node in a clustered environment. The event distribution mechanism has no knowledge about the intent of the event and therefore is not able to make delivery decisions by itself. It is up to the sender to decide what should happen. The sender must explicitly declare an event to be distributed as for example framework related events (bundle stopped, installed etc.) should not be distributed.</p>
<p>The event mechanism will provide additional functionality making it easier for event receivers to decide if they should process an event. The event receiver can determine if the event is a local event or comming from a remote application node. Therefore a general rule of thumb is to process events only if they're local and just regard remote events as a FYI.</p>
<p>For distributed events two properties are defined (check the <em>EventUtil</em> class):</p>
<ul>
- <li><em>event.distribute</em> - this flag is set by the sender of an event to give a hint if the event should be distributed across instances. For example JCR observation based events are already distributed on all instances, so there is no further need to distribute them. If the flag is present, the event will be distributed. The value has currently no meaning, however the EventUtil method should be used to add this property. If the flag is absent the event is distributed locally only.</li>
- <li><em>event.application</em> - An identifier for the current application node in the cluster. This information will be used to detect if an event has been created on different nodes. If the event has been created on the same node, the <em>event.application</em> is missing, if it is a remote event, the <em>event.application</em> contains the ID of the node, the event has been initially created. Use the <em>EventUtil.isLocal(Event)</em> method to detect if the event is a local or a dis [...]
+<li><em>event.distribute</em> - this flag is set by the sender of an event to give a hint if the event should be distributed across instances. For example JCR observation based events are already distributed on all instances, so there is no further need to distribute them. If the flag is present, the event will be distributed. The value has currently no meaning, however the EventUtil method should be used to add this property. If the flag is absent the event is distributed locally only.</li>
+<li><em>event.application</em> - An identifier for the current application node in the cluster. This information will be used to detect if an event has been created on different nodes. If the event has been created on the same node, the <em>event.application</em> is missing, if it is a remote event, the <em>event.application</em> contains the ID of the node, the event has been initially created. Use the <em>EventUtil.isLocal(Event)</em> method to detect if the event is a local or a distr [...]
</ul>
<p>While the <em>event.distribute</em> must be set by the sender of an event (if the event should be distributed), the <em>event.application</em> property is maintained by the event mechanism. Therefore a client sending an event should <em>never</em> set this information by itself. This will confuse the local event handlers and result in unexpected behaviour. On remote events the <em>event.application</em> is set by the event distribution mechanism.</p>
-<h3><a href="#event-distribution-across-application-nodes-cluster-" name="event-distribution-across-application-nodes-cluster-">Event Distribution Across Application Nodes (Cluster)</a></h3>
+<h3><a href="#event-distribution-across-application-nodes-cluster" id="event-distribution-across-application-nodes-cluster">Event Distribution Across Application Nodes (Cluster)</a></h3>
<p>The (local) event admin is the service distributing events locally. The Sling Distributing Event Handler is a registered event handler that is listening for events to be distributed. It distributes the events to remote application notes, Sling's resource tree is used for distribution. The distributing event handler writes the events into the resource tree, the distributing event handlers on other application nodes get notified through observation and then distribute the read events lo [...]
<p>As mentioned above, the client sending an event has to mark an event to be distributed in a cluster by setting the <em>event.distribute</em> in the event properties (through <em>EventUtil</em>). This distribution mechanism has the advantage that the application nodes do not need to know each other and the distribution mechanism is independent from the used event admin implementation.</p>
-<h2><a href="#sending-scheduled-events" name="sending-scheduled-events">Sending Scheduled Events</a></h2>
-<p>Scheduled events are OSGi events that have been created by the environemnt. They are generated on each application node of the cluster through an own scheduler instance. Sending these events works the same as sending events based on JCR events (see above).</p></section></div></div>
+<h2><a href="#sending-scheduled-events" id="sending-scheduled-events">Sending Scheduled Events</a></h2>
+<p>Scheduled events are OSGi events that have been created by the environemnt. They are generated on each application node of the cluster through an own scheduler instance. Sending these events works the same as sending events based on JCR events (see above).</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/bundle-resources-extensions-bundleresource.html b/documentation/bundles/bundle-resources-extensions-bundleresource.html
index aaf7f53..065609b 100644
--- a/documentation/bundles/bundle-resources-extensions-bundleresource.html
+++ b/documentation/bundles/bundle-resources-extensions-bundleresource.html
@@ -120,10 +120,10 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h1><a href="#introduction" name="introduction">Introduction</a></h1>
-<p>The Bundle Resource Provider provides access to files/directories included in an OSGi bundle through the Sling <code>ResourceResolver</code>. </p>
-<h1><a href="#configuration" name="configuration">Configuration</a></h1>
-<p>If a bundle wants to provide resources, it must specify the Bundle manifest header <code>Sling-Bundle-Resources</code> containing a list of absolute paths. The paths are separated by comma. Without any additional information such a path is mapped 1:1 meaning that the specified path is used as the root resource path and the corresponding resource is at the same path in the bundle. </p>
+<h1><a href="#introduction" id="introduction">Introduction</a></h1>
+<p>The Bundle Resource Provider provides access to files/directories included in an OSGi bundle through the Sling <code>ResourceResolver</code>.</p>
+<h1><a href="#configuration" id="configuration">Configuration</a></h1>
+<p>If a bundle wants to provide resources, it must specify the Bundle manifest header <code>Sling-Bundle-Resources</code> containing a list of absolute paths. The paths are separated by comma. Without any additional information such a path is mapped 1:1 meaning that the specified path is used as the root resource path and the corresponding resource is at the same path in the bundle.</p>
<p>The following example header maps the paths <code>/libs/sling/explorer</code> and <code>/libs/sling/servlet/default/explorer</code> in the resource tree to resources in the bundle at the same path:</p>
<pre><code>...
Sling-Bundle-Resources: /libs/sling/explorer,
@@ -136,13 +136,13 @@ Sling-Bundle-Resources: /libs/sling/explorer,
Sling-Bundle-Resources: /libs/sling/explorer;path:=/resources/explorer
...
</code></pre>
-<h1><a href="#resource-types" name="resource-types">Resource Types</a></h1>
+<h1><a href="#resource-types" id="resource-types">Resource Types</a></h1>
<p>Files and directories are mapped into the resource tree as regular <code>Resource</code> instances whose resource type depends on the actual nature of the mapped resource:</p>
<ul>
- <li>Regular files are assigned the <code>nt:file</code> resource type</li>
- <li>Directories are assigned the <code>nt:folder</code> resource type</li>
+<li>Regular files are assigned the <code>nt:file</code> resource type</li>
+<li>Directories are assigned the <code>nt:folder</code> resource type</li>
</ul>
-<h1><a href="#defining-resources-through-json" name="defining-resources-through-json">Defining Resources Through JSON</a></h1>
+<h1><a href="#defining-resources-through-json" id="defining-resources-through-json">Defining Resources Through JSON</a></h1>
<p>By default, there is a 1:1 mapping between resources in the bundle and resources in the resource tree as explained above. While this works for adding files to the resource tree, it doesn't support adding arbitrary resources to the resource tree where the resources just have a map of properties and are not actually a file. By specifying the directive <code>propsJSON</code> with an extension, all files in the bundle having this extension are passed as JSON files and the contained struct [...]
<p>For example with the following definition in the manifest:</p>
<pre><code>...
@@ -161,13 +161,13 @@ Sling-Bundle-Resources: /products;path:=/resources/products.json;propsJSON:=json
</code></pre>
<p>a resource named <code>products</code> with the resource type <code>products</code> has a single child resource named <code>sling</code> and the above three properties.</p>
<p>It's also possible to add additional properties to a file from a bundle resource. For example if the bundle contains the resource <code>tree.gif</code> and a JSON file <code>tree.gif.json</code> with the directive to parse all files ending in <code>json</code>, a file resource <code>tree.gif</code> exists in the resource tree with the additional properties from the json file. The JSON file can also override the default resource type in this case. In addition this json file can also co [...]
-<h1><a href="#adapters" name="adapters">Adapters</a></h1>
+<h1><a href="#adapters" id="adapters">Adapters</a></h1>
<p>Filesystem resources extend from Sling's <code>AbstractResource</code> class and thus are adaptable to any type for which an <code>AdapterFactory</code> is registered supporting bundle resources. In addition <code>BundleResource</code> support the following adapters natively:</p>
<ul>
- <li><code>java.net.URL</code> -- A valid <code>bundle://</code> URL to the resource in the bundle.</li>
- <li><code>java.io.InputStream</code> -- An <code>InputStream</code> to read file contents. Doesn't apply to folders.</li>
+<li><code>java.net.URL</code> -- A valid <code>bundle://</code> URL to the resource in the bundle.</li>
+<li><code>java.io.InputStream</code> -- An <code>InputStream</code> to read file contents. Doesn't apply to folders.</li>
</ul>
-<h1><a href="#capability" name="capability">Capability</a></h1>
+<h1><a href="#capability" id="capability">Capability</a></h1>
<p>The bundle implementing the support for bundle resources must provide the following extender capability:</p>
<pre><code><Provide-Capability>
osgi.extender;osgi.extender="org.apache.sling.bundleresource";version:Version="1.1"
@@ -179,8 +179,9 @@ Sling-Bundle-Resources: /products;path:=/resources/products.json;propsJSON:=json
</Require-Capability>
</code></pre>
<p>Without requiring the capability, the bundle containing the resources might resolve successfully but the resource are not part of the resource tree as there is no implementation picking them up.</p>
-<h1><a href="#webconsole-plugin" name="webconsole-plugin">WebConsole Plugin</a></h1>
-<p>The Bundle Resource Provider also has a web console plugin through which the currently installed bundles can be seen.</p></section></div></div>
+<h1><a href="#webconsole-plugin" id="webconsole-plugin">WebConsole Plugin</a></h1>
+<p>The Bundle Resource Provider also has a web console plugin through which the currently installed bundles can be seen.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/caching-services.html b/documentation/bundles/caching-services.html
index d3e3e5f..934d86a 100644
--- a/documentation/bundles/caching-services.html
+++ b/documentation/bundles/caching-services.html
@@ -114,10 +114,12 @@
</li>
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
-<div class="row"><div><section><p>Caching services are available under multiple repositories at <a href="https://github.com/apache/?utf8=✓&q=sling-cache">https://github.com/apache/?utf8=✓&q=sling-cache</a></p>
+<div class="row"><div><section><p>Caching services are available under multiple repositories at <a href="https://github.com/apache/?utf8=✓&q=sling-cache">https://github.com/apache/?utf8=✓&q=sling-cache</a></p>
<p>Both EhCache and Infinispan implementations are provided, with good unit and integration tests coverage.</p>
<!-- GIT-TODO portal stuff must be moved to the Git whiteboard -->
-<p>A portal cache provider API implementation is provided, that depends on the whiteboard portal modules found under <a href="https://svn.apache.org/repos/asf/sling/whiteboard/portal">https://svn.apache.org/repos/asf/sling/whiteboard/portal</a></p></section></div></div>
+A portal cache provider API implementation is provided, that depends on the whiteboard portal modules
+found under [https://svn.apache.org/repos/asf/sling/whiteboard/portal](https://svn.apache.org/repos/asf/sling/whiteboard/portal)
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/commons-crypto.html b/documentation/bundles/commons-crypto.html
index 7398992..d7e973a 100644
--- a/documentation/bundles/commons-crypto.html
+++ b/documentation/bundles/commons-crypto.html
@@ -122,8 +122,8 @@
</p>
<p><strong><a href="https://github.com/apache/sling-org-apache-sling-commons-crypto">Commons Crypto</a> provides a simple API to encrypt and decrypt messages and an extensible implementation based on <a href="http://www.jasypt.org">Jasypt</a>.</strong></p>
<p>The Jasypt implementation and Web Console plugin are optional.</p>
-<h2><a href="#api" name="api">API</a></h2>
-<h3><a href="#crypto-service" name="crypto-service">Crypto Service</a></h3>
+<h2><a href="#api" id="api">API</a></h2>
+<h3><a href="#crypto-service" id="crypto-service">Crypto Service</a></h3>
<p>Encrypt a secret message (e.g. service password) and decrypt the ciphertext. The used crypto method is up to the implementation.</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->public interface CryptoService {
@@ -139,7 +139,7 @@
)
private volatile CryptoService cryptoService;
</code></pre>
-<h3><a href="#password-provider" name="password-provider">Password Provider</a></h3>
+<h3><a href="#password-provider" id="password-provider">Password Provider</a></h3>
<p>Password providers are useful when dealing with password-based encryption (PBE, see also <a href="https://tools.ietf.org/html/rfc2898">RFC 2898</a>).</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->public interface PasswordProvider {
@@ -147,18 +147,18 @@ private volatile CryptoService cryptoService;
}
</code></pre>
-<h4><a href="#file-password-provider" name="file-password-provider">File Password Provider</a></h4>
+<h4><a href="#file-password-provider" id="file-password-provider">File Password Provider</a></h4>
<p>The file-based password provider reads the password for encryption/decryption from a given file.</p>
-<img src="commons-crypto/FilePasswordProvider~sample.png" alt="JasyptStandardPBEStringCryptoService Sample Configuration" style="width: 50%; border: 1px solid silver">
-<h2><a href="#jasypt-implementation" name="jasypt-implementation">Jasypt implementation</a></h2>
+<p><img src="commons-crypto/FilePasswordProvider~sample.png" alt="JasyptStandardPBEStringCryptoService Sample Configuration" style="width: 50%; border: 1px solid silver"></p>
+<h2><a href="#jasypt-implementation" id="jasypt-implementation">Jasypt implementation</a></h2>
<p>The Commons Crypto module provides a crypto service implementation based on the <a href="http://www.jasypt.org">Jasypt</a> <code>StandardPBEStringEncryptor</code>.</p>
<p>The <code>JasyptStandardPBEStringCryptoService</code> requires at least a password provider and an initialization vector (IV) generator (<code>IvGenerator</code>) to set up the internal <code>StandardPBEStringEncryptor</code>.</p>
-<img src="commons-crypto/JasyptStandardPBEStringCryptoService~sample.png" alt="JasyptStandardPBEStringCryptoService Sample Configuration" style="width: 50%; border: 1px solid silver">
-<img src="commons-crypto/JasyptRandomIvGeneratorRegistrar~sample.png" alt="JasyptRandomIvGeneratorRegistrar Sample Configuration" style="width: 50%; border: 1px solid silver">
-<h2><a href="#web-console-plugin" name="web-console-plugin">Web Console Plugin</a></h2>
+<p><img src="commons-crypto/JasyptStandardPBEStringCryptoService~sample.png" alt="JasyptStandardPBEStringCryptoService Sample Configuration" style="width: 50%; border: 1px solid silver"></p>
+<p><img src="commons-crypto/JasyptRandomIvGeneratorRegistrar~sample.png" alt="JasyptRandomIvGeneratorRegistrar Sample Configuration" style="width: 50%; border: 1px solid silver"></p>
+<h2><a href="#web-console-plugin" id="web-console-plugin">Web Console Plugin</a></h2>
<p>The plugin (<code>/system/console/sling-commons-crypto-encrypt</code>) allows message encryption with a selected crypto service.</p>
-<img src="commons-crypto/sling-commons-crypto-encrypt-webconsole-plugin.png" alt="Sling Commons Crypto Encrypt Web Console Plugin" style="width: 50%; border: 1px solid silver">
-<h2><a href="#sample-configurations" name="sample-configurations">Sample configurations</a></h2>
+<p><img src="commons-crypto/sling-commons-crypto-encrypt-webconsole-plugin.png" alt="Sling Commons Crypto Encrypt Web Console Plugin" style="width: 50%; border: 1px solid silver"></p>
+<h2><a href="#sample-configurations" id="sample-configurations">Sample configurations</a></h2>
<p>A module with (minimal) sample configurations can be found in <a href="https://github.com/apache/sling-samples/tree/master/sling-commons-crypto-configuration">Sling's samples Git repo</a>.</p>
<p><code>org.apache.sling.commons.crypto.internal.FilePasswordProvider~sample.json</code></p>
<pre><code>{
@@ -179,7 +179,8 @@ private volatile CryptoService cryptoService;
"names": ["sample"], // names is optional
"algorithm": "PBEWITHHMACSHA512ANDAES_256"
}
-</code></pre></section></div></div>
+</code></pre>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/commons-html-utilities.html b/documentation/bundles/commons-html-utilities.html
index e3db35f..27faee6 100644
--- a/documentation/bundles/commons-html-utilities.html
+++ b/documentation/bundles/commons-html-utilities.html
@@ -120,7 +120,8 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p>The Apache Sling Commons HTML Utilities bundle provides multiple HTML parsers which can be used to parse HTML and generate a <code>Document</code> or events based on the type of Parser used.</p>
<p>== Document Generation</p>
-<p>== TagSoup Based Parser</p></section></div></div>
+<p>== TagSoup Based Parser</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/configuration-installer-factory.html b/documentation/bundles/configuration-installer-factory.html
index c5a8c4f..d576d1b 100644
--- a/documentation/bundles/configuration-installer-factory.html
+++ b/documentation/bundles/configuration-installer-factory.html
@@ -115,11 +115,11 @@
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p>The configuration installer factory provides support for configurations to the <a href="/documentation/bundles/osgi-installer.html">OSGI installer</a>. The provisioning of artifacts is handled by installer providers like the <a href="/documentation/bundles/file-installer-provider.html">file installer</a> or the <a href="/documentation/bundles/jcr-installer-provider.html">JCR installer</a>.</p>
-<h2><a href="#configurations" name="configurations">Configurations</a></h2>
+<h2><a href="#configurations" id="configurations">Configurations</a></h2>
<p>Configuration file names are related to the PID and factory PID. The structure of the file name is as follows:</p>
-<pre><code>filename ::= <pid> ( ( '-' | '~' ) <subname> ) ? ( '.cfg' | '.config' | '.cfg.json')
+<pre><code>filename ::= <pid> ( ( '-' | '~' ) <subname> ) ? ( '.cfg' | '.config' | '.cfg.json')
</code></pre>
-<p>If the form is <code><pid>('.cfg'|'.config'|'.cfg.json')</code>, the file contains the properties for a Managed Service. The <code><pid></code> is then the PID of the Managed Service. See the Configuration Admin service for details.</p>
+<p>If the form is <code><pid>('.cfg'|'.config'|'.cfg.json')</code>, the file contains the properties for a Managed Service. The <code><pid></code> is then the PID of the Managed Service. See the Configuration Admin service for details.</p>
<p>When a Managed Service Factory is used, the situation is different. The <code><pid></code> part then describes the PID of the Managed Service Factory. You can pick any <code><subname></code>, the installer will then create an instance for the factory for each unique name. For example:</p>
<pre><code>com.acme.xyz.cfg // configuration for Managed Service
// com.acme.xyz
@@ -129,14 +129,14 @@ com.acme.abc-default.cfg // Managed Service Factory,
<p>Since Installer Configuration Factory 1.2.0 (<a href="https://jira.apache.org/jira/browse/SLING-7786">SLING-7786</a>) you should use the tilde <code>~</code> as separator between <code><pid></code> and <code><subname></code> instead of the <code>-</code>.</p>
<p>If a configuration is modified, the file installer will write the configuration back to a file to ensure persistence across restarts (if <code>sling.fileinstall.writeback</code> is enabled). A similar writeback mechanism is supported by the <a href="jcr-installer-provider.html">JCR installer</a>.</p>
<p>The code for parsing the configuration files is in <a href="https://github.com/apache/sling-org-apache-sling-installer-core/blob/7b2e4407baa45b79d954dd20c53bb2077c3a5e49/src/main/java/org/apache/sling/installer/core/impl/InternalResource.java#L230">InternalResource#readDictionary</a>.</p>
-<h3><a href="#configuration-files-cfg-json-" name="configuration-files-cfg-json-">Configuration Files (.cfg.json)</a></h3>
+<h3><a href="#configuration-files-cfgjson" id="configuration-files-cfgjson">Configuration Files (.cfg.json)</a></h3>
<p>This is the preferred way to specify configurations as it is an official format specified by OSGi in the <a href="https://osgi.org/specification/osgi.cmpn/7.0.0/service.configurator.html">OSGi R7 Service Configurator Spec</a> and is also used by the <a href="https://github.com/apache/sling-org-apache-sling-feature/blob/master/readme.md">Feature Model</a>. The detailed JSON format is described in that specification. It allows for typed values, allowing all possible types including Coll [...]
<p>There are some differences to the <a href="https://osgi.org/specification/osgi.cmpn/7.0.0/service.configurator.html#service.configurator-resources">resource format specification</a> as outlined below:</p>
<ul>
- <li>Each file contains exactly one configuration, therefore it only contains the properties of the configuration.</li>
- <li>Keys starting with <code>:configurator:</code> should not be used (in general they are validated but not further evaluated)</li>
- <li>The PID is given via the file name (the part preceeding the <code>.cfg.json</code>) instead of <code>:configurator:symbolic-name</code></li>
- <li>There is no version support i.e. <code>:configurator:version</code> should not be used either</li>
+<li>Each file contains exactly one configuration, therefore it only contains the properties of the configuration.</li>
+<li>Keys starting with <code>:configurator:</code> should not be used (in general they are validated but not further evaluated)</li>
+<li>The PID is given via the file name (the part preceeding the <code>.cfg.json</code>) instead of <code>:configurator:symbolic-name</code></li>
+<li>There is no version support i.e. <code>:configurator:version</code> should not be used either</li>
</ul>
<p>This is an example file</p>
<pre><code>{
@@ -146,91 +146,92 @@ com.acme.abc-default.cfg // Managed Service Factory,
"size:Integer" : 500
}
</code></pre>
-<h4><a href="#limitations" name="limitations">Limitations</a></h4>
+<h4><a href="#limitations" id="limitations">Limitations</a></h4>
<ul>
- <li>This is only supported since Installer Configuration Factory 1.2.0 .</li>
+<li>This is only supported since Installer Configuration Factory 1.2.0 .</li>
</ul>
-<h3><a href="#configuration-files-config-" name="configuration-files-config-">Configuration Files (.config)</a></h3>
+<h3><a href="#configuration-files-config" id="configuration-files-config">Configuration Files (.config)</a></h3>
<p>Configuration files ending in <code>.config</code> use the format of the <a href="http://svn.apache.org/viewvc/felix/releases/org.apache.felix.configadmin-1.8.12/src/main/java/org/apache/felix/cm/file/ConfigurationHandler.java?view=markup">Apache Felix ConfigAdmin implementation</a> (in version 1.8.12). This format allows to specify the type and cardinality of a configuration property and is not limited to string values. It must be stored in UTF-8 encoding. This format is preferred ov [...]
<p>The first line of such a file might start with a comment line (a line starting with a <code>#</code>). Comments within the file are not allowed.</p>
<p>The format is:</p>
<pre><code>file ::= (comment) (header) *
-comment ::= '#' <any>
-header ::= prop '=' value
+comment ::= '#' <any>
+header ::= prop '=' value
prop ::= symbolic-name // 1.4.2 of OSGi Core Specification
-symbolic-name ::= token { '.' token }
-token ::= { [ 0..9 ] | [ a..z ] | [ A..Z ] | '_' | '-' }
-value ::= [ type ] ( '[' values ']' | '(' values ')' | simple )
-values ::= ( simple { ',' simple } | '\' <nl> simple { ', \' <nl> simple } <nl> )
-simple ::= '"' stringsimple '"'
+symbolic-name ::= token { '.' token }
+token ::= { [ 0..9 ] | [ a..z ] | [ A..Z ] | '_' | '-' }
+value ::= [ type ] ( '[' values ']' | '(' values ')' | simple )
+values ::= ( simple { ',' simple } | '\' <nl> simple { ', \' <nl> simple } <nl> )
+simple ::= '"' stringsimple '"'
type ::= <1-char type code>
-stringsimple ::= <quoted string representation of the value where both '"' and '=' need to be escaped>
+stringsimple ::= <quoted string representation of the value where both '"' and '=' need to be escaped>
</code></pre>
-<p>The quoted string format is equal to the definition from HTTP 1.1 (<a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html">RFC2616</a>), except that both '"' and '=' need to be escaped.</p>
+<p>The quoted string format is equal to the definition from HTTP 1.1 (<a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html">RFC2616</a>), except that both '"' and '=' need to be escaped.</p>
<p>The 1 character type code is one of:</p>
<ul>
- <li><code>T</code> : <code>String</code></li>
- <li><code>I</code> : <code>Integer</code></li>
- <li><code>L</code> : <code>Long</code></li>
- <li><code>F</code> : <code>Float</code></li>
- <li><code>D</code> : <code>Double</code></li>
- <li><code>X</code> : <code>Byte</code></li>
- <li><code>S</code> : <code>Short</code></li>
- <li><code>C</code> : <code>Character</code></li>
- <li><code>B</code> : <code>Boolean</code></li>
+<li><code>T</code> : <code>String</code></li>
+<li><code>I</code> : <code>Integer</code></li>
+<li><code>L</code> : <code>Long</code></li>
+<li><code>F</code> : <code>Float</code></li>
+<li><code>D</code> : <code>Double</code></li>
+<li><code>X</code> : <code>Byte</code></li>
+<li><code>S</code> : <code>Short</code></li>
+<li><code>C</code> : <code>Character</code></li>
+<li><code>B</code> : <code>Boolean</code></li>
</ul>
<p>or for primitives</p>
<ul>
- <li><code>i</code> : <code>int</code></li>
- <li><code>l</code> : <code>long</code></li>
- <li><code>f</code> : <code>float</code></li>
- <li><code>d</code> : <code>double</code></li>
- <li><code>x</code> : <code>byte</code></li>
- <li><code>s</code> : <code>short</code></li>
- <li><code>c</code> : <code>char</code></li>
- <li><code>b</code> : <code>boolean</code></li>
+<li><code>i</code> : <code>int</code></li>
+<li><code>l</code> : <code>long</code></li>
+<li><code>f</code> : <code>float</code></li>
+<li><code>d</code> : <code>double</code></li>
+<li><code>x</code> : <code>byte</code></li>
+<li><code>s</code> : <code>short</code></li>
+<li><code>c</code> : <code>char</code></li>
+<li><code>b</code> : <code>boolean</code></li>
</ul>
<p>For Float and Double types the methods <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/Float.html#intBitsToFloat%28int%29">Float.intBitsToFloat</a> and <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/Double.html#longBitsToDouble%28long%29">Double.longBitsToDouble</a> are being used to convert the numeric string into the correct type. These methods rely on the IEEE-754 floating-point formats described in <a href="https://en.wikipedia.org/wiki/Single-precision_ [...]
<p>Multiple values enclosed by <code>[</code> and <code>]</code> lead to an array while those enclosed by <code>(</code> and <code>)</code> lead to a <code>Collection</code> in the underlying <code>java.util.Dictionary</code> of the <code>org.osgi.service.cm.Configuration</code> and vice-versa.</p>
<p>Although both objects and primites are supported, in case you use single-value entries or collections the deserialization will autobox primitives.</p>
<p>A number of such .config files exist in the Sling codebase and can be used as examples.</p>
-<h4><a href="#limitations" name="limitations">Limitations</a></h4>
+<h4><a href="#limitations" id="limitations">Limitations</a></h4>
<ul>
- <li>No support for collections containing different types</li>
- <li>No support for nested multivalues (arrays or Collections)</li>
- <li>No user-friendly (readable) values for floating points (<a href="https://issues.apache.org/jira/browse/SLING-7757">SLING-7757</a>)</li>
+<li>No support for collections containing different types</li>
+<li>No support for nested multivalues (arrays or Collections)</li>
+<li>No user-friendly (readable) values for floating points (<a href="https://issues.apache.org/jira/browse/SLING-7757">SLING-7757</a>)</li>
</ul>
-<h3><a href="#property-files-cfg-" name="property-files-cfg-">Property Files (.cfg)</a></h3>
+<h3><a href="#property-files-cfg" id="property-files-cfg">Property Files (.cfg)</a></h3>
<p>Configuration files ending in <code>.cfg</code> are plain property files (<code>java.util.Property</code>). The format is simple:</p>
<pre><code>file ::= ( header | comment ) *
-header ::= <header> ( ':' | '=' ) <value> ( '\<nl> <value> ) *
-comment ::= '#' <any>
+header ::= <header> ( ':' | '=' ) <value> ( '\<nl> <value> ) *
+comment ::= '#' <any>
</code></pre>
<p>Notice that this model only supports string properties. For example:</p>
<pre><code># default port
ftp.port = 21
</code></pre>
<p>In addition the XML format defined by <a href="https://docs.oracle.com/javase/7/docs/api/java/util/Properties.html#loadFromXML%28java.io.InputStream%29">java.util.Property</a> is supported if the file starts with the character <code><</code>.</p>
-<h4><a href="#limitations" name="limitations">Limitations</a></h4>
+<h4><a href="#limitations" id="limitations">Limitations</a></h4>
<ul>
- <li>Only String types are supported</li>
- <li>Only ISO 8859-1 character encoding supported</li>
- <li>No multi-values</li>
- <li>No writeback support</li>
+<li>Only String types are supported</li>
+<li>Only ISO 8859-1 character encoding supported</li>
+<li>No multi-values</li>
+<li>No writeback support</li>
</ul>
-<h3><a href="#sling-osgiconfig-resources" name="sling-osgiconfig-resources">sling:OsgiConfig resources</a></h3>
+<h3><a href="#slingosgiconfig-resources" id="slingosgiconfig-resources">sling:OsgiConfig resources</a></h3>
<p>Only the <a href="/documentation/bundles/jcr-installer-provider.html#configuration-and-scanning">JCR Installer</a> supports also configurations given as resources with properties of type <code>sling:OsgiConfig</code>. Internally those are converted directly into the Dictionary format being supported by the <a href="https://osgi.org/javadoc/r4v42/org/osgi/service/cm/Configuration.html#update%28java.util.Dictionary%29">OSGi Configuration Admin</a> in <a href="https://github.com/apache/s [...]
<p>While this way of specifying configurations in a JCR repository seems like a natural fit, it should be avoided as it neither supports all required types nor is it portable.</p>
-<h4><a href="#limitations" name="limitations">Limitations</a></h4>
+<h4><a href="#limitations" id="limitations">Limitations</a></h4>
<ul>
- <li>Not all types supported (<a href="https://issues.apache.org/jira/browse/SLING-2477">SLING-2477</a>)</li>
- <li>No writeback support</li>
- <li>Only array multivalue support (<a href="https://issues.apache.org/jira/browse/SLING-4183">SLING-4183</a>)</li>
+<li>Not all types supported (<a href="https://issues.apache.org/jira/browse/SLING-2477">SLING-2477</a>)</li>
+<li>No writeback support</li>
+<li>Only array multivalue support (<a href="https://issues.apache.org/jira/browse/SLING-4183">SLING-4183</a>)</li>
</ul>
-<h1><a href="#project-info" name="project-info">Project Info</a></h1>
+<h1><a href="#project-info" id="project-info">Project Info</a></h1>
<ul>
- <li>Configuration installer factory (<a href="https://github.com/apache/sling-org-apache-sling-installer-factory-configuration">org.apache.sling.installer.factory.configuration</a>)</li>
-</ul></section></div></div>
+<li>Configuration installer factory (<a href="https://github.com/apache/sling-org-apache-sling-installer-factory-configuration">org.apache.sling.installer.factory.configuration</a>)</li>
+</ul>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/connection-timeout-agent.html b/documentation/bundles/connection-timeout-agent.html
index 07c9782..900d675 100644
--- a/documentation/bundles/connection-timeout-agent.html
+++ b/documentation/bundles/connection-timeout-agent.html
@@ -112,25 +112,25 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h2><a href="#connection-timeout-agent" name="connection-timeout-agent">Connection Timeout Agent</a></h2>
+<h2><a href="#connection-timeout-agent" id="connection-timeout-agent">Connection Timeout Agent</a></h2>
<p>This module provides a java agent that uses the <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/instrument/package-summary.html">instrumentation API</a> to add connect and read timeouts to connections made via HTTP or HTTPs. It only applies these timeouts if none were set explicitly.</p>
<p>The agent is intended as an additional layer of control to use when running untrusted client code that may make calls without explicitly setting timeouts. It is always recommended to set timeouts in client code, rather than relying on this agent.</p>
<p>It currently supports setting timeouts for HTTP connections done using:</p>
<ul>
- <li><a href="https://docs.oracle.com/javase/7/docs/api/java/net/URL.html">java.net.URL</a> and/or <a href="https://docs.oracle.com/javase/7/docs/api/java/net/URLConnection.html">java.net.URLConnection</a></li>
- <li><a href="https://hc.apache.org/httpclient-3.x/">Apache Commons HttpClient 3.x</a></li>
- <li><a href="https://hc.apache.org/httpcomponents-client-ga/">Apache HttpComponents Client 4.x</a></li>
- <li><a href="https://square.github.io/okhttp/">OK Http</a></li>
+<li><a href="https://docs.oracle.com/javase/7/docs/api/java/net/URL.html">java.net.URL</a> and/or <a href="https://docs.oracle.com/javase/7/docs/api/java/net/URLConnection.html">java.net.URLConnection</a></li>
+<li><a href="https://hc.apache.org/httpclient-3.x/">Apache Commons HttpClient 3.x</a></li>
+<li><a href="https://hc.apache.org/httpcomponents-client-ga/">Apache HttpComponents Client 4.x</a></li>
+<li><a href="https://square.github.io/okhttp/">OK Http</a></li>
</ul>
-<h2><a href="#usage" name="usage">Usage</a></h2>
+<h2><a href="#usage" id="usage">Usage</a></h2>
<p>The agent can be loaded using the standard Java CLI invocation, by using the <code>-javaagent:...</code> argument.</p>
<pre><code>java -javaagent:org.apache.sling.connection-timeout-agent-jar-with-dependencies.jar=<agent-connect-timeout>,<agent-read-timeout>[,<logspec>] -jar org.apache.sling.starter-11.jar
</code></pre>
<p>It support two mandatory arguments and an optional one:</p>
<ul>
- <li><code><agent-connect-timeout></code> - connection timeout in milliseconds to apply via the agent</li>
- <li><code><agent-read-timeout></code>- read timeout in milliseconds to apply via the agent</li>
- <li><code><logspec></code> - if set to <code>v</code>, it will enter verbose mode and print additional information to <code>System.out</code></li>
+<li><code><agent-connect-timeout></code> - connection timeout in milliseconds to apply via the agent</li>
+<li><code><agent-read-timeout></code>- read timeout in milliseconds to apply via the agent</li>
+<li><code><logspec></code> - if set to <code>v</code>, it will enter verbose mode and print additional information to <code>System.out</code></li>
</ul>
<p>If started in verbose mode, output similar to the following will be printed</p>
<pre><code>[AGENT] Preparing to install URL transformers. Configured timeouts - connectTimeout : 1000, readTimeout: 1000
@@ -141,28 +141,29 @@
[AGENT] Transformation of sun/net/www/protocol/http/HttpURLConnection complete
</code></pre>
<p>Note that classes will be transformed when they are loaded. It is expected for a transformer for class <em>A</em> to be active but the class not to be transformed until it is actually used.</p>
-<h2><a href="#jmx" name="jmx">JMX</a></h2>
-<p>Various runtime information is exposed through a JMX MBean registered at <code>org.apache.sling.cta;ObjectType=Agent</code>. </p>
+<h2><a href="#jmx" id="jmx">JMX</a></h2>
+<p>Various runtime information is exposed through a JMX MBean registered at <code>org.apache.sling.cta;ObjectType=Agent</code>.</p>
<p><img src="/documentation/bundles/connection-timeout-agent/jmx-mbeans.png" alt="JMX MBeans" /></p>
-<h2><a href="#alternatives" name="alternatives">Alternatives</a></h2>
+<h2><a href="#alternatives" id="alternatives">Alternatives</a></h2>
<p>It is always recommended to set timeouts in the client code directly. The agent carries some risks, namely:</p>
<ul>
- <li>it is not transparent why and where timeouts are set and can lead to hard-to-debug scenarios</li>
- <li>it only sets one timeout for the whole JVM, whereas various services may need different timeouts</li>
+<li>it is not transparent why and where timeouts are set and can lead to hard-to-debug scenarios</li>
+<li>it only sets one timeout for the whole JVM, whereas various services may need different timeouts</li>
</ul>
<p>All HTTP client libraries offer a way of setting connect and read timeouts, and it strongly recommended to do so. Alternatively, various bundles offer a way of centrally defining timeouts, amongst them:</p>
<ul>
- <li><a href="https://github.com/code-distillery/httpclient-configuration-support">Code Distillery - OSGi Configuration Support for Apache HttpComponents Client</a></li>
- <li><a href="https://caravan.wcm.io/commons/httpclient/">WCM.io Caravan - Commons HTTP Client</a></li>
+<li><a href="https://github.com/code-distillery/httpclient-configuration-support">Code Distillery - OSGi Configuration Support for Apache HttpComponents Client</a></li>
+<li><a href="https://caravan.wcm.io/commons/httpclient/">WCM.io Caravan - Commons HTTP Client</a></li>
</ul>
-<h2><a href="#tested-platforms" name="tested-platforms">Tested platforms</a></h2>
+<h2><a href="#tested-platforms" id="tested-platforms">Tested platforms</a></h2>
<ul>
- <li>openjdk version "1.8.0_212"</li>
- <li>openjdk version "11.0.2" 2019-01-15</li>
- <li>commons-httpclient 3.1</li>
- <li>httpclient 4.5.4</li>
- <li>okhttp 3.14.2</li>
-</ul></section></div></div>
+<li>openjdk version "1.8.0_212"</li>
+<li>openjdk version "11.0.2" 2019-01-15</li>
+<li>commons-httpclient 3.1</li>
+<li>httpclient 4.5.4</li>
+<li>okhttp 3.14.2</li>
+</ul>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/content-distribution.html b/documentation/bundles/content-distribution.html
index 110f2bb..dfb4726 100644
--- a/documentation/bundles/content-distribution.html
+++ b/documentation/bundles/content-distribution.html
@@ -116,117 +116,117 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h2><a href="#introduction" name="introduction">Introduction</a></h2>
+<h2><a href="#introduction" id="introduction">Introduction</a></h2>
<p>The Sling Content Distribution (SCD) module allows one to distribute Sling resources between different Sling instances. The API works at path level and the distribution agents basically enable distribution of specific paths between instances. There are several main usecases in which SCD can help. Typically the distribution is done from one or more source instances to one or more target instances.</p>
-<h2><a href="#distribution-usecases" name="distribution-usecases">Distribution usecases</a></h2>
+<h2><a href="#distribution-usecases" id="distribution-usecases">Distribution usecases</a></h2>
<p>Some of the usecases have sample configuration in <a href="https://github.com/apache/sling/tree/trunk/contrib/extensions/distribution/sample/src/main/resources/SLING-CONTENT/libs/sling/distribution">Distribution Sample Module</a> and are tested in <a href="https://github.com/apache/sling/tree/trunk/contrib/extensions/distribution/it">Distribution ITs Module</a>.</p>
-<h3><a href="#forward-distribution" name="forward-distribution">Forward distribution</a></h3>
+<h3><a href="#forward-distribution" id="forward-distribution">Forward distribution</a></h3>
<p>A forward distribution setup allows one to transfer content from a source instance to a farm of target instances. That is done by pushing the content from source to target.</p>
-<h4><a href="#setup-overview" name="setup-overview">Setup overview</a></h4>
+<h4><a href="#setup-overview" id="setup-overview">Setup overview</a></h4>
<ul>
- <li>one source instance
- <ul>
- <li>one distribution agent connected to importer endpoints for all target instances.</li>
- </ul>
- </li>
- <li>N target instances
- <ul>
- <li>one distribution importer on each target instance used to import packages into the local instance.</li>
- </ul>
- </li>
+<li>one source instance
+<ul>
+<li>one distribution agent connected to importer endpoints for all target instances.</li>
+</ul>
+</li>
+<li>N target instances
+<ul>
+<li>one distribution importer on each target instance used to import packages into the local instance.</li>
+</ul>
+</li>
</ul>
-<h4><a href="#sample-configuration" name="sample-configuration">Sample configuration</a></h4>
+<h4><a href="#sample-configuration" id="sample-configuration">Sample configuration</a></h4>
<ul>
- <li>
- <p>on source instance: one forward agent</p>
- <pre><code>org.apache.sling.distribution.agent.impl.ForwardDistributionAgentFactory-publish.json
+<li>
+<p>on source instance: one forward agent</p>
+<pre><code>org.apache.sling.distribution.agent.impl.ForwardDistributionAgentFactory-publish.json
name="publish"
packageImporter.endpoints=["http://localhost:4503/libs/sling/distribution/services/importers/default"]
</code></pre>
- </li>
- <li>
- <p>on target instance: one local importer</p>
- <pre><code>org.apache.sling.distribution.packaging.impl.importer.LocalDistributionPackageImporterFactory-default
+</li>
+<li>
+<p>on target instance: one local importer</p>
+<pre><code>org.apache.sling.distribution.packaging.impl.importer.LocalDistributionPackageImporterFactory-default
name="default"
</code></pre>
- </li>
+</li>
</ul>
-<h4><a href="#trigger-forward-distribution" name="trigger-forward-distribution">Trigger forward distribution</a></h4>
+<h4><a href="#trigger-forward-distribution" id="trigger-forward-distribution">Trigger forward distribution</a></h4>
<p>Forward distribution can be triggered by sending a <code>POST</code> HTTP request to the agent resource on the source instance with the parameter <code>action=ADD</code> and parameters <code>path=<resourcePath></code>.</p>
<p>The example below distributes the path <code>/content/sample1</code></p>
-<pre><code>$ curl -v -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/publish -d 'action=ADD' -d 'path=/content/sample1'
+<pre><code>$ curl -v -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/publish -d 'action=ADD' -d 'path=/content/sample1'
</code></pre>
-<h3><a href="#reverse-distribution" name="reverse-distribution">Reverse distribution</a></h3>
+<h3><a href="#reverse-distribution" id="reverse-distribution">Reverse distribution</a></h3>
<p>A reverse distribution setup allows one to transfer content from a farm of source instances to a target instance. That is done by pulling the content from source instances into the target instance.</p>
-<h4><a href="#setup-overview" name="setup-overview">Setup overview</a></h4>
+<h4><a href="#setup-overview" id="setup-overview">Setup overview</a></h4>
<ul>
- <li>one target instance
- <ul>
- <li>one distribution agent connected to exporter endpoints for all target instances.</li>
- </ul>
- </li>
- <li>N source instances
- <ul>
- <li>one distribution (queue) agent on each source instance; changes from the source instances are placed in the queues of these agents.</li>
- <li>one distribution exporter on each source instance that exports packages from the queue agent.</li>
- </ul>
- </li>
+<li>one target instance
+<ul>
+<li>one distribution agent connected to exporter endpoints for all target instances.</li>
+</ul>
+</li>
+<li>N source instances
+<ul>
+<li>one distribution (queue) agent on each source instance; changes from the source instances are placed in the queues of these agents.</li>
+<li>one distribution exporter on each source instance that exports packages from the queue agent.</li>
+</ul>
+</li>
</ul>
-<h4><a href="#sample-configuration" name="sample-configuration">Sample configuration</a></h4>
+<h4><a href="#sample-configuration" id="sample-configuration">Sample configuration</a></h4>
<ul>
- <li>
- <p>on target instance: one reverse agent</p>
- <pre><code>org.apache.sling.distribution.agent.impl.ReverseDistributionAgentFactory-reverse.json
+<li>
+<p>on target instance: one reverse agent</p>
+<pre><code>org.apache.sling.distribution.agent.impl.ReverseDistributionAgentFactory-reverse.json
name="reverse"
packageExporter.endpoints=["http://localhost:4503/libs/sling/distribution/services/exporters/reverse"]
</code></pre>
- </li>
- <li>
- <p>on source instance: one queue agent and one exporter for that agent</p>
- <pre><code>org.apache.sling.distribution.agent.impl.QueueDistributionAgentFactory-reverse.json
+</li>
+<li>
+<p>on source instance: one queue agent and one exporter for that agent</p>
+<pre><code>org.apache.sling.distribution.agent.impl.QueueDistributionAgentFactory-reverse.json
name="reverse"
org.apache.sling.distribution.packaging.impl.exporter.AgentDistributionPackageExporterFactory-reverse
name="reverse"
agent.target="(name=reverse)"
</code></pre>
- </li>
+</li>
</ul>
-<h4><a href="#trigger-reverse-distribution" name="trigger-reverse-distribution">Trigger reverse distribution</a></h4>
+<h4><a href="#trigger-reverse-distribution" id="trigger-reverse-distribution">Trigger reverse distribution</a></h4>
<p>Reverse distribution can be triggered by sending a <code>POST</code> HTTP request to the agent resource on the target instance with the parameter <code>action=PULL</code>.</p>
<p>The example below adds the the path <code>/content/sample1</code> and then reverse distribute it.</p>
-<pre><code>$ curl -v -u admin:admin http://localhost:8081/libs/sling/distribution/services/agents/publish -d 'action=PULL' -d 'path=/content/sample1'
+<pre><code>$ curl -v -u admin:admin http://localhost:8081/libs/sling/distribution/services/agents/publish -d 'action=PULL' -d 'path=/content/sample1'
</code></pre>
-<h3><a href="#sync-distribution" name="sync-distribution">Sync distribution</a></h3>
+<h3><a href="#sync-distribution" id="sync-distribution">Sync distribution</a></h3>
<p>A sync distribution setup allows one to synchronize content in a farm of instances. That is done by using a coordinator instance (typically an author instance) that pulls content from all instances in a farm and pushes it back to all.</p>
-<h4><a href="#setup-overview-" name="setup-overview-">Setup overview:</a></h4>
+<h4><a href="#setup-overview" id="setup-overview">Setup overview:</a></h4>
<ul>
- <li>one coordinator instance
- <ul>
- <li>one distribution agent connected to exporter/importer endpoints for all farm instances.</li>
- </ul>
- </li>
- <li>N farm instances
- <ul>
- <li>one distribution (queue) agent on each farm instance; changes from these instances are placed in the queues of the queue agents.</li>
- <li>one distribution exporter on each farm instance that exports packages from the queue agent.</li>
- <li>one distribution importer on each farm instance used to import packages into the local instance.</li>
- </ul>
- </li>
+<li>one coordinator instance
+<ul>
+<li>one distribution agent connected to exporter/importer endpoints for all farm instances.</li>
+</ul>
+</li>
+<li>N farm instances
+<ul>
+<li>one distribution (queue) agent on each farm instance; changes from these instances are placed in the queues of the queue agents.</li>
+<li>one distribution exporter on each farm instance that exports packages from the queue agent.</li>
+<li>one distribution importer on each farm instance used to import packages into the local instance.</li>
+</ul>
+</li>
</ul>
-<h4><a href="#sample-configuration" name="sample-configuration">Sample configuration</a></h4>
+<h4><a href="#sample-configuration" id="sample-configuration">Sample configuration</a></h4>
<ul>
- <li>
- <p>on coordinator instance: one sync agent</p>
- <pre><code>org.apache.sling.distribution.agent.impl.SyncDistributionAgentFactory-sync.json
+<li>
+<p>on coordinator instance: one sync agent</p>
+<pre><code>org.apache.sling.distribution.agent.impl.SyncDistributionAgentFactory-sync.json
name="sync"
packageExporter.endpoints=["http://localhost:4503/libs/sling/distribution/services/exporters/reverse", "http://localhost:4504/libs/sling/distribution/services/exporters/reverse"]
packageImporter.endpoints=["http://localhost:4503/libs/sling/distribution/services/importers/default", "http://localhost:4504/libs/sling/distribution/services/importers/default"]
</code></pre>
- </li>
- <li>
- <p>on each farm instance: one local exporter and one local importer</p>
- <pre><code>org.apache.sling.distribution.agent.impl.QueueDistributionAgentFactory-reverse.json
+</li>
+<li>
+<p>on each farm instance: one local exporter and one local importer</p>
+<pre><code>org.apache.sling.distribution.agent.impl.QueueDistributionAgentFactory-reverse.json
name="reverse"
org.apache.sling.distribution.packaging.impl.exporter.AgentDistributionPackageExporterFactory-reverse
@@ -237,32 +237,32 @@ org.apache.sling.distribution.packaging.impl.importer.LocalDistributionPackageIm
name="reverse"
agent.target="(name=reverse)"
</code></pre>
- </li>
+</li>
</ul>
-<h3><a href="#multidatacenter-sync-distribution" name="multidatacenter-sync-distribution">Multidatacenter sync distribution</a></h3>
+<h3><a href="#multidatacenter-sync-distribution" id="multidatacenter-sync-distribution">Multidatacenter sync distribution</a></h3>
<p>A multidatacenter sync distribution setup allows one to synchronize content in a farm of publish instances across datacenters. This a variation of sync distribution but using a coordinator in each datacenter.</p>
-<h4><a href="#setup-overview" name="setup-overview">Setup overview</a></h4>
+<h4><a href="#setup-overview" id="setup-overview">Setup overview</a></h4>
<ul>
- <li>one coordinator instance in each datacenter
- <ul>
- <li>one distribution agent for intra-datacenter synchronization. Like a regular sync agent it connects to all farm instances in its datacenter and syncronizes them. In addition to a regular sync agent it keeps the packages also in dedicated queues for the other DCs, so that the coordinators from the other DCs can pull the updates.</li>
- <li>one distribution exporter for each queue dedicated for the remote DCs. The inter-dc coordinators from the other DCs will connect to these exporter endpoints.</li>
- <li>one distribution agent for inter-datacenter synchronization; it conntects to the dedicated queues exposed by intra-dc coordinators from the other datacenters.</li>
- </ul>
- </li>
- <li>N farm instances in each datacenter
- <ul>
- <li>one distribution (queue) agent on each farm instance; changes from these instances are placed in the queues of the queue agents.</li>
- <li>one distribution exporter on each farm instance that exports packages from the queue agent.</li>
- <li>one distribution importer on each farm instance used to import packages into the local instance.</li>
- </ul>
- </li>
+<li>one coordinator instance in each datacenter
+<ul>
+<li>one distribution agent for intra-datacenter synchronization. Like a regular sync agent it connects to all farm instances in its datacenter and syncronizes them. In addition to a regular sync agent it keeps the packages also in dedicated queues for the other DCs, so that the coordinators from the other DCs can pull the updates.</li>
+<li>one distribution exporter for each queue dedicated for the remote DCs. The inter-dc coordinators from the other DCs will connect to these exporter endpoints.</li>
+<li>one distribution agent for inter-datacenter synchronization; it conntects to the dedicated queues exposed by intra-dc coordinators from the other datacenters.</li>
+</ul>
+</li>
+<li>N farm instances in each datacenter
+<ul>
+<li>one distribution (queue) agent on each farm instance; changes from these instances are placed in the queues of the queue agents.</li>
+<li>one distribution exporter on each farm instance that exports packages from the queue agent.</li>
+<li>one distribution importer on each farm instance used to import packages into the local instance.</li>
+</ul>
+</li>
</ul>
-<h4><a href="#sample-configuration" name="sample-configuration">Sample configuration</a></h4>
+<h4><a href="#sample-configuration" id="sample-configuration">Sample configuration</a></h4>
<ul>
- <li>
- <p>on coordinator instance: one intradcsync agent with two exporters for the other dcs, and one interdcsync agent that connects to remote exporters.</p>
- <pre><code>org.apache.sling.distribution.agent.impl.SyncDistributionAgentFactory-intradcsync
+<li>
+<p>on coordinator instance: one intradcsync agent with two exporters for the other dcs, and one interdcsync agent that connects to remote exporters.</p>
+<pre><code>org.apache.sling.distribution.agent.impl.SyncDistributionAgentFactory-intradcsync
name="intradcsync"
packageExporter.endpoints=["http://localhost:4503/libs/sling/distribution/services/exporters/reverse", "http://localhost:4504/libs/sling/distribution/services/exporters/reverse"]
packageImporter.endpoints=["http://localhost:4503/libs/sling/distribution/services/importers/default", "http://localhost:4504/libs/sling/distribution/services/importers/default"]
@@ -283,10 +283,10 @@ org.apache.sling.distribution.agent.impl.SyncDistributionAgentFactory-interdcsyn
packageExporter.endpoints=["http://localhost:5502/libs/sling/distribution/services/exporters/dc1queue", "http://localhost:6502/libs/sling/distribution/services/exporters/dc1queue"]
packageImporter.endpoints=["http://localhost:4503/libs/sling/distribution/services/importers/default", "http://localhost:4504/libs/sling/distribution/services/importers/default"]
</code></pre>
- </li>
- <li>
- <p>on each farm instance: one local exporter and one local importer</p>
- <pre><code>org.apache.sling.distribution.agent.impl.QueueDistributionAgentFactory-reverse.json
+</li>
+<li>
+<p>on each farm instance: one local exporter and one local importer</p>
+<pre><code>org.apache.sling.distribution.agent.impl.QueueDistributionAgentFactory-reverse.json
name="reverse"
org.apache.sling.distribution.packaging.impl.exporter.AgentDistributionPackageExporterFactory-reverse
@@ -296,23 +296,24 @@ org.apache.sling.distribution.packaging.impl.exporter.AgentDistributionPackageEx
org.apache.sling.distribution.packaging.impl.importer.LocalDistributionPackageImporterFactory-default
name="default"
</code></pre>
- </li>
+</li>
</ul>
-<h2><a href="#additional-options" name="additional-options">Additional options</a></h2>
-<h3><a href="#how-to-configure-binary-less-distribution-" name="how-to-configure-binary-less-distribution-">How to configure binary-less distribution?</a></h3>
+<h2><a href="#additional-options" id="additional-options">Additional options</a></h2>
+<h3><a href="#how-to-configure-binary-less-distribution" id="how-to-configure-binary-less-distribution">How to configure binary-less distribution?</a></h3>
<p>Binary-less distribution is supported for deployments over a shared data store and involving agents that leverage the Vault based Distribution package exporter (Factory PID: org.apache.sling.distribution.serialization.impl.vlt.VaultDistributionPackageBuilderFactory) package builder.</p>
<p>With binary-less mode enabled, the content packages distributed contain references to binaries rather than the actual binaries.</p>
<p>SCD does not explicitly deal with binary references. Instead, it configures Apache Jackrabbit FileVault export options in order to assemble/import binary references.</p>
<p>Upon import, if a referenced binary is not visible on the destination instance, SCD will retry distributing the content package after a delay has elapsed.</p>
<p>Binary-less is configured by setting the 'useReferences' to true on the VaultDistributionPackageBuilderFactory.</p>
-<h3><a href="#how-to-configure-priority-queue-" name="how-to-configure-priority-queue-">How to configure priority queue?</a></h3>
+<h3><a href="#how-to-configure-priority-queue" id="how-to-configure-priority-queue">How to configure priority queue?</a></h3>
<p>SCD agents allow to prioritize the distribution of content depending on its path. This feature improves the delays in use cases where a subset of the content to be distributed must meet tighter delay than the remaining one (e.g. news flash).</p>
<p>Each agent can be configured with one or more priority queues.</p>
<p>In order to setup the priority queues, configure the 'priorityQueues' agent property by providing the queuePrefix and path regular expression.</p>
-<h3><a href="#how-to-configure-retry-strategy-" name="how-to-configure-retry-strategy-">How to configure retry strategy?</a></h3>
+<h3><a href="#how-to-configure-retry-strategy" id="how-to-configure-retry-strategy">How to configure retry strategy?</a></h3>
<p>The agent behaviour upon failed distribution request can be configured via the Retry Strategy 'retry.strategy' and 'retry.attempts' properties.</p>
<p>With the 'none' strategy, an agent will retry distributing an item forever, blocking the queue until the distribution succeeds. The 'none' strategy guarantees the distribution order but may block the queue until someone resolves the situation.</p>
-<p>With the 'errorQueue' strategy, an agent will automatically create an additional error queue. The agent will retry up to 'retry.attempts' attempts then move the failed item to the error queue. The error queue is passive and allow to keep track of the failed distribution item for post analysis. The 'errorQueue' strategy does not guarantee the distribution order, but it guarantee that the queue is stuck for a bounded number of retries.</p></section></div></div>
+<p>With the 'errorQueue' strategy, an agent will automatically create an additional error queue. The agent will retry up to 'retry.attempts' attempts then move the failed item to the error queue. The error queue is passive and allow to keep track of the failed distribution item for post analysis. The 'errorQueue' strategy does not guarantee the distribution order, but it guarantee that the queue is stuck for a bounded number of retries.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/content-loading-jcr-contentloader.html b/documentation/bundles/content-loading-jcr-contentloader.html
index b5299dc..f0fade9 100644
--- a/documentation/bundles/content-loading-jcr-contentloader.html
+++ b/documentation/bundles/content-loading-jcr-contentloader.html
@@ -119,141 +119,70 @@
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p>Apache Sling provides support for initial content loading into a repository and for registering node types. The <code>sling-jcr-contentloader</code> bundle provides loading of content from a bundle into the repository and the <code>sling-jcr-base</code> bundle provides node type registration.</p>
-<h2><a href="#initial-content-loading" name="initial-content-loading">Initial Content Loading</a></h2>
+<h2><a href="#initial-content-loading" id="initial-content-loading">Initial Content Loading</a></h2>
<p>Bundles can provide initial content, which is loaded into the repository when the bundle has entered the <em>started</em> state. Such content is expected to be contained in the bundles accessible through the Bundle entry API methods. Content to be loaded is declared in the <code>Sling-Initial-Content</code> bundle manifest header. This header takes a comma-separated list of bundle entry paths. Each entry and all its child entries are accessed and entered into starting with the child e [...]
<p>Adding this content preserves the paths of the entries as shown in this table, which assumes a <code>Sling-Initial-Content</code> header entry of <code>SLING-INF/content</code> (with no further directives):</p>
<table>
- <thead>
- <tr>
- <th>Source Entry Paths in Bundle </th>
- <th>Target Repository Path </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>SLING-INF/content/home</code> </td>
- <td><code>/home</code> </td>
- </tr>
- <tr>
- <td><code>SLING-INF/content/content/playground/en/home</code> </td>
- <td><code>/content/playground/en/home</code> </td>
- </tr>
- <tr>
- <td><code>SLING-INF/someothercontent/playground/en/home</code> </td>
- <td>not installed at all, because not below the <code>Sling-Initial-Content</code> header entry </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Source Entry Paths in Bundle </th><th> Target Repository Path </th></tr>
+</thead>
+<tbody>
+<tr><td> <code>SLING-INF/content/home</code> </td><td> <code>/home</code> </td></tr>
+<tr><td> <code>SLING-INF/content/content/playground/en/home</code> </td><td> <code>/content/playground/en/home</code> </td></tr>
+<tr><td> <code>SLING-INF/someothercontent/playground/en/home</code> </td><td> not installed at all, because not below the <code>Sling-Initial-Content</code> header entry </td></tr>
+</tbody>
</table>
<p>Bundle entries are installed as follows:</p>
<table>
- <thead>
- <tr>
- <th>Entry Type </th>
- <th>Installation method </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>Directory </td>
- <td>Created as a node of type <code>sling:Folder</code> unless a content definition file of the same name exists in the same directory as the directory to be installed. Example: A directory <code>SLING-INF/content/dir</code> is installed as node <code>/dir</code> of type <code>nt:folder</code> unless a <code>SLING-INF/content/dir.xml</code> or <code>SLING-INF/content/dir.json</code> file exists which defines the content for the <code>/dir</code> node. </td>
- </tr>
- <tr>
- <td>File </td>
- <td>Unless the file is a content definition file (see below) an <code>nt:file</code> node is created for the file and an <code>nt:resource</code> node is created as its <code>jcr:content</code> child node to take the contents of the bundle file. The properties of the <code>nt:resource</code> node are set from file information as available. If a content definition file exists with the same name as the file plus <code>.json</code> or <code>.xml</code> these properties are set additio [...]
- </tr>
- </tbody>
+<thead>
+<tr><th> Entry Type </th><th> Installation method </th></tr>
+</thead>
+<tbody>
+<tr><td> Directory </td><td> Created as a node of type <code>sling:Folder</code> unless a content definition file of the same name exists in the same directory as the directory to be installed. Example: A directory <code>SLING-INF/content/dir</code> is installed as node <code>/dir</code> of type <code>nt:folder</code> unless a <code>SLING-INF/content/dir.xml</code> or <code>SLING-INF/content/dir.json</code> file exists which defines the content for the <code>/dir</code> node. </td></tr>
+<tr><td> File </td><td> Unless the file is a content definition file (see below) an <code>nt:file</code> node is created for the file and an <code>nt:resource</code> node is created as its <code>jcr:content</code> child node to take the contents of the bundle file. The properties of the <code>nt:resource</code> node are set from file information as available. If a content definition file exists with the same name as the file plus <code>.json</code> or <code>.xml</code> these properties a [...]
+</tbody>
</table>
<p>It is possible to modify the intial content loading default behaviour by using certain optional directives. Directives should be specified separated by semicolon. They are defined as follows:</p>
<table>
- <thead>
- <tr>
- <th>Directive </th>
- <th>Definition </th>
- <th>Default value </th>
- <th>Description </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>overwrite</code> </td>
- <td><code>overwrite:=(true|false)<code> </td>
- <td><code>false</code> </td>
- <td>The overwrite directive specifies if content nodes should be overwritten (at the target repository path, which is "/" by default) or just initially added. If this is true, existing nodes are deleted and a new node is created in the same place. This directive should be used together with the <code>path</code> directive to limit overwriting. </td>
- </tr>
- <tr>
- <td><code>overwriteProperties</code> </td>
- <td><code>overwriteProperties:=(true|false)</code> </td>
- <td><code>false</code> </td>
- <td>The overwriteProperties directive specifying if content properties should be overwritten or just initially added (at the target repository path, which is "/" by default). This directive should be used together with the <code>path</code> directive to limit overwriting. </td>
- </tr>
- <tr>
- <td><code>uninstall</code> </td>
- <td><code>uninstall:=(true|false)</code> </td>
- <td>value from <code>overwrite</code> </td>
- <td>The uninstall directive specifies if content should be uninstalled when bundle is unregistered. This value defaults to the value of the <code>overwrite</code> directive. </td>
- </tr>
- <tr>
- <td><code>path</code> </td>
- <td><code>path:=*/target/location*</code> </td>
- <td><code>/</code> </td>
- <td>The path directive specifies the target node where initial content will be loaded. If the path does not exist yet in the repository, it is created by the content loader. The intermediate nodes are of type <code>sling:Folder</code>. </td>
- </tr>
- <tr>
- <td><code>checkin</code> </td>
- <td><code>checkin:=(true|false)</code> </td>
- <td><code>false</code> </td>
- <td>The checkin directive specifies whether versionable nodes should be checked in. </td>
- </tr>
- <tr>
- <td><code>ignoreImportProviders</code> </td>
- <td><code>ignoreImportProviders:=list of extensions</code> </td>
- <td><code>empty</code> </td>
- <td>This directive can be used to not run one of the configured extractors (see below). </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Directive </th><th> Definition </th><th> Default value </th><th> Description </th></tr>
+</thead>
+<tbody>
+<tr><td> <code>overwrite</code> </td><td> <code>overwrite:=(true|false)<code> </td><td> <code>false</code> </td><td> The overwrite directive specifies if content nodes should be overwritten (at the target repository path, which is "/" by default) or just initially added. If this is true, existing nodes are deleted and a new node is created in the same place. This directive should be used together with the <code>path</code> directive to limit overwriting. </td></tr>
+<tr><td> <code>overwriteProperties</code> </td><td> <code>overwriteProperties:=(true|false)</code> </td><td> <code>false</code> </td><td> The overwriteProperties directive specifying if content properties should be overwritten or just initially added (at the target repository path, which is "/" by default). This directive should be used together with the <code>path</code> directive to limit overwriting. </td></tr>
+<tr><td> <code>uninstall</code> </td><td> <code>uninstall:=(true|false)</code> </td><td> value from <code>overwrite</code> </td><td> The uninstall directive specifies if content should be uninstalled when bundle is unregistered. This value defaults to the value of the <code>overwrite</code> directive. </td></tr>
+<tr><td> <code>path</code> </td><td> <code>path:=<em>/target/location</em></code> </td><td> <code>/</code> </td><td> The path directive specifies the target node where initial content will be loaded. If the path does not exist yet in the repository, it is created by the content loader. The intermediate nodes are of type <code>sling:Folder</code>. </td></tr>
+<tr><td> <code>checkin</code> </td><td> <code>checkin:=(true|false)</code> </td><td> <code>false</code> </td><td> The checkin directive specifies whether versionable nodes should be checked in. </td></tr>
+<tr><td> <code>ignoreImportProviders</code> </td><td> <code>ignoreImportProviders:=list of extensions</code> </td><td> <code>empty</code> </td><td> This directive can be used to not run one of the configured extractors (see below). </td></tr>
+</tbody>
</table>
<p>Examples of these directives within <code>Sling-Initial-Content</code> header entries:</p>
<table>
- <thead>
- <tr>
- <th><code>Sling-Initial-Content</code> header entry </th>
- <th>Behaviour </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>SLING-INF/content/home;overwrite:=true;path:=/home</code> </td>
- <td>Overwrites already existing content in <em>/home</em> and uninstalls the content when the bundle is unregistered. </td>
- </tr>
- <tr>
- <td><code>SLING-INF/content/home;overwriteProperties:=true;path:=/home</code> </td>
- <td>Overwrites properties of existing content in <em>/home</em>. </td>
- </tr>
- <tr>
- <td><code>SLING-INF/content/home;path:=/sites/sling_website</code> </td>
- <td>This loads the content given in <em>SLING-INF/content/home</em> into <em>/sites/sling_website</em>. </td>
- </tr>
- <tr>
- <td><code>SLING-INF/content/home;checkin:=true</code> </td>
- <td>After content loading, versionable nodes are checked in. </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> <code>Sling-Initial-Content</code> header entry </th><th> Behaviour </th></tr>
+</thead>
+<tbody>
+<tr><td> <code>SLING-INF/content/home;overwrite:=true;path:=/home</code> </td><td> Overwrites already existing content in <em>/home</em> and uninstalls the content when the bundle is unregistered. </td></tr>
+<tr><td> <code>SLING-INF/content/home;overwriteProperties:=true;path:=/home</code> </td><td> Overwrites properties of existing content in <em>/home</em>. </td></tr>
+<tr><td> <code>SLING-INF/content/home;path:=/sites/sling_website</code> </td><td> This loads the content given in <em>SLING-INF/content/home</em> into <em>/sites/sling_website</em>. </td></tr>
+<tr><td> <code>SLING-INF/content/home;checkin:=true</code> </td><td> After content loading, versionable nodes are checked in. </td></tr>
+</tbody>
</table>
-<h2><a href="#loading-initial-content-from-bundles" name="loading-initial-content-from-bundles">Loading initial content from bundles</a></h2>
+<h2><a href="#loading-initial-content-from-bundles" id="loading-initial-content-from-bundles">Loading initial content from bundles</a></h2>
<p>Repository items to be loaded into the repository, when the bundle is first installed, may be defined in four ways:</p>
<ol>
- <li>Directories</li>
- <li>Files</li>
- <li>XML descriptor files</li>
- <li>JSON descriptor files</li>
+<li>Directories</li>
+<li>Files</li>
+<li>XML descriptor files</li>
+<li>JSON descriptor files</li>
</ol>
<p>Depending on the bundle entry found in the location indicated by the Sling-Initial-Content bundle manifest header, nodes are created (and/or updated) as follows:</p>
-<h3><a href="#directories" name="directories">Directories</a></h3>
-<p>Unless a node with the name of the directory already exists or has been defined in an XML or JSON descriptor file (see below) a directory is created as a node with the primary node type "nt:folder" in the repository.</p>
-<h3><a href="#files" name="files">Files</a></h3>
-<p>Unless a node with the name of the file already exists or has been defined in an XML or JSON descriptor file (see below) a file is created as two nodes in the repository. The node bearing the name of the file itself is created with the primary node type "nt:file". Underneath this file node, a resource node with the primary node type "nt:resource" is created, which is set to the contents of the file.</p>
-<p>The MIME type is derived from the file name extension by first trying to resolve it from the Bundle entry URL. If this does not resolve to a MIME type, the Sling MIME type resolution service is used to try to find a mime type. If all fals, the MIME type is defaulted to "application/octet-stream". </p>
-<h3><a href="#xml-descriptor-files" name="xml-descriptor-files">XML Descriptor Files</a></h3>
+<h3><a href="#directories" id="directories">Directories</a></h3>
+<p>Unless a node with the name of the directory already exists or has been defined in an XML or JSON descriptor file (see below) a directory is created as a node with the primary node type "nt:folder" in the repository.</p>
+<h3><a href="#files" id="files">Files</a></h3>
+<p>Unless a node with the name of the file already exists or has been defined in an XML or JSON descriptor file (see below) a file is created as two nodes in the repository. The node bearing the name of the file itself is created with the primary node type "nt:file". Underneath this file node, a resource node with the primary node type "nt:resource" is created, which is set to the contents of the file.</p>
+<p>The MIME type is derived from the file name extension by first trying to resolve it from the Bundle entry URL. If this does not resolve to a MIME type, the Sling MIME type resolution service is used to try to find a mime type. If all fals, the MIME type is defaulted to "application/octet-stream". </p>
+<h3><a href="#xml-descriptor-files" id="xml-descriptor-files">XML Descriptor Files</a></h3>
<p>Nodes, Properties and in fact complete subtrees may be described in XML files using either the JCR SystemView format, or the format described below. In either case, the file must have the .xml extension.</p>
<pre><code><node>
<!--
@@ -308,8 +237,8 @@
</node>
</node>
</code></pre>
-<h4><a href="#using-a-custom-xml-format" name="using-a-custom-xml-format">Using a custom XML format</a></h4>
-<p>By writing an XSLT stylesheet file, you can use whatever XML format you prefer. The XML file references an XSLT stylesheet by using the xml-stylesheet processing instruction: </p>
+<h4><a href="#using-a-custom-xml-format" id="using-a-custom-xml-format">Using a custom XML format</a></h4>
+<p>By writing an XSLT stylesheet file, you can use whatever XML format you prefer. The XML file references an XSLT stylesheet by using the xml-stylesheet processing instruction:</p>
<pre><code><?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="my-transform.xsl" type="text/xsl"?> <!-- The path to my-transform.xsl is relative to this file -->
@@ -333,7 +262,7 @@
...
</xsl:stylesheet>
</code></pre>
-<h3><a href="#json-descriptor-files" name="json-descriptor-files">JSON Descriptor Files</a></h3>
+<h3><a href="#json-descriptor-files" id="json-descriptor-files">JSON Descriptor Files</a></h3>
<p>Nodes, Properties and in fact complete subtrees may be described in JSON files using the following skeleton structure (see <a href="http://www.json.org">http://www.json.org</a> or information on the syntax of JSON) :</p>
<pre><code>{
// child node name
@@ -386,14 +315,14 @@
}
}
</code></pre>
-<h3><a href="#extractors" name="extractors">Extractors</a></h3>
+<h3><a href="#extractors" id="extractors">Extractors</a></h3>
<p>By default, the <code>sling-jcr-contentloader</code> bundle tries to extract certain file types during content loading. These include <code>json</code>, <code>xml</code>, <code>zip</code>, and <code>jar</code> files. Therefore all available extractors are used for content processing. However if some files should be put into the repository unextracted, the <code>ignoreImportProviders</code> directive can be used with a comma separated list of extensions that should not be extracted, li [...]
-<h3><a href="#file-name-escaping" name="file-name-escaping">File name escaping</a></h3>
-<p>When the node name you want to import with the JCR ContentLoader contains characters that are not allowed in typical file systems (e.g. a ":" is not allowed on windows file systems), you can URL-encode the file name. It uses the <a href="https://docs.oracle.com/javase/8/docs/api/java/net/URLDecoder.html">Java URLDecoder</a> internally.</p>
+<h3><a href="#file-name-escaping" id="file-name-escaping">File name escaping</a></h3>
+<p>When the node name you want to import with the JCR ContentLoader contains characters that are not allowed in typical file systems (e.g. a ":" is not allowed on windows file systems), you can URL-encode the file name. It uses the <a href="https://docs.oracle.com/javase/8/docs/api/java/net/URLDecoder.html">Java URLDecoder</a> internally.</p>
<p>Example: <code>jcr%3Acontent.txt</code> will be loaded into a node named <code>jcr:content.txt</code>.</p>
-<h3><a href="#workspace-targetting" name="workspace-targetting">Workspace Targetting</a></h3>
-<p>By default, initial content will be loaded into the default workspace. To override this, add a <code>Sling-Initial-Content-Workspace</code> bundle manifest header to specify the workspace. Note that <em>all</em> content from a bundle will be loaded into the same workspace. </p>
-<h3><a href="#example-load-i18n-json-files" name="example-load-i18n-json-files">Example: Load i18n JSON files</a></h3>
+<h3><a href="#workspace-targetting" id="workspace-targetting">Workspace Targetting</a></h3>
+<p>By default, initial content will be loaded into the default workspace. To override this, add a <code>Sling-Initial-Content-Workspace</code> bundle manifest header to specify the workspace. Note that <em>all</em> content from a bundle will be loaded into the same workspace.</p>
+<h3><a href="#example-load-i18n-json-files" id="example-load-i18n-json-files">Example: Load i18n JSON files</a></h3>
<p>The Sling Internationalization Support (i18n) supports providing JSON-filed based i18n files (see <a href="https://sling.apache.org/documentation/bundles/internationalization-support-i18n.html#json-file-based">i18n documentation</a>). In this case the JSON file is not interpreted as content definition file, but is stored as binary file in the repository. Additionally a mixin <code>mix:language</code> and a property <code>jcr:language</code> with the language code has to be set on the [...]
<p>This is an example how such an i18n file can be loaded from an OSGi bundle with the Sling Content Loader.</p>
<p>Within your bundle header you have to define a separate path for the i18n files where you have to explicitly disable the JSON provider:</p>
@@ -403,8 +332,8 @@
</code></pre>
<p>The folder <code>SLING-INF/i18n</code> from your bundles contains a pair of files for each language, e.g.:</p>
<ul>
- <li><code>en.json</code> - The JSON file containing the i18n keys</li>
- <li><code>en.json.xml</code> - Additional content descriptor file setting the mixing and language property</li>
+<li><code>en.json</code> - The JSON file containing the i18n keys</li>
+<li><code>en.json.xml</code> - Additional content descriptor file setting the mixing and language property</li>
</ul>
<p>Example for the content descriptor:</p>
<pre><code><?xml version="1.0" encoding="UTF-8"?>
@@ -418,19 +347,19 @@
</property>
</node>
</code></pre>
-<h2><a href="#declared-node-type-registration" name="declared-node-type-registration">Declared Node Type Registration</a></h2>
+<h2><a href="#declared-node-type-registration" id="declared-node-type-registration">Declared Node Type Registration</a></h2>
<p>The <code>sling-jcr-base</code> bundle provides low-level repository operations which are at the heart of the functionality of Sling: * <em>Node Type Definitions</em> - The class <code>org.apache.sling.content.jcr.base.NodeTypeLoader</code> provides methods to register custom node types with a repository given a repository session and a node type definition file in CND format. This class is also used by this bundle to register node types on behalf of other bundles.</p>
<p>Bundles may list node type definition files in CND format in the <code>Sling-Nodetypes</code> bundle header. This header is a comma-separated list of resources in the respective bundle. Each resource is taken and fed to the <code>NodeTypeLoader</code> to define the node types.</p>
<p>After a bundle has entered the <em>resolved</em> state, the node types listed in the <code>Sling-Nodetypes</code> bundle header are registered with the repository.</p>
-<p>Node types installed by this mechanism will never be removed again by the <code>sling-jcr-base</code> bundle. </p>
+<p>Node types installed by this mechanism will never be removed again by the <code>sling-jcr-base</code> bundle.</p>
<p>Starting with revision 911430, re-registration of existing node types is enabled by default. To disable this, add <code>;rereigster:=false</code> to the resource names for which re-registration should be disabled.</p>
<div class="warning">
Support for re-registration of node types is relatively limited. In Jackrabbit, for example, only "trivial" changes are allowed.
</div>
-<h3><a href="#automated-tests" name="automated-tests">Automated tests</a></h3>
+<h3><a href="#automated-tests" id="automated-tests">Automated tests</a></h3>
<p>The initial content found in the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-content/tree/master/src/main/resources/content/sling-test">sling-test folder of the launchpad initial content</a> is verified by the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/blob/master/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/InitialContentTest.java">InitialContentTest</a> when running the <em>launchpad testing</em> i [...]
<p>Those tests can be used as verified examples of initial content loading. Contributions are welcome to improve the coverage of those tests.</p>
-<h2><a href="#acls-and-principals" name="acls-and-principals">ACLs and Principals</a></h2>
+<h2><a href="#acls-and-principals" id="acls-and-principals">ACLs and Principals</a></h2>
<p><strong>Note:</strong> Creating system users is not supported by contentloader, you should use repoinit instead. Repoinit also allows to set ACLs. See <a href="repository-initialization.html">SlingRepositoryInitializer</a> for more information.</p>
<p>By adding a <code>security:acl</code> object to a content node definition in JSON you can define an ACL for this node. For each array entry in this example an ACE is added. Example:</p>
<pre><code>{
@@ -442,11 +371,11 @@ Support for re-registration of node types is relatively limited. In Jackrabbit,
</code></pre>
<p>If ACLs already exist on the node you can add an <code>order</code> property to each array entry controlling the position where the new ACE is inserted into the list of existing ACEs. Possible values for this property:</p>
<ul>
- <li><strong>first</strong>: Place the target ACE as the first amongst its siblings</li>
- <li><strong>last</strong>: Place the target ACE as the last amongst its siblings</li>
- <li><strong>before xyz</strong>: Place the target ACE immediately before the sibling whose name is xyz</li>
- <li><strong>after xyz</strong>: Place the target ACE immediately after the sibling whose name is xyz</li>
- <li><strong>numeric</strong>: Place the target ACE at the specified index</li>
+<li><strong>first</strong>: Place the target ACE as the first amongst its siblings</li>
+<li><strong>last</strong>: Place the target ACE as the last amongst its siblings</li>
+<li><strong>before xyz</strong>: Place the target ACE immediately before the sibling whose name is xyz</li>
+<li><strong>after xyz</strong>: Place the target ACE immediately after the sibling whose name is xyz</li>
+<li><strong>numeric</strong>: Place the target ACE at the specified index</li>
</ul>
<p>You can also add new principals (users or groups) to the repository by adding a <code>security:principals</code> object. This is not related to any specific path/node, so you can add this JSON fragment anywhere. Example for creating one use and one group:</p>
<pre><code>{
@@ -456,7 +385,7 @@ Support for re-registration of node types is relatively limited. In Jackrabbit,
]
}
</code></pre>
-<h3><a href="#ace-restrictions-since-2-3-0-" name="ace-restrictions-since-2-3-0-">ACE Restrictions (since 2.3.0)</a></h3>
+<h3><a href="#ace-restrictions-since-230" id="ace-restrictions-since-230">ACE Restrictions (since 2.3.0)</a></h3>
<p>When adding a <code>security:acl</code> object to a content node definition in JSON you can also define restrictions on the ACEs to further filter the impact. Example:</p>
<pre><code>{
"security:acl": [
@@ -484,7 +413,8 @@ Support for re-registration of node types is relatively limited. In Jackrabbit,
}
]
}
-</code></pre></section></div></div>
+</code></pre>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/content-package-installer-factory.html b/documentation/bundles/content-package-installer-factory.html
index f7d3777..da2ba3f 100644
--- a/documentation/bundles/content-package-installer-factory.html
+++ b/documentation/bundles/content-package-installer-factory.html
@@ -115,12 +115,13 @@
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p>The content package installer factory provides support for <a href="https://jackrabbit.apache.org/filevault/index.html">Jackrabbit FileVault Content Packages</a> to the <a href="/documentation/bundles/osgi-installer.html">OSGI installer</a>. The provisioning of artifacts is handled by installer providers like the <a href="/documentation/bundles/file-installer-provider.html">file installer</a> or the <a href="/documentation/bundles/jcr-installer-provider. [...]
-<h2><a href="#content-packages" name="content-packages">Content Packages</a></h2>
+<h2><a href="#content-packages" id="content-packages">Content Packages</a></h2>
<p>Content Packages must be provided with extension <code>.zip</code>. They will be automatically installed/uninstalled via the <a href="https://jackrabbit.apache.org/filevault/apidocs/org/apache/jackrabbit/vault/packaging/JcrPackageManager.html">JcrPackageManager API</a>. The (un-)installation behaviour can be further tweaked via the OSGi configuration provided for PID <code>org.apache.sling.installer.factory.packages.impl.PackageTransformer</code></p>
-<h1><a href="#project-info" name="project-info">Project Info</a></h1>
+<h1><a href="#project-info" id="project-info">Project Info</a></h1>
<ul>
- <li>Content package installer factory (<a href="https://github.com/apache/sling-org-apache-sling-installer-factory-packages">org.apache.sling.installer.factory.packages</a>)</li>
-</ul></section></div></div>
+<li>Content package installer factory (<a href="https://github.com/apache/sling-org-apache-sling-installer-factory-packages">org.apache.sling.installer.factory.packages</a>)</li>
+</ul>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html b/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html
index 2bac539..e4b5600 100644
--- a/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html
+++ b/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html
@@ -116,57 +116,57 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h1><a href="#about" name="about">About</a></h1>
+<h1><a href="#about" id="about">About</a></h1>
<p>By default the 'default implementation' us used by the Context-Aware Configuration concerning lookup and persistence of configuration data, resource and property inheritance and context path detection. Using the <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html">SPI</a> it is possible to overlay, extend or replace this functionality.</p>
<p>This page documents the details of the default implementation.</p>
-<h1><a href="#repository-paths" name="repository-paths">Repository paths</a></h1>
+<h1><a href="#repository-paths" id="repository-paths">Repository paths</a></h1>
<p>By default all configuration data is stored in <code>/conf</code>. Fallback paths are <code>/conf/global</code>, <code>/apps/conf</code>and <code>/libs/conf</code>.</p>
<p>The paths are configurable in the service configuration.</p>
-<h1><a href="#context-paths" name="context-paths">Context paths</a></h1>
+<h1><a href="#context-paths" id="context-paths">Context paths</a></h1>
<p>The content resource hierarchy is defined by setting <code>sling:configRef</code> properties. Each resource that has a <code>sling:configRef</code> property set defines the root resource of a context, the whole subtree is the context. Within the subtree further nested contexts can be defined.</p>
-<h1><a href="#configuration-resource-resolving" name="configuration-resource-resolving">Configuration resource resolving</a></h1>
+<h1><a href="#configuration-resource-resolving" id="configuration-resource-resolving">Configuration resource resolving</a></h1>
<p>This illustration shows an example for configuration resource lookup:</p>
<p><img src="config-resource-lookup.png" alt="Configuration resource lookup" /></p>
<p>If you get the context-aware configuration via the API for any resource below <code>/content/tenant1/region1/site1</code> it is looked up in this path in this order:</p>
<ol>
- <li><code>/conf/brand1/tenant1/region1/site1</code> - because referenced by <code>/content/tenant1/region1/site1</code></li>
- <li><code>/conf/brand1/tenant1/region1</code> - because referenced by <code>/content/tenant1/region1</code> (parent context)</li>
- <li><code>/conf/brand1/tenant1</code> - because referenced by <code>/content/tenant1</code> (parent context)</li>
- <li><code>/conf/brand1</code> - because it is a parent of by <code>/conf/brand1/tenant1</code></li>
- <li><code>/conf/global</code> - because it is configured as fallback path</li>
- <li><code>/apps/conf</code> - because it is configured as fallback path</li>
- <li><code>/libs/conf</code> - because it is configured as fallback path</li>
+<li><code>/conf/brand1/tenant1/region1/site1</code> - because referenced by <code>/content/tenant1/region1/site1</code></li>
+<li><code>/conf/brand1/tenant1/region1</code> - because referenced by <code>/content/tenant1/region1</code> (parent context)</li>
+<li><code>/conf/brand1/tenant1</code> - because referenced by <code>/content/tenant1</code> (parent context)</li>
+<li><code>/conf/brand1</code> - because it is a parent of by <code>/conf/brand1/tenant1</code></li>
+<li><code>/conf/global</code> - because it is configured as fallback path</li>
+<li><code>/apps/conf</code> - because it is configured as fallback path</li>
+<li><code>/libs/conf</code> - because it is configured as fallback path</li>
</ol>
<p>So the basic rules are:</p>
<ul>
- <li>Go up in the content resource tree until a resource with <code>sling:configRef</code> is found. This is the 'inner-most' context. Check if a configuration resource exists at the path the property points to.</li>
- <li>Check for parent resources of the references configuration resource (below <code>/conf</code>)</li>
- <li>Go further up in the content resource tree for parent contexts, and check their configuration resources as well (they may reference completely different location below <code>/conf</code>)</li>
- <li>Check the fallback paths</li>
+<li>Go up in the content resource tree until a resource with <code>sling:configRef</code> is found. This is the 'inner-most' context. Check if a configuration resource exists at the path the property points to.</li>
+<li>Check for parent resources of the references configuration resource (below <code>/conf</code>)</li>
+<li>Go further up in the content resource tree for parent contexts, and check their configuration resources as well (they may reference completely different location below <code>/conf</code>)</li>
+<li>Check the fallback paths</li>
</ul>
-<h1><a href="#configuration-persistence" name="configuration-persistence">Configuration persistence</a></h1>
+<h1><a href="#configuration-persistence" id="configuration-persistence">Configuration persistence</a></h1>
<p>Example for the resource structure for a configuration resource at <code>/conf/mysite</code>:</p>
<pre><code>/conf
/mysite
/sling:configs
/x.y.z.MyConfig
- @prop1 = 'value1'
+ @prop1 = 'value1'
@prop2 = 123
@prop3= true
</code></pre>
<p>Explanation:</p>
<ul>
- <li><code>sling:configs</code> is the bucket named which is used by the ConfigurationResolver by default for context-aware configurations. May be another name if you use the ConfigurationResourceResolver directly.</li>
- <li><code>x.y.z.MyConfig</code> is the configuration name, in this case derived from an annotation class. May be any other custom name as well.</li>
- <li><code>prop1..3</code>are example for configuration properties</li>
- <li>It is possible to use deeper hierarchies below <code>sling:configs</code> as well.</li>
- <li>Nested configurations are supported as well. This can be mapped to annotation classes referencing other annotation classes.</li>
+<li><code>sling:configs</code> is the bucket named which is used by the ConfigurationResolver by default for context-aware configurations. May be another name if you use the ConfigurationResourceResolver directly.</li>
+<li><code>x.y.z.MyConfig</code> is the configuration name, in this case derived from an annotation class. May be any other custom name as well.</li>
+<li><code>prop1..3</code>are example for configuration properties</li>
+<li>It is possible to use deeper hierarchies below <code>sling:configs</code> as well.</li>
+<li>Nested configurations are supported as well. This can be mapped to annotation classes referencing other annotation classes.</li>
</ul>
-<h1><a href="#resource-inheritance" name="resource-inheritance">Resource inheritance</a></h1>
+<h1><a href="#resource-inheritance" id="resource-inheritance">Resource inheritance</a></h1>
<p>We distinguish between:</p>
<ul>
- <li>Singleton resources: Configuration resources looked up by the <code>get</code>/<code>as</code> method variants</li>
- <li>Collection resources: Configuration resources lists looked up by the <code>getCollection</code>/<code>asCollection</code> method variants</li>
+<li>Singleton resources: Configuration resources looked up by the <code>get</code>/<code>as</code> method variants</li>
+<li>Collection resources: Configuration resources lists looked up by the <code>getCollection</code>/<code>asCollection</code> method variants</li>
</ul>
<p>For singleton resources, there is not resource inheritance. The first resource that is found in the configuration resource resolving lookup order is returned.</p>
<p>For collection resources there is no resource inheritance enabled by default. The children of the first resource that is found in the configuration resource resolving lookup order are returned.</p>
@@ -175,10 +175,11 @@
<p>Example for resource inheritance:</p>
<p><img src="resource-inheritance.png" alt="Resource inheritance" /></p>
<p>The result of this example is: <strong>C, A, B</strong>. It would by just <strong>C</strong> if the <code>sling:configCollectionInherit</code> is not set.</p>
-<h1><a href="#property-inheritance" name="property-inheritance">Property inheritance</a></h1>
+<h1><a href="#property-inheritance" id="property-inheritance">Property inheritance</a></h1>
<p>By default, no property inheritance takes place. That means only the properties that are stored in the configuration resource are mapped to the annotation class or returned as value map, regardless whether singleton or collection resources are returned, or if resource collection inheritance is enabled or not.</p>
<p>By defining a property <code>sling:configPropertyInherit</code> on the configuration resource, property merging is enabled between the current configuration resource and the next resource with the same name (singleton or resource collection item) in the configuration resource lookup order. That means that all properties that are not defined on the current configuration resource are inherited from the next resources and a merged value map is used for the configuration mapping.</p>
-<p>By setting the property <code>sling:configPropertyInherit</code> on multiple configuration resources that are part of the lookup order it is possible to form deeper inheritance chains following the same rules.</p></section></div></div>
+<p>By setting the property <code>sling:configPropertyInherit</code> on multiple configuration resources that are part of the lookup order it is possible to form deeper inheritance chains following the same rules.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html b/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html
index 2fa454e..b2e81e5 100644
--- a/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html
+++ b/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html
@@ -116,11 +116,11 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h1><a href="#about" name="about">About</a></h1>
+<h1><a href="#about" id="about">About</a></h1>
<p>Using overrides it is possible to override context-aware configuration values globally or for specific content paths (and their subtrees) within an instance. If an override is active the Configuration API returns the overridden values instead of the values from the configuration resources.</p>
<p>An example use case is to overwrite the Site URLs on your staging system which has a copy of the configuration content of the production system installed.</p>
<p>Via the <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html">SPI</a> you can add your own override providers - but in most cases the built-in ones described in this page are sufficient. All override providers use the same override syntax.</p>
-<h1><a href="#override-syntax" name="override-syntax">Override syntax</a></h1>
+<h1><a href="#override-syntax" id="override-syntax">Override syntax</a></h1>
<p>Generally an override consists of one single line. Syntax examples:</p>
<pre><code>{configName}/{propertyName}={propertyJsonValue}
{configName}={propertyJsonObject}
@@ -129,11 +129,11 @@
</code></pre>
<p>The different parts:</p>
<ul>
- <li><code>{configName}</code> - Configuration name - can be a relative path with sub-resources</li>
- <li><code>{propertyName}</code> - Property name</li>
- <li><code>{propertyJsonValue}</code> - Property value in JSON value syntax.</li>
- <li><code>{propertyJsonObject}</code> - If the property name is missing a JSON object can be defined containing all properties as key-value pairs.</li>
- <li><code>{contextPath}</code> - If the context path is missing, the override is applied to all context path. If it is defined (enclosed in brackets), the override is applied only to this content path and it's subtree.</li>
+<li><code>{configName}</code> - Configuration name - can be a relative path with sub-resources</li>
+<li><code>{propertyName}</code> - Property name</li>
+<li><code>{propertyJsonValue}</code> - Property value in JSON value syntax.</li>
+<li><code>{propertyJsonObject}</code> - If the property name is missing a JSON object can be defined containing all properties as key-value pairs.</li>
+<li><code>{contextPath}</code> - If the context path is missing, the override is applied to all context path. If it is defined (enclosed in brackets), the override is applied only to this content path and it's subtree.</li>
</ul>
<p>When the syntax <code>{configName}/{propertyName}={propertyJsonValue}</code> is used, only this specific property is overwritten leaving all other properties in the configuration resource untouched. When the syntax <code>{configName}={propertyJsonObject}</code> is used, all configuration properties in the configuration resources are replaced with the set from the JSON object.</p>
<p>Override string examples with real values:</p>
@@ -146,8 +146,8 @@ x.y.z.MyConfig={"prop1"="value1","prop2"=[1,2,3],&
[/content/region1]my-config/sub1={"prop1":"value 1"}
</code></pre>
<p>If multiple statements are defined affecting the same content path, configuration name and property name, they overwrite each other. That means the override string defined last wins.</p>
-<h1><a href="#built-in-override-providers" name="built-in-override-providers">Built-in override providers</a></h1>
-<h2><a href="#override-via-system-properties" name="override-via-system-properties">Override via system properties</a></h2>
+<h1><a href="#built-in-override-providers" id="built-in-override-providers">Built-in override providers</a></h1>
+<h2><a href="#override-via-system-properties" id="override-via-system-properties">Override via system properties</a></h2>
<p>Allows to define configuration property overrides from system environment properties.</p>
<p>The parameters are defined when starting the JVM using the -D command line parameter. Each parameter contains an override string. All parameter names have to be prefixed with the string <code>sling.caconfig.override.</code>.</p>
<p>Example:</p>
@@ -155,10 +155,11 @@ x.y.z.MyConfig={"prop1"="value1","prop2"=[1,2,3],&
-D"sling.caconfig.override.my-config/property1=[\"value 1\",\"value 2\"]"
-D"sling.caconfig.override.[/content/region1]x.y.z.MyConfig={\"prop1\"=\"value1\",\"prop2\"=[1,2,3],\"prop3\"=true,\"prop4\"=1.23}"
</code></pre>
-<p>This provider is not active by default, it has to be activated via OSGi configuration ("Apache Sling Context-Aware System Property Configuration Override Provider").</p>
-<h2><a href="#override-via-osgi-configuration" name="override-via-osgi-configuration">Override via OSGi configuration</a></h2>
+<p>This provider is not active by default, it has to be activated via OSGi configuration ("Apache Sling Context-Aware System Property Configuration Override Provider").</p>
+<h2><a href="#override-via-osgi-configuration" id="override-via-osgi-configuration">Override via OSGi configuration</a></h2>
<p>Allows to define configuration property overrides from OSGi configuration.</p>
-<p>You can provide multiple providers using a factory configuration ("Apache Sling Context-Aware OSGi Configuration Override Provider"), each of them provides list of override strings.</p></section></div></div>
+<p>You can provide multiple providers using a factory configuration ("Apache Sling Context-Aware OSGi Configuration Override Provider"), each of them provides list of override strings.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html b/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html
index e733196..c25056f 100644
--- a/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html
+++ b/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html
@@ -116,32 +116,33 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h1><a href="#about" name="about">About</a></h1>
+<h1><a href="#about" id="about">About</a></h1>
<p>The Context-Aware Configuration implementation provides a set of Service Provider Interfaces (SPI) that allows you to overlay, enhance or replace the default implementation and adapt it to your needs.</p>
<p>Please use the SPI with care, and first check if the <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html">Default Implementation</a> does not already fulfill your needs.</p>
-<h1><a href="#general-principles" name="general-principles">General principles</a></h1>
+<h1><a href="#general-principles" id="general-principles">General principles</a></h1>
<p>All SPIs share a common principle:</p>
<ul>
- <li>Support multiple strategies at the same time</li>
- <li>No need to switch off or „copy“ the initial strategy</li>
- <li>Apply additional strategies only for those places where needed (“minimally invasive”)</li>
+<li>Support multiple strategies at the same time</li>
+<li>No need to switch off or „copy“ the initial strategy</li>
+<li>Apply additional strategies only for those places where needed (“minimally invasive”)</li>
</ul>
<p>All existing implementations are iterated in order of their service ranking.</p>
-<h1><a href="#context-path-strategy" name="context-path-strategy">Context Path Strategy</a></h1>
+<h1><a href="#context-path-strategy" id="context-path-strategy">Context Path Strategy</a></h1>
<p>By providing an implementation of <code>org.apache.sling.caconfig.resource.spi.ContextPathStrategy</code> you can provide additional ways how context paths and their configuration references are detected in your content resource hierarchy.</p>
<p>E.g. you could implement detecting context paths by project-specific conventions.</p>
-<h1><a href="#configuration-resource-resolver-strategy" name="configuration-resource-resolver-strategy">Configuration Resource Resolver Strategy</a></h1>
+<h1><a href="#configuration-resource-resolver-strategy" id="configuration-resource-resolver-strategy">Configuration Resource Resolver Strategy</a></h1>
<p>By providing an implementation of <code>org.apache.sling.caconfig.resource.spi.ConfigurationResourceResolvingStrategy</code> you can define where configuration data is looked up, and how resource and property inheritance is handled.</p>
-<h1><a href="#configuration-inheritance-strategy" name="configuration-inheritance-strategy">Configuration Inheritance Strategy</a></h1>
+<h1><a href="#configuration-inheritance-strategy" id="configuration-inheritance-strategy">Configuration Inheritance Strategy</a></h1>
<p>By providing an implementation of <code>org.apache.sling.caconfig.spi.ConfigurationInheritanceStrategy</code> you can define if and how resources are inherited across the inheritance chain.</p>
-<h1><a href="#configuration-persistence-strategy" name="configuration-persistence-strategy">Configuration Persistence Strategy</a></h1>
+<h1><a href="#configuration-persistence-strategy" id="configuration-persistence-strategy">Configuration Persistence Strategy</a></h1>
<p>By providing an implementation of <code>org.apache.sling.caconfig.spi.ConfigurationPersistenceStrategy2</code> you can define the persistence structure of the configuration within the configuration resources.</p>
<p>E.g. you could use a specific JCR node type or slightly different content structure to store the configuration data.</p>
-<h1><a href="#configuration-metadata-provider" name="configuration-metadata-provider">Configuration Metadata Provider</a></h1>
+<h1><a href="#configuration-metadata-provider" id="configuration-metadata-provider">Configuration Metadata Provider</a></h1>
<p>By providing an implementation of <code>org.apache.sling.caconfig.spi.ConfigurationMetadataProvider</code> you can provide information about configuration metadata from other sources than annotation classes.</p>
-<h1><a href="#configuration-override-provider" name="configuration-override-provider">Configuration Override Provider</a></h1>
+<h1><a href="#configuration-override-provider" id="configuration-override-provider">Configuration Override Provider</a></h1>
<p>By providing an implementation of <code>org.apache.sling.caconfig.spi.ConfigurationOverrideProvider</code> you can provide your own overrides - if the built-in override providers do not fit your needs.</p>
-<p>See <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html">Override</a> for the list of built-in providers and the override syntax.</p></section></div></div>
+<p>See <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html">Override</a> for the list of built-in providers and the override syntax.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/context-aware-configuration/context-aware-configuration.html b/documentation/bundles/context-aware-configuration/context-aware-configuration.html
index 3215b1d..2c11a2b 100644
--- a/documentation/bundles/context-aware-configuration/context-aware-configuration.html
+++ b/documentation/bundles/context-aware-configuration/context-aware-configuration.html
@@ -116,25 +116,25 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h1><a href="#about" name="about">About</a></h1>
+<h1><a href="#about" id="about">About</a></h1>
<p>These bundles provide a service API that can be used to get context-aware configurations. Context-aware configurations are configurations that are related to a content resource or a resource tree, e.g. a web site or a tenant site.</p>
<p>Here is an example how your content structure may look like:</p>
<p><img src="context-aware-config-example.png" alt="Configuration example" /></p>
<p>The application needs different configuration for different sites, regions and tenants = different contexts. Some parameters may be shared, so inheritance for nested contexts and from global fallback values is supported as well. You have full control which content subtrees are the contexts in your application, the structure above is only an example.</p>
<p>Using the Context-Aware Configuration Java API you can get the matching configuration for each content resource without caring where it is stored or how the inheritance works.</p>
-<h1><a href="#java-api" name="java-api">Java API</a></h1>
+<h1><a href="#java-api" id="java-api">Java API</a></h1>
<p>To get and use configurations, the Java API must be used. Any using code must not make any assumptions on how the context-aware configurations are searched or stored!</p>
<p>The Java API consists of two parts:</p>
<ul>
- <li>Context-Aware Resources: 'Low-level' API for accessing configuration resources (which can be anything, e.g. workflow definitions)</li>
- <li>Context-Aware Configurations: 'High-level' API for accessing configuration data (key/value pairs)</li>
+<li>Context-Aware Resources: 'Low-level' API for accessing configuration resources (which can be anything, e.g. workflow definitions)</li>
+<li>Context-Aware Configurations: 'High-level' API for accessing configuration data (key/value pairs)</li>
</ul>
<p>In most cases you will use only the 'High-level' API for getting context-aware configurations.</p>
-<h2><a href="#context-aware-resources" name="context-aware-resources">Context-Aware Resources</a></h2>
+<h2><a href="#context-aware-resources" id="context-aware-resources">Context-Aware Resources</a></h2>
<p>The base concept are context-aware resources: for a given content resource, a named configuration resource can be get. The service for getting the configuration resources is called the ConfigurationResourceResolver. This service has two methods:</p>
<ul>
- <li>getting a named configuration resource</li>
- <li>getting all child resources of a named configuration resource.</li>
+<li>getting a named configuration resource</li>
+<li>getting all child resources of a named configuration resource.</li>
</ul>
<p>For example to get a configuration resource for a content resource at /content/mysite/page1, you would get a reference to the OSGi service <code>org.apache.sling.caconfig.resource.ConfigurationResourceResolver</code> and write:</p>
<pre><code><!-- TODO syntax marker (#!java) disabled -->Resource contentResource = resourceResolver.getResource("/content/mysite/page1");
@@ -144,9 +144,9 @@ Resource configResource = configurationResourceResolver.getResource(contentResou
<p>Or if you have several configuration resources of the same type and you need all of them:</p>
<pre><code><!-- TODO syntax marker (#!java) disabled -->Collection<Resource> configResources = configurationResourceResolver.getResourceCollection(contentResource, "my-bucket", "my-config");
</code></pre>
-<p>The ConfigurationResourceResolver has a concept of "buckets" (2nd parameter in the method signatures) that allows to separate different types of configuration resources into different resource hierarchies, so you have a separate "namespaces" for the named configuration resources. For example one bucket for workflow definitions, one bucket for template definitions, one for key/value-pairs.</p>
+<p>The ConfigurationResourceResolver has a concept of "buckets" (2nd parameter in the method signatures) that allows to separate different types of configuration resources into different resource hierarchies, so you have a separate "namespaces" for the named configuration resources. For example one bucket for workflow definitions, one bucket for template definitions, one for key/value-pairs.</p>
<p>The configuration name (3rd parameter) defines which configuration you are interested in. The name can be a relative path as well (e.g. <code>"sub1/my-config"</code>).</p>
-<h2><a href="#context-aware-configurations" name="context-aware-configurations">Context-Aware Configurations</a></h2>
+<h2><a href="#context-aware-configurations" id="context-aware-configurations">Context-Aware Configurations</a></h2>
<p>While context-aware resources give you pure resources and your application code can decide what to do with it, the most common use case is some configuration. A configuration is usually described by an annotation class (like Declarative Services does for component configurations). These are typed configuration objects and the context-aware configuration support automatically converts resources into the wanted configuration type.</p>
<p>Context-aware configurations are built on top of context-aware resources. The same concept is used: configurations are named and the service to get them is the ConfigurationResolver. You can get a reference to the OSGi service <code>org.apache.sling.caconfig.ConfigurationResolver</code> - it has a single method to get a ConfigurationBuilder. Alternatively you can directly adapt your content resource directly to the ConfigurationBuilder interface and get the configuration:</p>
<pre><code><!-- TODO syntax marker (#!java) disabled -->Resource contentResource = resourceResolver.getResource("/content/mysite/page1");
@@ -158,51 +158,51 @@ MyConfig config = contentResource.adaptTo(ConfigurationBuilder.class).as(MyConfi
</code></pre>
<p>The ConfigurationBuilder also supports getting the configurations as ValueMap or by adapting the configuration resources e.g. to a Sling Model. In this case you have to specify a configuration name which is otherwise derived automatically from the annotation class.</p>
<p>Internally the ConfigurationResolver used the ConfigurationResourceResolver to get the configuration resources. It uses always the bucket name <code>sling:configs</code>.</p>
-<h1><a href="#contexts-and-configuration-references" name="contexts-and-configuration-references">Contexts and configuration references</a></h1>
+<h1><a href="#contexts-and-configuration-references" id="contexts-and-configuration-references">Contexts and configuration references</a></h1>
<p>When you use the <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html">Default Implementation</a> contexts in the content resource hierarchy is defined by setting <code>sling:configRef</code> properties. Each resource that has a <code>sling:configRef</code> property set defines the root resource of a context, the whole subtree is the context. Within the subtree further nested contexts can be defined. [...]
<p>Example:</p>
<p><img src="context-and-config-reference.png" alt="Context and config reference" /></p>
<p>If you define nested contexts or use a deeper hierarchy of resourced in <code>/conf</code> the inheritance rules are applied. Additionally it is possible to define default values as fallback if no configuration resource exists yet in <code>/conf</code>. See <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html">Default Implementation</a> for details.</p>
-<h1><a href="#describe-configurations-via-annotation-classes" name="describe-configurations-via-annotation-classes">Describe configurations via annotation classes</a></h1>
+<h1><a href="#describe-configurations-via-annotation-classes" id="describe-configurations-via-annotation-classes">Describe configurations via annotation classes</a></h1>
<p>You need an annotation class for each configuration you want to read via the ConfigurationBuilder. The annotation classes may be provided by the applications/libraries you use, or you can define your own annotation classes for your application.</p>
<p>The annotation class may look like this:</p>
<pre><code><!-- TODO syntax marker (#!java) disabled -->@Configuration(label="My Configuration", description="Describe me")
public @interface MyConfig {
-
+
@Property(label="Parameter #1", description="Describe me")
String param1();
-
+
@Property(label="Parameter with Default value", description="Describe me")
String paramWithDefault() default "defValue";
-
+
@Property(label="Integer parameter", description="Describe me")
int intParam();
}
</code></pre>
-<p>The <code>@Configuration</code> annotation is mandatory. All properties on the <code>@Configuration</code> annotation and the <code>@Property</code> annotations are optional - they provide additional metadata for tooling e.g. configuration editors. </p>
+<p>The <code>@Configuration</code> annotation is mandatory. All properties on the <code>@Configuration</code> annotation and the <code>@Property</code> annotations are optional - they provide additional metadata for tooling e.g. configuration editors.</p>
<p>By default the annotation class name is used as configuration name, which is also the recommended option. If you want to use an arbitrary configuration name you can specify it via a <code>name</code> property on the <code>@Configuration</code> annotation.</p>
<p>You may specify custom properties (via <code>property</code> string array) for the configuration class or each properties. They are not used by the Sling Context-Aware configuration implementation, but may be used by additional tooling to manage the configurations.</p>
<p>If you provide your own configuration annotation classes in your bundle, you have to export them and list all class names in a bundle header named <code>Sling-ContextAware-Configuration-Classes</code> - example:</p>
<pre><code>Sling-ContextAware-Configuration-Classes: x.y.z.MyConfig, x.y.z.MyConfig2
</code></pre>
-<p>To automate this you can use the Context-Aware Configuration bnd plugin (see next chapter). </p>
-<h1><a href="#accessing-configuration-from-htl-sightly-templates" name="accessing-configuration-from-htl-sightly-templates">Accessing configuration from HTL/Sightly templates</a></h1>
+<p>To automate this you can use the Context-Aware Configuration bnd plugin (see next chapter).</p>
+<h1><a href="#accessing-configuration-from-htlsightly-templates" id="accessing-configuration-from-htlsightly-templates">Accessing configuration from HTL/Sightly templates</a></h1>
<p>Context-Aware configuration contains a Scripting Binding Values provider with automatically registeres a <code>caconfig</code> variable in your HTL/Sightly scripts to directly access context-aware configurations. It supports both singleton configurations and configuration lists. Please note that configuration lists are only supported when configuration metadata is present (e.g. via an annotation class).</p>
<p>Example for accessing a property of a singleton configuration (with a config name <code>x.y.z.ConfigSample</code>):</p>
<pre><code><!-- TODO syntax marker (#!html) disabled --><dl>
<dt>stringParam:</dt>
- <dd>${caconfig['x.y.z.ConfigSample'].stringParam}</dd>
+ <dd>${caconfig['x.y.z.ConfigSample'].stringParam}</dd>
</dl>
</code></pre>
<p>Example for accessing a property of a configuration list (with a config name <code>x.y.z.ConfigSampleList</code>):</p>
-<pre><code><!-- TODO syntax marker (#!html) disabled --><ul data-sly-list.item="${caconfig['x.y.z.ConfigSampleList']}">
+<pre><code><!-- TODO syntax marker (#!html) disabled --><ul data-sly-list.item="${caconfig['x.y.z.ConfigSampleList']}">
<li>stringParam: ${item.stringParam}</li>
</ul>
</code></pre>
-<p>If you want to access nested configurations you have to use a slash "/" as separator in the property name. Example:</p>
-<pre><code><!-- TODO syntax marker (#!html) disabled -->${caconfig['x.y.z.ConfigSample']['nestedConfig/stringParam']}
+<p>If you want to access nested configurations you have to use a slash "/" as separator in the property name. Example:</p>
+<pre><code><!-- TODO syntax marker (#!html) disabled -->${caconfig['x.y.z.ConfigSample']['nestedConfig/stringParam']}
</code></pre>
-<h1><a href="#context-aware-configuration-bnd-plugin" name="context-aware-configuration-bnd-plugin">Context-Aware Configuration bnd plugin</a></h1>
+<h1><a href="#context-aware-configuration-bnd-plugin" id="context-aware-configuration-bnd-plugin">Context-Aware Configuration bnd plugin</a></h1>
<p>A <a href="http://bnd.bndtools.org/">bnd</a> plugin is provided that scans the classpath of a bundle Maven project at build time and automatically generates a <code>Sling-ContextAware-Configuration-Classes</code> bundle header for all annotation classes annotated with <code>@Configuration</code>. It can be used by both <a href="http://felix.apache.org/components/bundle-plugin/">maven-bundle-plugin</a> and <a href="https://github.com/bndtools/bnd/tree/master/maven/bnd-maven-plugin">bnd [...]
<p>Example configuration:</p>
<pre><code><!-- TODO syntax marker (#!xml) disabled --><plugin>
@@ -229,10 +229,10 @@ public @interface MyConfig {
<groupId>biz.aQute.bnd</groupId>
<artifactId>bnd-maven-plugin</artifactId>
<configuration>
- <bnd><![CDATA[
+ <bnd><![CDATA[
...
- -plugin org.apache.sling.caconfig.bndplugin.ConfigurationClassScannerPlugin
- ]]></bnd>
+ -plugin org.apache.sling.caconfig.bndplugin.ConfigurationClassScannerPlugin
+ ]]></bnd>
</configuration>
<dependencies>
<dependency>
@@ -241,23 +241,23 @@ public @interface MyConfig {
<version>1.0.2</version>
</dependency>
</dependencies>
-</plugin>
+</plugin>
</code></pre>
-<h1><a href="#unit-tests-with-context-aware-configuration" name="unit-tests-with-context-aware-configuration">Unit Tests with Context-Aware Configuration</a></h1>
-<p>When your code depends on Sling Context-Aware Configuration and you want to write Sling Mocks-based unit tests running against the Context-Aware configuration implementation you have to register the proper OSGi services to use them. To make this easier, a "Apache Sling Context-Aware Configuration Mock Plugin" is provided which does this job for you.</p>
+<h1><a href="#unit-tests-with-context-aware-configuration" id="unit-tests-with-context-aware-configuration">Unit Tests with Context-Aware Configuration</a></h1>
+<p>When your code depends on Sling Context-Aware Configuration and you want to write Sling Mocks-based unit tests running against the Context-Aware configuration implementation you have to register the proper OSGi services to use them. To make this easier, a "Apache Sling Context-Aware Configuration Mock Plugin" is provided which does this job for you.</p>
<p>Example for setting up the unit test context rule:</p>
<pre><code><!-- TODO syntax marker (#!java) disabled -->import static org.apache.sling.testing.mock.caconfig.ContextPlugins.CACONFIG;
public class MyTest {
- @Rule
- public SlingContext context = new SlingContextBuilder().plugin(CACONFIG).build();
+ @Rule
+ public SlingContext context = new SlingContextBuilder().plugin(CACONFIG).build();
- @Before
- public void setUp() {
- // register configuration annotation class
- MockContextAwareConfig.registerAnnotationClasses(context, SimpleConfig.class);
- }
+ @Before
+ public void setUp() {
+ // register configuration annotation class
+ MockContextAwareConfig.registerAnnotationClasses(context, SimpleConfig.class);
+ }
...
</code></pre>
<p>In you project define a test dependency (additionally the sling-mock dependency is required):</p>
@@ -268,28 +268,29 @@ public class MyTest {
</dependency>
</code></pre>
<p>Full example: <a href="https://github.com/apache/sling-org-apache-sling-testing-caconfig-mock-plugin/blob/master/src/test/java/org/apache/sling/testing/mock/caconfig/ContextPluginsTest.java">Apache Sling Context-Aware Configuration Mock Plugin Test</a></p>
-<h1><a href="#customizing-the-configuration-lookup" name="customizing-the-configuration-lookup">Customizing the configuration lookup</a></h1>
+<h1><a href="#customizing-the-configuration-lookup" id="customizing-the-configuration-lookup">Customizing the configuration lookup</a></h1>
<p>The Context-Aware Configuration implementation provides a set of Service Provider Interfaces (SPI) that allows you to overlay, enhance or replace the default implementation and adapt it to your needs.</p>
<p>See <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html">SPI</a> for details.</p>
<p>You can also override specific context-aware configuration within an instance - see <a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html">Override</a> for details.</p>
-<h1><a href="#web-console-plugins" name="web-console-plugins">Web Console plugins</a></h1>
+<h1><a href="#web-console-plugins" id="web-console-plugins">Web Console plugins</a></h1>
<p>The Context-Aware Configuration implementation provides two extension to the Felix Web Console:</p>
<ul>
- <li>A plugin "Sling / Context-Aware Configuration" that allows to test configuration resolution and prints outs all metadata. This is helpful debugging the resolution and collection and property inheritance. For each resource and property value the the real source resource path is listed.</li>
- <li>A inventory printer "Sling Context-Aware Configuration" which lists all SPI implementations that are deployed, and additionally prints out all configuration metadata and override strings</li>
+<li>A plugin "Sling / Context-Aware Configuration" that allows to test configuration resolution and prints outs all metadata. This is helpful debugging the resolution and collection and property inheritance. For each resource and property value the the real source resource path is listed.</li>
+<li>A inventory printer "Sling Context-Aware Configuration" which lists all SPI implementations that are deployed, and additionally prints out all configuration metadata and override strings</li>
</ul>
-<p>To use the web console plugin you need to configure a "Service User" mapping for the bundle <code>org.apache.sling.caconfig.impl</code> to a system user which has read access to all context and configuration resources. By default this should be <code>/content</code>, <code>/conf</code>, <code>/apps/conf</code> and <code>/libs/conf</code>.</p>
-<h1><a href="#management-api" name="management-api">Management API</a></h1>
+<p>To use the web console plugin you need to configure a "Service User" mapping for the bundle <code>org.apache.sling.caconfig.impl</code> to a system user which has read access to all context and configuration resources. By default this should be <code>/content</code>, <code>/conf</code>, <code>/apps/conf</code> and <code>/libs/conf</code>.</p>
+<h1><a href="#management-api" id="management-api">Management API</a></h1>
<p>The Context-Aware Configuration Implementation Bundle provides a Management API which allows to read and write configuration data. It supports only Context-Aware configurations, not context-aware resources. It should not be used directly in applications, but is intended to provide an API for editor GUIs and other tools which allow to manage configurations.</p>
<p>The main entry point is the OSGi service <code>org.apache.sling.caconfig.management.ConfigurationManager</code>. It allows to get, write or delete singleton configurations and configuration lists. Configuration data is returned using <code>ConfigurationData</code> and <code>ConfigurationCollectionData</code> objects which also provide access to additional metadata about the resolving process and inheritance/override status of each property. Internally the configuration manager uses th [...]
-<p>Whenever configuration data is read or written from the configuration resources a filtering of property names is applied to make sure "system properties" like <code>jcr:primaryType</code> or <code>jcr:created</code> are not returned as part of the configuration data. A list of regular expressions for this filtering can be configured via the "Apache Sling Context-Aware Configuration Management Settings" OSGi configuration. The configuration is accessible to custom persistence implement [...]
-<h1><a href="#references" name="references">References</a></h1>
+<p>Whenever configuration data is read or written from the configuration resources a filtering of property names is applied to make sure "system properties" like <code>jcr:primaryType</code> or <code>jcr:created</code> are not returned as part of the configuration data. A list of regular expressions for this filtering can be configured via the "Apache Sling Context-Aware Configuration Management Settings" OSGi configuration. The configuration is accessible to custom p [...]
+<h1><a href="#references" id="references">References</a></h1>
<ul>
- <li><a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html">Context-Aware Configuration - Default Implementation</a></li>
- <li><a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html">Context-Aware Configuration - SPI</a></li>
- <li><a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html">Context-Aware Configuration - Override</a></li>
- <li><a href="https://adapt.to/2016/en/schedule/sling-context-aware-configuration.html">Sling Context-Aware Configuration - Talk from adaptTo() 2016</a></li>
-</ul></section></div></div>
+<li><a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html">Context-Aware Configuration - Default Implementation</a></li>
+<li><a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html">Context-Aware Configuration - SPI</a></li>
+<li><a href="http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html">Context-Aware Configuration - Override</a></li>
+<li><a href="https://adapt.to/2016/en/schedule/sling-context-aware-configuration.html">Sling Context-Aware Configuration - Talk from adaptTo() 2016</a></li>
+</ul>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/datasource-providers.html b/documentation/bundles/datasource-providers.html
index da64a0f..2180295 100644
--- a/documentation/bundles/datasource-providers.html
+++ b/documentation/bundles/datasource-providers.html
@@ -117,30 +117,30 @@
<div class="row"><div><section><p>DataSource provider bundle supports creation of <code>DataSource</code> instance and registering them with the OSGi service registry. Application using the DataSource just obtains it from OSGi while an administrator can configure the DataSource via Felix WebConsole configuration UI.</p>
<p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h2><a href="#pooled-connection-datasource-provider" name="pooled-connection-datasource-provider">Pooled Connection DataSource Provider</a></h2>
+<h2><a href="#pooled-connection-datasource-provider" id="pooled-connection-datasource-provider">Pooled Connection DataSource Provider</a></h2>
<p>This bundle enables creating and configuring JDBC DataSource in OSGi environment based on OSGi configuration. It uses <a href="http://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html">Tomcat JDBC Pool</a> as the JDBC Connection Pool provider.</p>
<ol>
- <li>Supports configuring the DataSource based on OSGi config with rich metatype</li>
- <li>Supports deploying of JDBC Driver as independent bundles and not as fragment</li>
- <li>Exposes the DataSource stats as JMX MBean</li>
- <li>Supports updating of DataSource connection pool properties at runtime without restart</li>
+<li>Supports configuring the DataSource based on OSGi config with rich metatype</li>
+<li>Supports deploying of JDBC Driver as independent bundles and not as fragment</li>
+<li>Exposes the DataSource stats as JMX MBean</li>
+<li>Supports updating of DataSource connection pool properties at runtime without restart</li>
</ol>
-<h3><a href="#driver-loading" name="driver-loading">Driver Loading</a></h3>
+<h3><a href="#driver-loading" id="driver-loading">Driver Loading</a></h3>
<p>Loading of JDBC driver is tricky on OSGi env. Mostly one has to attach the Driver bundle as a fragment bundle to the code which creates the JDBC Connection.</p>
<p>With JDBC 4 onwards the Driver class can be loaded via Java SE Service Provider mechanism (SPM) JDBC 4.0 drivers must include the file META-INF/services/java.sql.Driver. This file contains the name of the JDBC driver's implementation of java.sql.Driver. For example, to load the JDBC driver to connect to a Apache Derby database, the META-INF/services/java.sql.Driver file would contain the following entry:</p>
<pre><code>org.apache.derby.jdbc.EmbeddedDriver
</code></pre>
<p>Sling DataSource Provider bundles maintains a <code>DriverRegistry</code> which contains mapping of Driver bundle to Driver class supported by it. With this feature there is no need to wrap the Driver bundle as fragment to DataSource provider bundle</p>
-<h3><a href="#configuration" name="configuration">Configuration</a></h3>
+<h3><a href="#configuration" id="configuration">Configuration</a></h3>
<ol>
- <li>Install the current bundle</li>
- <li>Install the JDBC Driver bundle</li>
- <li>Configure the DataSource from OSGi config for PID <code>org.apache.sling.datasource.DataSourceFactory</code></li>
+<li>Install the current bundle</li>
+<li>Install the JDBC Driver bundle</li>
+<li>Configure the DataSource from OSGi config for PID <code>org.apache.sling.datasource.DataSourceFactory</code></li>
</ol>
<p>If Felix WebConsole is used then you can configure it via Configuration UI at http://localhost:8080/system/console/configMgr/org.apache.sling.datasource.DataSourceFactory</p>
<p><img src="/documentation/development/sling-datasource-config.png" alt="Web Console Config" /></p>
<p>Using the config ui above one can directly configure most of the properties as explained in <a href="http://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html">Tomcat Docs</a></p>
-<h3><a href="#convert-driver-jars-to-bundle" name="convert-driver-jars-to-bundle">Convert Driver jars to Bundle</a></h3>
+<h3><a href="#convert-driver-jars-to-bundle" id="convert-driver-jars-to-bundle">Convert Driver jars to Bundle</a></h3>
<p>Most of the JDBC driver jars have the required OSGi headers and can be directly deployed to OSGi container as bundles. However some of the drivers e.g. Postgres are not having such headers and hence need to be converted to OSGi bundles. For them we can use the <a href="http://bnd.bndtools.org/chapters/390-wrapping.html">Bnd Wrap</a> command.</p>
<p>For example to convert the Postgres driver jar follow the steps below</p>
<pre><code>$ wget https://github.com/bndtools/bnd/releases/download/2.3.0.REL/biz.aQute.bnd-2.3.0.jar -O bnd.jar
@@ -155,20 +155,20 @@ $ java -jar bnd.jar bnd.bnd
</code></pre>
<p>In the steps above we</p>
<ol>
- <li>Download the bnd jar and postgres driver jar</li>
- <li>Create a bnd file with required instructions.</li>
- <li>Execute the bnd command</li>
- <li>Resulting bundle is present in <code>org.postgresql-9.3.1101.jar</code></li>
+<li>Download the bnd jar and postgres driver jar</li>
+<li>Create a bnd file with required instructions.</li>
+<li>Execute the bnd command</li>
+<li>Resulting bundle is present in <code>org.postgresql-9.3.1101.jar</code></li>
</ol>
-<h2><a href="#jndi-datasource" name="jndi-datasource">JNDI DataSource</a></h2>
+<h2><a href="#jndi-datasource" id="jndi-datasource">JNDI DataSource</a></h2>
<p>While running in Application Server the DataSource instance might be managed by app server and registered with JNDI. To enable lookup of DataSource instance from JNDI you can configure <code>JNDIDataSourceFactory</code></p>
<ol>
- <li>Configure the DataSource from OSGi config for PID <code>org.apache.sling.datasource.JNDIDataSourceFactory</code></li>
- <li>Provide the JNDI name to lookup from and other details</li>
+<li>Configure the DataSource from OSGi config for PID <code>org.apache.sling.datasource.JNDIDataSourceFactory</code></li>
+<li>Provide the JNDI name to lookup from and other details</li>
</ol>
<p>If Felix WebConsole is used then you can configure it via Configuration UI at http://localhost:8080/system/console/configMgr/org.apache.sling.datasource.JNDIDataSourceFactory</p>
<p>Once configured <code>JNDIDataSourceFactory</code> would lookup the DataSource instance and register it with OSGi ServiceRegistry</p>
-<h2><a href="#usage" name="usage">Usage</a></h2>
+<h2><a href="#usage" id="usage">Usage</a></h2>
<p>Once the required configuration is done the <code>DataSource</code> would be registered as part of the OSGi Service Registry The service is registered with service property <code>datasource.name</code> whose value is the name of datasource provided in OSGi config.</p>
<p>Following snippet demonstrates accessing the DataSource named <code>foo</code> via DS annotation</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->import javax.sql.DataSource;
@@ -180,14 +180,15 @@ public class DSExample {
private DataSource dataSource;
}
</code></pre>
-<h2><a href="#installation" name="installation">Installation</a></h2>
+<h2><a href="#installation" id="installation">Installation</a></h2>
<p>Download the bundle from <a href="http://sling.apache.org/downloads.cgi">here</a> or use following Maven dependency</p>
<pre><code><!-- TODO syntax marker (::xml) disabled --><dependency>
<groupId>org.apache.sling</groupId>
<artifactId>org.apache.sling.datasource</artifactId>
<version>1.0.0</version>
</dependency>
-</code></pre></section></div></div>
+</code></pre>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/discovery-api-and-impl.html b/documentation/bundles/discovery-api-and-impl.html
index e57c258..95d9dd0 100644
--- a/documentation/bundles/discovery-api-and-impl.html
+++ b/documentation/bundles/discovery-api-and-impl.html
@@ -118,37 +118,37 @@
<p>The <code>discovery-api</code> bundle introduces an abstraction for such scenarios called <code>topology</code>. It provides access to the current topology, allows to be informed of any changes in the topology (such as joining or leaving instances) and contains a simple property exchange mechanism, e.g. to allow building communication services on top of it.</p>
<p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h2><a href="#discovery-entities" name="discovery-entities">Discovery Entities</a></h2>
+<h2><a href="#discovery-entities" id="discovery-entities">Discovery Entities</a></h2>
<p>The Discovery API defines the following entities</p>
-<h3><a href="#instance-instancedescription" name="instance-instancedescription">Instance, InstanceDescription</a></h3>
+<h3><a href="#instance-instancedescription" id="instance-instancedescription">Instance, InstanceDescription</a></h3>
<p>A Sling instance running in one VM is represented in the discovery API by an <code>InstanceDescription</code>:</p>
<ul>
- <li>it represents one Sling instance</li>
- <li>it has thus a unique Sling ID</li>
- <li>it has a flag that marks if it is leader in a cluster (more details below)</li>
- <li>plus it has properties (which can be provided via <code>PropertyProviders</code>)</li>
+<li>it represents one Sling instance</li>
+<li>it has thus a unique Sling ID</li>
+<li>it has a flag that marks if it is leader in a cluster (more details below)</li>
+<li>plus it has properties (which can be provided via <code>PropertyProviders</code>)</li>
</ul>
-<h3><a href="#cluster-clusterview" name="cluster-clusterview">Cluster, ClusterView</a></h3>
+<h3><a href="#cluster-clusterview" id="cluster-clusterview">Cluster, ClusterView</a></h3>
<p>Multiple instances that are connected to the same underlying repository are commonly referred to as a 'Cluster'. The reasoning behind this terminology being that they access the same data and can thus deliver or modify the same data.</p>
<p>In the discovery API this cluster concept is represented via a <code>ClusterView</code> object. A 'view' because it is a momentary snapshot of the cluster and only contains instances that are currently alive. It's features are:</p>
<ul>
- <li>each cluster has a stable leader. Stable meaning it won't change unless that leader crashes.</li>
- <li>it has an ordered, stable list of instances that are part of it, thus currently alive. the relative order of instances in this list is stable, meaning that it only stays or moves up one position if an instance listed 'above' crashes - a newly started instance will always be added at the end of this list.</li>
- <li>plus it has a unique id that is persistent across restarts</li>
+<li>each cluster has a stable leader. Stable meaning it won't change unless that leader crashes.</li>
+<li>it has an ordered, stable list of instances that are part of it, thus currently alive. the relative order of instances in this list is stable, meaning that it only stays or moves up one position if an instance listed 'above' crashes - a newly started instance will always be added at the end of this list.</li>
+<li>plus it has a unique id that is persistent across restarts</li>
</ul>
-<h3><a href="#topology-topologyview" name="topology-topologyview">Topology, TopologyView</a></h3>
+<h3><a href="#topology-topologyview" id="topology-topologyview">Topology, TopologyView</a></h3>
<p>The topology - or more precisely the <code>TopologyView</code> - represents a snapshot (<code>view</code>) of a number of loosely coupled Sling instances (<code>InstanceDescription</code>) and clusters (<code>ClusterView</code>) of a particular deployment. A cluster can consist of one or more instances. Each instance is always part of a cluster (even if the cluster consists of only one instance). The features are:</p>
<ul>
- <li>only one: it has a list of clusters</li>
+<li>only one: it has a list of clusters</li>
</ul>
<p>There are no further assumption made on the structure of a topology.</p>
<p>If different clusters in the topology should represent different 'types of clusters' (eg a publish or an author cluster), then that is not explicitly handled by the discovery API. Instead, applications can define properties on each instance that model such cluster types or other aspects.</p>
-<h2><a href="#cluster-leader-and-instance-ordering" name="cluster-leader-and-instance-ordering">Cluster Leader and Instance Ordering</a></h2>
+<h2><a href="#cluster-leader-and-instance-ordering" id="cluster-leader-and-instance-ordering">Cluster Leader and Instance Ordering</a></h2>
<p>As mentioned the discovery API introduces support for a <code>cluster leader</code>: within each cluster, the API guarantees that one and only one instance is leader at any time. That leader is guaranteed to be <code>stable</code>, ie as long as it stays alive and is visible by other instances of the same cluster, it will stay leader. As soon as it leaves the cluster (or the corresponding implementation bundle is deactivated), another instance in that cluster is elected leader. The le [...]
-<p>Additionally each cluster (<code>ClusterView</code>) orders its instances in a stable list: each newly joined instances is added at the end of the list and retains its order in the list as long as it doesn't leave the cluster. This can be used to distribute "singleton" work amongst the cluster to more than just the leader. </p>
-<h2><a href="#topology-changes" name="topology-changes">Topology Changes</a></h2>
+<p>Additionally each cluster (<code>ClusterView</code>) orders its instances in a stable list: each newly joined instances is added at the end of the list and retains its order in the list as long as it doesn't leave the cluster. This can be used to distribute "singleton" work amongst the cluster to more than just the leader.</p>
+<h2><a href="#topology-changes" id="topology-changes">Topology Changes</a></h2>
<p>The <code>DiscoveryService</code> provides access to the currently valid <code>TopologyView</code>. Additionally, applications can register a <code>TopologyEventListener</code> and thus be informed about any changes in the topology. Whenever the discovery service detects that an instance is no longer responding or has newly joined, or a new leader has been elected, it sends a <code>TOPOLOGY_CHANGING</code> event, starts settling the change within the topology (i.e. making sure everybo [...]
-<p>Additionally, when "only" properties have changed, a <code>PROPERTIES_CHANGED</code> event is sent.</p>
+<p>Additionally, when "only" properties have changed, a <code>PROPERTIES_CHANGED</code> event is sent.</p>
<p>Note that the detection of topology (or properties) changes will incur a delay which is implementation dependent.</p>
<p>The following is an example of a listener. Note that the binding is done automatically by OSGi, as soon as a <code>TopologyEventListener</code> is registered.</p>
<pre><code>import org.apache.felix.scr.annotations.Component;
@@ -161,12 +161,12 @@ import org.apache.sling.discovery.TopologyEventListener;
public class MyTopologyEventListener implements TopologyEventListener {
public void handleTopologyEvent(final TopologyEvent event) {
- // your code here
+ // your code here
}
}
</code></pre>
-<h2><a href="#properties" name="properties">Properties</a></h2>
+<h2><a href="#properties" id="properties">Properties</a></h2>
<p>The discovery API not only lists all clusters and instances that are part of a topology but also provides a simple mechanism for announcing properties of each instance to the topology, via the <code>PropertyProvider</code> service interface.</p>
<p>Typical use cases for this are announcements of endpoint URLs or ports such that applications can communicate to other instances in the topology.</p>
<p>Note that the properties mechanism is not meant be used as a messaging tool: both from an API point of view and the implementation of it are not optimized for frequent changes and its use for messaging is discouraged. It is only meant to be used to announce configuration information for accessing proper messaging services.</p>
@@ -181,142 +181,153 @@ import org.apache.sling.discovery.PropertyProvider;
value = {"sample.value1", "sample.value2" })
public class SamplePropertyProvider implements PropertyProvider {
- public String getProperty(final String name) {
- if ("sample.value1".equals(name)) {
- return "foo";
- } else if ("sample.value2".equals(name)) {
- return "bar";
- } else {
- return null;
- }
- }
+ public String getProperty(final String name) {
+ if ("sample.value1".equals(name)) {
+ return "foo";
+ } else if ("sample.value2".equals(name)) {
+ return "bar";
+ } else {
+ return null;
+ }
+ }
}
</code></pre>
-<h2><a href="#deployment-and-configuration" name="deployment-and-configuration">Deployment and configuration</a></h2>
+<h2><a href="#deployment-and-configuration" id="deployment-and-configuration">Deployment and configuration</a></h2>
<p>The discovery API makes no assumptions as to how the instances and clusters discover each other. This is entirely up to the implementations. Some might choose automatic discovery within a LAN using IP multicast, others might choose explicit configuration via a central service etc.</p>
-<h2><a href="#discovery-impl-resource-based-ootb-implementation" name="discovery-impl-resource-based-ootb-implementation">discovery.impl: Resource-based, OOTB Implementation</a></h2>
-<p>The <code>discovery.impl</code> bundle is a resource-based, out of the box implementation of the <code>discovery.api</code> using standard Sling. </p>
-<p>The discovery within a cluster is done by writing heartbeat information into the (common) repository (there's no other form of communication within a cluster). The establishment of a clusterview is done by analyzing these heartbeats, initiating a voting within the cluster (such that each instance can agree that it sees the same number of instances) and by concluding the voting by promoting it as the new "established" view.</p>
+<h2><a href="#discoveryimpl-resource-based-ootb-implementation" id="discoveryimpl-resource-based-ootb-implementation">discovery.impl: Resource-based, OOTB Implementation</a></h2>
+<p>The <code>discovery.impl</code> bundle is a resource-based, out of the box implementation of the <code>discovery.api</code> using standard Sling.</p>
+<p>The discovery within a cluster is done by writing heartbeat information into the (common) repository (there's no other form of communication within a cluster). The establishment of a clusterview is done by analyzing these heartbeats, initiating a voting within the cluster (such that each instance can agree that it sees the same number of instances) and by concluding the voting by promoting it as the new "established" view.</p>
<p>The discovery of instances and clusters outside the local cluster requires explicit configuration of what is termed 'topology connectors', which are HTTP PUTs (see below).</p>
-<h3><a href="#location-in-repository" name="location-in-repository">Location in Repository</a></h3>
+<h3><a href="#location-in-repository" id="location-in-repository">Location in Repository</a></h3>
<p>Administrative note: All the information about the topology is stored at the following location in the repository:</p>
<pre><code>/var/discovery/impl
</code></pre>
-<h4><a href="#var-discovery-impl-clusterinstances-lt-slingid-gt-" name="var-discovery-impl-clusterinstances-lt-slingid-gt-">/var/discovery/impl/clusterInstances/<slingId></a></h4>
+<h4><a href="#vardiscoveryimplclusterinstancesslingid" id="vardiscoveryimplclusterinstancesslingid">/var/discovery/impl/clusterInstances/<slingId></a></h4>
<p>Each instance has its own node under <code>clusterInstances/</code> where it stores:</p>
<ul>
- <li><code>lastHeartbeat</code>: property, which marks the instance as alive for another <code>heartbeatTimeout</code></li>
- <li><code>leaderElectionId</code>: an id which is used to determine the leader: the instance with the lowest such leaderElectionId is the leader. Therefore this id is crucial to implement stable leader and ordering. The id contains a prefix (to account for a crx2 edge case where jobs might want to be executed on slave rather than on master), followed by the bundle activate time (to honour stability) and ultimately by the slingId (to have a discriminator should there be multiple instanc [...]
- <li><code>runtimeId</code>: a plain, random UUID that is created fresh upon bundle activation. It is used to detect situations where multiple instances have the same slingId and thus write into the same <code>/var/discovery/impl/clusterInstances/<slingId></code> node.</li>
- <li><code>slingHomePath</code> and <code>endpoints</code>: these are used for logging purpose only</li>
+<li><code>lastHeartbeat</code>: property, which marks the instance as alive for another <code>heartbeatTimeout</code></li>
+<li><code>leaderElectionId</code>: an id which is used to determine the leader: the instance with the lowest such leaderElectionId is the leader. Therefore this id is crucial to implement stable leader and ordering. The id contains a prefix (to account for a crx2 edge case where jobs might want to be executed on slave rather than on master), followed by the bundle activate time (to honour stability) and ultimately by the slingId (to have a discriminator should there be multiple instances [...]
+<li><code>runtimeId</code>: a plain, random UUID that is created fresh upon bundle activation. It is used to detect situations where multiple instances have the same slingId and thus write into the same <code>/var/discovery/impl/clusterInstances/<slingId></code> node.</li>
+<li><code>slingHomePath</code> and <code>endpoints</code>: these are used for logging purpose only</li>
</ul>
<p>Additionally, there are two sub-nodes:</p>
<ul>
- <li><code>announcements</code>: this contains announcements of topology connector peers (also see below). An announcement is a json-encoded representation of the sub-tree that the connector peer is aware of and is thereby announcing to this instance. Announcements are sent in both directions of a topology connector. Discovery.impl takes care of filtering out duplicate instances should the structure of topology connectors, and thus these announcements overlap (which is legal)</li>
- <li><code>properties</code>: contains all properties as specified by registered <code>PropertyProvider</code></li>
+<li><code>announcements</code>: this contains announcements of topology connector peers (also see below). An announcement is a json-encoded representation of the sub-tree that the connector peer is aware of and is thereby announcing to this instance. Announcements are sent in both directions of a topology connector. Discovery.impl takes care of filtering out duplicate instances should the structure of topology connectors, and thus these announcements overlap (which is legal)</li>
+<li><code>properties</code>: contains all properties as specified by registered <code>PropertyProvider</code></li>
</ul>
-<h4><a href="#var-discovery-impl-establishedview" name="var-discovery-impl-establishedview">/var/discovery/impl/establishedView</a></h4>
+<h4><a href="#vardiscoveryimplestablishedview" id="vardiscoveryimplestablishedview">/var/discovery/impl/establishedView</a></h4>
<p>This contains the currently valid, agreed/voted upon cluster view that lists all alive instances:</p>
<ul>
- <li>the name of the node directly under <code>establishedView</code> is a unique id of the current incarnation of the cluster view - thus changes whenever an instance joins or leaves or there is a new voting for another reason. ** <code>clusterId</code> : name of the persistent identifier of this cluster. As this is propagated from cluster view to cluster view it stays unchanged forever. ** <code>leaderElectionId</code>: the leaderElectionId that was winning, ie that was lowest ** <cod [...]
- <li><code>members</code>: just an intermediate node containing all alive instances as child nodes</li>
- <li>child node of <code>members</code>: each child represents a particular alive node (with the name being the slingId) and contains the following properties: ** <code>leaderElectionId</code>: the id that will be used to determine the leader - this value is copied from the corresponding <code>/var/discovery/impl/clusterInstances/<slingId></code> ** <code>initiator</code>: this marks the instance that originally created this voting ** <code>vote</code>: represents this instance's [...]
+<li>the name of the node directly under <code>establishedView</code> is a unique id of the current incarnation of the cluster view - thus changes whenever an instance joins or leaves or there is a new voting for another reason. ** <code>clusterId</code> : name of the persistent identifier of this cluster. As this is propagated from cluster view to cluster view it stays unchanged forever. ** <code>leaderElectionId</code>: the leaderElectionId that was winning, ie that was lowest ** <code> [...]
+<li><code>members</code>: just an intermediate node containing all alive instances as child nodes</li>
+<li>child node of <code>members</code>: each child represents a particular alive node (with the name being the slingId) and contains the following properties: ** <code>leaderElectionId</code>: the id that will be used to determine the leader - this value is copied from the corresponding <code>/var/discovery/impl/clusterInstances/<slingId></code> ** <code>initiator</code>: this marks the instance that originally created this voting ** <code>vote</code>: represents this instance's vo [...]
</ul>
-<h4><a href="#var-discovery-impl-ongoingvotings" name="var-discovery-impl-ongoingvotings">/var/discovery/impl/ongoingVotings</a></h4>
+<h4><a href="#vardiscoveryimplongoingvotings" id="vardiscoveryimplongoingvotings">/var/discovery/impl/ongoingVotings</a></h4>
<p>This area is used for voting. Each instance can initiate a voting when it realizes that the live instances - denominated by those instances that have a not-yet-timed-out heartbeat property - does not match with the <code>establishedView</code>.</p>
<p>Once a voting gets a yes vote by all instances it is promoted (moved) under <code>establishedView</code> by the initiating instance. Each establishedView was once a voting, thus the structure is the same as described above.</p>
-<h4><a href="#var-discovery-impl-previousview" name="var-discovery-impl-previousview">/var/discovery/impl/previousView</a></h4>
+<h4><a href="#vardiscoveryimplpreviousview" id="vardiscoveryimplpreviousview">/var/discovery/impl/previousView</a></h4>
<p>The instance that promotes its winning voting to <code>establishedView</code> first moves what was there before under <code>previousView</code>. This is purely for debugging and not used anywhere, it just represents a persistet history of previous views of length 1.</p>
-<h3><a href="#heartbeats-voting-and-intra-cluster-discovery" name="heartbeats-voting-and-intra-cluster-discovery">Heartbeats, Voting and Intra-Cluster Discovery</a></h3>
+<h3><a href="#heartbeats-voting-and-intra-cluster-discovery" id="heartbeats-voting-and-intra-cluster-discovery">Heartbeats, Voting and Intra-Cluster Discovery</a></h3>
<p><code>discovery.impl</code> uses the fact that all instance of a cluster are connected to the same repository as the basis for discovering those instances. It does so by using a heartbeat and voting mechanism:</p>
<ul>
- <li>each instance periodically stores a 'heartbeat' into the repository in a well-known location. This is done by setting a corresponding <code>lastHeartbeat</code> property to the current timestamp</li>
- <li>a 'heartbeat' that has not yet timed out is considered a signal that the instance is alive</li>
- <li>as soon as a 'heartbeat' is timed out, the assumption is that the corresponding instance is dead/shutdown</li>
+<li>each instance periodically stores a 'heartbeat' into the repository in a well-known location. This is done by setting a corresponding <code>lastHeartbeat</code> property to the current timestamp</li>
+<li>a 'heartbeat' that has not yet timed out is considered a signal that the instance is alive</li>
+<li>as soon as a 'heartbeat' is timed out, the assumption is that the corresponding instance is dead/shutdown</li>
</ul>
-<p>To avoid having each instance make it's own, perhaps differing conclusions as to which instance/heartbeat is dead or not, there is an explicit, unanimous voting mechanism that agrees upon a list of alive instances. This list of alive instances is called cluster view. </p>
+<p>To avoid having each instance make it's own, perhaps differing conclusions as to which instance/heartbeat is dead or not, there is an explicit, unanimous voting mechanism that agrees upon a list of alive instances. This list of alive instances is called cluster view.</p>
<ul>
- <li>as soon as any instance notices a change in the list of active instances, it is free to calculate a new such list and start a voting in the cluster - each voting carries a unique votingId</li>
- <li>since any instance can do this, you can have concurrent creation of new votings</li>
- <li>each instance has one 'yes' vote - and if there are multiple concurrent votings the lowest one wins</li>
- <li>when a voting receives a 'yes' from all instances that it enlists it is considered as 'winning' and is promoted to be the new, valid view from now on.</li>
- <li>a promoted view is stored in <code>/var/discovery/impl/establishedView</code> and any change therein is passed on in a TopologyEvent to all registered listeners.</li>
+<li>as soon as any instance notices a change in the list of active instances, it is free to calculate a new such list and start a voting in the cluster - each voting carries a unique votingId</li>
+<li>since any instance can do this, you can have concurrent creation of new votings</li>
+<li>each instance has one 'yes' vote - and if there are multiple concurrent votings the lowest one wins</li>
+<li>when a voting receives a 'yes' from all instances that it enlists it is considered as 'winning' and is promoted to be the new, valid view from now on.</li>
+<li>a promoted view is stored in <code>/var/discovery/impl/establishedView</code> and any change therein is passed on in a TopologyEvent to all registered listeners.</li>
</ul>
-<h3><a href="#pseudo-network-partitioning-aka-split-brain" name="pseudo-network-partitioning-aka-split-brain">pseudo-network partitioning aka split-brain</a></h3>
+<h3><a href="#pseudo-network-partitioning-aka-split-brain" id="pseudo-network-partitioning-aka-split-brain">pseudo-network partitioning aka split-brain</a></h3>
<p><code>discovery.impl</code> requires the, eventually consistent, underlying repository to propagate changes within reasonable time: in less than the configured heartbeat timeout. If heartbeats for some reason are not becoming visible by peers in the cluster within that time, <code>discovery.impl</code> will consider that peer instance as dead. At which point it will first send a TOPOLOGY_CHANGING event to all listeners to make them aware that something is changing in the topology, and [...]
-<p>Given the voting is happening through the repository as well, one could imagine a situation where the repository delays can cause a topology to be "pseudo partitioned" into two or more parts, each one agreeing on a set of instances in that sub-cluster (one requirement for such a scenario being that the delays must be asymmetric, ie changes from a subset of instances propagate slow, while the remaining changes propagate fast - ie. two different sets of delays in the cluster). Such a si [...]
+<p>Given the voting is happening through the repository as well, one could imagine a situation where the repository delays can cause a topology to be "pseudo partitioned" into two or more parts, each one agreeing on a set of instances in that sub-cluster (one requirement for such a scenario being that the delays must be asymmetric, ie changes from a subset of instances propagate slow, while the remaining changes propagate fast - ie. two different sets of delays in the cluster). [...]
<p>The following is an illustration of the impact of large cluster delays:</p>
<p><img src="discovery-impl-split-brain.png" alt="discovery.impl split brain" /></p>
<p>In discovery.impl 1.2.2 several improvements have been done to avoid pseudo-network partitioning including the following: (see SLING-3432 for more in-depth details)</p>
<ul>
- <li>SLING-5195 : monitor the HeartbeatHandler for long-running session.saves.</li>
- <li>SLING-5280 : reduce synchronization for HeartbeatHandler to avoid other threads blocking it</li>
- <li>SLING-5030 : avoid "isolated mode" and replace it with larger TOPOLOGY_CHANGING phase</li>
+<li>SLING-5195 : monitor the HeartbeatHandler for long-running session.saves.</li>
+<li>SLING-5280 : reduce synchronization for HeartbeatHandler to avoid other threads blocking it</li>
+<li>SLING-5030 : avoid "isolated mode" and replace it with larger TOPOLOGY_CHANGING phase</li>
</ul>
<p>All of the above greatly reduce the likelyhood of pseudo-network partitioning with <code>discovery.impl</code>, however, as also described in SLING-4640, there is still a small time-window in which it cannot be ruled out entirely. The successor of discovery.impl, the <code>discovery.oak</code> bundle, addresses these concerns to avoid pseudo-network partitioning alltogether.</p>
<p>In the context of <code>discovery.impl</code> it is therefore paramount that the underlying repository is monitored and optimized such that the delays are well under control and do not exceed the configured heartbeat timeout.</p>
-<h3><a href="#topology-connectors-for-cross-cluster-discovery" name="topology-connectors-for-cross-cluster-discovery">Topology Connectors for Cross-Cluster Discovery</a></h3>
+<h3><a href="#topology-connectors-for-cross-cluster-discovery" id="topology-connectors-for-cross-cluster-discovery">Topology Connectors for Cross-Cluster Discovery</a></h3>
<p>From a discovery API's point of view a cluster consists of all instances that are connected to the same repository. The above described built-in mechanism of storing a lastHeartbeat property into the (shared) repository, of voting on changes and creating an explicit establishedView results in automatic discovery within a cluster. There is therefore no further configuration needed for discovering instances in the same cluster.</p>
<p>However, for discovering multiple clusters such an automatic discovery is not possible and the clusters need to be explicitly configured using (cross-cluster) topology connectors:</p>
<p>A topology connector is a periodically issued HTTP PUT that announces the part of the topology known to the sending instance to the receiving instance and vica-verca the receiving instance announces its part of the topology to the sender in the response of the very same HTTP PUT. This way whatever other clusters are connected to sender or receiver will be made known to each other. Such a 'topology announcement' will be valid either until the same sender sends the announcement again (w [...]
<p>Topology connectors are configured at <a href="http://localhost:8080/system/console/configMgr/org.apache.sling.discovery.impl.Config">/system/console/configMgr/org.apache.sling.discovery.impl.Config</a>. They use the same interval and timeout as the repository heartbeats (heartbeatInterval and heartbeatTimeout).</p>
-<h3><a href="#webconsole" name="webconsole">WebConsole</a></h3>
+<h3><a href="#webconsole" id="webconsole">WebConsole</a></h3>
<p>A Felix WebConsole plugin at <a href="http://localhost:8080/system/console/topology">/system/console/topology</a> provides a (read-only) overview of the topology.</p>
-<h3><a href="#configuration" name="configuration">Configuration</a></h3>
+<h3><a href="#configuration" id="configuration">Configuration</a></h3>
<p>The following properties can be configured (at <a href="http://localhost:8080/system/console/configMgr/org.apache.sling.discovery.impl.Config">/system/console/configMgr/org.apache.sling.discovery.impl.Config</a>):</p>
<ul>
- <li>
- <p>heartbeatInterval: the time in seconds between two heartbeats (both cluster-internal and for HTTP-connectors). Default value is 15 seconds.</p></li>
- <li>
- <p>heartbeatTimeout: the time in seconds after which an instance is considered dead if no heartbeat was sent since. Default value is 20 seconds.</p></li>
- <li>
- <p>topologyConnectorUrls: a list of connector URLs to which this instance should connect to. The list can contain multiple instances of the same cluster (for fallback configurations). If the list is empty, no connector will be created. The default relative URL is /libs/sling/topology/connector. Note that this URL is accessible without authentication - to avoid having to configure administrative username/passwords in all instances. Instead, a whitelist approach is used (see next ite [...]
- <li>
- <p>topologyConnectorWhitelist: As mentioned above, the path /libs/sling/topology/connector does not require authentication. To assure that only trusted instances can connect to the topology, its hostname or IP address must be in a whitelist. By default this whitelist only contains localhost and 127.0.0.1.</p></li>
- <li>
- <p>minEventDelay: To reduce the number of events sent during changes, there is a delay (in seconds) before the event is sent. If additional changes happen during this delay, the change will be combined in one event.</p></li>
- <li>
- <p>leaderElectionRepositoryDescriptor: this is an advanced parameter. It denotes a repository descriptor that is evaluated and taken into account for leader Election: the corresponding value of the descriptor is sorted by first.</p></li>
- <li>
- <p>hmacEnabled: If this is true, and sharedKey is set to a value on all Sling instances within the same topology, then messages are validates using a signature of the content of the message based on the shared key. The signature and the digest of the content appear as http headers. When hmac message validation is enabled, whitelisting is disabled. This use useful where the topology messages are transported through multiple reverse proxy layers or the topology is dynamic. The Hmac al [...]
- <li>
- <p>sharedKey: If hmacEnabled is true, this must be set to a secret value, shared amongst all Sling instances that are members of the same topology.</p></li>
- <li>
- <p>enableEncryption: If hmacEnabled is true, and sharedKey is set, setting this to true will encrypt the body of the message using 128 Bit AES encryption. The encryption key is derived from the sharedKey using a 9 byte random salt, giving 2^^72 potential salt values.</p></li>
- <li>
- <p>hmacSharedKeyTTL: The key used for the signatures is derived from the shared key. Each derived key has a lifetime before the next key is generated. This parameter sets the lifetime of each key in ms. The default is 4h. Messages sent using old keys will remain valid for 2x the TTL, after which time the message will be ignored.</p></li>
+<li>
+<p>heartbeatInterval: the time in seconds between two heartbeats (both cluster-internal and for HTTP-connectors). Default value is 15 seconds.</p>
+</li>
+<li>
+<p>heartbeatTimeout: the time in seconds after which an instance is considered dead if no heartbeat was sent since. Default value is 20 seconds.</p>
+</li>
+<li>
+<p>topologyConnectorUrls: a list of connector URLs to which this instance should connect to. The list can contain multiple instances of the same cluster (for fallback configurations). If the list is empty, no connector will be created. The default relative URL is /libs/sling/topology/connector. Note that this URL is accessible without authentication - to avoid having to configure administrative username/passwords in all instances. Instead, a whitelist approach is used (see next item).</p>
+</li>
+<li>
+<p>topologyConnectorWhitelist: As mentioned above, the path /libs/sling/topology/connector does not require authentication. To assure that only trusted instances can connect to the topology, its hostname or IP address must be in a whitelist. By default this whitelist only contains localhost and 127.0.0.1.</p>
+</li>
+<li>
+<p>minEventDelay: To reduce the number of events sent during changes, there is a delay (in seconds) before the event is sent. If additional changes happen during this delay, the change will be combined in one event.</p>
+</li>
+<li>
+<p>leaderElectionRepositoryDescriptor: this is an advanced parameter. It denotes a repository descriptor that is evaluated and taken into account for leader Election: the corresponding value of the descriptor is sorted by first.</p>
+</li>
+<li>
+<p>hmacEnabled: If this is true, and sharedKey is set to a value on all Sling instances within the same topology, then messages are validates using a signature of the content of the message based on the shared key. The signature and the digest of the content appear as http headers. When hmac message validation is enabled, whitelisting is disabled. This use useful where the topology messages are transported through multiple reverse proxy layers or the topology is dynamic. The Hmac algorit [...]
+</li>
+<li>
+<p>sharedKey: If hmacEnabled is true, this must be set to a secret value, shared amongst all Sling instances that are members of the same topology.</p>
+</li>
+<li>
+<p>enableEncryption: If hmacEnabled is true, and sharedKey is set, setting this to true will encrypt the body of the message using 128 Bit AES encryption. The encryption key is derived from the sharedKey using a 9 byte random salt, giving 2^^72 potential salt values.</p>
+</li>
+<li>
+<p>hmacSharedKeyTTL: The key used for the signatures is derived from the shared key. Each derived key has a lifetime before the next key is generated. This parameter sets the lifetime of each key in ms. The default is 4h. Messages sent using old keys will remain valid for 2x the TTL, after which time the message will be ignored.</p>
+</li>
</ul>
-<h2><a href="#discovery-oak-oak-based-ootb-implementation" name="discovery-oak-oak-based-ootb-implementation">discovery.oak: Oak-based, OOTB-implementation</a></h2>
+<h2><a href="#discoveryoak-oak-based-ootb-implementation" id="discoveryoak-oak-based-ootb-implementation">discovery.oak: Oak-based, OOTB-implementation</a></h2>
<p>When running discovery.impl ontop of an eventually consistent repository (such as documentMK of oak), the heartbeat mechanism becomes unreliable. The eventual-ness of the repository has an inherent problem in that it doesn't guarantee by when a change initiated from instance A is visible by instance B. And when there are no hard guarantees, it becomes impossible to choose a <code>heartbeatTimeout</code> that works for all eventualities.</p>
-<p>Therefore it becomes necessary to be able to store heartbeats in a (low-level) location that provides higher consistency (than eventualness). Such a 'low-level location' is the DocumentStore of oak (which is an internal API of the DocumentNodeStore). Turns out that the DocumentNodeStore already has a heartbeat-like concept called leases. Those can be re-used for discovery to fulfill the same aspect as heartbeats do: indicate alive instances. This can further be combined with an explic [...]
-<h3><a href="#jackrabbit-oak-s-discovery-lite" name="jackrabbit-oak-s-discovery-lite">Jackrabbit Oak's discovery-lite</a></h3>
+<p>Therefore it becomes necessary to be able to store heartbeats in a (low-level) location that provides higher consistency (than eventualness). Such a 'low-level location' is the DocumentStore of oak (which is an internal API of the DocumentNodeStore). Turns out that the DocumentNodeStore already has a heartbeat-like concept called leases. Those can be re-used for discovery to fulfill the same aspect as heartbeats do: indicate alive instances. This can further be combined with an explic [...]
+<h3><a href="#jackrabbit-oaks-discovery-lite" id="jackrabbit-oaks-discovery-lite">Jackrabbit Oak's discovery-lite</a></h3>
<p>All of the above mentioned features have been implemented in so-called 'discovery-lite': Discovery-lite is a simplified version of discovery on the oak level. Other than the discovery API it only provides one thing, and that's the clusterview-json:</p>
-<h4><a href="#oak-discoverylite-clusterview-" name="oak-discoverylite-clusterview-">'oak.discoverylite.clusterview'</a></h4>
+<h4><a href="#oakdiscoveryliteclusterview" id="oakdiscoveryliteclusterview">'oak.discoverylite.clusterview'</a></h4>
<p>The discovery-lite descriptor <code>oak.discoverylite.clusterview</code> is a shrink-wrapped json-formatted object representing the current state of the cluster. It contains the following:</p>
<ul>
- <li><code>active</code>: a list of active nodes in the documentNodeStore cluster</li>
- <li><code>deactivating</code>: a list of nodes that are in the process of being deactivated</li>
- <li><code>inactive</code>: a list of nodes that are inactive</li>
- <li><code>me</code>: the id (number) of the local instance (which is always part of the active nodes)</li>
- <li><code>id</code>: the id (unique, persistent) of the cluster (which thus survives node/cluster restarts)</li>
- <li><code>seq</code>: a sequence number that is incremented upon each change in this descriptor (to be able to identify a change even if the other values are unchanged) and shared amongst all instances in the cluster, ie all instances see the same sequence number. This number can thus be used by upper layers to identify this particular incarnation of clusterview.</li>
- <li><code>final</code>: when this flag is <code>false</code> it indicates that the sequence number has changed (as well as eg <code>active</code> and <code>inactive</code>), but that the local instance has not yet fully processed this changed on a low-level. I.e. it marks that the local instance has not yet read the entire back-log of another, deactivating instance. Thus when <code>final==false</code>, the upper layers should wait until <code>final==true</code>, at which point they kno [...]
+<li><code>active</code>: a list of active nodes in the documentNodeStore cluster</li>
+<li><code>deactivating</code>: a list of nodes that are in the process of being deactivated</li>
+<li><code>inactive</code>: a list of nodes that are inactive</li>
+<li><code>me</code>: the id (number) of the local instance (which is always part of the active nodes)</li>
+<li><code>id</code>: the id (unique, persistent) of the cluster (which thus survives node/cluster restarts)</li>
+<li><code>seq</code>: a sequence number that is incremented upon each change in this descriptor (to be able to identify a change even if the other values are unchanged) and shared amongst all instances in the cluster, ie all instances see the same sequence number. This number can thus be used by upper layers to identify this particular incarnation of clusterview.</li>
+<li><code>final</code>: when this flag is <code>false</code> it indicates that the sequence number has changed (as well as eg <code>active</code> and <code>inactive</code>), but that the local instance has not yet fully processed this changed on a low-level. I.e. it marks that the local instance has not yet read the entire back-log of another, deactivating instance. Thus when <code>final==false</code>, the upper layers should wait until <code>final==true</code>, at which point they know [...]
</ul>
-<h4><a href="#accessing-discovery-lite" name="accessing-discovery-lite">Accessing discovery-lite</a></h4>
+<h4><a href="#accessing-discovery-lite" id="accessing-discovery-lite">Accessing discovery-lite</a></h4>
<p>The <code>oak.discoverylite.clusterview</code> descriptor is exposed as a JCR repository descriptor and can be accessed like so:</p>
<pre><code>getRepository().getDescriptor("oak.discoverylite.clusterview")
</code></pre>
<p>which will return the json-formatted clusterview as described above.</p>
<p>Note however, that this API is not meant to be a public, stable API and changes will be done without prior notice. It is merely an internal information exposed by oak and not standardized nor guaranteed to remain supported or unchanged!</p>
-<h3><a href="#sling-s-discovery-oak" name="sling-s-discovery-oak">Sling's discovery.oak</a></h3>
+<h3><a href="#slings-discoveryoak" id="slings-discoveryoak">Sling's discovery.oak</a></h3>
<p>discovery.oak is a implementation of the discovery API that now makes use of this new discovery-lite descriptor in oak. It basically delegates the detection of the instances in the local cluster to discovery-lite. To do so, it periodically reads this descriptor (which is designed to be read at a high-frequency without problems) and triggers <code>TopologyEvents</code> when this descriptor changes.</p>
<p>The advantage of using discovery-lite (which uses oak leases) instead of writing heartbeats into the repository is that discovery.oak thus becomes independent of the speed/latency that the repository can produce under high load. The discovery-lite should be entirley resilient to high load, thus is discovery.oak.</p>
<p>Additionally, it reuses functionality from discovery.impl, such as the way properties (from <code>PropertyProviders</code>) or cross-cluster topology announcements (via topology connectors) are handled.</p>
<p>In order to do this, the discovery.impl bundle has been refactored as follows:</p>
-<h4><a href="#discovery-commons" name="discovery-commons">discovery.commons</a></h4>
+<h4><a href="#discoverycommons" id="discoverycommons">discovery.commons</a></h4>
<p>This is a bundle usable by any implementation of discovery and contains very basic, implementation-independent functionality</p>
-<h4><a href="#discovery-base" name="discovery-base">discovery.base</a></h4>
-<p>This is the base bundle solely used by discovery.impl and discovery.oak and contains exactly the mentioned properties and announcement handling.</p></section></div></div>
+<h4><a href="#discoverybase" id="discoverybase">discovery.base</a></h4>
+<p>This is the base bundle solely used by discovery.impl and discovery.oak and contains exactly the mentioned properties and announcement handling.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/distribution.html b/documentation/bundles/distribution.html
index b966405..bc2a4c0 100644
--- a/documentation/bundles/distribution.html
+++ b/documentation/bundles/distribution.html
@@ -114,50 +114,50 @@
</li>
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
-<div class="row"><div><section><h2><a href="#overview" name="overview">Overview</a></h2>
-<p>The Sling Content Distribution module main goal is allowing distribution of content (Sling resources) among different Sling instances. The term "distribution" here means the ability of picking one or more resources on a certain Sling instance in order to copy and persist them onto another Sling instance. The Sling Content Distribution module is able to distribute content by:</p>
+<div class="row"><div><section><h2><a href="#overview" id="overview">Overview</a></h2>
+<p>The Sling Content Distribution module main goal is allowing distribution of content (Sling resources) among different Sling instances. The term "distribution" here means the ability of picking one or more resources on a certain Sling instance in order to copy and persist them onto another Sling instance. The Sling Content Distribution module is able to distribute content by:</p>
<ul>
- <li>"pushing" from Sling instance A to Sling instance B</li>
- <li>"pulling" from Sling instance B to Sling instance A</li>
- <li>"synchronizing" Sling instances A and B via a (third) coordinating instance C</li>
+<li>"pushing" from Sling instance A to Sling instance B</li>
+<li>"pulling" from Sling instance B to Sling instance A</li>
+<li>"synchronizing" Sling instances A and B via a (third) coordinating instance C</li>
</ul>
-<h3><a href="#bundles" name="bundles">Bundles</a></h3>
+<h3><a href="#bundles" id="bundles">Bundles</a></h3>
<p>The Sling Content Distribution module consists of the following bundles:</p>
<ul>
- <li><code>org.apache.sling.distribution.api</code>: this is where the APIs are defined</li>
- <li><code>org.apache.sling.distribution.core</code>: this is where the basic infrastructure for distributing content is implemented</li>
- <li><code>org.apache.sling.distribution.kryo-serializer</code>: Kryo based distribution package serializer</li>
- <li><code>org.apache.sling.distribution.avro-serializer</code>: Apache Avro based distribution package serializer</li>
- <li><code>org.apache.sling.distribution.sample</code>: this is a set of sample configurations and implementations for demo purpose</li>
- <li><code>org.apache.sling.distribution.it</code>: this is the integration testing suite</li>
+<li><code>org.apache.sling.distribution.api</code>: this is where the APIs are defined</li>
+<li><code>org.apache.sling.distribution.core</code>: this is where the basic infrastructure for distributing content is implemented</li>
+<li><code>org.apache.sling.distribution.kryo-serializer</code>: Kryo based distribution package serializer</li>
+<li><code>org.apache.sling.distribution.avro-serializer</code>: Apache Avro based distribution package serializer</li>
+<li><code>org.apache.sling.distribution.sample</code>: this is a set of sample configurations and implementations for demo purpose</li>
+<li><code>org.apache.sling.distribution.it</code>: this is the integration testing suite</li>
</ul>
-<h2><a href="#design" name="design">Design</a></h2>
+<h2><a href="#design" id="design">Design</a></h2>
<p>The Sling Content Distribution aims to be: <em>Reliable</em>, <em>simple</em> and <em>extensible</em>.</p>
-<p>Reliability means that the system should be able to keep working also in presence of failures regarding I/O, network, etc. An example of such problems is when pushing content from instance A to instance B fails because B is unreachable: in such scenarios instance A should be able to keep pushing (pulling, etc.) content to other instances seamlessly. Another example is when delivery of a certain content (package) fails too many times the distribution module should be able to either d [...]
+<p>Reliability means that the system should be able to keep working also in presence of failures regarding I/O, network, etc. An example of such problems is when pushing content from instance A to instance B fails because B is unreachable: in such scenarios instance A should be able to keep pushing (pulling, etc.) content to other instances seamlessly. Another example is when delivery of a certain content (package) fails too many times the distribution module should be able to either dro [...]
<p>A distribution <em>request</em> represents the need of aggregating some resources and to copy them from / to another Sling instance. Such requests are handled by <em>agents</em> that are the main entry point for working with the distribution module. Each agent distributes content from one or more sources to one or more targets, such distribution can be triggered by:</p>
<ul>
- <li>"pushing" the content to the (remote) target instances</li>
- <li>"pulling" content from the (remote) source instances</li>
- <li>"coordinating" instances, that is they are used to synchronize multiple instances by having them as both sources and targets</li>
+<li>"pushing" the content to the (remote) target instances</li>
+<li>"pulling" content from the (remote) source instances</li>
+<li>"coordinating" instances, that is they are used to synchronize multiple instances by having them as both sources and targets</li>
</ul>
<p>An <em>agent</em> is capable of handling a certain distribution <em>request</em> by creating one or more <em>packages</em> of resources out of it from the source(s), dispatching such <em>packages</em> to one or more <em>queues</em> and of processing such queued <em>packages</em> by persisting them into the target instance(s).</p>
-<p>The process of creating one or more packages is called <em>exporting</em> as such operation may either happen locally to the agent (the "push" scenario) or remotely (the "pull" scenario).</p>
-<p>The process of persisting one or more packages is called <em>importing</em> as such operation may either happen locally (the "pull" scenario) or remotely (the "push" scenario).</p>
-<p>In order to properly handle large number of <em>requests</em> against the same <em>agent</em> each of them is provided with <em>queues</em> where the exported <em>packages</em> are sent, the <em>agent</em> takes then care to process such a <em>queue</em> in order to <em>import</em> each <em>package</em>. </p>
-<h3><a href="#distribution-agents-configuration" name="distribution-agents-configuration">Distribution agents configuration</a></h3>
+<p>The process of creating one or more packages is called <em>exporting</em> as such operation may either happen locally to the agent (the "push" scenario) or remotely (the "pull" scenario).</p>
+<p>The process of persisting one or more packages is called <em>importing</em> as such operation may either happen locally (the "pull" scenario) or remotely (the "push" scenario).</p>
+<p>In order to properly handle large number of <em>requests</em> against the same <em>agent</em> each of them is provided with <em>queues</em> where the exported <em>packages</em> are sent, the <em>agent</em> takes then care to process such a <em>queue</em> in order to <em>import</em> each <em>package</em>.</p>
+<h3><a href="#distribution-agents-configuration" id="distribution-agents-configuration">Distribution agents configuration</a></h3>
<p>Distribution agents configurations are proper OSGi configurations (backed by nodes of type <code>sling:OsgiConfig</code> in the repository).</p>
<p>There are specialized factories for each supported scenario:</p>
<ul>
- <li>"forward" agents, see <a href="https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-sample.git;a=blob_plain;f=src/main/resources/SLING-CONTENT/libs/sling/distribution/install.author/publish/org.apache.sling.distribution.agent.impl.ForwardDistributionAgentFactory-publish.json">ForwardDistributionAgentFactory-publish.json</a>.</li>
- <li>"reverse" agents, see <a href="https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-sample.git;a=blob_plain;f=src/main/resources/SLING-CONTENT/libs/sling/distribution/install.author/publish-reverse/org.apache.sling.distribution.agent.impl.ReverseDistributionAgentFactory-publish-reverse.json">ReverseDistributionAgentFactory-publish-reverse.json</a>.</li>
- <li>"sync" agents, see <a href="https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-sample.git;a=blob_plain;f=src/main/resources/SLING-CONTENT/libs/sling/distribution/install.author/pubsync/org.apache.sling.distribution.agent.impl.SyncDistributionAgentFactory-pubsync.json">SyncDistributionAgentFactory-pubsync.json</a>.</li>
- <li>"queue" agents, see <a href="https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-sample.git;a=blob_plain;f=src/main/resources/SLING-CONTENT/libs/sling/distribution/install.publish/reverse/org.apache.sling.distribution.agent.impl.QueueDistributionAgentFactory-reverse.json">QueueDistributionAgentFactory-reverse.json</a>.</li>
+<li>"forward" agents, see <a href="https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-sample.git;a=blob_plain;f=src/main/resources/SLING-CONTENT/libs/sling/distribution/install.author/publish/org.apache.sling.distribution.agent.impl.ForwardDistributionAgentFactory-publish.json">ForwardDistributionAgentFactory-publish.json</a>.</li>
+<li>"reverse" agents, see <a href="https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-sample.git;a=blob_plain;f=src/main/resources/SLING-CONTENT/libs/sling/distribution/install.author/publish-reverse/org.apache.sling.distribution.agent.impl.ReverseDistributionAgentFactory-publish-reverse.json">ReverseDistributionAgentFactory-publish-reverse.json</a>.</li>
+<li>"sync" agents, see <a href="https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-sample.git;a=blob_plain;f=src/main/resources/SLING-CONTENT/libs/sling/distribution/install.author/pubsync/org.apache.sling.distribution.agent.impl.SyncDistributionAgentFactory-pubsync.json">SyncDistributionAgentFactory-pubsync.json</a>.</li>
+<li>"queue" agents, see <a href="https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-sample.git;a=blob_plain;f=src/main/resources/SLING-CONTENT/libs/sling/distribution/install.publish/reverse/org.apache.sling.distribution.agent.impl.QueueDistributionAgentFactory-reverse.json">QueueDistributionAgentFactory-reverse.json</a>.</li>
</ul>
-<p>For example a "forward" agent can be defined specifying</p>
+<p>For example a "forward" agent can be defined specifying</p>
<ul>
- <li>The name of the agent (name property)</li>
- <li>The sub service name used to access content and build packages (serviceName property)</li>
- <li>The endpoints where the packages are to be imported (packageImporter.endpoints property)</li>
+<li>The name of the agent (name property)</li>
+<li>The sub service name used to access content and build packages (serviceName property)</li>
+<li>The endpoints where the packages are to be imported (packageImporter.endpoints property)</li>
</ul>
<p>The sample package contains endpoints for exposing configuration for distribution agents. The <em>DistributionConfigurationResourceProviderFactory</em> is used to expose agent configurations as resources.</p>
<pre><code>{
@@ -169,7 +169,7 @@
<p>Distribution agents' configurations can be retrieved via <code>HTTP GET</code>:</p>
<pre><code>$ curl -u admin:admin http://localhost:8080/libs/sling/distribution/settings/agents/{agentName}.json
</code></pre>
-<h3><a href="#distribution-agents-services" name="distribution-agents-services">Distribution agents services</a></h3>
+<h3><a href="#distribution-agents-services" id="distribution-agents-services">Distribution agents services</a></h3>
<p>Each distribution agent is an OSGi service and is resolved using a <a href="#Resource_Providers">Sling Resource Provider</a> who locate it under <code>libs/sling/distribution/services/agents</code>.</p>
<p>The <em>DistributionConfigurationResourceProviderFactory</em> allows one to configure HTTP endpoints to access distribution OSGI configurations. The sample package contains endpoints for exposing distribution agents. The <em>DistributionServiceResourceProviderFactory</em> is used to expose agent services as resources.</p>
<pre><code>{
@@ -181,107 +181,108 @@
<p>Distribution agents can be triggered by sending <code>HTTP POST</code> requests to</p>
<p><code>http://$host:$port/libs/sling/distribution/services/agents/{agentName}</code></p>
<p>with HTTP parameters <code>action</code> and <code>path</code>.</p>
-<h3><a href="#distribution-queues" name="distribution-queues">Distribution queues</a></h3>
-<h4><a href="#in-memory-queue" name="in-memory-queue">In Memory queue</a></h4>
+<h3><a href="#distribution-queues" id="distribution-queues">Distribution queues</a></h3>
+<h4><a href="#in-memory-queue" id="in-memory-queue">In Memory queue</a></h4>
<p>That's a draft implementation using an in memory blocking queue together with a Sling scheduled processor which periodically fetches the first item of each queue and trigger a distribution of such an item. It's not suitable for production as it's currently not persisted and therefore restarting the bundle / platform would not keep the queue together with its items.</p>
-<h4><a href="#sling-job-handling-based-queue" name="sling-job-handling-based-queue">Sling Job Handling based queue</a></h4>
+<h4><a href="#sling-job-handling-based-queue" id="sling-job-handling-based-queue">Sling Job Handling based queue</a></h4>
<p>That's a queue implementation based on the queues and jobs provided by Sling Event bundle. Each item addition to a queue triggers the creation of a Sling job which will handle the processing of that item in the queue. By default Sling queues for distribution have the following options:</p>
<ul>
- <li>ordered</li>
- <li>with max priority</li>
- <li>with infinite retries</li>
- <li>keeping job history</li>
+<li>ordered</li>
+<li>with max priority</li>
+<li>with infinite retries</li>
+<li>keeping job history</li>
</ul>
-<h3><a href="#distribution-of-packages-among-queues" name="distribution-of-packages-among-queues">Distribution of packages among queues</a></h3>
+<h3><a href="#distribution-of-packages-among-queues" id="distribution-of-packages-among-queues">Distribution of packages among queues</a></h3>
<p>Each distribution agent uses a specific queue distribution mechanism, specified via a 'queue distribution strategy', which defines how packages are routed into agent queues. The currently available distribution strategies are</p>
<ul>
- <li>single: the agent has one only queue and all the items are routed there</li>
- <li>priority path: the agent can route a configurable set of paths (note that this configuration is currently global for the system, not per agent) to a dedicated priority queue while all the others go to the default queue</li>
- <li>error aware: the agent has one default queue for all the items, items failing for a configurable amount of times are either dropped or moved to an error queue (depending on configuration)</li>
+<li>single: the agent has one only queue and all the items are routed there</li>
+<li>priority path: the agent can route a configurable set of paths (note that this configuration is currently global for the system, not per agent) to a dedicated priority queue while all the others go to the default queue</li>
+<li>error aware: the agent has one default queue for all the items, items failing for a configurable amount of times are either dropped or moved to an error queue (depending on configuration)</li>
</ul>
-<h2><a href="#usecases" name="usecases">Usecases</a></h2>
-<h3><a href="#forward-distribution" name="forward-distribution">Forward distribution</a></h3>
-<p>In order to configure the "forward" distribution workflow, that transfers content from an author instance to a publish instance:</p>
+<h2><a href="#usecases" id="usecases">Usecases</a></h2>
+<h3><a href="#forward-distribution" id="forward-distribution">Forward distribution</a></h3>
+<p>In order to configure the "forward" distribution workflow, that transfers content from an author instance to a publish instance:</p>
<ul>
- <li>configure a remote importer on publish</li>
- <li>configure a "forward" agent on author pointing to the url of the importer on publish</li>
+<li>configure a remote importer on publish</li>
+<li>configure a "forward" agent on author pointing to the url of the importer on publish</li>
</ul>
<p>Send <code>HTTP POST</code>request to <code>http://localhost:8080/libs/sling/distribution/services/agents/publish</code> with parameters <code>action=ADD</code> and <code>path=/content</code></p>
-<h4><a href="#create-update-content" name="create-update-content">Create/update content</a></h4>
-<pre><code>$ curl -v -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/publish -d 'action=ADD' -d 'path=/content/sample1'
+<h4><a href="#createupdate-content" id="createupdate-content">Create/update content</a></h4>
+<pre><code>$ curl -v -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/publish -d 'action=ADD' -d 'path=/content/sample1'
</code></pre>
-<h4><a href="#delete-content" name="delete-content">Delete content</a></h4>
-<pre><code>$ curl -v -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/publish -d 'action= DELETE' -d 'path=/content/sample1'
+<h4><a href="#delete-content" id="delete-content">Delete content</a></h4>
+<pre><code>$ curl -v -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/publish -d 'action= DELETE' -d 'path=/content/sample1'
</code></pre>
-<h3><a href="#reverse-distribution" name="reverse-distribution">Reverse distribution</a></h3>
-<p>In order to configure the "reverse" distribution workflow, that transfers content from a publish instance to an author instance: - configure a queue agent on publish to hold the packages that need to be distributed to author - configure a remote exporter on publish that exports package from the queue agent - configure a "reverse" agent on author pointing to the url of the exporter on publish</p>
+<h3><a href="#reverse-distribution" id="reverse-distribution">Reverse distribution</a></h3>
+<p>In order to configure the "reverse" distribution workflow, that transfers content from a publish instance to an author instance: - configure a queue agent on publish to hold the packages that need to be distributed to author - configure a remote exporter on publish that exports package from the queue agent - configure a "reverse" agent on author pointing to the url of the exporter on publish</p>
<p>Send <code>HTTP POST</code>request to <code>http://localhost:8080/libs/sling/distribution/services/agents/publish-reverse</code> with parameters <code>action=PULL</code></p>
-<h4><a href="#create-update-content" name="create-update-content">Create/update content</a></h4>
-<pre><code>$ curl -u admin:admin http://localhost:8081/libs/sling/distribution/services/agents/reverse -d 'action=ADD' -d 'path=/content/sample1'
-$ curl -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/publish-reverse -d 'action=PULL'
+<h4><a href="#createupdate-content" id="createupdate-content">Create/update content</a></h4>
+<pre><code>$ curl -u admin:admin http://localhost:8081/libs/sling/distribution/services/agents/reverse -d 'action=ADD' -d 'path=/content/sample1'
+$ curl -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/publish-reverse -d 'action=PULL'
</code></pre>
-<h3><a href="#sync-distribution" name="sync-distribution">Sync distribution</a></h3>
-<p>In order to configure the "sync" distribution workflow, that transfers content from two publish instances via an author instance: - configure a remote exporter on each publish instance - configure a remote importer on each publish instance - configure a "sync" agent on author pointing to the urls of the exporter and importers on publish</p>
+<h3><a href="#sync-distribution" id="sync-distribution">Sync distribution</a></h3>
+<p>In order to configure the "sync" distribution workflow, that transfers content from two publish instances via an author instance: - configure a remote exporter on each publish instance - configure a remote importer on each publish instance - configure a "sync" agent on author pointing to the urls of the exporter and importers on publish</p>
<p>Send <code>HTTP POST</code>request to <code>http://localhost:8080/libs/sling/distribution/services/agents/pubsync</code> with parameters <code>action=PULL</code></p>
-<h4><a href="#create-update-content" name="create-update-content">Create/update content</a></h4>
-<pre><code>$ curl -u admin:admin http://localhost:8081/libs/sling/distribution/services/agents/reverse-pubsync -d 'action=ADD' -d 'path=/content/sample1'
-$ curl -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/pubsync -d 'action=PULL'
+<h4><a href="#createupdate-content" id="createupdate-content">Create/update content</a></h4>
+<pre><code>$ curl -u admin:admin http://localhost:8081/libs/sling/distribution/services/agents/reverse-pubsync -d 'action=ADD' -d 'path=/content/sample1'
+$ curl -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/pubsync -d 'action=PULL'
</code></pre>
-<h3><a href="#installation" name="installation">Installation</a></h3>
+<h3><a href="#installation" id="installation">Installation</a></h3>
<ul>
- <li>install the dependency bundles on all Sling instances</li>
- <li>install Sling Distribution api, core, samples on all Sling instances</li>
+<li>install the dependency bundles on all Sling instances</li>
+<li>install Sling Distribution api, core, samples on all Sling instances</li>
</ul>
-<h2><a href="#http-api" name="http-api">HTTP API</a></h2>
-<h3><a href="#api-requirements" name="api-requirements">API Requirements</a></h3>
+<h2><a href="#http-api" id="http-api">HTTP API</a></h2>
+<h3><a href="#api-requirements" id="api-requirements">API Requirements</a></h3>
<p>We need to expose APIs for configuring, commanding and monitoring distribution agents.</p>
<ul>
- <li>Configuration API should allow:</li>
- <li>CRUD operations for agent configs</li>
- <li>Command API (eventually issued to multiple agents at once) should allow:</li>
- <li>to trigger a distribution request on a specific agent</li>
- <li>to explicitly create and export a package</li>
- <li>to explicitly import a formerly created package</li>
- <li>Monitoring API should allow:</li>
- <li>inspection to internal queues of distribution agents</li>
- <li>inspection of commands history</li>
+<li>Configuration API should allow:</li>
+<li>CRUD operations for agent configs</li>
+<li>Command API (eventually issued to multiple agents at once) should allow:</li>
+<li>to trigger a distribution request on a specific agent</li>
+<li>to explicitly create and export a package</li>
+<li>to explicitly import a formerly created package</li>
+<li>Monitoring API should allow:</li>
+<li>inspection to internal queues of distribution agents</li>
+<li>inspection of commands history</li>
</ul>
-<h3><a href="#api-endpoints" name="api-endpoints"> API endpoints</a></h3>
-<h4><a href="#configuration-api" name="configuration-api">Configuration API</a></h4>
+<h3><a href="#api-endpoints" id="api-endpoints"> API endpoints</a></h3>
+<h4><a href="#configuration-api" id="configuration-api">Configuration API</a></h4>
<ul>
- <li>Create config: - POST <em>/libs/sling/distribution/settings/agents</em></li>
- <li>Read config - GET <em>/libs/sling/distribution/settings/agents/{agentName}</em></li>
- <li>Update config - PUT <em>/libs/sling/distribution/settings/agents/{agentName}</em></li>
- <li>Delete config - DELETE <em>/libs/sling/distribution/settings/agents/{agentName}</em></li>
+<li>Create config: - POST <em>/libs/sling/distribution/settings/agents</em></li>
+<li>Read config - GET <em>/libs/sling/distribution/settings/agents/{agentName}</em></li>
+<li>Update config - PUT <em>/libs/sling/distribution/settings/agents/{agentName}</em></li>
+<li>Delete config - DELETE <em>/libs/sling/distribution/settings/agents/{agentName}</em></li>
</ul>
-<h4><a href="#command-api" name="command-api">Command API</a></h4>
+<h4><a href="#command-api" id="command-api">Command API</a></h4>
<ul>
- <li>Distribute - POST <em>/libs/sling/distribution/services/agents/{agentName}</em></li>
- <li>Import package - POST <em>/libs/sling/distribution/services/importers/{importerName}</em></li>
- <li>Export package - POST <em>/libs/sling/distribution/services/exporters/{exporterName}</em></li>
+<li>Distribute - POST <em>/libs/sling/distribution/services/agents/{agentName}</em></li>
+<li>Import package - POST <em>/libs/sling/distribution/services/importers/{importerName}</em></li>
+<li>Export package - POST <em>/libs/sling/distribution/services/exporters/{exporterName}</em></li>
</ul>
-<h4><a href="#monitoring-api" name="monitoring-api">Monitoring API</a></h4>
+<h4><a href="#monitoring-api" id="monitoring-api">Monitoring API</a></h4>
<ul>
- <li>Distribution history - GET <em>/libs/sling/distribution/services/agents/{agentName}/log</em></li>
- <li>Agent queue inspection - GET <em>/libs/sling/distribution/services/agents/{agentName}/queues</em></li>
+<li>Distribution history - GET <em>/libs/sling/distribution/services/agents/{agentName}/log</em></li>
+<li>Agent queue inspection - GET <em>/libs/sling/distribution/services/agents/{agentName}/queues</em></li>
</ul>
-<h2><a href="#java-api" name="java-api">Java API</a></h2>
+<h2><a href="#java-api" id="java-api">Java API</a></h2>
<p>There is a single entry point in triggering a distribution workflow, via <a href="https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-api.git;a=blob_plain;f=src/main/java/org/apache/sling/distribution/Distributor.java">Distributor</a> API.</p>
<pre><code>Distributor.distribute(agentName, resourceResolver, distributionRequest)
</code></pre>
-<h2><a href="#extensions" name="extensions">Extensions</a></h2>
+<h2><a href="#extensions" id="extensions">Extensions</a></h2>
<p>The following extensions for Apache Sling Content Distribution exist.</p>
-<h3><a href="#apache-avro-serializer" name="apache-avro-serializer">Apache Avro serializer</a></h3>
+<h3><a href="#apache-avro-serializer" id="apache-avro-serializer">Apache Avro serializer</a></h3>
<p>The <em>org.apache.sling.distribution.avro-serializer</em> contains a <em>DistributionContentSerializer</em> based on <a href="http://avro.apache.org">Apache Avro</a>.</p>
-<h3><a href="#kryo-serializer" name="kryo-serializer">Kryo serializer</a></h3>
+<h3><a href="#kryo-serializer" id="kryo-serializer">Kryo serializer</a></h3>
<p>The <em>org.apache.sling.distribution.kryo-serializer</em> contains a <em>DistributionContentSerializer</em> based on <a href="http://github.com/EsotericSoftware/kryo">Kryo</a>.</p>
-<h2><a href="#ideas-for-future-developments" name="ideas-for-future-developments">Ideas for future developments</a></h2>
+<h2><a href="#ideas-for-future-developments" id="ideas-for-future-developments">Ideas for future developments</a></h2>
<ul>
- <li>distributed configuration</li>
- <li>pushing to / pulling from JMS (pros: established pattern for producers/consumers problems, cons: other library / systems involved as a possible PoF)</li>
- <li>WebSocket support (pros: once established it's bidirectional and therefore also publish can directly push stuff to author)</li>
- <li>asynchronous import of packages (pros: parallel transport and import, cons: complex management of multiple queues on different publish instances)</li>
-</ul></section></div></div>
+<li>distributed configuration</li>
+<li>pushing to / pulling from JMS (pros: established pattern for producers/consumers problems, cons: other library / systems involved as a possible PoF)</li>
+<li>WebSocket support (pros: once established it's bidirectional and therefore also publish can directly push stuff to author)</li>
+<li>asynchronous import of packages (pros: parallel transport and import, cons: complex management of multiple queues on different publish instances)</li>
+</ul>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/dynamic-includes.html b/documentation/bundles/dynamic-includes.html
index 6d5b169..91def9c 100644
--- a/documentation/bundles/dynamic-includes.html
+++ b/documentation/bundles/dynamic-includes.html
@@ -114,16 +114,16 @@
</li>
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
-<div class="row"><div><section><h2><a href="#introduction" name="introduction">Introduction</a></h2>
+<div class="row"><div><section><h2><a href="#introduction" id="introduction">Introduction</a></h2>
<p>This module introduces a Servlet Filter that replaces dynamic components (eg. current time or foreign exchange rates) with server-side include tags (eg. <a href="http://httpd.apache.org/docs/current/howto/ssi.html">SSI</a> or <a href="http://www.w3.org/TR/esi-lang">ESI</a>). Thanks to this approach, the whole page can be cached by the Dispatcher or a Content Delivery Network while dynamic components are generated and included with every request. Components to include in this manner ar [...]
<p>When the filter intercepts a request for a component with a matching <code>resourceType</code>, it'll return a server-side include tag (eg. <code><!--#include virtual="/path/to/resource" --></code> when the Apache HTTP server with <code>mod_include</code> is used). However, an additional selector (<code>nocache</code> by default) is inserted into the path. This serves as a marker for the filter, instructing it to return actual content.</p>
<p>Components don't have to be modified in order to use this module (or even be aware of its existence). It's a Servlet Filter, installed as an OSGi bundle and it can be enabled, disabled or reconfigured at runtime.</p>
-<h2><a href="#prerequisites" name="prerequisites">Prerequisites</a></h2>
+<h2><a href="#prerequisites" id="prerequisites">Prerequisites</a></h2>
<ul>
- <li>AEM / Apache Sling 2+</li>
- <li>Maven 2.x, 3.x</li>
+<li>AEM / Apache Sling 2+</li>
+<li>Maven 2.x, 3.x</li>
</ul>
-<h2><a href="#installation" name="installation">Installation</a></h2>
+<h2><a href="#installation" id="installation">Installation</a></h2>
<p>Add following dependency to your project:</p>
<pre><code><dependency>
<groupId>org.apache.sling</groupId>
@@ -131,35 +131,35 @@
<version>3.1.2</version>
</dependency>
</code></pre>
-<h2><a href="#configuration" name="configuration">Configuration</a></h2>
+<h2><a href="#configuration" id="configuration">Configuration</a></h2>
<p>The filter is delivered as a standard OSGi bundle. SDI is configured via a configuration factory called <em>SDI Configuration</em>. The following properties are available:</p>
<ul>
- <li><strong>Enabled</strong> - enable SDI</li>
- <li><strong>Base path</strong> - This SDI configuration will work only for paths matching this value. If the value starts with a <code>^</code> character, regular expression matching (Available since 3.1.0) will be performed. Otherwise it will try to match the value as a path prefix.</li>
- <li><strong>Resource types</strong> - specifies which components should be replaced with tags</li>
- <li><strong>Include type</strong> - type of the include tag (SSI, ESI or JavaScript)</li>
- <li><strong>Add comment</strong> - adds a debug comment: <code><!-- SDI include (path: %s, resourceType: %s) --></code> to every component replaced</li>
- <li><strong>Filter selector</strong> - the selector used in the request to get actual content</li>
- <li><strong>Component TTL</strong> - time to live in seconds, set for rendered component (requires Dispatcher 4.1.11+ or another caching proxy that respects the <code>max-age</code> directive of the <code>Cache-Control</code> HTTP header)</li>
- <li><strong>Required header</strong> - SDI will be enabled only if the configured header is present in the request. By default it's <code>Server-Agent=Communique-Dispatcher</code> header, added by the AEM Dispatcher. You may enter just the header name only or the name and the value split with <code>=</code>.</li>
- <li><strong>Ignore URL params</strong> - SDI normally skips all requests containing any GET parameters. This option allows to set a list of parameters that should be ignored in the test. See the <a href="https://docs.adobe.com/docs/en/dispatcher/disp-config.html#Ignoring%20URL%20Parameters">Ignoring URL parameters</a> section in the dispatcher documentation.</li>
- <li><strong>Include path rewriting</strong> - enable rewriting link (according to <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html">Sling mapping</a>) that is used for dynamic content inclusion.</li>
+<li><strong>Enabled</strong> - enable SDI</li>
+<li><strong>Base path</strong> - This SDI configuration will work only for paths matching this value. If the value starts with a <code>^</code> character, regular expression matching (Available since 3.1.0) will be performed. Otherwise it will try to match the value as a path prefix.</li>
+<li><strong>Resource types</strong> - specifies which components should be replaced with tags</li>
+<li><strong>Include type</strong> - type of the include tag (SSI, ESI or JavaScript)</li>
+<li><strong>Add comment</strong> - adds a debug comment: <code><!-- SDI include (path: %s, resourceType: %s) --></code> to every component replaced</li>
+<li><strong>Filter selector</strong> - the selector used in the request to get actual content</li>
+<li><strong>Component TTL</strong> - time to live in seconds, set for rendered component (requires Dispatcher 4.1.11+ or another caching proxy that respects the <code>max-age</code> directive of the <code>Cache-Control</code> HTTP header)</li>
+<li><strong>Required header</strong> - SDI will be enabled only if the configured header is present in the request. By default it's <code>Server-Agent=Communique-Dispatcher</code> header, added by the AEM Dispatcher. You may enter just the header name only or the name and the value split with <code>=</code>.</li>
+<li><strong>Ignore URL params</strong> - SDI normally skips all requests containing any GET parameters. This option allows to set a list of parameters that should be ignored in the test. See the <a href="https://docs.adobe.com/docs/en/dispatcher/disp-config.html#Ignoring%20URL%20Parameters">Ignoring URL parameters</a> section in the dispatcher documentation.</li>
+<li><strong>Include path rewriting</strong> - enable rewriting link (according to <a href="https://sling.apache.org/documentation/the-sling-engine/mappings-for-resource-resolution.html">Sling mapping</a>) that is used for dynamic content inclusion.</li>
</ul>
-<h2><a href="#compatibility-with-components" name="compatibility-with-components">Compatibility with components</a></h2>
+<h2><a href="#compatibility-with-components" id="compatibility-with-components">Compatibility with components</a></h2>
<p>The filter is incompatible with the following types of component:</p>
<ul>
- <li>components which handle POST requests or GET parameters (query strings),</li>
- <li>synthetic components which use suffixes (because suffix is used to pass <code>requestType</code> of the synthetic resource).</li>
+<li>components which handle POST requests or GET parameters (query strings),</li>
+<li>synthetic components which use suffixes (because suffix is used to pass <code>requestType</code> of the synthetic resource).</li>
</ul>
<p>If a component does not generate HTML but JSON, binary data or any format that doesn't allow XML-style comments, make sure to turn off the <em>Comment</em> option in configuration.</p>
-<h2><a href="#enabling-ssi-in-apache-with-the-aem-dispatcher-module" name="enabling-ssi-in-apache-with-the-aem-dispatcher-module">Enabling SSI in Apache with the AEM Dispatcher Module</a></h2>
+<h2><a href="#enabling-ssi-in-apache-with-the-aem-dispatcher-module" id="enabling-ssi-in-apache-with-the-aem-dispatcher-module">Enabling SSI in Apache with the AEM Dispatcher Module</a></h2>
<p>One of the most common stacks where SDI proves useful is when the Apache HTTP server is set up as a caching proxy in front of Adobe Experience Manager (a Sling-based content management system). A dedicated module called the <a href="https://helpx.adobe.com/experience-manager/dispatcher/using/dispatcher.html">Dispatcher</a> is used to serve as the caching layer.</p>
<p>If you're working with a Sling-based application other than AEM, the <code>mod_proxy</code> configuration remains relevant. The Dispatcher is specific to AEM but even if you're using a different caching layer, the changes you will need to make should be similar in principle to the ones outlined below.</p>
<p>This section describes the minimal configuration necessary to use Sling Dynamic Include in this manner. You will need:</p>
<ul>
- <li>Apache HTTP server with <a href="https://httpd.apache.org/docs/2.4/mod/mod_include.html"><code>mod_include</code></a> (to process Server Side Includes) and the <a href="https://helpx.adobe.com/experience-manager/dispatcher/using/dispatcher-install.html#ApacheWebServer">Dispatcher module</a> (to handle caching)</li>
- <li>Adobe Experience Manager as a Sling installation to serve your content</li>
- <li>SDI installed on the AEM Publish instance</li>
+<li>Apache HTTP server with <a href="https://httpd.apache.org/docs/2.4/mod/mod_include.html"><code>mod_include</code></a> (to process Server Side Includes) and the <a href="https://helpx.adobe.com/experience-manager/dispatcher/using/dispatcher-install.html#ApacheWebServer">Dispatcher module</a> (to handle caching)</li>
+<li>Adobe Experience Manager as a Sling installation to serve your content</li>
+<li>SDI installed on the AEM Publish instance</li>
</ul>
<p>Start by <a href="https://helpx.adobe.com/experience-manager/dispatcher/using/dispatcher-install.html#ApacheWebServer">installing Apache and the Dispatcher</a></p>
<p>Then, enable <a href="https://httpd.apache.org/docs/2.4/mod/mod_include.html"><code>mod_include</code></a> (on Debian: <code>a2enmod include</code>) on Apache. This will allow the Server-Side Include tags rendered by SDI to be processed.</p>
@@ -194,12 +194,12 @@
}
</code></pre>
<p>at the end of the <code>/rules</code> section. This way, dynamic components will not be cached by the Dispatcher. This step may not be necessary if you're using SDI to optimize the caching of static components.</p>
-<h2><a href="#enabling-ttl-in-dispatcher-4-1-11-" name="enabling-ttl-in-dispatcher-4-1-11-">Enabling TTL in dispatcher 4.1.11+</a></h2>
+<h2><a href="#enabling-ttl-in-dispatcher-4111" id="enabling-ttl-in-dispatcher-4111">Enabling TTL in dispatcher 4.1.11+</a></h2>
<p>In order to enable TTL on Apache with the Dispatcher just add:</p>
<pre><code>/enableTTL "1"
</code></pre>
<p>to your Dispatcher configuration.</p>
-<h2><a href="#enabling-esi-in-varnish" name="enabling-esi-in-varnish">Enabling ESI in Varnish</a></h2>
+<h2><a href="#enabling-esi-in-varnish" id="enabling-esi-in-varnish">Enabling ESI in Varnish</a></h2>
<p>Edge Side Includes can be used as an alternative to SSI. ESI tags can be processed by <a href="https://varnish-cache.org/">Varnish</a> which can be installed locally and often made available as part of Content Delivery Networks.</p>
<p>In order to configure Varnish to work with SDI, add following lines at the beginning of the <code>vcl_fetch</code> section in your <code>/etc/varnish/default.vcl</code> file:</p>
<pre><code> if(req.url ~ "\.nocache.html") {
@@ -209,9 +209,9 @@
}
</code></pre>
<p>It'll enable ESI includes in <code>.html</code> files and disable caching of the <code>.nocache.html</code> files.</p>
-<h2><a href="#javascript-include" name="javascript-include">JavaScript Include</a></h2>
+<h2><a href="#javascript-include" id="javascript-include">JavaScript Include</a></h2>
<p>The Dynamic Include Filter can also replace dynamic components with script tags using AJAX so that they are loaded by the browser. It's called JSI. In the current version of SDI, the jQuery library is used. More attention is required if the included component renders some JavaScript code. For example, the Geometrixx Carousel component won't work because its initialization is done in page's <code><head></code> section while the component itself is still not loaded.</p>
-<h2><a href="#plain-and-synthetic-resources" name="plain-and-synthetic-resources">Plain and synthetic resources</a></h2>
+<h2><a href="#plain-and-synthetic-resources" id="plain-and-synthetic-resources">Plain and synthetic resources</a></h2>
<p>Resources in Apache Sling can be backed by JCR nodes but that's not always the case. In this section, we will look at the different ways SDI handles JCR-based resources</p>
<p>Let's start with an example of a JCR-based component available at some URL, e.g.</p>
<pre><code>/content/geometrixx/en/jcr:content/carousel.html
@@ -232,29 +232,30 @@
<pre><code>/content/geometrixx/en/jcr:content/userinfo.nocache.html
</code></pre>
<p>The selector is necessary because without it the filter would replace the component with an SSI tag again, resulting in an infinite loop leading to an SSI/ESI processing error.</p>
-<h1><a href="#external-resources" name="external-resources">External resources</a></h1>
+<h1><a href="#external-resources" id="external-resources">External resources</a></h1>
<ul>
- <li><a href="http://www.pro-vision.de/content/medialib/pro-vision/production/adaptto/2012/adaptto2012-sling-dynamic-include-tomasz-rekaweki-pdf/_jcr_content/renditions/rendition.file/adaptto2012-sling-dynamic-include-tomasz-rekaweki.pdf">SDI presentation</a> on <a href="http://www.pro-vision.de/de/adaptto/adaptto-2012.html">adaptTo() 2012</a></li>
- <li><a href="http://www.cognifide.com/blogs/cq/sling-dynamic-include/">SDI blog</a> post on the Cognifide website</li>
- <li>See the <a href="http://sling.apache.org/">Apache Sling website</a> for the Sling reference documentation. Apache Sling, Apache and Sling are trademarks of the <a href="http://apache.org">Apache Software Foundation</a>.</li>
+<li><a href="http://www.pro-vision.de/content/medialib/pro-vision/production/adaptto/2012/adaptto2012-sling-dynamic-include-tomasz-rekaweki-pdf/_jcr_content/renditions/rendition.file/adaptto2012-sling-dynamic-include-tomasz-rekaweki.pdf">SDI presentation</a> on <a href="http://www.pro-vision.de/de/adaptto/adaptto-2012.html">adaptTo() 2012</a></li>
+<li><a href="http://www.cognifide.com/blogs/cq/sling-dynamic-include/">SDI blog</a> post on the Cognifide website</li>
+<li>See the <a href="http://sling.apache.org/">Apache Sling website</a> for the Sling reference documentation. Apache Sling, Apache and Sling are trademarks of the <a href="http://apache.org">Apache Software Foundation</a>.</li>
</ul>
-<h1><a href="#release-notes" name="release-notes">Release notes</a></h1>
-<h2><a href="#3-1-2" name="3-1-2">3.1.2</a></h2>
+<h1><a href="#release-notes" id="release-notes">Release notes</a></h1>
+<h2><a href="#312" id="312">3.1.2</a></h2>
<ul>
- <li>Introduced readable names for SDI configuration entries in the OSGi console (<a href="https://issues.apache.org/jira/browse/SLING-7695">SLING-7695</a>)</li>
- <li>Fixed a bug where the selector configured for use with SDI was added multiple times to the same selector string (<a href="https://issues.apache.org/jira/browse/SLING-7742">SLING-7742</a>)</li>
- <li>Introduced a mechanism that allows synthetic resources included via SDI to be cached by the AEM Dispatcher (<a href="https://issues.apache.org/jira/browse/SLING-7785">SLING-7785</a>)</li>
+<li>Introduced readable names for SDI configuration entries in the OSGi console (<a href="https://issues.apache.org/jira/browse/SLING-7695">SLING-7695</a>)</li>
+<li>Fixed a bug where the selector configured for use with SDI was added multiple times to the same selector string (<a href="https://issues.apache.org/jira/browse/SLING-7742">SLING-7742</a>)</li>
+<li>Introduced a mechanism that allows synthetic resources included via SDI to be cached by the AEM Dispatcher (<a href="https://issues.apache.org/jira/browse/SLING-7785">SLING-7785</a>)</li>
</ul>
-<h2><a href="#3-1-0" name="3-1-0">3.1.0</a></h2>
+<h2><a href="#310" id="310">3.1.0</a></h2>
<ul>
- <li>Regular expression matching can be used when configuring resource paths (<a href="https://issues.apache.org/jira/browse/SLING-7621">SLING-7621</a>)</li>
+<li>Regular expression matching can be used when configuring resource paths (<a href="https://issues.apache.org/jira/browse/SLING-7621">SLING-7621</a>)</li>
</ul>
-<h2><a href="#3-0-0" name="3-0-0">3.0.0</a></h2>
+<h2><a href="#300" id="300">3.0.0</a></h2>
<p>Sling Dynamic Include donated to the Apache Sling project (<a href="https://issues.apache.org/jira/browse/SLING-5594">SLING-5594</a>), repackaged and released (<a href="https://issues.apache.org/jira/browse/SLING-6301">SLING-6301</a>)</p>
-<h2><a href="#2-2-0" name="2-2-0">2.2.0</a></h2>
+<h2><a href="#220" id="220">2.2.0</a></h2>
<ul>
- <li>Support for time-based (TTL) caching, Dispatcher 4.1.11+ required</li>
-</ul></section></div></div>
+<li>Support for time-based (TTL) caching, Dispatcher 4.1.11+ required</li>
+</ul>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/file-installer-provider.html b/documentation/bundles/file-installer-provider.html
index 9d39fba..ed8082c 100644
--- a/documentation/bundles/file-installer-provider.html
+++ b/documentation/bundles/file-installer-provider.html
@@ -115,48 +115,33 @@
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p>The file installer provider scans configured directories and provides the found artifacts (files) to the <a href="/documentation/bundles/osgi-installer.html">OSGI installer</a>. The functionality is very similar to Apache Felix FileInstall, with the major difference that this service implements just the task of scanning a file directory. All the management logic is implemented in the OSGi installer and support of various artifact types like bundles, conf [...]
-<h2><a href="#setup" name="setup">Setup</a></h2>
+<h2><a href="#setup" id="setup">Setup</a></h2>
<p>The file installer can be configured with these framework (system) properties:</p>
<table>
- <thead>
- <tr>
- <th>Property</th>
- <th>Default</th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>sling.fileinstall.dir</code></td>
- <td> </td>
- <td>The name/path of the directories to watch. Several directories can be specified by using a comma separated list. Each directory might have arbitrarily many sub directories (even nested ones) which may contain the artifacts</td>
- </tr>
- <tr>
- <td><code>sling.fileinstall.interval</code></td>
- <td>5000 ms</td>
- <td>Number of milliseconds between 2 polls of the directory</td>
- </tr>
- <tr>
- <td><code>sling.fileinstall.writeback</code></td>
- <td>true</td>
- <td>If the file provider supports writeback of changed artifacts, e.g. if a configuration is changed through Config Admin the change is written back to the file system.</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Property</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>sling.fileinstall.dir</code></td><td> </td><td>The name/path of the directories to watch. Several directories can be specified by using a comma separated list. Each directory might have arbitrarily many sub directories (even nested ones) which may contain the artifacts</td></tr>
+<tr><td><code>sling.fileinstall.interval</code></td><td>5000 ms</td><td>Number of milliseconds between 2 polls of the directory</td></tr>
+<tr><td><code>sling.fileinstall.writeback</code></td><td>true</td><td>If the file provider supports writeback of changed artifacts, e.g. if a configuration is changed through Config Admin the change is written back to the file system.</td></tr>
+</tbody>
</table>
-<h2><a href="#bundles" name="bundles">Bundles</a></h2>
+<h2><a href="#bundles" id="bundles">Bundles</a></h2>
<p>Bundles are supported by the OSGi installer. If a bundle jar is added to a scanned directory, this bundle is installed. If the file is updated/changed, the bundle is updated. If the file is removed, the bundle gets removed. Of course, these are the simple rules. The actual action depends by the overall state of the system and is controlled by the OSGi installer. For example if already the same bundle with a higher version is installed, when a bundle is dropped into the install folder, [...]
<p>Start levels are supported as well by creating a directory with the name of the start level within the scan directory and putting the bundles within this directory. For example, if the <code>install</code> folder is scanned, the bundle <code>install/3/mybundle.jar</code> will be installed with start level 3. Without such a directory the default start level is used.</p>
-<h2><a href="#configurations" name="configurations">Configurations</a></h2>
+<h2><a href="#configurations" id="configurations">Configurations</a></h2>
<p>Configurations are handled by the <a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a>. The different formats are described there.</p>
-<h2><a href="#custom-artifacts" name="custom-artifacts">Custom Artifacts</a></h2>
+<h2><a href="#custom-artifacts" id="custom-artifacts">Custom Artifacts</a></h2>
<p>Custom artifacts are handled by the OSGi installer depending on the installed plugins. Have a look at the OSGi installer and its plugins for more information.</p>
-<h2><a href="#runmode-support" name="runmode-support">Runmode Support</a></h2>
-<p>The file installer supports run modes for installing artifacts (added with <a href="https://issues.apache.org/jira/browse/SLING-4478">SLING-4478</a>). Within the scanned directory, a folder prefixed with "install." and followed by one or more run modes (separated by ".") will only be considered if all the respective run modes are active. For example artifacts below a folder named <code>install.a1.dev</code> are only taken into account if the run modes <code>a1</code> and <code>dev</co [...]
+<h2><a href="#runmode-support" id="runmode-support">Runmode Support</a></h2>
+<p>The file installer supports run modes for installing artifacts (added with <a href="https://issues.apache.org/jira/browse/SLING-4478">SLING-4478</a>). Within the scanned directory, a folder prefixed with "install." and followed by one or more run modes (separated by ".") will only be considered if all the respective run modes are active. For example artifacts below a folder named <code>install.a1.dev</code> are only taken into account if the run modes <code>a1</cod [...]
<p>You can even combine start level and run mode support. Just pay attention that the run mode foldername must be set on a direct child folder of <code>sling.fileinstall.dir</code> while the start level must be set directly on the parent folder of the artifact you want to install. E.g. <code><sling.fileinstall.dir>/install.a1.dev/3/mybundle.jar</code> will only be considered if both run modes <code>a1</code> and <code>dev</code> are set. If this is the case then the according artif [...]
-<h1><a href="#project-info" name="project-info">Project Info</a></h1>
+<h1><a href="#project-info" id="project-info">Project Info</a></h1>
<ul>
- <li>File installer provider (<a href="https://github.com/apache/sling-org-apache-sling-installer-provider-file">org.apache.sling.installer.provider.file</a>)</li>
-</ul></section></div></div>
+<li>File installer provider (<a href="https://github.com/apache/sling-org-apache-sling-installer-provider-file">org.apache.sling.installer.provider.file</a>)</li>
+</ul>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/hapi.html b/documentation/bundles/hapi.html
index d2f8768..13139cc 100644
--- a/documentation/bundles/hapi.html
+++ b/documentation/bundles/hapi.html
@@ -114,16 +114,16 @@
</li>
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
-<div class="row"><div><section><h1><a name="section-1">HApi - Hypermedia API tools</a></h1>
-<p>The hypermedia API tools are a way to enable sling component developers to add metadata information to their HTML components and easily define an API using the html markup generated by the components. </p>
+<div class="row"><div><section><h1><a href="#hapi-hypermedia-api-tools" id="hapi-hypermedia-api-tools"><a name="section-1">HApi - Hypermedia API tools</a></a></h1>
+<p>The hypermedia API tools are a way to enable sling component developers to add metadata information to their HTML components and easily define an API using the html markup generated by the components.</p>
<p>HApi tools work with <a href="http://docs.adobe.com/docs/en/aem/6-0/develop/sightly.html">sightly</a>, JSP or any scripting language that can call java code. For understanding how microdata works, read the next section, <a href="#section-2">Hypermedia API with Microdata</a>.</p>
<p>To see how the HApi implemetation works, read <a href="#section-3">How HApi works, by example</a></p>
-<h2><a name="section-install">Installation</a></h2>
+<h2><a href="#installation" id="installation"><a name="section-install">Installation</a></a></h2>
<p>The two bundles, core and samplecontent need sightly installed on the sling instance.</p>
<p>You can then install both with <em>mvn clean install sling:install</em></p>
<p>After that, to check the sample page go to http://localhost:8080/apps/sling/hapi_sample/site/site.html and check out the sample page.</p>
<p>See below for consuming the API with a generic client.</p>
-<h2><a name="section-2">Hypermedia API with Microdata</a></h2>
+<h2><a href="#hypermedia-api-with-microdata" id="hypermedia-api-with-microdata"><a name="section-2">Hypermedia API with Microdata</a></a></h2>
<p>There is a lot of confusion surrounding this term, but shortly put, it's an API having content with links. We can use it a way of defining a protocol-agnostic API for our resources, designing it from the client-side, using the html markup as the media type. This means the requested resource representation would be displayed in browsers out-of-the-box, but also understood by any user or automaton which understands the API. Such APIs can be defined for XML, HTML, JSON and becomes a hype [...]
<p>For us out there in a hurry, let's take the following short example from the <a href="http://schema.org/docs/gs.html">schema.org</a> page:</p>
<pre><code><div itemscope itemtype="http://schema.org/Movie">
@@ -136,11 +136,11 @@
</div>
</div>
</code></pre>
-<p>The attribute <em>itemscope</em> defines a scope for an object. The (optional) <em>itemtype</em> links to a description of the type of the object. Inside an element with an <em>itemscope</em> attribute, we have descendant elements with a property <em>itemprop</em>. This means the <em>name</em> property will point to the enclosed object, which is the simple text "Avatar". Similarly, the <em>genre</em> property is "Science Fiction". </p>
+<p>The attribute <em>itemscope</em> defines a scope for an object. The (optional) <em>itemtype</em> links to a description of the type of the object. Inside an element with an <em>itemscope</em> attribute, we have descendant elements with a property <em>itemprop</em>. This means the <em>name</em> property will point to the enclosed object, which is the simple text "Avatar". Similarly, the <em>genre</em> property is "Science Fiction".</p>
<p>The <em>director</em> property is not a simple type, so it defines a new <em>itemscope</em>. Also, the <em>itemtype</em> shows it's a Person. Now, the schema for Person defines the <em>name</em> and the <em>birthDate</em> properties, which are pointed to the same way as above.</p>
-<h2><a name="section-3">How HApi works, by example</a></h2>
+<h2><a href="#how-hapi-works-by-example" id="how-hapi-works-by-example"><a name="section-3">How HApi works, by example</a></a></h2>
<p>In order to see how HApi works, the best way is to check an example. In the sample content module, we have a demo app that defines an API and uses that in the sightly components. The best way to start is to analyze the end result and acknowledge it's usefuleness:</p>
-<h3><a name="section-3a">Consuming the API</a></h3>
+<h3><a href="#consuming-the-api" id="consuming-the-api"><a name="section-3a">Consuming the API</a></a></h3>
<p>The app looks like this in the browser: <img src="hapi/browser1.png" alt="Page in the browser" /></p>
<p>The generated content looks something like this for the first card:</p>
<pre><code><div itemtype="/apps/sling/hapi_sample/types/album_card.html" itemscope="itemscope" class="card-asset">
@@ -167,12 +167,12 @@
</code></pre>
<p>The entities that have semantic meaning to us (e.g. Are part of the API) are the elements annotated with microdata, links and forms:</p>
<ul>
- <li><code><div itemtype="/apps/sling/hapi_sample/types/album_card.html" itemscope="itemscope" class="card-asset"></code></li>
- <li><code><a href="details.html" rel="self"></code></li>
- <li><code><link ...></code></li>
- <li><code><form ... ></code></li>
+<li><code><div itemtype="/apps/sling/hapi_sample/types/album_card.html" itemscope="itemscope" class="card-asset"></code></li>
+<li><code><a href="details.html" rel="self"></code></li>
+<li><code><link ...></code></li>
+<li><code><form ... ></code></li>
</ul>
-<p>Because the API is defined using the generated HTML (same consumed by the browser), we can consume the <em>real</em> content using any microdata thin, application-agnostic client. A simple example is using <a href="https://github.com/dulvac/htmlapi-client-python/blob/master/htmlapi_client.py">a simple html python client</a>, but any client can be used. Here's what it can do:</p>
+<p>Because the API is defined using the generated HTML (same consumed by the browser), we can consume the <em>real</em> content using any microdata thin, application-agnostic client. A simple example is using <a href="https://github.com/dulvac/htmlapi-client-python/blob/master/htmlapi_client.py">a simple html python client</a>, but any client can be used. Here's what it can do:</p>
<p><img src="hapi/python1.png" alt="Enter example" /></p>
<p>We can see that we have two objects in the page/ resource (because I've chosen to expose just two), one of type <strong>pic_card</strong> and one of type <strong>album_card</strong>. The types are URLs resolvable in sling. They look something like this in the browser:</p>
<p><img src="hapi/browser2.png" alt="Type in browser" /></p>
@@ -182,7 +182,7 @@
<p><img src="hapi/python4.png" alt="Links example" /></p>
<p>So navigating/ changing state works by using the semantic meaning of links in html. Except the enter() function, there is no http url needed to use the sling web application. If you define your links and link relations correctly, any microdata client like this can change the state, in addition to consuming the content defined through the microdata hypermedia API.</p>
<p>As you've probably noticed, we use some domain-specific types for <em>itemtype</em>. This is how you define the types:</p>
-<h3><a href="#defining-the-types" name="defining-the-types">Defining the types</a></h3>
+<h3><a href="#defining-the-types" id="defining-the-types">Defining the types</a></h3>
<p>The types are defined as nt:unstructured nodes in the repository with a certain <em>sling:resourceType</em> configurable in the OSGi config of the HApiUtil service:</p>
<pre><code>{
@@ -241,21 +241,21 @@
}
</code></pre>
-<h3><a href="#using-the-sightly-hapiuse-class" name="using-the-sightly-hapiuse-class">Using the sightly HApiUse class</a></h3>
-<p>After defining the types needed for the component in question, you can immediately benefit from the HApi tools and add the microdata annotations. There is also validation for the properties and the itemtype for properties is added automatically by the tools. </p>
+<h3><a href="#using-the-sightly-hapiuse-class" id="using-the-sightly-hapiuse-class">Using the sightly HApiUse class</a></h3>
+<p>After defining the types needed for the component in question, you can immediately benefit from the HApi tools and add the microdata annotations. There is also validation for the properties and the itemtype for properties is added automatically by the tools.</p>
<p>This is how a sightly component using it looks like:</p>
-<pre><code><div data-sly-use.card="${'org.apache.sling.hapi.sightly.HApiUse' @type='/apps/sling/hapi_sample/types/pic_card'}"
+<pre><code><div data-sly-use.card="${'org.apache.sling.hapi.sightly.HApiUse' @type='/apps/sling/hapi_sample/types/pic_card'}"
data-sly-attribute="${card.itemtype}" class="card-asset">
<a rel="self" href="details.html">
<img data-sly-attribute="${card.itemprop.thumbnail}" class="show-grid" src="assets/preview-small.png" alt="">
<div>
- <h4 data-sly-attribute="${card.itemprop['title']}">PIC 001</h4>
+ <h4 data-sly-attribute="${card.itemprop['title']}">PIC 001</h4>
<p class="type">PSD</p>
<p data-sly-attribute="${card.itemprop.resolution}"
- data-sly-use.resolution="${'org.apache.sling.hapi.sightly.HApiUse' @type=card.proptype.resolution}" class="resolution">
+ data-sly-use.resolution="${'org.apache.sling.hapi.sightly.HApiUse' @type=card.proptype.resolution}" class="resolution">
<span data-sly-attribute="${resolution.itemprop.width}">1620</span> x <span
data-sly-attribute="${resolution.itemprop.height}">670</span>
</p>
@@ -277,7 +277,8 @@
<pre><code><img data-sly-attribute="${card.itemprop.inexistent_property}" class="show-grid" src="assets/preview-small.png" alt=""></span>
org.apache.sling.hapi.HApiException: Property inexistent_property does not exist for type /apps/hapi-sample/types/pic_card
-</code></pre></section></div></div>
+</code></pre>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/installer-provider-installhook.html b/documentation/bundles/installer-provider-installhook.html
index adbdd79..5ebc7c7 100644
--- a/documentation/bundles/installer-provider-installhook.html
+++ b/documentation/bundles/installer-provider-installhook.html
@@ -114,12 +114,12 @@
</li>
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
-<div class="row"><div><section><h2><a href="#overview" name="overview">Overview</a></h2>
+<div class="row"><div><section><h2><a href="#overview" id="overview">Overview</a></h2>
<p>The Installer Vault Package Install Hook allows to install bundles and configurations synchronously during vault package installation by feeding them directly to the <a href="/documentation/bundles/osgi-installer.html">OSGI Installer core</a>. That way <a href="http://jackrabbit.apache.org/filevault/properties.html">vault package dependencies</a> can be used to not only depend on content of a package, but also on configurations and bundles contained in a package (the installer install [...]
<p>NOTE: When using with a package that should be usable with both the <a href="https://sling.apache.org/documentation/development/feature-model.html">Feature Model</a> (usually without the <a href="https://sling.apache.org/documentation/bundles/osgi-installer.html">OSGi Installer</a>) and <a href="https://sling.apache.org/documentation/development/slingstart.html">Provisioning Model</a> (usually with the OSGi Installer), ensure you use version 1.1.0 of this hook that will auto-detect it [...]
-<h2><a href="#installation-process" name="installation-process">Installation Process</a></h2>
+<h2><a href="#installation-process" id="installation-process">Installation Process</a></h2>
<p>The Installer Vault Package Install Hook scans through the contained files and installs bundles (extension <code>jar</code>) and OSGi configurations with extension <code>config</code> (<code>conf</code> and node configurations are not supported). Runmode folders (e.g. <code>install.publish</code> or <code>config.author</code>) are supported. To perform the installation, the hook registers the installable resources to the OSGi installer core with the exact same digest as the JCR instal [...]
-<h2><a href="#configuration" name="configuration">Configuration</a></h2>
+<h2><a href="#configuration" id="configuration">Configuration</a></h2>
<p>To include the install hook into a content package, use the following code:</p>
<pre><code><plugin>
<groupId>org.apache.maven.plugins</groupId>
@@ -147,41 +147,18 @@
</code></pre>
<p>The following package properties are supported (only <code>installPathRegex</code> is required):</p>
<table>
- <thead>
- <tr>
- <th>Property </th>
- <th>Value</th>
- <th>Description </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>installPathRegex</code> </td>
- <td>Regex, e.g. <code>/apps/myproj/.*</code> or <code>/apps/myproj/install/mybundle-1.0.0.jar</code> </td>
- <td>Regex to match all bundles/configurations to be installed synchronously, . Note: The JCR installer will pick up paths that are not matched asynchronously</td>
- </tr>
- <tr>
- <td><code>maxWaitForOsgiInstallerInSec</code> </td>
- <td>defaults to 60 sec </td>
- <td>Maximum wait time until installation is successful </td>
- </tr>
- <tr>
- <td><code>waitForOsgiEventsQuietInSec</code> </td>
- <td>defaults to 1 sec </td>
- <td>Time to wait for OSGi events to go quiet. Default normally works well for bundles, for certain configurations that trigger restart of bundles this can be increased. </td>
- </tr>
- <tr>
- <td><code>osgiInstallerPriority</code> </td>
- <td>defaults to 2000 </td>
- <td>Priority, by default higher than the standard installation priority of the JCR installer to ensure bundles/configs from this mechanism take higher priority </td>
- </tr>
- <tr>
- <td><code>installhook.installer.class</code> </td>
- <td><code>org.apache.sling.installer.provider.installhook.OsgiInstallerHookOsgiInstallerHookEntry</code> </td>
- <td>Alternative to including the hook in package, however then the bundle <code>org.apache.sling.installer.provider.installhook</code> needs to be installed as prerequisite </td>
- </tr>
- </tbody>
-</table></section></div></div>
+<thead>
+<tr><th> Property </th><th> Value</th><th> Description </th></tr>
+</thead>
+<tbody>
+<tr><td> <code>installPathRegex</code> </td><td> Regex, e.g. <code>/apps/myproj/.*</code> or <code>/apps/myproj/install/mybundle-1.0.0.jar</code> </td><td> Regex to match all bundles/configurations to be installed synchronously, . Note: The JCR installer will pick up paths that are not matched asynchronously</td></tr>
+<tr><td> <code>maxWaitForOsgiInstallerInSec</code> </td><td> defaults to 60 sec </td><td> Maximum wait time until installation is successful </td></tr>
+<tr><td> <code>waitForOsgiEventsQuietInSec</code> </td><td> defaults to 1 sec </td><td> Time to wait for OSGi events to go quiet. Default normally works well for bundles, for certain configurations that trigger restart of bundles this can be increased. </td></tr>
+<tr><td> <code>osgiInstallerPriority</code> </td><td> defaults to 2000 </td><td> Priority, by default higher than the standard installation priority of the JCR installer to ensure bundles/configs from this mechanism take higher priority </td></tr>
+<tr><td> <code>installhook.installer.class</code> </td><td> <code>org.apache.sling.installer.provider.installhook.OsgiInstallerHookOsgiInstallerHookEntry</code> </td><td> Alternative to including the hook in package, however then the bundle <code>org.apache.sling.installer.provider.installhook</code> needs to be installed as prerequisite </td></tr>
+</tbody>
+</table>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/internationalization-support-i18n.html b/documentation/bundles/internationalization-support-i18n.html
index 949306a..3dec8c6 100644
--- a/documentation/bundles/internationalization-support-i18n.html
+++ b/documentation/bundles/internationalization-support-i18n.html
@@ -116,41 +116,43 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p>Internationalization support in Sling consists of four methods in the <code>SlingHttpServletRequest</code> interface:</p>
<ul>
- <li><code>getLocale()</code> -- Returns the primary <code>Locale</code> for the current request. This method is inherited from the <code>javax.servlet.ServletRequest</code> interface.</li>
- <li><code>getLocales()</code> -- Returns the <code>Locale</code> instances for the current request. This method is inherited from the <code>javax.servlet.ServletRequest</code> interface.</li>
- <li><code>getResourceBundle(Locale)</code> -- Returns a <code>ResourceBundle</code> for the given <code>Locale</code>. This method is specific to Sling.</li>
- <li><code>getResourceBundle(String, Locale)</code> -- Returns a <code>ResourceBundle</code> of a given base name for the given <code>Locale</code>. This method is specific to Sling.</li>
+<li><code>getLocale()</code> -- Returns the primary <code>Locale</code> for the current request. This method is inherited from the <code>javax.servlet.ServletRequest</code> interface.</li>
+<li><code>getLocales()</code> -- Returns the <code>Locale</code> instances for the current request. This method is inherited from the <code>javax.servlet.ServletRequest</code> interface.</li>
+<li><code>getResourceBundle(Locale)</code> -- Returns a <code>ResourceBundle</code> for the given <code>Locale</code>. This method is specific to Sling.</li>
+<li><code>getResourceBundle(String, Locale)</code> -- Returns a <code>ResourceBundle</code> of a given base name for the given <code>Locale</code>. This method is specific to Sling.</li>
</ul>
<p>These methods have a default implementation in the <code>org.apache.sling.core</code> bundle and an extended and extensible implementation in the <code>org.apache.sling.i18n</code> bundle.</p>
-<h2>Default Implementation in the <code>org.apache.sling.engine</code> Bundle</h2>
+<h2><a href="#default-implementation-in-the-orgapacheslingengine-bundle" id="default-implementation-in-the-orgapacheslingengine-bundle">Default Implementation in the <code>org.apache.sling.engine</code> Bundle</a></h2>
<p>The default implementation of the above mentioned four methods in the Sling Engine bundle is contained in the bundle-private class <code>org.apache.sling.engine.impl.SlingHttpServletRequestImpl</code> which is the primary implementation of the <code>SlingHttpServletRequest</code> interface:</p>
<ul>
- <li><code>getLocale()</code> -- Returns the <code>Locale</code> from the request object of the servlet container in which Sling is running. As per the Servlet API specification, this is either the primary Locale of the <code>Accept-Language</code> request header or the server default locale.</li>
- <li><code>getLocales()</code> -- Returns the <code>Enumeration</code> from the request object of the servlet container in which Sling is running. As per the Servlet API specification, this is either based on the <code>Accept-Language</code> request header or just the server default locale.</li>
- <li><code>getResourceBundle(Locale)</code> -- Returns a <code>ResourceBundle</code> whose <code>getString(String key)</code> method returns the <code>key</code> as the message and whose <code>getKeys()</code> method returns an empty <code>Enumeration</code>.</li>
- <li><code>getResourceBundle(String, Locale)</code> -- Returns a <code>ResourceBundle</code> whose <code>getString(String key)</code> method returns the <code>key</code> as the message and whose <code>getKeys()</code> method returns an empty <code>Enumeration</code>.</li>
+<li><code>getLocale()</code> -- Returns the <code>Locale</code> from the request object of the servlet container in which Sling is running. As per the Servlet API specification, this is either the primary Locale of the <code>Accept-Language</code> request header or the server default locale.</li>
+<li><code>getLocales()</code> -- Returns the <code>Enumeration</code> from the request object of the servlet container in which Sling is running. As per the Servlet API specification, this is either based on the <code>Accept-Language</code> request header or just the server default locale.</li>
+<li><code>getResourceBundle(Locale)</code> -- Returns a <code>ResourceBundle</code> whose <code>getString(String key)</code> method returns the <code>key</code> as the message and whose <code>getKeys()</code> method returns an empty <code>Enumeration</code>.</li>
+<li><code>getResourceBundle(String, Locale)</code> -- Returns a <code>ResourceBundle</code> whose <code>getString(String key)</code> method returns the <code>key</code> as the message and whose <code>getKeys()</code> method returns an empty <code>Enumeration</code>.</li>
</ul>
<p>NOTE: Unlike the default implementations of the <code>ResourceBundle</code> abstract class in the Java Runtime -- <code>PropertyResourceBundle</code> and <code>ListResourceBundle</code> -- the <code>ResourceBundle</code> returned by the default implementation of the <code>getResourceBundle(Locale)</code> and <code>getResourceBundle(String, Locale)</code> always returns a string message for any key, which is the key itself. This prevents throwing <code>MissingResourceException</code>.</p>
-<h2>Extensible Implementation in the <code>org.apache.sling.i18n</code> Bundle</h2>
+<h2><a href="#extensible-implementation-in-the-orgapacheslingi18n-bundle" id="extensible-implementation-in-the-orgapacheslingi18n-bundle">Extensible Implementation in the <code>org.apache.sling.i18n</code> Bundle</a></h2>
<p>The <code>org.apache.sling.i18n</code> Bundle implements a request level <code>Filter</code> providing extensible implementations of the above mentioned three methods. Extensibility is attained by defining two service interfaces:</p>
<ul>
- <li>
- <p><code>LocaleResolver</code> -- The <code>LocaleResolver</code> interface defines a method which may be implemented by a service outside of the sling.i18n bundle. If no such service is registered the default behaviour is as described above for the sling.core bundle. The service described by this interface is used to implement the <code>getLocale()</code> and <code>getLocales()</code> method.</p></li>
- <li>
- <p><code>ResourceBundleProvider</code> -- The <code>ResourceBundleProvider</code> interface defines two methods to acquire a <code>ResourceBundle</code> for any <code>Locale</code> and an optional base name. This service interface is not intended to be implemented outside of the sling.i18n bundle: A JCR Repository based implementation is contained in the sling.i18n bundle. The <code>ResourceBundleProvider</code> service is not only used within the sling.i18n bundle to implement the <co [...]
+<li>
+<p><code>LocaleResolver</code> -- The <code>LocaleResolver</code> interface defines a method which may be implemented by a service outside of the sling.i18n bundle. If no such service is registered the default behaviour is as described above for the sling.core bundle. The service described by this interface is used to implement the <code>getLocale()</code> and <code>getLocales()</code> method.</p>
+</li>
+<li>
+<p><code>ResourceBundleProvider</code> -- The <code>ResourceBundleProvider</code> interface defines two methods to acquire a <code>ResourceBundle</code> for any <code>Locale</code> and an optional base name. This service interface is not intended to be implemented outside of the sling.i18n bundle: A JCR Repository based implementation is contained in the sling.i18n bundle. The <code>ResourceBundleProvider</code> service is not only used within the sling.i18n bundle to implement the <code [...]
+</li>
</ul>
-<h3>JCR Repository based <code>ResourceBundleProvider</code></h3>
+<h3><a href="#jcr-repository-based-resourcebundleprovider" id="jcr-repository-based-resourcebundleprovider">JCR Repository based <code>ResourceBundleProvider</code></a></h3>
<p>The sling.i18n Bundle provides the implementation of the <code>ResourceBundleProvider</code> interface, which may also be used outside of Sling requests for service tasks. This implementation gets the messages from a JCR Repository stored below nodes of the mixin node type <code>mix:language</code>. These language nodes have a <code>jcr:language</code> property naming the language of the resources. In the context of the JCR based <code>ResourceBundleProvider</code> this is of course e [...]
<p>The exact location of these nodes is not relevant as the <code>ResourceBundleProvider</code> finds them by applying a JCR search.</p>
<p>Two different types of storage formats are supported for the individual dictionaries</p>
-<h4><code>sling:MessageEntry</code> based</h4>
+<h4><a href="#slingmessageentry-based" id="slingmessageentry-based"><code>sling:MessageEntry</code> based</a></h4>
<p>The (direct) child nodes of the <code>mix:language</code> node must have the <code>jcr:primaryType</code> set to <code>sling:MessageEntry</code> and must contain two special properties naming the key string and the message:</p>
<ul>
- <li><code>sling:key</code> -- The <code>sling:key</code> property is a string property being the key for which the node contains the message(s). This property is optional. If it is not set the key is determined by the name of this <code>sling:messageEntry</code> resource.</li>
- <li><code>sling:message</code> -- The <code>sling:message</code> property represents the resource for the key.</li>
+<li><code>sling:key</code> -- The <code>sling:key</code> property is a string property being the key for which the node contains the message(s). This property is optional. If it is not set the key is determined by the name of this <code>sling:messageEntry</code> resource.</li>
+<li><code>sling:message</code> -- The <code>sling:message</code> property represents the resource for the key.</li>
</ul>
<p>It is only required that the message nodes are located below <code>mix:language</code> nodes. Such structures may also be scattered in the repository to allow storing message resources next to where they are most likely used, such as request scripts.</p>
-<h5><a href="#sample-resources" name="sample-resources">Sample Resources</a></h5>
+<h5><a href="#sample-resources" id="sample-resources">Sample Resources</a></h5>
<p>Content for dictionaries in this format might look like this:</p>
<pre><code> /libs/languages
+-- English (nt:folder, mix:language)
@@ -183,9 +185,9 @@
+-- sling:message = "Ein Anwendungstext"
</code></pre>
<p>This content defines two languages <em>en</em> and <em>de</em> with three messages <em>msg001</em>, <em>msg002</em> and <em>msgXXX</em> each. The names of the respective resources have no significance (in case the <code>sling:key</code> is set).</p>
-<h4><a href="#json-file-based" name="json-file-based">JSON-file based</a></h4>
-<p>Since Version 2.4.2 the i18n bundle supports dictionaries in JSON-format (<a href="https://issues.apache.org/jira/browse/SLING-4543">SLING-4543</a>). Since loading such dictionaries is much faster than loading the ones based on <code>sling:MessageEntry</code>s this format should be used preferably. This format is assumed if the <code>mix:language</code> resource name is ending with the extension <code>.json</code>. The parser will take any "key":"value" pair in the JSON file, includin [...]
-<h5><a href="#sample-resources" name="sample-resources">Sample Resources</a></h5>
+<h4><a href="#json-file-based" id="json-file-based">JSON-file based</a></h4>
+<p>Since Version 2.4.2 the i18n bundle supports dictionaries in JSON-format (<a href="https://issues.apache.org/jira/browse/SLING-4543">SLING-4543</a>). Since loading such dictionaries is much faster than loading the ones based on <code>sling:MessageEntry</code>s this format should be used preferably. This format is assumed if the <code>mix:language</code> resource name is ending with the extension <code>.json</code>. The parser will take any "key":"value" pair in the [...]
+<h5><a href="#sample-resources" id="sample-resources">Sample Resources</a></h5>
<p>Content for this format might look like this:</p>
<pre><code> /libs/languages
+-- english.json (nt:file, mix:language)
@@ -197,7 +199,7 @@
+-- jcr:content (nt:resource)
+ jcr:data (containing the actual JSON file)
</code></pre>
-<h4>JCR Node Types supporting the JCR Repository based <code>ResourceBundleProvider</code></h4>
+<h4><a href="#jcr-node-types-supporting-the-jcr-repository-based-resourcebundleprovider" id="jcr-node-types-supporting-the-jcr-repository-based-resourcebundleprovider">JCR Node Types supporting the JCR Repository based <code>ResourceBundleProvider</code></a></h4>
<p>The sling.i18n bundle asserts the following node types:</p>
<pre><code>[mix:language]
mixin
@@ -212,56 +214,45 @@
[sling:MessageEntry] > nt:hierarchyNode, sling:Message
</code></pre>
<p>The <code>sling:Message</code> and <code>sling:MessageEntry</code> are helper node types. The latter must be used to create the nodes for the <code>sling:MessageEntry</code> based format.</p>
-<h3><code>ResourceBundle</code> with base names</h3>
+<h3><a href="#resourcebundle-with-base-names" id="resourcebundle-with-base-names"><code>ResourceBundle</code> with base names</a></h3>
<p>Similar to standard Java <code>ResourceBundle</code> instances, Sling <code>ResourceBundle</code> instances may be created for base names through any of the <code>getResourceBundle(String, Locale)</code> methods. These methods use the base name parameter as a selector for the values of the <code>sling:basename</code> property of the <code>mix:language</code> nodes.</p>
<p>The base name argument can take one three values:</p>
<table>
- <thead>
- <tr>
- <th>Value </th>
- <th><code>ResourceBundle</code> selection </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>null</code> </td>
- <td>Selects messages of <code>mix:language</code> nodes ignoring the existence or absence of <code>sling:basename</code> properties </td>
- </tr>
- <tr>
- <td>Empty String </td>
- <td>Selects messages of <code>mix:language</code> nodes which have <code>sling:basename</code> properties, ignoring the actual values </td>
- </tr>
- <tr>
- <td>Any other Value </td>
- <td>Selects messages of <code>mix:language</code> nodes whose <code>sling:basename</code> properties has any value which matches the base name string </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Value </th><th> <code>ResourceBundle</code> selection </th></tr>
+</thead>
+<tbody>
+<tr><td> <code>null</code> </td><td> Selects messages of <code>mix:language</code> nodes ignoring the existence or absence of <code>sling:basename</code> properties </td></tr>
+<tr><td> Empty String </td><td> Selects messages of <code>mix:language</code> nodes which have <code>sling:basename</code> properties, ignoring the actual values </td></tr>
+<tr><td> Any other Value </td><td> Selects messages of <code>mix:language</code> nodes whose <code>sling:basename</code> properties has any value which matches the base name string </td></tr>
+</tbody>
</table>
<p>The <code>sling:basename</code> property may be multi-valued, that is the messages of a <code>mix:language</code> nodes may belong to multiple base names and thus <code>ResourceBundle</code> instances.</p>
-<h3><code>ResourceBundle</code> hierarchies</h3>
+<h3><a href="#resourcebundle-hierarchies" id="resourcebundle-hierarchies"><code>ResourceBundle</code> hierarchies</a></h3>
<p>The dictionary entries for one <code>JcrResourceBundle</code> are always ordered like the resource resolver search paths, so usually</p>
<ol>
- <li>dictionary entries below <code>/apps</code></li>
- <li>dictionary entries below <code>/libs</code></li>
- <li>dictionary entries anywhere else (outside the search path)</li>
+<li>dictionary entries below <code>/apps</code></li>
+<li>dictionary entries below <code>/libs</code></li>
+<li>dictionary entries anywhere else (outside the search path)</li>
</ol>
<p>That means that the message for the same key in <code>/apps</code> overwrites the one in <code>/libs</code> (if both are for the same locale and base name). Within those categories the order is non-deterministic, so if there is more than one entry for the same key in <code>/apps/...</code> (for the same locale and base name), any of those entries may be used.</p>
<p>The resource bundles of the same base name with different locales also form a hierarchy. Each key is looked up recursively first in the current resource bundle and then in its parent resource bundle. The parent resource bundle is the one having the same base name but the parent locale.</p>
<p>The locale hierarchy is ordered like this:</p>
<ol>
- <li><code><Language> <Country> <Variant></code></li>
- <li><code><Language> <Country></code></li>
- <li><code><Language></code></li>
- <li><code><Default Locale></code>, usually <code>en</code></li>
+<li><code><Language> <Country> <Variant></code></li>
+<li><code><Language> <Country></code></li>
+<li><code><Language></code></li>
+<li><code><Default Locale></code>, usually <code>en</code></li>
</ol>
<p>So for the locale <code>de-DE-MAC</code> the fallback order would be</p>
<ol>
- <li><code>de-DE-MAC</code></li>
- <li><code>de-DE</code></li>
- <li><code>de</code></li>
- <li><code>en</code></li>
+<li><code>de-DE-MAC</code></li>
+<li><code>de-DE</code></li>
+<li><code>de</code></li>
+<li><code>en</code></li>
</ol>
-<p>In case there is a resource bundle requested for a locale without country or variant, there is only 1 fallback (i.e. the default locale). The last resort (root resource bundle in all hierarchies) is always the bundle which returns the requested key as the value.</p></section></div></div>
+<p>In case there is a resource bundle requested for a locale without country or variant, there is only 1 fallback (i.e. the default locale). The last resort (root resource bundle in all hierarchies) is always the bundle which returns the requested key as the value.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/jcr-installer-provider.html b/documentation/bundles/jcr-installer-provider.html
index 8f35544..818e3d3 100644
--- a/documentation/bundles/jcr-installer-provider.html
+++ b/documentation/bundles/jcr-installer-provider.html
@@ -115,25 +115,25 @@
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p>The JCR installer provider scans the JCR repository for artifacts and provides them to the <a href="/documentation/bundles/osgi-installer.html">OSGI installer</a>.</p>
-<h1><a href="#configuration-and-scanning" name="configuration-and-scanning">Configuration and Scanning</a></h1>
+<h1><a href="#configuration-and-scanning" id="configuration-and-scanning">Configuration and Scanning</a></h1>
<p>The JCR installer provider can be configured with weighted paths which are scanned. By default, the installer scans in <code>/apps</code> and <code>/libs</code> where artifacts found in <code>/apps</code> get a higher priority. The installer does a deep scan and uses a regular expression to detect folders containing artifacts to be installed. By default, artifacts from within a folder named <code>install</code> are provided to the OSGi installer.</p>
-<p>If such an install folder contains a binary artifact (e.g. a bundle or a config file as described in <a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a>) this is provided to the OSGi installer. </p>
+<p>If such an install folder contains a binary artifact (e.g. a bundle or a config file as described in <a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a>) this is provided to the OSGi installer.</p>
<p>In addition every node of type <code>sling:OsgiConfig</code> is provided as a configuration to the installer. This has the advantage of leveraging the JCR structure better than binary files, but has the known limitations outlined in <a href="https://issues.apache.org/jira/browse/SLING-4183">SLING-4183</a> and <a href="https://issues.apache.org/jira/browse/SLING-2477">SLING-2477</a>, therefore it is recommended to stick to one of the binary formats described in <a href="/documentation/ [...]
<p>The JCR installer provider does not check or scan the artifacts itself, the detection and installation is deferred to the OSGi installer.</p>
-<h3><a href="#runmode-support" name="runmode-support">Runmode Support</a></h3>
+<h3><a href="#runmode-support" id="runmode-support">Runmode Support</a></h3>
<p>The JCR installer supports run modes for installing artifacts. By default folders named <code>install</code> are checked for artifacts. If Apache Sling is started with one (or more run modes), all folders named <code>install.[RUNMODE]</code> are scanned as well. To be precise, the folder name can be followed by any number of run modes separated by dot (<code>.</code>). For example, if started with run modes <code>dev</code>, <code>a1</code>, and <code>public</code>, folders like <code [...]
<p>Artifacts from folders with a run mode get a higher priority. For example by default, an <code>install</code> folder underneath <code>/libs</code> gets the priority <code>50</code>. For each run mode in the folder name, this priority is increased by <code>1</code>, so <code>install.dev</code> has <code>51</code> and <code>install.a1.dev</code> has <code>52</code>.</p>
-<h3><a href="#start-level-support" name="start-level-support">Start Level Support</a></h3>
-<p>If the parent folder of a bundle has a name which is a number, this is used as the start level (when installing the bundle for the first time, compare with <a href="https://issues.apache.org/jira/browse/SLING-2011">SLING-2011</a>). So e.g. a bundle in the path <code>/libs/sling/install/15/somebundle.jar</code> is having the start level <code>15</code>. </p>
-<h1><a href="#write-back-support" name="write-back-support">Write Back Support</a></h1>
+<h3><a href="#start-level-support" id="start-level-support">Start Level Support</a></h3>
+<p>If the parent folder of a bundle has a name which is a number, this is used as the start level (when installing the bundle for the first time, compare with <a href="https://issues.apache.org/jira/browse/SLING-2011">SLING-2011</a>). So e.g. a bundle in the path <code>/libs/sling/install/15/somebundle.jar</code> is having the start level <code>15</code>.</p>
+<h1><a href="#write-back-support" id="write-back-support">Write Back Support</a></h1>
<p>The JCR installer supports writing back of configurations which are changed by some other ways, e.g by using the Apache Felix web console. If this is a new configuration which was not originally stored in the repository, a new configuration is stored under <code>/apps/sling/install</code>. The highest search path is used together with a configurable folder (<code>sling/install</code> in this case). If a configuration is changed which already exists in the repository, then it depends w [...]
<p>Write back can be turned off by configuration.</p>
-<h1><a href="#example" name="example">Example</a></h1>
+<h1><a href="#example" id="example">Example</a></h1>
<p>Here's a quick walkthrough of the JCR installer functionality.</p>
-<h2><a href="#installation" name="installation">Installation</a></h2>
+<h2><a href="#installation" id="installation">Installation</a></h2>
<p>Run the <a href="https://github.com/apache/sling-org-apache-sling-starter">Sling Starter</a>.</p>
-<p>To watch the logs produced by these modules, you can filter <code>sling/logs/error.log</code> using <code>egrep 'jcrinstall|osgi.installer'</code>.</p>
-<h2><a href="#install-and-remove-a-bundle" name="install-and-remove-a-bundle">Install and remove a bundle</a></h2>
+<p>To watch the logs produced by these modules, you can filter <code>sling/logs/error.log</code> using <code>egrep 'jcrinstall|osgi.installer'</code>.</p>
+<h2><a href="#install-and-remove-a-bundle" id="install-and-remove-a-bundle">Install and remove a bundle</a></h2>
<p>We'll use the <a href="http://www.knopflerfish.org/releases/2.0.5/jars/desktop_awt/desktop_awt_all-2.0.0.jar">Knopflerfish Desktop</a> bundle for this example, it is convenient as it displays a graphical user interface when started.</p>
<p>We use <code>curl</code> to create content, to make it easy to reproduce the example by copying and pasting the <code>curl</code> commands. Any other way to create content in the repository will work, of course.</p>
<p>By default, JCRInstall picks up bundles found in folders named <em>install</em> under <code>/libs</code> and <code>/apps</code>, so we start by creating such a folder:</p>
@@ -150,7 +150,7 @@ curl -X MKCOL http://admin:admin@localhost:8080/apps/jcrtest/install
http://admin:admin@localhost:8080/apps/jcrtest/install/desktop_awt_all-2.0.0.jar
</code></pre>
<p>Should cause the <em>Knopflerfish Desktop</em> window to disappear as the bundle is uninstalled.</p>
-<h2><a href="#install-modify-and-remove-a-configuration" name="install-modify-and-remove-a-configuration">Install, modify and remove a configuration</a></h2>
+<h2><a href="#install-modify-and-remove-a-configuration" id="install-modify-and-remove-a-configuration">Install, modify and remove a configuration</a></h2>
<p>JCRInstall installs OSGi configurations from nodes having the <em>sling:OsgiConfig</em> node type, found in folders named <em>install</em> under the installation roots (/apps and /libs).</p>
<p>Let's try this feature by creating a configuration with two properties:</p>
<pre><code>curl \
@@ -196,17 +196,18 @@ curl -X MKCOL http://admin:admin@localhost:8080/apps/jcrtest/install
</code></pre>
<p>And verify that the corresponding configuration is gone in the console page (after 1-2 seconds, like for all other JCRInstall operations).</p>
<p>A node named like <code>o.a.s.foo.bar-a</code> uses <em>o.a.s.foo.bar</em> as its factory PID creating a configuration with an automatically generated PID. The value of <em>a</em> is stored as an alias in the OSGi installer to correlate the configuration object with the repository node.</p>
-<h1><a href="#automated-tests" name="automated-tests">Automated Tests</a></h1>
+<h1><a href="#automated-tests" id="automated-tests">Automated Tests</a></h1>
<p>The following modules contain lots of automated tests (under <code>src/test</code>, as usual):</p>
<ul>
- <li>OSGi installer integration tests (<a href="https://github.com/apache/sling-org-apache-sling-installer-it">org.apache.sling.installer.it</a>)</li>
- <li>JCR installer service (<a href="https://github.com/apache/sling-org-apache-sling-installer-provider-jcr">org.apache.sling.installer.providers.jcr</a>)</li>
+<li>OSGi installer integration tests (<a href="https://github.com/apache/sling-org-apache-sling-installer-it">org.apache.sling.installer.it</a>)</li>
+<li>JCR installer service (<a href="https://github.com/apache/sling-org-apache-sling-installer-provider-jcr">org.apache.sling.installer.providers.jcr</a>)</li>
</ul>
<p>Many of these tests are fairly readable, and can be used to find out in more detail how these modules work.</p>
-<h1><a href="#project-info" name="project-info">Project Info</a></h1>
+<h1><a href="#project-info" id="project-info">Project Info</a></h1>
<ul>
- <li>JCR installer provider (<a href="https://github.com/apache/sling-org-apache-sling-installer-provider-jcr">org.apache.sling.installer.provider.jcr</a>)</li>
-</ul></section></div></div>
+<li>JCR installer provider (<a href="https://github.com/apache/sling-org-apache-sling-installer-provider-jcr">org.apache.sling.installer.provider.jcr</a>)</li>
+</ul>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/log-tracers.html b/documentation/bundles/log-tracers.html
index 8f46134..01c94ca 100644
--- a/documentation/bundles/log-tracers.html
+++ b/documentation/bundles/log-tracers.html
@@ -125,11 +125,11 @@
-d "tracers=oak-writes" \
http://localhost:4502/content/dam/
</code></pre>
-<h2><a href="#configuration" name="configuration">Configuration</a></h2>
+<h2><a href="#configuration" id="configuration">Configuration</a></h2>
<p><img src="/documentation/bundles/tracer-config.png" alt="Tracer Config" /></p>
<p><strong>Note that by default Tracer would not be enabled and you would need to save the OSGi config to get it activated</strong></p>
<p>Tracer support two ways to enable logging.</p>
-<h3><a href="#tracer-sets" name="tracer-sets">Tracer Sets</a></h3>
+<h3><a href="#tracer-sets" id="tracer-sets">Tracer Sets</a></h3>
<p>Tracer sets are collection of predefined logging categories matching specific area of an application. These can for now be configured as part of OSGi config</p>
<pre><code>oak-query : org.apache.jackrabbit.oak.query.QueryEngineImpl;level=debug
auth : org.apache.sling.auth;level=trace,org.apache.jackrabbit.oak.security
@@ -138,53 +138,53 @@ auth : org.apache.sling.auth;level=trace,org.apache.jackrabbit.oak.security
<pre><code>< set name > : <tracer config>
</code></pre>
<p>Where the config is of following format</p>
-<pre><code>tracerConfig := loggerConfig ( ',' loggerConfig) *
+<pre><code>tracerConfig := loggerConfig ( ',' loggerConfig) *
loggerConfig := loggerName (; attributes)*
-attributes := attributeName '=' attributeValue
+attributes := attributeName '=' attributeValue
</code></pre>
<p>Currently following attributes are support</p>
<ul>
- <li><code>level</code> - Either of TRACE, DEBUG, INFO, WARN, ERROR</li>
- <li><code>caller</code> - Used to dump stacktrace of caller. It can have following value (_since 1.0.0_, <a href="https://issues.apache.org/jira/browse/SLING-5505">SLING-5505</a>)
- <ul>
- <li><code>true</code> - Complete call stack for that logger would be included</li>
- <li><code><depth></code> - Call stack upto depth (integer) would be included e.g. caller=5</li>
- </ul>
- </li>
- <li><code>caller-exclude-filter</code> - (optional) - '|' separated package prefixes which should not be included in the output. e.g. <em>org.apache.jackrabbit.oak.query.QueryImpl;caller=28;caller-exclude-filter="org.eclipse|org.felix"</em> this would exclude eclipse and felix packages from the resulting stack</li>
+<li><code>level</code> - Either of TRACE, DEBUG, INFO, WARN, ERROR</li>
+<li><code>caller</code> - Used to dump stacktrace of caller. It can have following value (<em>since 1.0.0</em>, <a href="https://issues.apache.org/jira/browse/SLING-5505">SLING-5505</a>)
+<ul>
+<li><code>true</code> - Complete call stack for that logger would be included</li>
+<li><code><depth></code> - Call stack upto depth (integer) would be included e.g. caller=5</li>
+</ul>
+</li>
+<li><code>caller-exclude-filter</code> - (optional) - '|' separated package prefixes which should not be included in the output. e.g. <em>org.apache.jackrabbit.oak.query.QueryImpl;caller=28;caller-exclude-filter="org.eclipse|org.felix"</em> this would exclude eclipse and felix packages from the resulting stack</li>
</ul>
-<h3><a href="#performance-impact" name="performance-impact">Performance Impact</a></h3>
+<h3><a href="#performance-impact" id="performance-impact">Performance Impact</a></h3>
<p>Tracer makes use of <a href="http://logback.qos.ch/manual/filters.html#TurboFilter">Logback TuboFilter</a> to intercept the logging calls and only enable them for those which are enabled via tracer config for the request. The filter is only registered for the duration of that request hence would avoid adding the cost for normal run.</p>
<p>You can also disable the Tracer completely via OSGi config.</p>
-<h2><a href="#where-do-logs-go" name="where-do-logs-go">Where do logs go</a></h2>
+<h2><a href="#where-do-logs-go" id="where-do-logs-go">Where do logs go</a></h2>
<p>The logs captured are logged at two places</p>
-<h3><a href="#requestprogresstracker" name="requestprogresstracker">RequestProgressTracker</a></h3>
+<h3><a href="#requestprogresstracker" id="requestprogresstracker">RequestProgressTracker</a></h3>
<p>Sling provides support for recording recent requests which can be accessed via <a href="https://sling.apache.org/documentation/development/monitoring-requests.html">Recent Requests Plugin</a>. It would list down the list of recent request and then on clicking them you can see the logs showed on the UI.</p>
<p>The logging there is done via <a href="https://sling.apache.org/apidocs/sling5/org/apache/sling/api/request/RequestProgressTracker.html">RequestProgressTracker</a> (<a href="http://dev.day.com/content/ddc/blog/2008/06/requestprogresstracker.html">intro</a>). By default recent request plugin gets overflown as it captures request even for css, js files. To avoid that you can modify the config as part of <em>Sling Main Servlet</em> config</p>
<p><img src="/documentation/bundles/sling-main-servlet-config.png" alt="Sling Main Servlet Config" /></p>
<p>Using a regex like <code>^.*\.(?!jpg$|png$|js$|css$|woff$)[^.]+$</code> would avoid noise</p>
<p>With that you can see log entries like below at http://localhost:8080/system/console/requests?index=xxx</p>
-<pre><code>132 (2015-05-11 17:39:55) LOG [JCR] Query SELECT * FROM [granite:InboxItem] AS s where status='ACTIVE' ORDER BY s.startTime DESC
+<pre><code>132 (2015-05-11 17:39:55) LOG [JCR] Query SELECT * FROM [granite:InboxItem] AS s where status='ACTIVE' ORDER BY s.startTime DESC
134 (2015-05-11 17:39:55) TIMER_END{53,/libs/cq/gui/components/endor/badge/badge.jsp#18}
...
1316 (2015-05-11 17:39:56) LOG JCR Query Count 3
1320 (2015-05-11 17:39:56) TIMER_END{1320,Request Processing} Request Processing
</code></pre>
-<h3><a href="#server-logs" name="server-logs">Server Logs</a></h3>
+<h3><a href="#server-logs" id="server-logs">Server Logs</a></h3>
<p>Further the logs also go to normal server side logs. By default they would go to the error.log. If you have routed the logs of specific categories to different files then normal Logback logging rules would apply</p>
-<h2><a href="#usage" name="usage">Usage</a></h2>
+<h2><a href="#usage" id="usage">Usage</a></h2>
<p>Tracing can be done in various ways for a given HTTP request. Tracer looks for following hints as part of request</p>
<ul>
- <li>Tracer set names - Comma separated list of tracer set names which need to be enabled. e.g. <code>oak-query, oak-writes</code> etc</li>
- <li>tracerConfig - Raw tracing config only used for that specific request</li>
+<li>Tracer set names - Comma separated list of tracer set names which need to be enabled. e.g. <code>oak-query, oak-writes</code> etc</li>
+<li>tracerConfig - Raw tracing config only used for that specific request</li>
</ul>
-<h3><a href="#request-parameters" name="request-parameters">Request Parameters</a></h3>
+<h3><a href="#request-parameters" id="request-parameters">Request Parameters</a></h3>
<p>Param names</p>
<ul>
- <li><code>tracers</code> - Tracer set names</li>
- <li><code>tracerConfig</code> - Tracer config like org.apache.sling.auth;level=trace`
- <p>curl -u admin:admin http://localhost:4802/projects.html?tracerConfig=org.apache.sling</p>
- </li>
+<li><code>tracers</code> - Tracer set names</li>
+<li><code>tracerConfig</code> - Tracer config like org.apache.sling.auth;level=trace`
+<p>curl -u admin:admin http://localhost:4802/projects.html?tracerConfig=org.apache.sling</p>
+</li>
</ul>
<p>Above request would turn on debug level logging (default level for tracer) for <code>org.apache.sling</code> category.</p>
<pre><code>curl -D - -u admin:admin \
@@ -195,7 +195,7 @@ attributes := attributeName '=' attributeValue
-d "tracers=oak-writes" \
http://localhost:4502/content/dam/
</code></pre>
-<p>Above request would create a folder in Assets and for that we have enabled the <code>oak-writes</code> tracer. This would result in following output </p>
+<p>Above request would create a folder in Assets and for that we have enabled the <code>oak-writes</code> tracer. This would result in following output</p>
<pre><code>2015-05-11 17:30:42,840 INFO admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] c.a.acs.acs-aem-tools-bundle - Service [4858] ServiceEvent REGISTERED
2015-05-11 17:30:42,846 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] Adding node [/content/dam/summer-collection]
2015-05-11 17:30:42,849 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType
@@ -205,11 +205,11 @@ attributes := attributeName '=' attributeValue
2015-05-11 17:30:42,850 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType
2015-05-11 17:30:42,856 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] save
</code></pre>
-<h3><a href="#request-headers" name="request-headers">Request Headers</a></h3>
+<h3><a href="#request-headers" id="request-headers">Request Headers</a></h3>
<p>Some request like initial authentication processing does not involve Sling MainServlet and hence for those request logging cannot be done to RequestProgressTracker. Instead we can just get logs enabled and route them to normal logging on server side. For that you need to use HTTP header</p>
<ul>
- <li><code>Sling-Tracers</code> - Set of tracer set names</li>
- <li><code>Sling-Tracer-Config</code> - Tracer config</li>
+<li><code>Sling-Tracers</code> - Set of tracer set names</li>
+<li><code>Sling-Tracer-Config</code> - Tracer config</li>
</ul>
<p>So to enable authentication related logging following request can be sent</p>
<pre><code>curl -D - -d "j_username=admin" \
@@ -226,14 +226,14 @@ attributes := attributeName '=' attributeValue
2015-05-11 17:34:56,548 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.u.LoginModuleImpl - Adding Credentials to shared state.
2015-05-11 17:34:56,548 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.u.LoginModuleImpl - Adding login name to shared state.
</code></pre>
-<h2><a href="#tracer-recording" name="tracer-recording">Tracer Recording</a></h2>
+<h2><a href="#tracer-recording" id="tracer-recording">Tracer Recording</a></h2>
<p><em>Since 1.0.0 <a href="https://issues.apache.org/jira/browse/SLING-5459">SLING-5459</a></em></p>
<p>Apart from routing the logs to the server logs they can also be stored in memory and accessed in json form from Felix Web Console. By default support for recording is disabled and it needs to be explicitly enabled via OSGi config</p>
<p>Recording features works as explained below</p>
<ol>
- <li>
- <p>Client sends an HTTP request with header <code>Sling-Tracer-Record</code> set to <code>true</code></p>
- <pre><code>curl -D - -u admin:admin \
+<li>
+<p>Client sends an HTTP request with header <code>Sling-Tracer-Record</code> set to <code>true</code></p>
+<pre><code>curl -D - -u admin:admin \
-H "Sling-Tracer-Record : true" \
-d "./jcr:content/jcr:title=Summer Collection" \
-d ":name=summer-collection" \
@@ -242,10 +242,10 @@ attributes := attributeName '=' attributeValue
-d "tracers=oak-writes" \
http://localhost:4802/content/dam/
</code></pre>
- </li>
- <li>
- <p>Server includes a request id as part of <code>Sling-Tracer-Request-Id</code> response headers </p>
- <pre><code>HTTP/1.1 201 Created
+</li>
+<li>
+<p>Server includes a request id as part of <code>Sling-Tracer-Request-Id</code> response headers</p>
+<pre><code>HTTP/1.1 201 Created
Date: Wed, 27 Jan 2016 07:30:22 GMT
Sling-Tracer-Request-Id: 9b5b01f6-f269-47c3-a889-2dc8d4d7938f
X-Content-Type-Options: nosniff
@@ -254,15 +254,15 @@ Location: /content/dam/summer-collection
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
</code></pre>
- </li>
- <li>
- <p>The logs in json format can then be fetched from server at <code>/system/console/tracer</code> like http://localhost:8080/system/console/tracer/9b5b01f6-f269-47c3-a889-2dc8d4d7938f.json. </p>
- <pre><code>curl -s -D - -H "Sling-Tracer-Record : true" -H "Sling-Tracers : oak-query" \
+</li>
+<li>
+<p>The logs in json format can then be fetched from server at <code>/system/console/tracer</code> like http://localhost:8080/system/console/tracer/9b5b01f6-f269-47c3-a889-2dc8d4d7938f.json.</p>
+<pre><code>curl -s -D - -H "Sling-Tracer-Record : true" -H "Sling-Tracers : oak-query" \
-H "Sling-Tracer-Config : org.apache.jackrabbit.oak.query" \
-u admin:admin http://localhost:4512/assets.html/content/dam -o /dev/null
</code></pre>
- <p>Below is a json output for GET request</p>
- <pre><code><!-- TODO syntax marker (::javascript) disabled -->{
+<p>Below is a json output for GET request</p>
+<pre><code><!-- TODO syntax marker (::javascript) disabled -->{
"method": "GET",
"time": 15140,
"timestamp": 1461574009024,
@@ -272,8 +272,8 @@ Transfer-Encoding: chunked
...
],
"queries": [{
- "query": "/jcr:root/etc/workflow/instances//element(*,app:Workflow)[@status='RUNNING'] order by @startTime descending",
- "plan": "[app:Workflow] as [a] /* property status = RUNNING where ([a].[status] = 'RUNNING') and (isdescendantnode([a], [/etc/workflow/instances])) */",
+ "query": "/jcr:root/etc/workflow/instances//element(*,app:Workflow)[@status='RUNNING'] order by @startTime descending",
+ "plan": "[app:Workflow] as [a] /* property status = RUNNING where ([a].[status] = 'RUNNING') and (isdescendantnode([a], [/etc/workflow/instances])) */",
"caller": "com.example.WorkflowManager.getWorkflowInstances(WorkflowManager.java:902)"
}
],
@@ -281,36 +281,37 @@ Transfer-Encoding: chunked
"timestamp": 1461574022401,
"level": "DEBUG",
"logger": "org.apache.jackrabbit.oak.query.QueryEngineImpl",
- "message": "Parsing xpath statement: /jcr:root/etc/workflow/instances//element(*,cq:Workflow)[@status='RUNNING'] order by @startTime descending",
+ "message": "Parsing xpath statement: /jcr:root/etc/workflow/instances//element(*,cq:Workflow)[@status='RUNNING'] order by @startTime descending",
"params": [
"xpath",
- "/jcr:root/etc/workflow/instances//element(*,cq:Workflow)[@status='RUNNING'] order by @startTime descending"
+ "/jcr:root/etc/workflow/instances//element(*,cq:Workflow)[@status='RUNNING'] order by @startTime descending"
]
}
...
]
}
</code></pre>
- </li>
+</li>
</ol>
<p>JSON output consist of following sections</p>
<ol>
- <li><code>method</code> - Request method</li>
- <li><code>time</code> - Time in mills spent in request processing on server</li>
- <li><code>timestamp</code> - Request start time</li>
- <li><code>requestProgressLogs</code> - Sling Request Progress Tracker log for the given request</li>
- <li><code>queries</code> - List of queries fired along with details around <code>query</code>, <code>plan</code> and <code>caller</code> i.e. from where the query is invoked</li>
- <li><code>logs</code> - List of log entries captured (as enabled by tracer config) for current request</li>
+<li><code>method</code> - Request method</li>
+<li><code>time</code> - Time in mills spent in request processing on server</li>
+<li><code>timestamp</code> - Request start time</li>
+<li><code>requestProgressLogs</code> - Sling Request Progress Tracker log for the given request</li>
+<li><code>queries</code> - List of queries fired along with details around <code>query</code>, <code>plan</code> and <code>caller</code> i.e. from where the query is invoked</li>
+<li><code>logs</code> - List of log entries captured (as enabled by tracer config) for current request</li>
</ol>
<p>The recordings are held in memory for 15 mins (per default setting) and can be seen listed at http://localhost:8080/system/console/tracer. Look into the OSGi config for more config options around this.</p>
-<h2><a href="#installation" name="installation">Installation</a></h2>
+<h2><a href="#installation" id="installation">Installation</a></h2>
<p>Download the bundle from <a href="http://sling.apache.org/downloads.cgi">here</a> or use following Maven dependency</p>
<pre><code><!-- TODO syntax marker (::xml) disabled --><dependency>
<groupId>org.apache.sling</groupId>
<artifactId>org.apache.sling.tracer</artifactId>
<version>1.0.0</version>
</dependency>
-</code></pre></section></div></div>
+</code></pre>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html b/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html
index 3f8ad31..26fc266 100644
--- a/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html
+++ b/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html
@@ -116,137 +116,14 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p>The <code>jackrabbit-accessmanager</code> bundle delivers a REST interface to manipulate users permissions in the JCR. After installing the <code>jackrabbit-accessmanager</code> bundle the REST services are exposed under the path of the node where you will manipulate the permissions for a user with a specific selector like <code>modifyAce</code>, <code>acl</code>, <code>eacl</code> and <code>deleteAce</code>. <!-- TODO reactivate TOC once JBake moves to [...]
</p>
-<h2><a href="#privileges" name="privileges">Privileges</a></h2>
-<table>
- <thead>
- <tr>
- <th>Name </th>
- <th>Description </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>jcr:read </td>
- <td>the privilege to retrieve a node and get its properties and their values </td>
- </tr>
- <tr>
- <td>jcr:readAccessControl </td>
- <td>the privilege to get the access control policy of a node </td>
- </tr>
- <tr>
- <td>jcr:modifyProperties </td>
- <td>the privilege to create, modify and remove the properties of a node </td>
- </tr>
- <tr>
- <td>jcr:addChildNodes </td>
- <td>the privilege to create child nodes of a node </td>
- </tr>
- <tr>
- <td>jcr:removeChildNodes </td>
- <td>the privilege to remove child nodes of a node </td>
- </tr>
- <tr>
- <td>jcr:removeNode </td>
- <td>the privilege to remove a node </td>
- </tr>
- <tr>
- <td>jcr:write </td>
- <td>an aggregate privilege that contains: jcr:modifyProperties jcr:addChildNodes jcr:removeNode jcr:removeChildNodes </td>
- </tr>
- <tr>
- <td>jcr:modifyAccessControl </td>
- <td>the privilege to modify the access control policies of a node </td>
- </tr>
- <tr>
- <td>jcr:lockManagement </td>
- <td>the privilege to lock and unlock a node </td>
- </tr>
- <tr>
- <td>jcr:versionManagement </td>
- <td>the privilege to perform versioning operations on a node </td>
- </tr>
- <tr>
- <td>jcr:nodeTypeManagement </td>
- <td>the privilege to add and remove mixin node types and change the primary node type of a node </td>
- </tr>
- <tr>
- <td>jcr:retentionManagement </td>
- <td>the privilege to perform retention management operations on a node </td>
- </tr>
- <tr>
- <td>jcr:lifecycleManagement </td>
- <td>the privilege to perform lifecycle operations on a node </td>
- </tr>
- <tr>
- <td>jcr:all </td>
- <td>an aggregate privilege that contains all predefined privileges </td>
- </tr>
- </tbody>
-</table>
-<h2><a href="#add-or-modify-permissions" name="add-or-modify-permissions">Add or modify permissions</a></h2>
+<h2><a href="#privileges" id="privileges">Privileges</a></h2>
+<p>| Name | Description | |--|--| | jcr:read | the privilege to retrieve a node and get its properties and their values | | jcr:readAccessControl | the privilege to get the access control policy of a node | | jcr:modifyProperties | the privilege to create, modify and remove the properties of a node | | jcr:addChildNodes | the privilege to create child nodes of a node | | jcr:removeChildNodes | the privilege to remove child nodes of a node | | jcr:removeNode | the privilege to remove a no [...]
+<h2><a href="#add-or-modify-permissions" id="add-or-modify-permissions">Add or modify permissions</a></h2>
<p>To modify the permissions for a node POST a request to <code>/<path-to-the-node>.modifyAce.<html or json></code>. The following parameters are available:</p>
-<table>
- <thead>
- <tr>
- <th>Name </th>
- <th>Description </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>principalId </td>
- <td>The id of the user or group to modify the access rights for </td>
- </tr>
- <tr>
- <td>order </td>
- <td>The position of the entry within the list (see below for details) </td>
- </tr>
- <tr>
- <td>privilege@[privilege_name] </td>
- <td>One param for each privilege to modify. The value must be either 'granted', 'denied' or 'none'. </td>
- </tr>
- <tr>
- <td>restriction@[restriction_name] </td>
- <td>(since 3.0.4) One param for each restriction value. The same parameter name may be used again for multi-value restrictions. The value is the target value of the restriction. </td>
- </tr>
- <tr>
- <td>restriction@[restriction_name]@Delete </td>
- <td>(since 3.0.4) One param for each restriction to delete. The parameter value is ignored and can be anything. </td>
- </tr>
- </tbody>
-</table>
+<p>| Name | Description | |--|--| | principalId | The id of the user or group to modify the access rights for | | order | The position of the entry within the list (see below for details) | | privilege@[privilege_name] | One param for each privilege to modify. The value must be either 'granted', 'denied' or 'none'. | | restriction@[restriction_name] | (since 3.0.4) One param for each restriction value. The same parameter name may be used again for multi-value restrictions. The value i [...]
<p>The <code>order</code> parameter may have the following values:</p>
-<table>
- <thead>
- <tr>
- <th>Value </th>
- <th>Description </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>first</code> </td>
- <td>Place the target entry as the first amongst its siblings </td>
- </tr>
- <tr>
- <td><code>last</code> </td>
- <td>Place the target entry as the last amongst its siblings </td>
- </tr>
- <tr>
- <td><code>before *xyz*</code> </td>
- <td>Place the target entry immediately before the sibling whose name is <em>xyz</em> </td>
- </tr>
- <tr>
- <td><code>after *xyz*</code> </td>
- <td>Place the target entry immediately after the sibling whose name is <em>xyz</em> </td>
- </tr>
- <tr>
- <td>numeric </td>
- <td>Place the target entry at the indicated numeric place amongst its siblings where <em>0</em> is equivalent to <code>first</code> and <em>1</em> means the second place </td>
- </tr>
- </tbody>
-</table>
-<p>Responses: | 200 | Success | | 500 | Failure, HTML (or JSON) explains failure. |</p>
+<p>| Value | Description | |--|--| | <code>first</code> | Place the target entry as the first amongst its siblings | | <code>last</code> | Place the target entry as the last amongst its siblings | | <code>before *xyz*</code> | Place the target entry immediately before the sibling whose name is <em>xyz</em> | | <code>after *xyz*</code> | Place the target entry immediately after the sibling whose name is <em>xyz</em> | | numeric | Place the target entry at the indicated numeric place among [...]
+<p>Responses: | 200 | Success | | 500 | Failure, HTML (or JSON) explains failure. |</p>
<p>Example with curl:</p>
<pre><code>curl -FprincipalId=myuser -Fprivilege@jcr:read=granted http://localhost:8080/test/node.modifyAce.html
</code></pre>
@@ -259,25 +136,26 @@
<p>Remove existing restriction example with curl:</p>
<pre><code>curl -FprincipalId=myuser -Frestriction@rep:glob@Delete=yes http://localhost:8080/test/node.modifyAce.html
</code></pre>
-<h2><a href="#delete-permissions" name="delete-permissions">Delete permissions</a></h2>
+<h2><a href="#delete-permissions" id="delete-permissions">Delete permissions</a></h2>
<p>To delete permissions for a node POST a request to <code>/<path-to-the-node>.deleteAce.<html or json></code>. The following parameters are available:</p>
-<p>Responses: | 200 | Success | | 500 | Failure, HTML (or JSON) explains failure. | Example with curl:</p>
+<p>Responses: | 200 | Success | | 500 | Failure, HTML (or JSON) explains failure. | Example with curl:</p>
<pre><code>curl -F:applyTo=myuser http://localhost:8080/test/node.deleteAce.html
</code></pre>
-<h2><a href="#get-permissions" name="get-permissions">Get permissions</a></h2>
-<h3><a href="#bound-permissions" name="bound-permissions">Bound Permissions</a></h3>
-<p>To get the permissions bound to a particular node in a json format for a node send a GET request to <code>/<path-to-the-node>.acl.json</code>. </p>
+<h2><a href="#get-permissions" id="get-permissions">Get permissions</a></h2>
+<h3><a href="#bound-permissions" id="bound-permissions">Bound Permissions</a></h3>
+<p>To get the permissions bound to a particular node in a json format for a node send a GET request to <code>/<path-to-the-node>.acl.json</code>.</p>
<p>Example:</p>
<pre><code>http://localhost:8080/test/node.acl.json
</code></pre>
-<h3><a href="#effective-permissions" name="effective-permissions">Effective Permissions</a></h3>
-<p>To get the permissions which are effective for a particular node in a json format for a node send a GET request to <code>/<path-to-the-node>.eacl.json</code>. </p>
+<h3><a href="#effective-permissions" id="effective-permissions">Effective Permissions</a></h3>
+<p>To get the permissions which are effective for a particular node in a json format for a node send a GET request to <code>/<path-to-the-node>.eacl.json</code>.</p>
<p>Example:</p>
<pre><code>http://localhost:8080/test/node.eacl.json
</code></pre>
<div class="note">
See section 16.3 of the JCR 2.0 specification for an explanation of the difference between bound and effective policies.
-</div></section></div></div>
+</div>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html b/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html
index 0263882..37447fd 100644
--- a/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html
+++ b/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html
@@ -118,8 +118,8 @@
<p>For getting information about existing authorizables it provides all authorizables as Sling resources through its <code>AuthorizableResourceProvider</code> below <code>/system/userManager/user</code> and <code>/system/userManager/group</code>. Those resources can be exposed via the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a>.</p>
<p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h2><a href="#list-users" name="list-users">List users</a></h2>
-<p>To list existing users a GET request to the <code>/system/userManager/user</code> resource can be issued. Depending on the configuration of the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a> and/or the availability of a Servlet or Script handling the <code>sling/users</code> resource type, a result may be delivered/</p>
+<h2><a href="#list-users" id="list-users">List users</a></h2>
+<p>To list existing users a GET request to the <code>/system/userManager/user</code> resource can be issued. Depending on the configuration of the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a> and/or the availability of a Servlet or Script handling the <code>sling/users</code> resource type, a result may be delivered/</p>
<p>Example with curl and the default JSON rendering:</p>
<pre><code>$ curl http://localhost:8080/system/userManager/user.tidy.1.json
{
@@ -133,8 +133,8 @@
}
}
</code></pre>
-<h2><a href="#get-user" name="get-user">Get user</a></h2>
-<p><em>since version 2.0.8</em> The properties of a single user can be retrieved by sending a GET request to the user's resource at <code>/system/userManager/user/<username></code> where <code><username></code> would be replaced with the name of the user. Depending on the configuration of the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a> and/or the availability of a Servlet or Script handling the <code>sling/user</code> r [...]
+<h2><a href="#get-user" id="get-user">Get user</a></h2>
+<p><em>since version 2.0.8</em> The properties of a single user can be retrieved by sending a GET request to the user's resource at <code>/system/userManager/user/<username></code> where <code><username></code> would be replaced with the name of the user. Depending on the configuration of the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a> and/or the availability of a Servlet or Script handling the <code>sling/user</code> [...]
<p>Example with curl and the default JSON rendering:</p>
<pre><code>$ curl http://localhost:8080/system/userManager/user/admin.tidy.1.json
{
@@ -143,222 +143,113 @@
}
</code></pre>
<p>If a non-existing user is requested a <code>404/NOT FOUND</code> status is sent back.</p>
-<h2><a href="#create-user" name="create-user">Create user</a></h2>
+<h2><a href="#create-user" id="create-user">Create user</a></h2>
<p>To create a new user POST a request to <code>/system/userManager/user.create.<html or json></code>. The following parameters are available:</p>
<table>
- <thead>
- <tr>
- <th>Parameter Name </th>
- <th>Required </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>:name</code> </td>
- <td>yes </td>
- <td>The name of the new user</td>
- </tr>
- <tr>
- <td><code>pwd</code> </td>
- <td>yes </td>
- <td>The password of the new user</td>
- </tr>
- <tr>
- <td><code>pwdConfirm</code> </td>
- <td>yes </td>
- <td>The password of the new user (must be equal to the value of <code>pwd</code>)</td>
- </tr>
- <tr>
- <td><code><anyproperty></code> </td>
- <td>no </td>
- <td>Additional parameters will be stored as node properties in the JCR. Nested properties are supported since 2.2.6 (<a href="https://issues.apache.org/jira/browse/SLING-6747">SLING-6747</a>).</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Parameter Name </th><th> Required </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>:name</code> </td><td> yes </td><td> The name of the new user</td></tr>
+<tr><td><code>pwd</code> </td><td> yes </td><td> The password of the new user</td></tr>
+<tr><td><code>pwdConfirm</code> </td><td> yes </td><td> The password of the new user (must be equal to the value of <code>pwd</code>)</td></tr>
+<tr><td><code><anyproperty></code> </td><td> no </td><td> Additional parameters will be stored as node properties in the JCR. Nested properties are supported since 2.2.6 (<a href="https://issues.apache.org/jira/browse/SLING-6747">SLING-6747</a>).</td></tr>
+</tbody>
</table>
<p>Responses:</p>
<table>
- <thead>
- <tr>
- <th>Status Code </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200 </td>
- <td>Success, a redirect is sent to the users resource locator with HTML (or JSON) describing status.</td>
- </tr>
- <tr>
- <td>500 </td>
- <td>Failure, including user already exists. HTML (or JSON) explains failure.</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Status Code </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td>200 </td><td> Success, a redirect is sent to the users resource locator with HTML (or JSON) describing status.</td></tr>
+<tr><td>500 </td><td> Failure, including user already exists. HTML (or JSON) explains failure.</td></tr>
+</tbody>
</table>
<p>Example with curl:</p>
<pre><code>curl -F:name=myuser -Fpwd=password -FpwdConfirm=password -Fanyproperty1=value1 \
http://localhost:8080/system/userManager/user.create.html
</code></pre>
-<h2><a href="#update-user" name="update-user">Update user</a></h2>
+<h2><a href="#update-user" id="update-user">Update user</a></h2>
<p>To update an existing user POST a request to <code>/system/userManager/user/username.update.<html or json></code>. You can NOT update the username or the password (see Change Password below) only the additional properties are updateable through this URL. The following parameters are available:</p>
<table>
- <thead>
- <tr>
- <th>Parameter Name </th>
- <th>Required </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>:disabled</code> </td>
- <td>no </td>
- <td>(since version 2.1.1) If <code>true</code> disables the user to block further login attempts. If <code>false</code> enables a disabled user.</td>
- </tr>
- <tr>
- <td><code>:disabledReason</code> </td>
- <td>no </td>
- <td>Specifies the reason why a user has been disabled.</td>
- </tr>
- <tr>
- <td><code><anyproperty></code> </td>
- <td>no </td>
- <td>Additional parameters will be stored as node properties in the JCR. Nested properties are supported since 2.2.6 (<a href="https://issues.apache.org/jira/browse/SLING-6747">SLING-6747</a>).</td>
- </tr>
- <tr>
- <td><code><anyproperty>@Delete</code> </td>
- <td>no </td>
- <td>Properties with @Delete at the end of the name will be deleted in the JCR. Nested properties are supported since 2.2.6 (<a href="https://issues.apache.org/jira/browse/SLING-6747">SLING-6747</a>).</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Parameter Name </th><th> Required </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>:disabled</code> </td><td> no </td><td> (since version 2.1.1) If <code>true</code> disables the user to block further login attempts. If <code>false</code> enables a disabled user.</td></tr>
+<tr><td><code>:disabledReason</code> </td><td> no </td><td> Specifies the reason why a user has been disabled.</td></tr>
+<tr><td><code><anyproperty></code> </td><td> no </td><td> Additional parameters will be stored as node properties in the JCR. Nested properties are supported since 2.2.6 (<a href="https://issues.apache.org/jira/browse/SLING-6747">SLING-6747</a>).</td></tr>
+<tr><td><code><anyproperty>@Delete</code> </td><td> no </td><td> Properties with @Delete at the end of the name will be deleted in the JCR. Nested properties are supported since 2.2.6 (<a href="https://issues.apache.org/jira/browse/SLING-6747">SLING-6747</a>).</td></tr>
+</tbody>
</table>
<p>Responses:</p>
<table>
- <thead>
- <tr>
- <th>Status Code </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200 </td>
- <td>Success, a redirect is sent to the users resource locator with HTML (or JSON) describing status.</td>
- </tr>
- <tr>
- <td>404 </td>
- <td>User was not found.</td>
- </tr>
- <tr>
- <td>500 </td>
- <td>Any other failure. HTML (or JSON) explains failure.</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Status Code </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td>200 </td><td> Success, a redirect is sent to the users resource locator with HTML (or JSON) describing status.</td></tr>
+<tr><td>404 </td><td> User was not found.</td></tr>
+<tr><td>500 </td><td> Any other failure. HTML (or JSON) explains failure.</td></tr>
+</tbody>
</table>
<p>Example</p>
<pre><code>curl -Fanyproperty1@Delete -Fproperty2=value2 \
http://localhost:8080/system/userManager/user/myuser.update.html
</code></pre>
-<h2><a href="#change-password" name="change-password">Change password</a></h2>
-<p>To change a password of an existing user POST a request to <code>/system/userManager/user/username.changePassword.<html or json></code>. NOTE: since version 2.1.1, the oldPwd is optional if the current user is a user administrator. The following parameters are available:</p>
+<h2><a href="#change-password" id="change-password">Change password</a></h2>
+<p>To change a password of an existing user POST a request to <code>/system/userManager/user/username.changePassword.<html or json></code>. NOTE: since version 2.1.1, the oldPwd is optional if the current user is a user administrator. The following parameters are available:</p>
<table>
- <thead>
- <tr>
- <th>Parameter Name </th>
- <th>Required </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>oldPwd</code> </td>
- <td>yes </td>
- <td>Old password.</td>
- </tr>
- <tr>
- <td><code>newPwd</code> </td>
- <td>yes </td>
- <td>New password.</td>
- </tr>
- <tr>
- <td><code>newPwdConfirm</code> </td>
- <td>yes </td>
- <td>New password (must be equal to the value of <code>newPwd</code>).</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Parameter Name </th><th> Required </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>oldPwd</code> </td><td> yes </td><td> Old password.</td></tr>
+<tr><td><code>newPwd</code> </td><td> yes </td><td> New password.</td></tr>
+<tr><td><code>newPwdConfirm</code> </td><td> yes </td><td> New password (must be equal to the value of <code>newPwd</code>).</td></tr>
+</tbody>
</table>
<p>Responses:</p>
<table>
- <thead>
- <tr>
- <th>Status Code </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200 </td>
- <td>Success, no body.</td>
- </tr>
- <tr>
- <td>404 </td>
- <td>User was not found.</td>
- </tr>
- <tr>
- <td>500 </td>
- <td>Any other failure. HTML (or JSON) explains failure.</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Status Code </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td>200 </td><td> Success, no body.</td></tr>
+<tr><td>404 </td><td> User was not found.</td></tr>
+<tr><td>500 </td><td> Any other failure. HTML (or JSON) explains failure.</td></tr>
+</tbody>
</table>
<p>Example</p>
<pre><code>curl -FoldPwd=oldpassword -FnewPwd=newpassword -FnewPwdConfirm=newpassword \
http://localhost:8080/system/userManager/user/myuser.changePassword.html
</code></pre>
-<h2><a href="#delete-user" name="delete-user">Delete user</a></h2>
+<h2><a href="#delete-user" id="delete-user">Delete user</a></h2>
<p>To delete an existing user POST a request to <code>/system/userManager/user/username.delete.<html or json></code>. The following parameters are available:</p>
<table>
- <thead>
- <tr>
- <th>Parameter Name </th>
- <th>Required </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>:applyTo</code> </td>
- <td>no </td>
- <td>An array of relative resource references to users to be deleted. If this parameter is present, the username from the URL is ignored and all listed users are removed.</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Parameter Name </th><th> Required </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>:applyTo</code> </td><td> no </td><td> An array of relative resource references to users to be deleted. If this parameter is present, the username from the URL is ignored and all listed users are removed.</td></tr>
+</tbody>
</table>
<p>Responses:</p>
<table>
- <thead>
- <tr>
- <th>Status Code </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200 </td>
- <td>Success, no body.</td>
- </tr>
- <tr>
- <td>404 </td>
- <td>User(s) was/were not found.</td>
- </tr>
- <tr>
- <td>500 </td>
- <td>Any other failure. HTML (or JSON) explains failure.</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Status Code </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td>200 </td><td> Success, no body.</td></tr>
+<tr><td>404 </td><td> User(s) was/were not found.</td></tr>
+<tr><td>500 </td><td> Any other failure. HTML (or JSON) explains failure.</td></tr>
+</tbody>
</table>
<p>Example</p>
<pre><code>curl -Fgo=1 http://localhost:8080/system/userManager/user/myuser.delete.html
</code></pre>
-<h2><a href="#list-groups" name="list-groups">List groups</a></h2>
+<h2><a href="#list-groups" id="list-groups">List groups</a></h2>
<p>To list existing groups a GET request to the <code>/system/userManager/group</code> resource can be sent. Depending on the configuration of the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a> and/or the availability of a Servlet or Script handling the <code>sling/groups</code> resource type, a result may be delivered.</p>
<p>Example with curl and the default JSON rendering:</p>
<pre><code>$ curl http://localhost:8080/system/userManager/group.tidy.1.json
@@ -383,8 +274,8 @@
}
}
</code></pre>
-<h2><a href="#get-group" name="get-group">Get group</a></h2>
-<p>The properties of a single group can be retrieved by sending a GET request to the group's resource at <code>/system/userManager/group/groupname</code> where <em>groupname</em> would be replaced with the name of the group. Depending on the configuration of the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a> and/or the availability of a Servlet or Script handling the <code>sling/group</code> resource type, a result may be delivered.</p>
+<h2><a href="#get-group" id="get-group">Get group</a></h2>
+<p>The properties of a single group can be retrieved by sending a GET request to the group's resource at <code>/system/userManager/group/groupname</code> where <em>groupname</em> would be replaced with the name of the group. Depending on the configuration of the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a> and/or the availability of a Servlet or Script handling the <code>sling/group</code> resource type, a result may be delivered.</p>
<p>Example with curl and the default JSON rendering:</p>
<pre><code>$ curl http://localhost:8080/system/userManager/group/administrators.tidy.1.json
{
@@ -395,192 +286,101 @@
}
</code></pre>
<p>If a non-existing group is requested a 404/NOT FOUND status is sent back.</p>
-<h2><a href="#create-group" name="create-group">Create group</a></h2>
+<h2><a href="#create-group" id="create-group">Create group</a></h2>
<p>To create a new group POST a request to <code>/system/userManager/group.create.<html or json></code>. The following parameters are available:</p>
<table>
- <thead>
- <tr>
- <th>Parameter Name </th>
- <th>Required </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>:name</code> </td>
- <td>yes </td>
- <td>The name of the new group</td>
- </tr>
- <tr>
- <td><code><anyproperty></code> </td>
- <td>no </td>
- <td>Additional parameters will be stored as node properties in the JCR. Nested properties are supported since 2.2.6 (<a href="https://issues.apache.org/jira/browse/SLING-6747">SLING-6747</a>).</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Parameter Name </th><th> Required </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>:name</code> </td><td> yes </td><td> The name of the new group</td></tr>
+<tr><td><code><anyproperty></code> </td><td> no </td><td> Additional parameters will be stored as node properties in the JCR. Nested properties are supported since 2.2.6 (<a href="https://issues.apache.org/jira/browse/SLING-6747">SLING-6747</a>).</td></tr>
+</tbody>
</table>
<p>Responses:</p>
<table>
- <thead>
- <tr>
- <th>Status Code </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200 </td>
- <td>Success, a redirect is sent to the group resource locator with HTML (or JSON) describing status</td>
- </tr>
- <tr>
- <td>500 </td>
- <td>Failure including group already exists. HTML (or JSON) explains failure.</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Status Code </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td>200 </td><td> Success, a redirect is sent to the group resource locator with HTML (or JSON) describing status</td></tr>
+<tr><td>500 </td><td> Failure including group already exists. HTML (or JSON) explains failure.</td></tr>
+</tbody>
</table>
<p>Example with curl:</p>
<pre><code>curl -F:name=mygroup -Fanyproperty1=value1 \
http://localhost:8080/system/userManager/group.create.html
</code></pre>
-<h2><a href="#update-group" name="update-group">Update group</a></h2>
+<h2><a href="#update-group" id="update-group">Update group</a></h2>
<p>To update an existing group POST a request to <code>/system/userManager/group/groupname.update.<html or json></code>. You can NOT update the name of the group only the additional properties are updateable. The following parameters are available:</p>
<table>
- <thead>
- <tr>
- <th>Parameter Name </th>
- <th>Required </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>:member</code> </td>
- <td>no </td>
- <td>user(s) (name or URI) to add to the group as a member. Can also be an array of users.</td>
- </tr>
- <tr>
- <td><code>:member@Delete</code> </td>
- <td>no </td>
- <td>user(s) (name or URI) to remove from the group. Can also be an array of users.</td>
- </tr>
- <tr>
- <td><code><anyproperty></code> </td>
- <td>no </td>
- <td>Additional parameters will be stored as node properties in the JCR. Nested properties are supported since 2.2.6 (<a href="https://issues.apache.org/jira/browse/SLING-6747">SLING-6747</a>).</td>
- </tr>
- <tr>
- <td><code><anyproperty>@Delete</code> </td>
- <td>no </td>
- <td>Properties with @Delete at the end of the name will be deleted in the JCR. Nested properties are supported since 2.2.6 (<a href="https://issues.apache.org/jira/browse/SLING-6747">SLING-6747</a>).</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Parameter Name </th><th> Required </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>:member</code> </td><td> no </td><td> user(s) (name or URI) to add to the group as a member. Can also be an array of users.</td></tr>
+<tr><td><code>:member@Delete</code> </td><td> no </td><td> user(s) (name or URI) to remove from the group. Can also be an array of users.</td></tr>
+<tr><td><code><anyproperty></code> </td><td> no </td><td> Additional parameters will be stored as node properties in the JCR. Nested properties are supported since 2.2.6 (<a href="https://issues.apache.org/jira/browse/SLING-6747">SLING-6747</a>).</td></tr>
+<tr><td><code><anyproperty>@Delete</code> </td><td> no </td><td> Properties with @Delete at the end of the name will be deleted in the JCR. Nested properties are supported since 2.2.6 (<a href="https://issues.apache.org/jira/browse/SLING-6747">SLING-6747</a>).</td></tr>
+</tbody>
</table>
<p>Responses:</p>
<table>
- <thead>
- <tr>
- <th>Status Code </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200 </td>
- <td>Success, a redirect is sent to the group resource locator with HTML (or JSON) describing status.</td>
- </tr>
- <tr>
- <td>404 </td>
- <td>Group was not found.</td>
- </tr>
- <tr>
- <td>500 </td>
- <td>Any other failure. HTML (or JSON) explains failure.</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Status Code </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td>200 </td><td> Success, a redirect is sent to the group resource locator with HTML (or JSON) describing status.</td></tr>
+<tr><td>404 </td><td> Group was not found.</td></tr>
+<tr><td>500 </td><td> Any other failure. HTML (or JSON) explains failure.</td></tr>
+</tbody>
</table>
<p>Example</p>
<pre><code>curl -Fanyproperty1@Delete -Fproperty2=value2 -F ":member=/system/userManager/user/myuser" \
http://localhost:8080/system/userManager/group/mygroup.update.html
</code></pre>
-<h2><a href="#delete-group" name="delete-group">Delete group</a></h2>
+<h2><a href="#delete-group" id="delete-group">Delete group</a></h2>
<p>To delete an existing group POST a request to <code>/system/userManager/group/groupname.delete.<html or json></code>. The following parameters are available:</p>
<table>
- <thead>
- <tr>
- <th>Parameter Name </th>
- <th>Required </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>:applyTo</code> </td>
- <td>no </td>
- <td>An array of relative resource references to groups to be deleted. If this parameter is present, the name of the group from the URL is ignored and all listed groups are removed.</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Parameter Name </th><th> Required </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>:applyTo</code> </td><td> no </td><td> An array of relative resource references to groups to be deleted. If this parameter is present, the name of the group from the URL is ignored and all listed groups are removed.</td></tr>
+</tbody>
</table>
<p>Responses:</p>
<table>
- <thead>
- <tr>
- <th>Status Code </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200 </td>
- <td>Success, sent with no body.</td>
- </tr>
- <tr>
- <td>404 </td>
- <td>Group(s) was/were not found.</td>
- </tr>
- <tr>
- <td>500 </td>
- <td>Any other failure. HTML (or JSON) explains failure.</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Status Code </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td>200 </td><td> Success, sent with no body.</td></tr>
+<tr><td>404 </td><td> Group(s) was/were not found.</td></tr>
+<tr><td>500 </td><td> Any other failure. HTML (or JSON) explains failure.</td></tr>
+</tbody>
</table>
<p>Example</p>
<pre><code>curl -Fgo=1 http://localhost:8080/system/userManager/group/mygroup.delete.html
</code></pre>
-<h2><a href="#automated-tests" name="automated-tests">Automated Tests</a></h2>
+<h2><a href="#automated-tests" id="automated-tests">Automated Tests</a></h2>
<p>The <a href="https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/blob/master/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/accessManager/">launchpad/testing</a> module contains test classes for various operations of the <code>jackrabbit-usermanager</code>. Such tests run as part of our continuous integration process, to demonstrate and verify the behavior of the various operations, in a way that's guaranteed to be in sync with the actual Slin [...]
-<h2><a href="#permissions-checking-from-scripts" name="permissions-checking-from-scripts">Permissions checking from scripts</a></h2>
+<h2><a href="#permissions-checking-from-scripts" id="permissions-checking-from-scripts">Permissions checking from scripts</a></h2>
<p><em>Since Version 2.0.6</em></p>
-<p>When developing scripts that will perform user or group updates, you may want to know what actions the current user is provisioned to do. This information can be used to conditionally render parts of your page differently based on the user rights.</p>
+<p>When developing scripts that will perform user or group updates, you may want to know what actions the current user is provisioned to do. This information can be used to conditionally render parts of your page differently based on the user rights.</p>
<p>The jackrabbit.usermanager bundle provides a service (AuthorizablePrivilegesInfo) you can utilize to do help with this permission checking.</p>
<p>The AuthorizablePrivilegesInfo provides methods for checking the following actions</p>
<table>
- <thead>
- <tr>
- <th>Method </th>
- <th>Description </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>canAddUser(jcrSession)</code> </td>
- <td>Checks if the current user may add new users </td>
- </tr>
- <tr>
- <td><code>canAddGroup(jcrSession)</code> </td>
- <td>Checks if the current user may add new groups </td>
- </tr>
- <tr>
- <td><code>canUpdateProperties(jcrSession, principalId)</code> </td>
- <td>Checks if the current user may update the properties of the specified principal </td>
- </tr>
- <tr>
- <td><code>canRemove(jcrSession, principalId)</code> </td>
- <td>Checks if the current user may remove the specified user or group </td>
- </tr>
- <tr>
- <td><code>canUpdateGroupMembers(jcrSession, groupId)</code> </td>
- <td>Checks if the current user may modify the membership of the specified group </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Method </th><th> Description </th></tr>
+</thead>
+<tbody>
+<tr><td> <code>canAddUser(jcrSession)</code> </td><td> Checks if the current user may add new users </td></tr>
+<tr><td> <code>canAddGroup(jcrSession)</code> </td><td> Checks if the current user may add new groups </td></tr>
+<tr><td> <code>canUpdateProperties(jcrSession, principalId)</code> </td><td> Checks if the current user may update the properties of the specified principal </td></tr>
+<tr><td> <code>canRemove(jcrSession, principalId)</code> </td><td> Checks if the current user may remove the specified user or group </td></tr>
+<tr><td> <code>canUpdateGroupMembers(jcrSession, groupId)</code> </td><td> Checks if the current user may modify the membership of the specified group </td></tr>
+</tbody>
</table>
<p>Example:</p>
<pre><code><%
@@ -607,7 +407,8 @@
//TODO: draw your UI that allows the user to update the group memebership here
}
%>
-</code></pre></section></div></div>
+</code></pre>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html b/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html
index 4d6f4db..e554af2 100644
--- a/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html
+++ b/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html
@@ -120,9 +120,9 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h2><a href="#multiple-ways-to-modify-content" name="multiple-ways-to-modify-content">Multiple Ways to Modify Content</a></h2>
+<h2><a href="#multiple-ways-to-modify-content" id="multiple-ways-to-modify-content">Multiple Ways to Modify Content</a></h2>
<p>As always in life there is more than one way to do it. So to modify content in Sling, you have multiple options, the Sling default POST Servlet also called the <em>SlingPostServlet</em> is one of them. This page is about how you can modify - create, modify, copy, move, delete, import - content through the <em>SlingPostServlet</em>. In addition it also explains how to extend the SlingPostServlet with new operations.</p>
-<h2><a href="#quickstart-creating-content" name="quickstart-creating-content">Quickstart: Creating Content</a></h2>
+<h2><a href="#quickstart-creating-content" id="quickstart-creating-content">Quickstart: Creating Content</a></h2>
<p>To create content you simply send an HTTP POST request using the path of the resource to store the content in and include the actual content as request parameters. So one possibility to do just that is by having an HTML Form like the following:</p>
<pre><code><form method="POST" action="http://host/some/new/content" enctype="multipart/form-data">
<input type="text" name="title" value="" />
@@ -142,21 +142,21 @@
-Ftext="some body text content" http://host/some/new/content
</code></pre>
<p>Similarly, you may assign JCR mixin node types using the <code>jcr:mixinTypes</code> property.</p>
-<h2><a href="#preface-multipart-form-data-posts" name="preface-multipart-form-data-posts">Preface: multipart/form-data POSTs</a></h2>
+<h2><a href="#preface-multipartform-data-posts" id="preface-multipartform-data-posts">Preface: multipart/form-data POSTs</a></h2>
<p>Sometimes you might want to have the content modifications applied in a certain order. This is particularly interesting if you use fields to create child nodes and if you want to stipulate a certain child node order based on the form fields.</p>
<p>In this case, ensure you are submitting the POST request using <code>multipart/form-data</code> encoding. This preserves the order of parameter application according to the original HTML form. To this avail, ensure to always include the <code>enctype="multipart/form-data"</code> attribute with the <code><form></code> tag.</p>
<p>This support requires Sling Engine 2.1.0 and the Sling Default Post Servlet 2.0.6.</p>
-<h2><a href="#slingpostservlet-operations" name="slingpostservlet-operations">SlingPostServlet Operations</a></h2>
+<h2><a href="#slingpostservlet-operations" id="slingpostservlet-operations">SlingPostServlet Operations</a></h2>
<p>The SlingPostServlet is actually just a front-end to the actual operations. To select the actual operation to execute, the <code>:operation</code> request parameter is used. Out of the box, the SlingPostServlet supports the following operations:</p>
<ul>
- <li>property not set or empty -- Create new content or modify existing content</li>
- <li><code>delete</code> -- Remove existing content</li>
- <li><code>move</code> -- Move existing content to a new location</li>
- <li><code>copy</code> -- Copy existing content to a new location</li>
- <li><code>import</code> -- Import content structures from JSON/XML/Zip</li>
- <li><code>nop</code> -- Explicitly requests to do nothing and just sets the response status</li>
- <li><code>checkin</code> - Check in a versionable node</li>
- <li><code>checkout</code> - Check out a versionable node</li>
+<li>property not set or empty -- Create new content or modify existing content</li>
+<li><code>delete</code> -- Remove existing content</li>
+<li><code>move</code> -- Move existing content to a new location</li>
+<li><code>copy</code> -- Copy existing content to a new location</li>
+<li><code>import</code> -- Import content structures from JSON/XML/Zip</li>
+<li><code>nop</code> -- Explicitly requests to do nothing and just sets the response status</li>
+<li><code>checkin</code> - Check in a versionable node</li>
+<li><code>checkout</code> - Check out a versionable node</li>
</ul>
<p>All these operations always operate on the resource of the request as returned by <code>SlingHttpServletRequest.getResource()</code>. Some operations require additional parameters to be set to operate completely.</p>
<p>Please note that operations are mutually exclusive. For a single POST request only one operation may be executed. Operations also only consume the request parameters as described below. Any excess parameters are silently ignored.</p>
@@ -169,55 +169,31 @@ Note that the launchpad test services module contains a number of <a href="https
This applies to operations that use this parameter, since version 2.1.2 of the *org.apache.sling.servlets.post* bundle: If the last segment of the `:applyTo` value is '*' then the operation applies to all the children of the resolved parent resource. This can be used to act on all the children
of a resource without having to specify the path of each individual child resource.
</div>
-<h3><a href="#content-creation-or-modification" name="content-creation-or-modification">Content Creation or Modification</a></h3>
+<h3><a href="#content-creation-or-modification" id="content-creation-or-modification">Content Creation or Modification</a></h3>
<p>The simplest and most common use case, probably, is content creation and modification. We already saw an example above in the quickstart section. In this section we elaborate more on the concrete stuff.</p>
<p>First, the request URL indicates the actual resource to be handled. If the URL addresses an existing resource, the request parameters just provide values for the properties to be set on the existing resource.</p>
<p>If the resource of the request is a synthetic resource, e.g. <code>NonExistingResource</code> or <code>StarResource</code>, a new item is created. The path (including name) of the resource to be created is derived from the resource path:</p>
<ul>
- <li>If the resource path ends with a <code>/*</code> or <code>/</code> the name of the resource is automatically created using a name creation algorithm taking into account various request parameters.</li>
- <li>Otherwise the resource path is used as the path and name of the new resource.</li>
+<li>If the resource path ends with a <code>/*</code> or <code>/</code> the name of the resource is automatically created using a name creation algorithm taking into account various request parameters.</li>
+<li>Otherwise the resource path is used as the path and name of the new resource.</li>
</ul>
<p>In both cases the path may still include selectors and extensions, which are cut off the path before finding out, what to do.</p>
<p>To illustrate this algorithm, lets look at some examples (and check the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/blob/master/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/servlets/post/PostServletCreateTest.java"><code>PostServletCreateTest</code></a> in case of doubt):</p>
<table>
- <thead>
- <tr>
- <th>Resource Path </th>
- <th>Item path </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>/content/new</code> </td>
- <td><code>/content/new</code> </td>
- </tr>
- <tr>
- <td><code>/content/new.html</code> </td>
- <td><code>/content/new</code> </td>
- </tr>
- <tr>
- <td><code>/content/new.print.a4.html</code> </td>
- <td><code>/content/new</code> </td>
- </tr>
- <tr>
- <td><code>/content/</code> </td>
- <td><code>/content/xxx</code> where <code>xxx</code> is a generated name </td>
- </tr>
- <tr>
- <td><code>/content/*</code></td>
- <td><code>/content/xxx</code> where <code>xxx</code> is a generated name </td>
- </tr>
- <tr>
- <td><code>/content/*.html</code></td>
- <td><code>/content/xxx</code> where <code>xxx</code> is a generated name </td>
- </tr>
- <tr>
- <td><code>/content/*.print.a4.html</code></td>
- <td><code>/content/xxx</code> where <code>xxx</code> is a generated name </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Resource Path </th><th> Item path </th></tr>
+</thead>
+<tbody>
+<tr><td> <code>/content/new</code> </td><td> <code>/content/new</code> </td></tr>
+<tr><td> <code>/content/new.html</code> </td><td> <code>/content/new</code> </td></tr>
+<tr><td> <code>/content/new.print.a4.html</code> </td><td> <code>/content/new</code> </td></tr>
+<tr><td> <code>/content/</code> </td><td> <code>/content/xxx</code> where <code>xxx</code> is a generated name </td></tr>
+<tr><td> <code>/content/*</code></td><td> <code>/content/xxx</code> where <code>xxx</code> is a generated name </td></tr>
+<tr><td> <code>/content/*.html</code></td><td> <code>/content/xxx</code> where <code>xxx</code> is a generated name </td></tr>
+<tr><td> <code>/content/*.print.a4.html</code></td><td> <code>/content/xxx</code> where <code>xxx</code> is a generated name </td></tr>
+</tbody>
</table>
-<h5><a href="#setting-property-values" name="setting-property-values">Setting Property Values</a></h5>
+<h5><a href="#setting-property-values" id="setting-property-values">Setting Property Values</a></h5>
<p>Setting property values is as simple as just adding a request parameter whose name is the name of the property to be set and whose value is the value to be assigned to the property. We already saw how to do this in the quick start examples above.</p>
<p>Here is another example showing a simple HTML form to create a new resource with an automatically created name:</p>
<pre><code><form method="POST" action="/content/page/first" enctype="multipart/form-data">
@@ -230,34 +206,38 @@ of a resource without having to specify the path of each individual child resour
<p>If a parameter has multiple values, the respective property will be created as a multi-value property. So for example the command line:</p>
<pre><code>$ curl -Fmulti=one -Fmulti=two http://host/content/page
</code></pre>
-<p>Would assign the <code>/content/page/multi</code> property the value <em>[ "one", "two" ]</em>.</p>
+<p>Would assign the <code>/content/page/multi</code> property the value <em>[ "one", "two" ]</em>.</p>
<p>This is pretty much all there is to know about creating and modifying content. The following sections will now introduce more functionality which help you with more fine-grained control in your content management application.</p>
<p>For more operations with multiple values you can use the <a href="#patch"><code>@Patch</code></a> suffix.</p>
-<h5><a href="#automatic-property-values-last-modified-and-created-by" name="automatic-property-values-last-modified-and-created-by">Automatic property values: last modified and created by</a></h5>
-<p>To make it easier to set "last modified" and "created by" property values from POST requests, values are generated automatically for the following property names <em>if they are supplied with empty values in such a request</em>:</p>
+<h5><a href="#automatic-property-values-last-modified-and-created-by" id="automatic-property-values-last-modified-and-created-by">Automatic property values: last modified and created by</a></h5>
+<p>To make it easier to set "last modified" and "created by" property values from POST requests, values are generated automatically for the following property names <em>if they are supplied with empty values in such a request</em>:</p>
<ul>
- <li>
- <p><code>created</code> and <code>jcr:created</code> are set to the node creation time, as a Date value.</p></li>
- <li>
- <p><code>lastModified</code>, <code>jcr:lastModified</code> are set to the node modification time, as a Date value.</p></li>
- <li>
- <p><code>createdBy</code> and <code>jcr:createdBy</code> are set to the name of the user who created the node.</p></li>
- <li>
- <p><code>lastModifiedBy</code>, <code>jcr:lastModifiedBy</code> are set to the name of the user who modified the node.</p></li>
+<li>
+<p><code>created</code> and <code>jcr:created</code> are set to the node creation time, as a Date value.</p>
+</li>
+<li>
+<p><code>lastModified</code>, <code>jcr:lastModified</code> are set to the node modification time, as a Date value.</p>
+</li>
+<li>
+<p><code>createdBy</code> and <code>jcr:createdBy</code> are set to the name of the user who created the node.</p>
+</li>
+<li>
+<p><code>lastModifiedBy</code>, <code>jcr:lastModifiedBy</code> are set to the name of the user who modified the node.</p>
+</li>
</ul>
<p>This is demonstrated by the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/blob/master/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/servlets/post/SlingAutoPropertiesTest.java">SlingAutoPropertiesTest</a> which is part of our launchpad integration tests.</p>
-<h5><a href="#file-uploads" name="file-uploads">File Uploads</a></h5>
+<h5><a href="#file-uploads" id="file-uploads">File Uploads</a></h5>
<p>File uploads are typically done using the <code><input type="file""/></code> element of an HTML form and ensuring the correct form encoding. The SlingPostServlet handles uploaded files specially, in that the file data is not simply written into a property, but a node is actually created with three properties:</p>
<ul>
- <li><code>jcr:data</code> -- The actual file contents</li>
- <li><code>jcr:lastModified</code> -- The time stamp of processing the uploaded file</li>
- <li><code>jcr:mimeType</code> -- The MIME type from the original file submission (if contained in the file body part) or derived from the original file name</li>
+<li><code>jcr:data</code> -- The actual file contents</li>
+<li><code>jcr:lastModified</code> -- The time stamp of processing the uploaded file</li>
+<li><code>jcr:mimeType</code> -- The MIME type from the original file submission (if contained in the file body part) or derived from the original file name</li>
</ul>
<p>The name of the node is either taken from the parameter name or if the name is <code>*</code> from the name of the uploaded file.</p>
<p>The primary node type of the uploaded file is selected using the following algorithm:</p>
<ul>
- <li>If a `@TypeHint suffixed parameter (see below for a description) is present check whether the value is a known non-mixin node type. If so, the node is created with this primary node type.</li>
- <li>If a <code>@TypeHint</code> suffixed parameter is not present or the value does not denote an existing non-mixin node type, the node will be created as an <code>nt:file</code> node if the parent node is of type <code>nt:folder</code>. Otherwise the node will be created with primary node type <code>nt:resource</code>.</li>
+<li>If a `@TypeHint suffixed parameter (see below for a description) is present check whether the value is a known non-mixin node type. If so, the node is created with this primary node type.</li>
+<li>If a <code>@TypeHint</code> suffixed parameter is not present or the value does not denote an existing non-mixin node type, the node will be created as an <code>nt:file</code> node if the parent node is of type <code>nt:folder</code>. Otherwise the node will be created with primary node type <code>nt:resource</code>.</li>
</ul>
<p>If the node to be created is <code>nt:file</code>, the actual file data will really be stored in the <code>jcr:content</code> child node of the new <code>nt:file</code> node whose primary node type is then set as <code>nt:resource</code>.</p>
<p>Example 1: Upload an image to a node named <code>image</code> below <code>/content/page</code>:</p>
@@ -274,21 +254,21 @@ of a resource without having to specify the path of each individual child resour
</form>
</code></pre>
<p>Assuming the user selected a file named <code>myImage.jpg</code> the uploaded file would be stored in an <code>nt:file</code> node at <code>/content/folder/myImage.jpg</code>.</p>
-<h5><a href="#date-properties" name="date-properties">Date properties</a></h5>
+<h5><a href="#date-properties" id="date-properties">Date properties</a></h5>
<p>Parameters providing date/time values to be stored in JCR properties of type <em>Date</em> require special handling. The problem is that there are a number of formats to represent such date/time values. To account for this open-ended list of formats, the Sling Post Servlet supports configurability of the process of parsing strings into <code>Calendar</code> objects.</p>
<p>The Sling Post Servlet configuration property <code>servlet.post.dateFormats</code> takes a list of format strings which are used to setup <code>java.text.SimpleDateFormat</code> instances for parsing date/time string representations. A special format string <code>ISO8601</code> is supported to indicate the string to be parsed as a JCR standard string representation of a <em>Date</em> property. Only the latter supports storing the actual timezone offset. All the parsers leveraging <co [...]
<p>The default list of configured date/time parse pattern is:</p>
<ul>
- <li>EEE MMM dd yyyy HH:mm:ss 'GMT'Z</li>
- <li>ISO8601, using the org.apache.jackrabbit.util.ISO8601 parser (±YYYY-MM-DDThh:mm:ss.SSSTZD)</li>
- <li>yyyy-MM-dd'T'HH:mm:ss.SSSZ</li>
- <li>yyyy-MM-dd'T'HH:mm:ss</li>
- <li>yyyy-MM-dd</li>
- <li>dd.MM.yyyy HH:mm:ss</li>
- <li>dd.MM.yyyy</li>
+<li>EEE MMM dd yyyy HH:mm:ss 'GMT'Z</li>
+<li>ISO8601, using the org.apache.jackrabbit.util.ISO8601 parser (±YYYY-MM-DDThh:mm:ss.SSSTZD)</li>
+<li>yyyy-MM-dd'T'HH:mm:ss.SSSZ</li>
+<li>yyyy-MM-dd'T'HH:mm:ss</li>
+<li>yyyy-MM-dd</li>
+<li>dd.MM.yyyy HH:mm:ss</li>
+<li>dd.MM.yyyy</li>
</ul>
<p>Any date/time string parameter supplied is subject to the patterns in the configured order. The first pattern accepting the string and parsing it into a <code>Date</code> -- and thus a <code>Calendar</code> -- object is used. Therefore this list is best ordered in a most-stringent to least-stringent order.</p>
-<h5><a href="#omitting-some-parameters" name="omitting-some-parameters">Omitting Some Parameters</a></h5>
+<h5><a href="#omitting-some-parameters" id="omitting-some-parameters">Omitting Some Parameters</a></h5>
<p>There may be times that you have forms which contain a lot of fields which you do not want to actually store in content. Such forms usually are created using some client-side GUI library which uses the fields for its own purposes. To be able to easily differentiate between real content to be actually stored and such control parameters, you may prefix the names of the fields destined for content with a dot-slash (<code>./</code>).</p>
<p>As soon as the SlingPostServlet encounters parameters prefixed with dot-slash, only those parameters are considered for content updates while all other parameters not prefixed are just ignored. In addition to dot-slash prefixed parameters, also parameters prefixed with dot-dot-slash (<code>../</code>) and slash (<code>/</code>) are considered in this situation.</p>
<p>For example, the following form only uses the first two fields for content update and ignores the rest:</p>
@@ -304,16 +284,16 @@ of a resource without having to specify the path of each individual child resour
<p>Background: The name of the parameters used for content update are actually intended to be relative path names of the properties to modify. So in effect using the field name <code>text</code> is equivalent to <code>./text</code> -- dot-slash meaning relative to the current node identified by the <code>action</code> attribute value for <code>form</code> tag -- or <code>../first/text</code> if <code>first</code> is the name of the node to modify -- dot-dot-slash meaning relative to the [...]
<p>In addition to the mechanism explained here, the following parameters are also ignored:</p>
<ul>
- <li>Parameters whose name start with a colon (<code>:</code>) are always ignored by the SlingPostServlet with respect to content update. The reason is that the prefixing colon is intended as a marker for SlingPostServlet control parameters.</li>
- <li>The <code>charset</code> request parameter is also never written back because this parameter is used to convey the character encoding used to transport the request parameters.</li>
- <li>Request parameters matching a regular expression supplied with the <code>servlet.post.ignorePattern</code> configuration parameter are also ignored. By default this pattern is <code>j_.*</code> thus ignoring any request parameters with the prefix <code>j_</code> such as <code>j_username</code>. Those request parameters are generally used for authentication purposes and may hit the Sling POST Servlet in some situations.</li>
+<li>Parameters whose name start with a colon (<code>:</code>) are always ignored by the SlingPostServlet with respect to content update. The reason is that the prefixing colon is intended as a marker for SlingPostServlet control parameters.</li>
+<li>The <code>charset</code> request parameter is also never written back because this parameter is used to convey the character encoding used to transport the request parameters.</li>
+<li>Request parameters matching a regular expression supplied with the <code>servlet.post.ignorePattern</code> configuration parameter are also ignored. By default this pattern is <code>j_.*</code> thus ignoring any request parameters with the prefix <code>j_</code> such as <code>j_username</code>. Those request parameters are generally used for authentication purposes and may hit the Sling POST Servlet in some situations.</li>
</ul>
-<h5>Controlling Content Updates with <code>@</code> Suffixes</h5>
+<h5><a href="#controlling-content-updates-with-suffixes" id="controlling-content-updates-with-suffixes">Controlling Content Updates with <code>@</code> Suffixes</a></h5>
<p>Generally just creating forms with parameters and their values suffices it completely. Sometimes, though, you want to have more control on how the parameter values are actually stored in the properties. For example, you want to set a property to a default value if the user did provide an actual value. Or you might want to store a parameter explicitly with a given data type, such as numeric, boolean etc.</p>
<p>The SlingPostServlet provides such property control in the form of <code>@</code> suffixed parameters, which are now presented.</p>
<p>The <code>@</code> suffixed parameters are not used on their own but always in conjunction with a plain parameter. The part of the parameter name before the <code>@</code> suffix is used in this case for correlation and must match exactly the name of the parameter to which the <code>@</code> suffixed parameter belongs.</p>
<p>For example, the parameter <code>width@TypeHint</code> applies to the <code>width</code> parameter and the <code>./height@TypeHint</code> parameter applies to the <code>./height</code> parameter. As can be seen, the correlation between the parameters is a simple case-sensitive string comparison. That is the <code>widht@TypeHint</code> parameter would not apply to the <code>./width</code> even though both parameters address the same property but they do not have a string match.</p>
-<h6><a href="#typehint" name="typehint">@TypeHint</a></h6>
+<h6><a href="#typehint" id="typehint"><code>@TypeHint</code></a></h6>
<p>Parameters with the <code>@TypeHint</code> suffix may be used to force storing the named parameter in a property with the given type. The value of the <code>@TypeHint</code> parameter, if applied to a parameter for a property, is the JCR property type name. If the <code>@TypeHint</code> parameter is applied to a field upload parameter, the value is used to indicate the JCR primary node type for the node into which the uploaded file is stored.</p>
<p>If the <code>@TypeHint</code> value ends with <code>[]</code>, it indicates a multi-value property. A multi-value property is usually auto-detected if there are multiple values for the property (i.e. request parameter). But if only a single value is present in the request, the desired property type needs to be explicitly defined as multi-value by stating <code>@TypeHint=<type>[]</code>.</p>
<p>Example: The following form sets the numeric <code>width</code>, the boolean <code>checked</code>, and the multi-valued <code>hobbys</code> (with 3 values to enter) properties:</p>
@@ -329,11 +309,11 @@ of a resource without having to specify the path of each individual child resour
<input type="Submit" />
</form>
</code></pre>
-<p>In real applications you would need some JavaScript that allows to add/remove values, ie. add/remove inputs with the name "hobbys". Or a pure JavaScript based form post would be used, that gathers the properties to update programmatically, but the additional parameter <code>hobbys@TypeHint=String[]</code> would be the same.</p>
+<p>In real applications you would need some JavaScript that allows to add/remove values, ie. add/remove inputs with the name "hobbys". Or a pure JavaScript based form post would be used, that gathers the properties to update programmatically, but the additional parameter <code>hobbys@TypeHint=String[]</code> would be the same.</p>
<p>The <code>@TypeHint</code> suffixed parameter is assumed to be single-valued. If the parameter has multiple values, only the first is actually used.</p>
<p>For multi-value properties, see also the <code>@Patch</code> option.</p>
<p>For more information on applying <code>@TypeHint</code> to a file upload parameter see the section on File Uploads above.</p>
-<h6><a href="#defaultvalue" name="defaultvalue">@DefaultValue</a></h6>
+<h6><a href="#defaultvalue" id="defaultvalue"><code>@DefaultValue</code></a></h6>
<p>The <code>@DefaultValue</code> suffixed parameter may be provided to set a property to a default value should no value be provided in the actual parameters. Same as for normal parameters, the <code>@DefaultValue</code> parameter may have multiple values to create multi-valued properties.</p>
<p>Example: Set the <code>text</code> property to a default value if the user does not provide one:</p>
<pre><code><form method="POST" action="/content/page/first" enctype="multipart/form-data">
@@ -342,7 +322,7 @@ of a resource without having to specify the path of each individual child resour
<input type="Submit" />
</form>
</code></pre>
-<h6><a href="#usedefaultwhenmissing" name="usedefaultwhenmissing">@UseDefaultWhenMissing</a></h6>
+<h6><a href="#usedefaultwhenmissing" id="usedefaultwhenmissing"><code>@UseDefaultWhenMissing</code></a></h6>
<p>As described above, <code>@DefaultValue</code> only takes effect if no value is provided for a particular parameter. However, in some cases, such as HTML checkboxes, this isn't sufficient because the parameter isn't submitted at all. To handle this scenario, you can use the <code>@UseDefaultWhenMissing</code> suffixed parameter.</p>
<pre><code><form method="POST" action="/content/page/first" enctype="multipart/form-data">
<input name="queryIgnoreNoise" class="input" type="checkbox" value="true"/>
@@ -350,7 +330,7 @@ of a resource without having to specify the path of each individual child resour
<input type="hidden" name="queryIgnoreNoise@UseDefaultWhenMissing" value="true"/>
</form>
</code></pre>
-<h6><a href="#empty-values-ignoreblanks" name="empty-values-ignoreblanks">Empty Values / @IgnoreBlanks</a></h6>
+<h6><a href="#empty-values-ignoreblanks" id="empty-values-ignoreblanks"><code>Empty Values / @IgnoreBlanks</code></a></h6>
<p>Sometimes a form client will supply empty parameter values resulting in content being created or modified. For example submitting this form:</p>
<pre><code><form method="POST" action="/content/page/first" enctype="multipart/form-data">
<input type="hidden" name="stringProperty@TypeHint" value="String[]"/>
@@ -359,12 +339,12 @@ of a resource without having to specify the path of each individual child resour
<input type="text" name="stringProperty" value=""/>
</form>
</code></pre>
-<p>will result in multi-value String property being set to [ "foo", "bar", "" ]. Notice the blank value.</p>
+<p>will result in multi-value String property being set to [ "foo", "bar", "" ]. Notice the blank value.</p>
<p>To overcome this situation the <code>@IgnoreBlanks</code> suffix may be used to consider parameters with an empty string value to be ignored during processing. That is such parameter values would be treated as if they would not be supplied.</p>
<p>Adding</p>
<pre><code><input type="hidden" name="stringProperty@IgnoreBlanks" value="true"/>
</code></pre>
-<p>to the above forms will cause the multi-value property be set to the two-element value [ "foo", "bar" ] and to not modify the property at all in the second single-value example.</p>
+<p>to the above forms will cause the multi-value property be set to the two-element value [ "foo", "bar" ] and to not modify the property at all in the second single-value example.</p>
<p>However, single empty values are not set and always cause the property to be removed. Submitting this form without a value entered:</p>
<pre><code><form method="POST" action="/content/page/first" enctype="multipart/form-data">
<input type="hidden" name="stringProperty@TypeHint" value="String"/>
@@ -373,7 +353,7 @@ of a resource without having to specify the path of each individual child resour
</code></pre>
<p>will result in the single-value String property being removed / not set.</p>
<p>This is actually a bug in the Sling Post Servlet which has been there from the beginning and therefore can't be changed anymore as too many clients count on this behaviour. A solution for this will be provided in a future version. Please also note that the Sling Post Servlet from version 2.3.28 to 2.3.34 treat an empty value as an empty value. Therefore do not use these versions as you will get into trouble once you update to a newer version.</p>
-<h6><a href="#valuefrom" name="valuefrom">@ValueFrom</a></h6>
+<h6><a href="#valuefrom" id="valuefrom"><code>@ValueFrom</code></a></h6>
<p>In some situations, an HTML form with parameters may be reused to update content. But one or more form parameters may not comply with the names expected to be used for properties. In this case a parameter suffixed with <code>@ValueFrom</code> may be set containing the name of the parameter providing the actual data to be used.</p>
<p>Example: To set the property <code>text</code> from a form element <code>supplied_text</code>, you might use the following form:</p>
<pre><code><form method="POST" action="/content/page/first" enctype="multipart/form-data">
@@ -385,7 +365,7 @@ of a resource without having to specify the path of each individual child resour
<p>To prevent storing the additional parameters in the repository you might want to use the prefixing mechanism as shown in the example above, where the <code>@ValueFrom</code> parameter is prefixed and thus the <code>supplied_text</code> parameter is not used for property setting.</p>
<p>The <code>@ValueFrom</code> suffixed parameter is assumed to be single-valued. If the parameter has multiple values it is ignored completely.</p>
<p>The <code>@ValueFrom</code> suffixed parameter is also special in that there must not be a correlated parameter without a suffix. Thus have parameters <code>text</code> and <code>text@ValueFrom</code> may have unexpected results.</p>
-<h6><a href="#delete" name="delete">@Delete</a></h6>
+<h6><a href="#delete" id="delete"><code>@Delete</code></a></h6>
<p>Sometimes it may be required to not set a property to a specific value but to just remove it while processing the content update request. One such situation is a property filled from one or more checkboxes in an HTML form. If none of the checkboxes are checked, no parameter is actually submitted for these checkboxes. Hence the SlingPostServlet will not touch this property and effectively leave it untouched, while the natural reaction would have been to remove the property.</p>
<p>Here comes the <code>@Delete</code> suffixed parameter. This simply causes the indicated property be removed if it exists. If the property does not exist, nothing more happens. The actual value of the <code>@Delete</code> suffixed parameter does not care as long as the parameter is submitted.</p>
<p>Example: To ensure the <code>color</code> property is actually removed if no color has been selected, you might use the following form:</p>
@@ -400,7 +380,7 @@ of a resource without having to specify the path of each individual child resour
<p>The <code>@Delete</code> suffixed parameter is also special in that there need not be a correlated parameter without a suffix. If both -- a parameters <code>text</code> and <code>text@Delete</code> are set, the <code>text</code> property is first deleted and then filled with the new content.</p>
<p>The <code>@Delete</code> suffixed parameter in fact calls for a sub-operation, which is executed after the node addressed by the request URL is created (if needed) but before any other tasks of content creation and modification are done. Any item -- this may be a property or a node, actually -- addressed by the <code>@Delete</code> suffixed parameter is just removed if it exists. If the item does not exist, nothing happens.</p>
<p>If using both <code>@Delete</code> and <code>@MoveFrom</code> in the same request please see the note below on the <a href="#movefrom_delete_interaction">interaction between these instructions</a>.</p>
-<h6><a href="#movefrom" name="movefrom">@MoveFrom</a></h6>
+<h6><a href="#movefrom" id="movefrom"><code>@MoveFrom</code></a></h6>
<p>Now, that your bright and shiny content management application has great Flash-based file upload feature you will want to be able to use the pre-uploaded files for your content with the same request as when you upload other content. For example you might have a node storing some text and an illustration you uploaded as an image file.</p>
<p>To support this kind of functionality, the <code>@MoveFrom</code> suffixed parameter may be set to the repository path of the node to where you uploaded the image file.</p>
<p>Example: Your Flash-based file upload stored the file on the server at <code>/tmp/upload/123</code>. You now want to store this file along with a title and a text in a newly created node. The following form will be your friend:</p>
@@ -416,7 +396,7 @@ of a resource without having to specify the path of each individual child resour
<p>The <code>@MoveFrom</code> suffixed parameter is assumed to be single-valued. If the parameter has multiple values it is ignored completely.</p>
<p>The <code>@MoveFrom</code> suffixed parameter is also special in that there must not be a correlated parameter without a suffix. Thus have parameters <code>text</code> and <code>text@MoveFrom</code> may have unexpected results.</p>
<p>The <code>@MoveFrom</code> suffixed parameter in fact calls for a sub-operation, which is executed after the <code>@Delete</code> sub operation but before any other tasks of content creation and modification are done.</p>
-<a name="movefrom_delete_interaction"></a>
+<p><a name="movefrom_delete_interaction"></a></p>
<div class="note">
<b>Interaction between @MoveFrom and @Delete</b>
<p>
@@ -426,7 +406,7 @@ See <a href="https://issues.apache.org/jira/browse/SLING-8186">SLING-8186</a> an
<a href="https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/blob/3da37cc963fa1367d07eb1ed2d37cb3296d6b270/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/servlets/post/PostServletAtMoveTest.java#L209">corresponding integration test</a>. for more info.
</p>
</div>
-<h6><a href="#copyfrom" name="copyfrom">@CopyFrom</a></h6>
+<h6><a href="#copyfrom" id="copyfrom"><code>@CopyFrom</code></a></h6>
<p>Similar to the <code>@MoveFrom</code> suffix exists a <code>@CopyFrom</code> suffix. The latter works exactly the same as the former except that the item addressed by the parameter value is not moved but just copied.</p>
<p>Example: Your Flash-based file upload stored the file on the server at <code>/tmp/upload/123</code>. You now want to store this file along with a title and a text in a newly created node. The following form may be your friend:</p>
<pre><code><!-- trailing slash generates a name for the new node -->
@@ -441,9 +421,9 @@ See <a href="https://issues.apache.org/jira/browse/SLING-8186">SLING-8186</a> an
<p>The <code>@CopyFrom</code> suffixed parameter is assumed to be single-valued. If the parameter has multiple values it is ignored completely.</p>
<p>The <code>@CopyFrom</code> suffixed parameter is also special in that there must not be a correlated parameter without a suffix. Thus have parameters <code>text</code> and <code>text@CopyFrom</code> may have unexpected results.</p>
<p>The <code>@CopyFrom</code> suffixed parameter in fact calls for a sub-operation, which is executed after the <code>@MoveFrom</code> sub operation but before any other tasks of content creation and modification are done.</p>
-<h6><a href="#patch" name="patch">@Patch</a></h6>
+<h6><a href="#patch" id="patch"><code>@Patch</code></a></h6>
<p>When modifying multi-value properties, the <code>@Patch</code> suffix can be used to just add <code>+</code> or remove <code>-</code> individual values without overwriting the full array. This allows to change the array without knowing the current values.</p>
-<p>For example, imagine a multi-value string property that stores tags or keywords. To both add a tag "cool" and remove "boring" from the list:</p>
+<p>For example, imagine a multi-value string property that stores tags or keywords. To both add a tag "cool" and remove "boring" from the list:</p>
<pre><code><form method="POST" action="/content/page/first" enctype="multipart/form-data">
<input type="hidden" name="tags@TypeHint" value="String[]" />
<input type="hidden" name="tags@Patch" value="true" />
@@ -458,76 +438,52 @@ See <a href="https://issues.apache.org/jira/browse/SLING-8186">SLING-8186</a> an
<p>Operation <code>-</code> will remove all occurrences of <code><value></code> from the array.</p>
<p>The value of the <code>@Patch</code> suffixed parameter is irrelevant, it can be empty (example above uses <code>true</code> for clarity).</p>
<p>All types should be supported via <code>@TypeHint</code>, but it needs to indicate a multi-value property, ending with <code>[]</code>.</p>
-<h5><a href="#algorithm-for-node-name-creation" name="algorithm-for-node-name-creation">Algorithm for Node Name Creation</a></h5>
+<h5><a href="#algorithm-for-node-name-creation" id="algorithm-for-node-name-creation">Algorithm for Node Name Creation</a></h5>
<p>If request is posted with an URL ending in slash <code>/</code> or slash-star <code>/*</code>, the SlingPostServlet derives a name for the node to be created upon the request applying the following algorithm:</p>
<ol>
- <li>If a <code>:name</code> parameter is supplied, the (first) value of this parameter is used unmodified as the name for the new node. If the name is illegally formed with respect to JCR name requirements, an exception will be thrown when trying to create the node. The assumption with the <code>:name</code> parameter is, that the caller knows what he (or she) is supplying and should get the exact result if possible.</li>
- <li>Otherwise if a <code>:nameHint</code> parameter is supplied, the (first) value of this parameter is used to generate the node name. A name filtering is applied to this hint to ensure a valid JCR node name.</li>
- <li>Otherwise a series of request parameters supplied to set content is inspected for a possible name. The list of the names of these parameter is configurable with the SlingPostServlet and defaults to <code>title, jcr:title, name, description, jcr:description, abstract</code>. The first request parameter with a non-empty value is used and filtered to get the valid JCR name.</li>
- <li>Otherwise an ever increasing auto generated number is used. Filtering is also applied to this numeric name.</li>
+<li>If a <code>:name</code> parameter is supplied, the (first) value of this parameter is used unmodified as the name for the new node. If the name is illegally formed with respect to JCR name requirements, an exception will be thrown when trying to create the node. The assumption with the <code>:name</code> parameter is, that the caller knows what he (or she) is supplying and should get the exact result if possible.</li>
+<li>Otherwise if a <code>:nameHint</code> parameter is supplied, the (first) value of this parameter is used to generate the node name. A name filtering is applied to this hint to ensure a valid JCR node name.</li>
+<li>Otherwise a series of request parameters supplied to set content is inspected for a possible name. The list of the names of these parameter is configurable with the SlingPostServlet and defaults to <code>title, jcr:title, name, description, jcr:description, abstract</code>. The first request parameter with a non-empty value is used and filtered to get the valid JCR name.</li>
+<li>Otherwise an ever increasing auto generated number is used. Filtering is also applied to this numeric name.</li>
</ol>
<p>The filtering algorithm to create a valid name of the hints from above steps (except the first) works as follows:</p>
<ul>
- <li>Convert the proposed name to all lower case.</li>
- <li>Replace all characters not in the range [0..9a..z*] by a single underscore <code>_</code>.</li>
- <li>If the name starts with a digit prepend an underscore. Technically names with leading digits are valid, but they present major issues when using such names in JCR XPath expressions. The algorithm takes care to not create names with two or more consecutive underscore characters.</li>
- <li>Finally the name is cut to a configurable maximum length (default is 20 characters).</li>
+<li>Convert the proposed name to all lower case.</li>
+<li>Replace all characters not in the range [0..9a..z*] by a single underscore <code>_</code>.</li>
+<li>If the name starts with a digit prepend an underscore. Technically names with leading digits are valid, but they present major issues when using such names in JCR XPath expressions. The algorithm takes care to not create names with two or more consecutive underscore characters.</li>
+<li>Finally the name is cut to a configurable maximum length (default is 20 characters).</li>
</ul>
<p>For example the <code>:nameHint</code> value <em>A quick brown Fox ...</em> is filtered to become <em>a_quick_brown_fox_</em>.</p>
<p>After generating and filtering the name it is further guaranteed that the name is unique: If a node of the same name as just generated from the algorithm already exists below the same parent node a numeric index is appended to the new node name to make it unique.</p>
-<h5><a href="#response-status" name="response-status">Response Status</a></h5>
+<h5><a href="#response-status" id="response-status">Response Status</a></h5>
<p>The modification operation has the following status responses:</p>
<table>
- <thead>
- <tr>
- <th>Status </th>
- <th>Explanation </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200/OK </td>
- <td>An existing node has been updated with content </td>
- </tr>
- <tr>
- <td>201/CREATED </td>
- <td>A new node has been created and filled with content </td>
- </tr>
- <tr>
- <td>500/INTERNAL SERVER ERROR </td>
- <td>Some exception, for example a <code>RepositoryException</code>, occurred while processing the request </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Status </th><th> Explanation </th></tr>
+</thead>
+<tbody>
+<tr><td> 200/OK </td><td> An existing node has been updated with content </td></tr>
+<tr><td> 201/CREATED </td><td> A new node has been created and filled with content </td></tr>
+<tr><td> 500/INTERNAL SERVER ERROR </td><td> Some exception, for example a <code>RepositoryException</code>, occurred while processing the request </td></tr>
+</tbody>
</table>
-<h3><a href="#content-removal" name="content-removal">Content Removal</a></h3>
+<h3><a href="#content-removal" id="content-removal">Content Removal</a></h3>
<p>To remove existing content just address the item to be removed and set the <code>:operation</code> parameter to <code>delete</code>. For example the following command line removes the <code>/content/sample</code> page:</p>
<pre><code>$ curl -F":operation=delete" http://host/content/sample
</code></pre>
-<h5><a href="#response-status" name="response-status">Response Status</a></h5>
+<h5><a href="#response-status" id="response-status">Response Status</a></h5>
<p>The delete operation has the following status responses:</p>
<table>
- <thead>
- <tr>
- <th>Status </th>
- <th>Explanation </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200/OK </td>
- <td>The resource (and all its descendants) has been removed </td>
- </tr>
- <tr>
- <td>404/NOT FOUND </td>
- <td>The request URL does not address an existing repository item </td>
- </tr>
- <tr>
- <td>500/INTERNAL SERVER ERROR </td>
- <td>Some exception, for example a <code>RepositoryException</code>, occurred while processing the request </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Status </th><th> Explanation </th></tr>
+</thead>
+<tbody>
+<tr><td> 200/OK </td><td> The resource (and all its descendants) has been removed </td></tr>
+<tr><td> 404/NOT FOUND </td><td> The request URL does not address an existing repository item </td></tr>
+<tr><td> 500/INTERNAL SERVER ERROR </td><td> Some exception, for example a <code>RepositoryException</code>, occurred while processing the request </td></tr>
+</tbody>
</table>
-<h5><a href="#deleting-multiple-items" name="deleting-multiple-items">Deleting Multiple Items</a></h5>
+<h5><a href="#deleting-multiple-items" id="deleting-multiple-items">Deleting Multiple Items</a></h5>
<p>By using the <code>:applyTo</code> request parameter it is possible to remove multiple items in one single request. Deleting items in this way leaves you with less control, though. In addition, if a single item removal fails, no item at all is removed.</p>
<p>When specifying the item(s) to be removed with the <code>:applyTo</code> parameter, the request resource is left untouched (unless of course if listed in the <code>:applyTo</code> parameter) and only used to resolve any relative paths in the <code>:applyTo</code> parameter.</p>
<p>To remove the <code>/content/page1</code> and <code>/content/page2</code> nodes, for example, you might use the following command line:</p>
@@ -538,89 +494,47 @@ See <a href="https://issues.apache.org/jira/browse/SLING-8186">SLING-8186</a> an
<pre><code>$ curl -F":operation=delete" -F":applyTo=/content/*" http://host/content/sample
</code></pre>
<p>If any resource listed in the <code>:applyTo</code> parameter does not exist, it is silently ignored.</p>
-<h6><a href="#response-status" name="response-status">Response Status</a></h6>
+<h6><a href="#response-status" id="response-status">Response Status</a></h6>
<p>The delete operation applied to multiple resources has the following status responses:</p>
<table>
- <thead>
- <tr>
- <th>Status </th>
- <th>Explanation </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200/OK </td>
- <td>All requested and existing resources have been removed </td>
- </tr>
- <tr>
- <td>500/INTERNAL SERVER ERROR </td>
- <td>Some exception, for example a <code>RepositoryException</code>, occurred while processing the request </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Status </th><th> Explanation </th></tr>
+</thead>
+<tbody>
+<tr><td> 200/OK </td><td> All requested and existing resources have been removed </td></tr>
+<tr><td> 500/INTERNAL SERVER ERROR </td><td> Some exception, for example a <code>RepositoryException</code>, occurred while processing the request </td></tr>
+</tbody>
</table>
-<h3><a href="#copying-content" name="copying-content">Copying Content</a></h3>
+<h3><a href="#copying-content" id="copying-content">Copying Content</a></h3>
<p>To copy existing content to a new location, the <code>copy</code> operation is specified. This operation copies the item addressed by the request URL to a new location indicated by the <code>:dest</code> parameter. The <code>:dest</code> parameter is the absolute or relative path to which the resource is copied. If the path is relative it is assumed to be below the same parent as the request resource. If it is terminated with a <code>/</code> character the request resource is copied t [...]
<p>To illustrate the <code>:dest</code> parameter handling, lets look at a few examples. All examples are based on addressing the <code>/content/sample</code> item:</p>
<table>
- <thead>
- <tr>
- <th><code>:dest</code> Parameter </th>
- <th>Destination Absolute Path </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>/content/newSample</code> </td>
- <td><code>/content/newSample</code> </td>
- </tr>
- <tr>
- <td><code>different/newSample</code> </td>
- <td><code>/content/different/newSample</code> </td>
- </tr>
- <tr>
- <td><code>/content/different/</code> </td>
- <td><code>/content/different/sample</code> </td>
- </tr>
- <tr>
- <td><code>different/</code> </td>
- <td><code>/content/different/sample</code> </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> <code>:dest</code> Parameter </th><th> Destination Absolute Path </th></tr>
+</thead>
+<tbody>
+<tr><td> <code>/content/newSample</code> </td><td> <code>/content/newSample</code> </td></tr>
+<tr><td> <code>different/newSample</code> </td><td> <code>/content/different/newSample</code> </td></tr>
+<tr><td> <code>/content/different/</code> </td><td> <code>/content/different/sample</code> </td></tr>
+<tr><td> <code>different/</code> </td><td> <code>/content/different/sample</code> </td></tr>
+</tbody>
</table>
<p>If an item already exists at the location derived from the <code>:dest</code> parameter, the copy operation fails unless the <code>:replace</code> parameter is set to <code>true</code> (case is ignored when checking the parameter value).</p>
-<h5><a href="#response-status" name="response-status">Response Status</a></h5>
+<h5><a href="#response-status" id="response-status">Response Status</a></h5>
<p>The copy operation has the following status responses:</p>
<table>
- <thead>
- <tr>
- <th>Status </th>
- <th>Explanation </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200/OK </td>
- <td>The node has been copied to the new location replacing an existing item at the destination </td>
- </tr>
- <tr>
- <td>201/CREATED </td>
- <td>The node has been copied to the new location creating a new item at the destination </td>
- </tr>
- <tr>
- <td>404/NOT FOUND </td>
- <td>The request URL does not address an existing repository item </td>
- </tr>
- <tr>
- <td>412/PRECONDITION FAILED </td>
- <td>An item already exists at the destination and the <code>:replace</code> parameter is not set to <code>true</code> </td>
- </tr>
- <tr>
- <td>500/INTERNAL SERVER ERROR </td>
- <td>Some exception, for example a <code>RepositoryException</code>, occurred while processing the request </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Status </th><th> Explanation </th></tr>
+</thead>
+<tbody>
+<tr><td> 200/OK </td><td> The node has been copied to the new location replacing an existing item at the destination </td></tr>
+<tr><td> 201/CREATED </td><td> The node has been copied to the new location creating a new item at the destination </td></tr>
+<tr><td> 404/NOT FOUND </td><td> The request URL does not address an existing repository item </td></tr>
+<tr><td> 412/PRECONDITION FAILED </td><td> An item already exists at the destination and the <code>:replace</code> parameter is not set to <code>true</code> </td></tr>
+<tr><td> 500/INTERNAL SERVER ERROR </td><td> Some exception, for example a <code>RepositoryException</code>, occurred while processing the request </td></tr>
+</tbody>
</table>
-<h5><a href="#copying-multiple-items" name="copying-multiple-items">Copying Multiple Items</a></h5>
+<h5><a href="#copying-multiple-items" id="copying-multiple-items">Copying Multiple Items</a></h5>
<p>By using the <code>:applyTo</code> request parameter it is possible to copy multiple items in one single request. Copying items in this way leaves you with less control, though. In addition, if a single item copy fails, no item at all is copied.</p>
<p>When specifying the item(s) to be copied with the <code>:applyTo</code> parameter, the request resource is left untouched (unless of course if listed in the <code>:applyTo</code> parameter) and only used to resolve any relative paths in the <code>:applyTo</code> parameter.</p>
<p>To copy the <code>/content/page1</code> and <code>/content/page2</code> nodes to <code>/content/target</code>, for example, use:</p>
@@ -633,93 +547,48 @@ See <a href="https://issues.apache.org/jira/browse/SLING-8186">SLING-8186</a> an
http://host/content/sample
</code></pre>
<p>If any resource listed in the <code>:applyTo</code> parameter does not exist, it is silently ignored. Any item already existing at the copy destination whose name is the same as the name of an item to be copied is silently overwritten with the source item.</p>
-<h6><a href="#response-status" name="response-status">Response Status</a></h6>
+<h6><a href="#response-status" id="response-status">Response Status</a></h6>
<p>The copy operation applied to multiple resources has the following status responses:</p>
<table>
- <thead>
- <tr>
- <th>Status </th>
- <th>Explanation </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200/OK </td>
- <td>All requested and existing resources have been copied </td>
- </tr>
- <tr>
- <td>412/PRECONDITION FAILED </td>
- <td>The node indicated by the <code>:dest</code> parameter does not exist </td>
- </tr>
- <tr>
- <td>500/INTERNAL SERVER ERROR </td>
- <td>Some exception, for example a <code>RepositoryException</code>, occurred while processing the request. This status is also set if the <code>:dest</code> parameter value does not have a trailing slash character. </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Status </th><th> Explanation </th></tr>
+</thead>
+<tbody>
+<tr><td> 200/OK </td><td> All requested and existing resources have been copied </td></tr>
+<tr><td> 412/PRECONDITION FAILED </td><td> The node indicated by the <code>:dest</code> parameter does not exist </td></tr>
+<tr><td> 500/INTERNAL SERVER ERROR </td><td> Some exception, for example a <code>RepositoryException</code>, occurred while processing the request. This status is also set if the <code>:dest</code> parameter value does not have a trailing slash character. </td></tr>
+</tbody>
</table>
-<h3><a href="#moving-content" name="moving-content">Moving Content</a></h3>
+<h3><a href="#moving-content" id="moving-content">Moving Content</a></h3>
<p>To move existing content to a new location, the <code>move</code> operation is specified. This operation moves the item addressed by the request URL to a new location indicated by the <code>:dest</code> parameter. The <code>:dest</code> parameter is the absolute or relative path to which the resource is moved. If the path is relative it is assumed to be below the same parent as the request resource. If it is terminated with a <code>/</code> character the request resource is moved to a [...]
<p>To illustrate the <code>:dest</code> parameter handling, lets look at a few examples. All examples are based on addressing the <code>/content/sample</code> item:</p>
<table>
- <thead>
- <tr>
- <th><code>:dest</code> Parameter </th>
- <th>Destination Absolute Path </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>/content/newSample</code> </td>
- <td><code>/content/newSample</code> </td>
- </tr>
- <tr>
- <td><code>different/newSample</code> </td>
- <td><code>/content/different/newSample</code> </td>
- </tr>
- <tr>
- <td><code>/content/different/</code> </td>
- <td><code>/content/different/sample</code> </td>
- </tr>
- <tr>
- <td><code>different/</code> </td>
- <td><code>/content/different/sample</code> </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> <code>:dest</code> Parameter </th><th> Destination Absolute Path </th></tr>
+</thead>
+<tbody>
+<tr><td> <code>/content/newSample</code> </td><td> <code>/content/newSample</code> </td></tr>
+<tr><td> <code>different/newSample</code> </td><td> <code>/content/different/newSample</code> </td></tr>
+<tr><td> <code>/content/different/</code> </td><td> <code>/content/different/sample</code> </td></tr>
+<tr><td> <code>different/</code> </td><td> <code>/content/different/sample</code> </td></tr>
+</tbody>
</table>
<p>If an item already exists at the location derived from the <code>:dest</code> parameter, the move operation fails unless the <code>:replace</code> parameter is set to <code>true</code> (case is ignored when checking the parameter value).</p>
-<h5><a href="#response-status" name="response-status">Response Status</a></h5>
+<h5><a href="#response-status" id="response-status">Response Status</a></h5>
<p>The move operation has the following status responses:</p>
<table>
- <thead>
- <tr>
- <th>Status </th>
- <th>Explanation </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200/OK </td>
- <td>The node has been moved to the new location replacing an existing item at the destination </td>
- </tr>
- <tr>
- <td>201/CREATED </td>
- <td>The node has been moved to the new location creating a new item at the destination </td>
- </tr>
- <tr>
- <td>404/NOT FOUND </td>
- <td>The request URL does not address an existing repository item </td>
- </tr>
- <tr>
- <td>412/PRECONDITION FAILED </td>
- <td>An item already exists at the destination and the <code>:replace</code> parameter is not set to <code>true</code> </td>
- </tr>
- <tr>
- <td>500/INTERNAL SERVER ERROR </td>
- <td>Some exception, for example a <code>RepositoryException</code>, occurred while processing the request </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Status </th><th> Explanation </th></tr>
+</thead>
+<tbody>
+<tr><td> 200/OK </td><td> The node has been moved to the new location replacing an existing item at the destination </td></tr>
+<tr><td> 201/CREATED </td><td> The node has been moved to the new location creating a new item at the destination </td></tr>
+<tr><td> 404/NOT FOUND </td><td> The request URL does not address an existing repository item </td></tr>
+<tr><td> 412/PRECONDITION FAILED </td><td> An item already exists at the destination and the <code>:replace</code> parameter is not set to <code>true</code> </td></tr>
+<tr><td> 500/INTERNAL SERVER ERROR </td><td> Some exception, for example a <code>RepositoryException</code>, occurred while processing the request </td></tr>
+</tbody>
</table>
-<h5><a href="#moving-multiple-items" name="moving-multiple-items">Moving Multiple Items</a></h5>
+<h5><a href="#moving-multiple-items" id="moving-multiple-items">Moving Multiple Items</a></h5>
<p>By using the <code>:applyTo</code> request parameter it is possible to move multiple items in one single request. Moving items in this way leaves you with less control, though. In addition, if a single item move fails, no item at all is moved.</p>
<p>When specifying the item(s) to be moved with the <code>:applyTo</code> parameter, the request resource is left untouched (unless of course if listed in the <code>:applyTo</code> parameter) and only used to resolve any relative paths in the <code>:applyTo</code> parameter.</p>
<p>To for example move the <code>/content/page1</code> and <code>/content/page2</code> nodes to <code>/content/target</code>, you might use the following command line:</p>
@@ -732,96 +601,44 @@ See <a href="https://issues.apache.org/jira/browse/SLING-8186">SLING-8186</a> an
http://host/content/sample
</code></pre>
<p>If any resource listed in the <code>:applyTo</code> parameter does not exist, it is silently ignored. Any item already existing at the move destination whose name is the same as the name of an item to be moved is silently overwritten with the source item.</p>
-<h6><a href="#response-status" name="response-status">Response Status</a></h6>
+<h6><a href="#response-status" id="response-status">Response Status</a></h6>
<p>The move operation applied to multiple resources has the following status responses:</p>
<table>
- <thead>
- <tr>
- <th>Status </th>
- <th>Explanation </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200/OK </td>
- <td>All requested and existing resources have been moved </td>
- </tr>
- <tr>
- <td>412/PRECONDITION FAILED </td>
- <td>The node indicated by the <code>:dest</code> parameter does not exist </td>
- </tr>
- <tr>
- <td>500/INTERNAL SERVER ERROR </td>
- <td>Some exception, for example a <code>RepositoryException</code>, occurred while processing the request. This status is also set if the <code>:dest</code> parameter value does not have a trailing slash character. </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Status </th><th> Explanation </th></tr>
+</thead>
+<tbody>
+<tr><td> 200/OK </td><td> All requested and existing resources have been moved </td></tr>
+<tr><td> 412/PRECONDITION FAILED </td><td> The node indicated by the <code>:dest</code> parameter does not exist </td></tr>
+<tr><td> 500/INTERNAL SERVER ERROR </td><td> Some exception, for example a <code>RepositoryException</code>, occurred while processing the request. This status is also set if the <code>:dest</code> parameter value does not have a trailing slash character. </td></tr>
+</tbody>
</table>
-<h3><a href="#importing-content-structures" name="importing-content-structures">Importing Content Structures</a></h3>
-<p>To import content structures just address the parent item to import into and set the <code>:operation</code> parameter to <code>import</code>. </p>
+<h3><a href="#importing-content-structures" id="importing-content-structures">Importing Content Structures</a></h3>
+<p>To import content structures just address the parent item to import into and set the <code>:operation</code> parameter to <code>import</code>.</p>
<p>The optional name of the root node of the imported content may optionally be supplied using the <a href="#algorithm-for-node-name-creation">Algorithm for Node Name Creation</a>.</p>
<p>Other parameters for the import operation:</p>
<table>
- <thead>
- <tr>
- <th>Parameter </th>
- <th>Required </th>
- <th>Default value </th>
- <th>Description </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>:contentType</code> </td>
- <td><code>true</code> </td>
- <td> </td>
- <td>The <code>:contentType</code> value specifies the type of content being imported. Possible values are: xml, jcr.xml, json, jar, zip </td>
- </tr>
- <tr>
- <td><code>:content</code> </td>
- <td><code>false</code> </td>
- <td> </td>
- <td>The <code>:content</code> value specifies content string to import. The format of the import content is the same as is used by the jcr.contentloader bundle. This parameter is required if the :contentFile parameter is not supplied. </td>
- </tr>
- <tr>
- <td><code>:contentFile</code> </td>
- <td><code>false</code> </td>
- <td> </td>
- <td>The <code>:contentFile</code> value specifies a file uploaded for import. The format of the import content is the same as is used by the jcr.contentloader bundle. This parameter is required if the :content parameter is not supplied. </td>
- </tr>
- <tr>
- <td><code>:checkin</code> </td>
- <td><code>false</code> </td>
- <td>false </td>
- <td>The <code>:checkin</code> value specifies whether versionable nodes should be checked in during the import. </td>
- </tr>
- <tr>
- <td><code>:autoCheckout</code> </td>
- <td><code>false</code> </td>
- <td>false </td>
- <td>The <code>:autoCheckout</code> value specifies whether versionable nodes should be checked out when necessary during the import. </td>
- </tr>
- <tr>
- <td><code>:replace</code> </td>
- <td><code>false</code> </td>
- <td>false </td>
- <td>The <code>:replace</code> value specifies whether the import should replace any existing nodes at the same path. Note: When true, the existing nodes will be deleted and a new node is created in the same place. </td>
- </tr>
- <tr>
- <td><code>:replaceProperties</code> </td>
- <td><code>false</code> </td>
- <td>false </td>
- <td>The <code>:replaceProperties</code> value specifies whether the import should replace properties if they already exist. </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Parameter </th><th> Required </th><th> Default value </th><th> Description </th></tr>
+</thead>
+<tbody>
+<tr><td> <code>:contentType</code> </td><td> <code>true</code> </td><td> </td><td> The <code>:contentType</code> value specifies the type of content being imported. Possible values are: xml, jcr.xml, json, jar, zip </td></tr>
+<tr><td> <code>:content</code> </td><td> <code>false</code> </td><td> </td><td> The <code>:content</code> value specifies content string to import. The format of the import content is the same as is used by the jcr.contentloader bundle. This parameter is required if the :contentFile parameter is not supplied. </td></tr>
+<tr><td> <code>:contentFile</code> </td><td> <code>false</code> </td><td> </td><td> The <code>:contentFile</code> value specifies a file uploaded for import. The format of the import content is the same as is used by the jcr.contentloader bundle. This parameter is required if the :content parameter is not supplied. </td></tr>
+<tr><td> <code>:checkin</code> </td><td> <code>false</code> </td><td> false </td><td> The <code>:checkin</code> value specifies whether versionable nodes should be checked in during the import. </td></tr>
+<tr><td> <code>:autoCheckout</code> </td><td> <code>false</code> </td><td> false </td><td> The <code>:autoCheckout</code> value specifies whether versionable nodes should be checked out when necessary during the import. </td></tr>
+<tr><td> <code>:replace</code> </td><td> <code>false</code> </td><td> false </td><td> The <code>:replace</code> value specifies whether the import should replace any existing nodes at the same path. Note: When true, the existing nodes will be deleted and a new node is created in the same place. </td></tr>
+<tr><td> <code>:replaceProperties</code> </td><td> <code>false</code> </td><td> false </td><td> The <code>:replaceProperties</code> value specifies whether the import should replace properties if they already exist. </td></tr>
+</tbody>
</table>
<p>For example the following command line imports the <code>/content/sample</code> page:</p>
<pre><code>$ curl -F":operation=import" -F":contentType=json" -F":name=sample" \
- -F':content={ "jcr:primaryType": "nt:unstructured", "p1" : "p1Value", "child1" : { "childProp1" : true } }' \
+ -F':content={ "jcr:primaryType": "nt:unstructured", "p1" : "p1Value", "child1" : { "childProp1" : true } }' \
http://host/content
</code></pre>
<p>For example the following command line imports the <code>/content/sample</code> page without the optional name parameter:</p>
<pre><code>$ curl -F":operation=import" -F":contentType=json"
- -F':content={ "sample" : {"propOne" : "propOneValue", "childOne" : { "childPropOne" : true } } }' \
+ -F':content={ "sample" : {"propOne" : "propOneValue", "childOne" : { "childPropOne" : true } } }' \
http://host/content
</code></pre>
<p>For example the following form imports the <code>/content/sample</code> page:</p>
@@ -848,137 +665,96 @@ See <a href="https://issues.apache.org/jira/browse/SLING-8186">SLING-8186</a> an
<input type="Submit" />
</form>
</code></pre>
-<h6><a href="#response-status" name="response-status">Response Status</a></h6>
+<h6><a href="#response-status" id="response-status">Response Status</a></h6>
<p>The move operation applied to multiple resources has the following status responses:</p>
<table>
- <thead>
- <tr>
- <th>Status </th>
- <th>Explanation </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200/OK </td>
- <td>All requested content has been imported </td>
- </tr>
- <tr>
- <td>404/NOT FOUND </td>
- <td>The target parent node does not exist </td>
- </tr>
- <tr>
- <td>412/PRECONDITION FAILED </td>
- <td>One or more of the required parameters does not exist </td>
- </tr>
- <tr>
- <td>500/INTERNAL SERVER ERROR </td>
- <td>Some exception, for example a <code>RepositoryException</code>, occurred while processing the request. This status is also set if the ContentImporter service is missing. </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Status </th><th> Explanation </th></tr>
+</thead>
+<tbody>
+<tr><td> 200/OK </td><td> All requested content has been imported </td></tr>
+<tr><td> 404/NOT FOUND </td><td> The target parent node does not exist </td></tr>
+<tr><td> 412/PRECONDITION FAILED </td><td> One or more of the required parameters does not exist </td></tr>
+<tr><td> 500/INTERNAL SERVER ERROR </td><td> Some exception, for example a <code>RepositoryException</code>, occurred while processing the request. This status is also set if the ContentImporter service is missing. </td></tr>
+</tbody>
</table>
-<h3><a href="#null-operation" name="null-operation">Null Operation</a></h3>
+<h3><a href="#null-operation" id="null-operation">Null Operation</a></h3>
<p>Sometimes it is useful to explicitly request that nothing is to be done. The SlingPostServlet now provides such an operation under the name <code>nop</code>. Apart from doing nothing, the <code>nop</code> operations sets the response status to either the default <code>200/OK</code> or to any status requested by the <code>:nopstatus</code> request parameter.</p>
<p>The <code>:nopstatus</code> request parameter must be an integral number in the range [ 100 .. 999 ]. If the parameter value cannot be parsed to an integer or the value is outside of this range, the default status <code>200/OK</code> is still set.</p>
-<h6><a href="#response-status" name="response-status">Response Status</a></h6>
+<h6><a href="#response-status" id="response-status">Response Status</a></h6>
<p>The null operation sets a default status or the status requested by the <code>:nopstatus</code> request parameter.</p>
<table>
- <thead>
- <tr>
- <th>Status </th>
- <th>Explanation </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>200/OK </td>
- <td>Default status set if <code>:nopstatus</code> parameter is not set or does not have a valid value </td>
- </tr>
- <tr>
- <td>{:nopstatus} </td>
- <td>The status as requested by the <code>:nopstatus</code> parameter </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Status </th><th> Explanation </th></tr>
+</thead>
+<tbody>
+<tr><td> 200/OK </td><td> Default status set if <code>:nopstatus</code> parameter is not set or does not have a valid value </td></tr>
+<tr><td> {:nopstatus} </td><td> The status as requested by the <code>:nopstatus</code> parameter </td></tr>
+</tbody>
</table>
-<h2><a href="#special-parameters" name="special-parameters">Special Parameters</a></h2>
+<h2><a href="#special-parameters" id="special-parameters">Special Parameters</a></h2>
<p>Some parameters have special significance for the complete processing of the SlingPostServlet or are used by multiple operations. This section summarizes these parameters:</p>
-<h3><a href="#order" name="order">:order</a></h3>
+<h3><a href="#order" id="order"><code>:order</code></a></h3>
<p>Child nodes may be ordered if the primary node type of their common parent node is defined as having orderable child nodes. To employ such ordering, the content creation/modification, move and copy operations support the <code>:order</code> parameter which apply child node ordering amongst its siblings of the target node.</p>
<p>The <code>:order</code> parameter may have the following values:</p>
<table>
- <thead>
- <tr>
- <th>Value </th>
- <th>Description </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>first</code> </td>
- <td>Place the target node as the first amongst its siblings </td>
- </tr>
- <tr>
- <td><code>last</code> </td>
- <td>Place the target node as the last amongst its siblings </td>
- </tr>
- <tr>
- <td><code>before *xyz*</code> </td>
- <td>Place the target node immediately before the sibling whose name is <em>xyz</em> </td>
- </tr>
- <tr>
- <td><code>after *xyz*</code> </td>
- <td>Place the target node immediately after the sibling whose name is <em>xyz</em> </td>
- </tr>
- <tr>
- <td>numeric </td>
- <td>Place the target node at the indicated numeric place amongst its siblings where <em>0</em> is equivalent to <code>first</code> and <em>1</em> means the second place </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Value </th><th> Description </th></tr>
+</thead>
+<tbody>
+<tr><td> <code>first</code> </td><td> Place the target node as the first amongst its siblings </td></tr>
+<tr><td> <code>last</code> </td><td> Place the target node as the last amongst its siblings </td></tr>
+<tr><td> <code>before *xyz*</code> </td><td> Place the target node immediately before the sibling whose name is <em>xyz</em> </td></tr>
+<tr><td> <code>after *xyz*</code> </td><td> Place the target node immediately after the sibling whose name is <em>xyz</em> </td></tr>
+<tr><td> numeric </td><td> Place the target node at the indicated numeric place amongst its siblings where <em>0</em> is equivalent to <code>first</code> and <em>1</em> means the second place </td></tr>
+</tbody>
</table>
<p>Note that simple content reordering can be requested without applying any other operations. This is easiest done by placing a request to the resource to be reordered and just setting the <code>:order</code> parameter. For example to order the <code>/content/sample/page5</code> resource above its sibling resource <code>/content/sample/other</code> a simple request</p>
<pre><code>$ curl -F":order=before other" http://host/content/sample/page5
</code></pre>
<p>does the trick. To be redirected after the reodering, the <code>:redirect</code> parameter may optionally also be specified.</p>
-<h3><a href="#redirect" name="redirect">:redirect</a></h3>
+<h3><a href="#redirect" id="redirect"><code>:redirect</code></a></h3>
<p>Instructs the SlingPostServlet to redirect the client to the indicated location if the operation succeeds. That is the response status is set to <em>302/FOUND</em> and the <code>Location</code> header is set to the value of the <code>:redirect</code> parameter.</p>
-<h3><a href="#status" name="status">:status</a></h3>
+<h3><a href="#status" id="status"><code>:status</code></a></h3>
<p>By default the SlingPostServlet sets response status according to the status of the operation executed. In some cases, it may be desirable to not have the real status codes (e.g. 404 or 505) but a normal <em>200/OK</em> to trick the client browser into displaying the response content generated by the SlingPostServlet.</p>
<p>To not send the actual response status back to the client, the <code>:status</code> request parameter should be set to <code>browser</code>. If this parameter is not set, is empty, is set to <code>standard</code> or to any other value, the actual status code is sent back to the client.</p>
-<h2><a href="#response-format" name="response-format">Response format</a></h2>
+<h2><a href="#response-format" id="response-format">Response format</a></h2>
<p>The SlingPostServlet produces a basic HTTP response body, listing the response status, what changes have been made, and other meta-data about the result of the POST request.</p>
-<p>The format of this response is either HTML or JSON (JSON support introduced with <a href="https://issues.apache.org/jira/browse/SLING-1336">SLING-1336</a>). SlingPostServlet determines which format to use by examining the Accept header of the incoming request. If the client has specified a preference for the media type "application/json", the JSON format is used, otherwise HTML is returned. The Accept header can be overridden (and simulated) by posting a :http-equiv-accept field, whic [...]
+<p>The format of this response is either HTML or JSON (JSON support introduced with <a href="https://issues.apache.org/jira/browse/SLING-1336">SLING-1336</a>). SlingPostServlet determines which format to use by examining the Accept header of the incoming request. If the client has specified a preference for the media type "application/json", the JSON format is used, otherwise HTML is returned. The Accept header can be overridden (and simulated) by posting a :http-equiv-accept f [...]
<p>Examples:</p>
<ol>
- <li>Accept: text/html,application/xhtml+xml,application/xml;q=0.9,**/**;q=0.8</li>
- <li>Accept: application/json,**/**;q=0.9</li>
+<li>Accept: text/html,application/xhtml+xml,application/xml;q=0.9,<strong>/</strong>;q=0.8</li>
+<li>Accept: application/json,<strong>/</strong>;q=0.9</li>
</ol>
<p>In example #1, SlingPostServlet will return HTML, since the client has specified a preference for text/html. In example #2, SlingPostServlet will return JSON.</p>
<p>See <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">RFC 2616, section 14.1</a> for information on the HTTP Accept header.</p>
-<h2><a href="#versionable-node-support" name="versionable-node-support">Versionable Node Support</a></h2>
+<h2><a href="#versionable-node-support" id="versionable-node-support">Versionable Node Support</a></h2>
<p>The modify (default), delete, move, and copy operations of the SlingPostServlet support JCR Versionable Nodes. By default, when a node needs to be checked out for a modification to occur, it will be checked out and any nodes the operation checks out will be checked in upon completion of the request. Newly created versionable nodes (or non-versionable nodes made versionable by adding the mix:versionable mixin) will be left in their default, checked out state.</p>
<p>This default behavior can be modified either globally (i.e. for all requests) or on a per-request basis. The global behavior is changed through OSGi ConfigAdmin using these three properties of the PID <code>org.apache.sling.servlets.post.impl.SlingPostServlet</code>:</p>
<ul>
- <li><code>servlet.post.checkinNewVersionableNodes</code></li>
- <li><code>servlet.post.autoCheckout</code></li>
- <li><code>servlet.post.autoCheckin</code></li>
+<li><code>servlet.post.checkinNewVersionableNodes</code></li>
+<li><code>servlet.post.autoCheckout</code></li>
+<li><code>servlet.post.autoCheckin</code></li>
</ul>
-<p><img src="2010-07-01_1036.png" /></p>
+<p><img src="2010-07-01_1036.png" alt="" /></p>
<p>On a per-request basis, these request parameters can be used:</p>
<ul>
- <li><code>:checkinNewVersionableNodes</code></li>
- <li><code>:autoCheckout</code></li>
- <li><code>:autoCheckin</code></li>
+<li><code>:checkinNewVersionableNodes</code></li>
+<li><code>:autoCheckout</code></li>
+<li><code>:autoCheckin</code></li>
</ul>
<p>Checkout and Check In changes will be reflected in the ChangeLog portion of the response.</p>
-<h2><a href="#extending-the-slingpostservlet" name="extending-the-slingpostservlet">Extending the SlingPostServlet</a></h2>
-<h3><a href="#additional-post-operations" name="additional-post-operations">Additional POST operations</a></h3>
+<h2><a href="#extending-the-slingpostservlet" id="extending-the-slingpostservlet">Extending the SlingPostServlet</a></h2>
+<h3><a href="#additional-post-operations" id="additional-post-operations">Additional POST operations</a></h3>
<p>OSGi services of the <code>org.apache.sling.servlets.post.PostOperation</code> type can be used to implement new POST operations.</p>
<p>Such services must have a <code>sling.post.operation</code> service registration property set to the name of the operation. This name is used as the value of the <code>:operation</code> parameter of POST requests to select the extended operation.</p>
<p>Before version 2.1.2 of the <em>org.apache.sling.servlets.post</em> bundle, such additional operations were implemented by the <code>org.apache.sling.servlets.post.SlingPostOperation</code> interface, which is now deprecated but still supported via a bridge. See <a href="https://issues.apache.org/jira/browse/SLING-1725">SLING-1725</a> for details and discussions about this change.</p>
<p>Two examples (old and new style) of additional POST operations are found in the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-test-services/tree/master/src/main/java/org/apache/sling/launchpad/testservices/post">test-services</a> module, with the corresponding test code in the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/blob/master/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/servlets/post/CustomPostOpe [...]
-<h3><a href="#slingpostprocessor" name="slingpostprocessor">SlingPostProcessor</a></h3>
+<h3><a href="#slingpostprocessor" id="slingpostprocessor">SlingPostProcessor</a></h3>
<p>OSGi services of the <code>org.apache.sling.servlets.post.SlingPostOperation</code> type can be used to post process <code>PostOperation</code>s. They are called after the operation has performed its changes but before the changes are persisted (via commit). All registered SlingPostProcessors are always called in the reverse order of their service ranking (i.e. the one with the highest service ranking first).</p>
<p>A <code>SlingPostProcessor</code> may perform additional changes or revert previous ones. It is important that the <code>SlingPostProcessor</code> does not commit its changes but rather only performs the changes in the transient space (with the resource resolver bound to the current request) and in addition reports the changes through the 2nd parameter of the method <code>process(SlingHttpServletRequest, List<Modification>)</code>.</p>
-<p>Two examples of SlingPostProcessors are found in the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-test-services/tree/master/src/main/java/org/apache/sling/launchpad/testservices/post">test-services</a> module, with the corresponding test code in the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/blob/master/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/servlets/post/SlingPostProcessorTest.java">integration [...]
+<p>Two examples of SlingPostProcessors are found in the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-test-services/tree/master/src/main/java/org/apache/sling/launchpad/testservices/post">test-services</a> module, with the corresponding test code in the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/blob/master/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/servlets/post/SlingPostProcessorTest.java">integration [...]
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/metrics.html b/documentation/bundles/metrics.html
index 5dbd331..d5911b5 100644
--- a/documentation/bundles/metrics.html
+++ b/documentation/bundles/metrics.html
@@ -114,14 +114,14 @@
</li>
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
-<div class="row"><div><section><p>Sling Metrics bundle provides integration with <a href="http://metrics.dropwizard.io/">Dropwizard Metrics</a> library which provides a toolkit to capture runtime performance statistics in your application. </p>
-<h2><a href="#features" name="features">Features</a></h2>
+<div class="row"><div><section><p>Sling Metrics bundle provides integration with <a href="http://metrics.dropwizard.io/">Dropwizard Metrics</a> library which provides a toolkit to capture runtime performance statistics in your application.</p>
+<h2><a href="#features" id="features">Features</a></h2>
<ul>
- <li>Registers a <a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/MetricsService.java">MetricsService</a> which can be used to create various types of Metric instances</li>
- <li>WebConsole Plugin which provides a HTML Reporter for the various Metric instances</li>
- <li>Inventory Plugin which dumps the Metric state in plain text format</li>
+<li>Registers a <a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/MetricsService.java">MetricsService</a> which can be used to create various types of Metric instances</li>
+<li>WebConsole Plugin which provides a HTML Reporter for the various Metric instances</li>
+<li>Inventory Plugin which dumps the Metric state in plain text format</li>
</ul>
-<h2><a href="#basic-usage" name="basic-usage">Basic Usage</a></h2>
+<h2><a href="#basic-usage" id="basic-usage">Basic Usage</a></h2>
<pre><code><!-- TODO syntax marker (::java) disabled -->import org.apache.sling.metrics.Counter;
import org.apache.sling.metrics.MetricsService;
@@ -141,32 +141,32 @@ public void onSessionCreation(){
</code></pre>
<p>To make use of <code>MetricsService</code></p>
<ol>
- <li>Get a reference to <code>org.apache.sling.metrics.MetricsService</code></li>
- <li>Initialize the metric e.g. Counter in above case. This avoids any potential lookup cost in critical code paths</li>
- <li>Make use of metric instance to capture require stats</li>
+<li>Get a reference to <code>org.apache.sling.metrics.MetricsService</code></li>
+<li>Initialize the metric e.g. Counter in above case. This avoids any potential lookup cost in critical code paths</li>
+<li>Make use of metric instance to capture require stats</li>
</ol>
<p>Refer to <a href="https://dropwizard.github.io/metrics/3.1.0/getting-started/#counters">Metric Getting Started</a> guide to see how various types of Metric instances can be used. Note that when using Sling Commons Metrics bundle class names belong to <code>org.apache.sling.commons.metrics</code> package</p>
-<h2><a href="#best-practices" name="best-practices">Best Practices</a></h2>
+<h2><a href="#best-practices" id="best-practices">Best Practices</a></h2>
<ol>
- <li>Use descriptive names - Qualify the name with class/package name where the metric is being used</li>
- <li>Do not use the metrics for operation which take less than 1E-7s i.e. 1000 nano seconds otherwise timer overhead (Metrics makes use of System.nanoTime) would start affecting the performance.</li>
+<li>Use descriptive names - Qualify the name with class/package name where the metric is being used</li>
+<li>Do not use the metrics for operation which take less than 1E-7s i.e. 1000 nano seconds otherwise timer overhead (Metrics makes use of System.nanoTime) would start affecting the performance.</li>
</ol>
-<h2><a href="#api" name="api">API</a></h2>
-<p>Sling Metrics bundle provides its own Metric classes which are modelled on <a href="http://metrics.dropwizard.io/">Dropwizard Metrics</a> library. The metric interfaces defined by Sling bundle only provides methods related to data collection. </p>
+<h2><a href="#api" id="api">API</a></h2>
+<p>Sling Metrics bundle provides its own Metric classes which are modelled on <a href="http://metrics.dropwizard.io/">Dropwizard Metrics</a> library. The metric interfaces defined by Sling bundle only provides methods related to data collection.</p>
<ul>
- <li><a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Meter.java">org.apache.sling.commons.metrics.Meter</a> - Similar to <a href="https://dropwizard.github.io/metrics/3.1.0/manual/core/#meters">Dropwizard Meter</a></li>
- <li><a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Timer.java">org.apache.sling.commons.metrics.Timer</a> - Similar to <a href="https://dropwizard.github.io/metrics/3.1.0/manual/core/#timers">Dropwizard Timer</a></li>
- <li><a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Counter.java">org.apache.sling.commons.metrics.Counter</a> - Similar to <a href="https://dropwizard.github.io/metrics/3.1.0/manual/core/#counters">Dropwizard Counter</a></li>
- <li><a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Histogram.java">org.apache.sling.commons.metrics.Histogram</a> - Similar to <a href="https://dropwizard.github.io/metrics/3.1.0/manual/core/#histograms">Dropwizard Histogram</a></li>
+<li><a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Meter.java">org.apache.sling.commons.metrics.Meter</a> - Similar to <a href="https://dropwizard.github.io/metrics/3.1.0/manual/core/#meters">Dropwizard Meter</a></li>
+<li><a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Timer.java">org.apache.sling.commons.metrics.Timer</a> - Similar to <a href="https://dropwizard.github.io/metrics/3.1.0/manual/core/#timers">Dropwizard Timer</a></li>
+<li><a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Counter.java">org.apache.sling.commons.metrics.Counter</a> - Similar to <a href="https://dropwizard.github.io/metrics/3.1.0/manual/core/#counters">Dropwizard Counter</a></li>
+<li><a href="https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Histogram.java">org.apache.sling.commons.metrics.Histogram</a> - Similar to <a href="https://dropwizard.github.io/metrics/3.1.0/manual/core/#histograms">Dropwizard Histogram</a></li>
</ul>
<p>Further it provides a <code>MetricsService</code> which enables creation of different type of Metrics like Meter, Timer, Counter and Histogram.</p>
-<h3><a href="#requirement-of-wrapper-interfaces" name="requirement-of-wrapper-interfaces">Requirement of wrapper interfaces</a></h3>
+<h3><a href="#requirement-of-wrapper-interfaces" id="requirement-of-wrapper-interfaces">Requirement of wrapper interfaces</a></h3>
<ul>
- <li>Abstraction - Provides an abstraction around how metrics are collected and how they are reported and consumed. Most of the code would only be concerned with collecting interesting data. How it gets consumed or reported is implementation detail.</li>
- <li>Ability to turnoff stats collection - We can easily turn off data collection by switching to NOOP variant of <code>MetricsService</code> in case it starts adding appreciable overhead. Turning on and off can also be done on individual metric basis.</li>
+<li>Abstraction - Provides an abstraction around how metrics are collected and how they are reported and consumed. Most of the code would only be concerned with collecting interesting data. How it gets consumed or reported is implementation detail.</li>
+<li>Ability to turnoff stats collection - We can easily turn off data collection by switching to NOOP variant of <code>MetricsService</code> in case it starts adding appreciable overhead. Turning on and off can also be done on individual metric basis.</li>
</ul>
<p>It also allows us to later extend the type of data collected. For e.g. we can also collect <a href="https://jackrabbit.apache.org/api/2.6/org/apache/jackrabbit/api/stats/TimeSeries.html">TimerSeries</a> type of data for each metric without modifying the caller logic.</p>
-<h3><a href="#access-to-dropwizard-metrics-api" name="access-to-dropwizard-metrics-api">Access to Dropwizard Metrics API</a></h3>
+<h3><a href="#access-to-dropwizard-metrics-api" id="access-to-dropwizard-metrics-api">Access to Dropwizard Metrics API</a></h3>
<p>Sling Metrics bundle also registers the <code>MetricRegistry</code> instance with OSGi service registry. The instance registered has a service property <code>name</code> set to <code>sling</code> (so as allow distinguishing from any other registered <code>MetricRegistry</code> instance). It can be used to get direct access to Dropwizard Metric API if required.</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Reference(target = "(name=sling)")
private MetricRegistry registry;
@@ -177,11 +177,11 @@ private MetricRegistry registry;
Counter counter = metricService.counter("login");
com.codahale.metrics.Counter = counter.adaptTo(com.codahale.metrics.Counter.class)
</code></pre>
-<h2><a href="#webconsole-plugin" name="webconsole-plugin">WebConsole Plugin</a></h2>
-<p>A Web Console plugin is also provided which is accessible at http://localhost:8080/system/console/slingmetrics. It lists down all registered Metric instances and their state. </p>
+<h2><a href="#webconsole-plugin" id="webconsole-plugin">WebConsole Plugin</a></h2>
+<p>A Web Console plugin is also provided which is accessible at http://localhost:8080/system/console/slingmetrics. It lists down all registered Metric instances and their state.</p>
<p><img src="/documentation/bundles/metric-web-console.png" alt="Metric Plugin" /></p>
<p>The plugin lists all Metric instances from any <code>MetricRegistry</code> instance found in the OSGi service registry. If the <code>MetricRegistry</code> service has a <code>name</code> property defined then that would be prefixed to the Metric names from that registry. This allows use of same name in different registry instances.</p>
-<h2><a href="#installation" name="installation">Installation</a></h2>
+<h2><a href="#installation" id="installation">Installation</a></h2>
<p>Add following Maven dependency to your pom.xml:</p>
<pre><code><!-- TODO syntax marker (::xml) disabled --><dependency>
<groupId>org.apache.sling</groupId>
@@ -189,7 +189,8 @@ com.codahale.metrics.Counter = counter.adaptTo(com.codahale.metrics.Counter.clas
<version>1.0.0</version>
</dependency>
</code></pre>
-<p>Or download from <a href="http://sling.apache.org/downloads.cgi">here</a></p></section></div></div>
+<p>Or download from <a href="http://sling.apache.org/downloads.cgi">here</a></p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/mime-type-support-commons-mime.html b/documentation/bundles/mime-type-support-commons-mime.html
index eaeb0aa..a626f8b 100644
--- a/documentation/bundles/mime-type-support-commons-mime.html
+++ b/documentation/bundles/mime-type-support-commons-mime.html
@@ -117,67 +117,67 @@
<div class="row"><div><section><p>Support for MIME type mappings is generally a problematic issue. On the one hand applications have to take care to stay up to date with their mappings on the other hands in web applications it is tedious to maintain the mappings. Apache Sling takes a very user and deployment friendly approadch to this problem which is described in detail on this page.</p>
<p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h2><a href="#servlet-api-support" name="servlet-api-support">Servlet API Support</a></h2>
+<h2><a href="#servlet-api-support" id="servlet-api-support">Servlet API Support</a></h2>
<p>The Servlet API specification provides a limited support for MIME type mappings :</p>
<ul>
- <li>Mappings may be defined in the <code>mime-mapping</code> elements of the the web application descriptor <code>web.xml</code>. Managing these mappings is presumably tedious. So servlet containers may provide reasonable defaults (or not).</li>
- <li>The <code>ServletContext.getMimeType(String)</code> returns a MIME type for a given file name based on the extension of the filename. The mapping returned is based on the servlet container configuration as well as the web application descriptor's <code>mime-mapping</code> elements.</li>
+<li>Mappings may be defined in the <code>mime-mapping</code> elements of the the web application descriptor <code>web.xml</code>. Managing these mappings is presumably tedious. So servlet containers may provide reasonable defaults (or not).</li>
+<li>The <code>ServletContext.getMimeType(String)</code> returns a MIME type for a given file name based on the extension of the filename. The mapping returned is based on the servlet container configuration as well as the web application descriptor's <code>mime-mapping</code> elements.</li>
</ul>
-<h2><a href="#the-sling-mimetypeservice" name="the-sling-mimetypeservice">The Sling MimeTypeService</a></h2>
+<h2><a href="#the-sling-mimetypeservice" id="the-sling-mimetypeservice">The Sling MimeTypeService</a></h2>
<p>Already at the start of the Sling project we realized, that just basing the MIME type mapping decisions on the servlet container will not yield acceptable results. For this reason the Apache Sling projects provides a spezialized and configurable service supporting such mappings: The <a href="/apidocs/sling6/org/apache/sling/commons/mime/MimeTypeService.html"><code>MimeTypeService</code></a> provided by the <code>org.apache.sling.commons.mime</code> bundle.</p>
<p>This service provides access to registered MIME types and their mappings with two methods:</p>
<ul>
- <li><code>getExtension(String)</code> -- given a MIME type this methods returns a primary extension. For example for the type <code>text/plain</code> this method will return <code>txt</code></li>
- <li><code>getMimeType(String)</code> -- given a file name or just the extension) returns the mapped MIME type. For example for the filename <code>sample.html</code> (or just the extension <code>html</code>) this method will return <code>text/html</code></li>
+<li><code>getExtension(String)</code> -- given a MIME type this methods returns a primary extension. For example for the type <code>text/plain</code> this method will return <code>txt</code></li>
+<li><code>getMimeType(String)</code> -- given a file name or just the extension) returns the mapped MIME type. For example for the filename <code>sample.html</code> (or just the extension <code>html</code>) this method will return <code>text/html</code></li>
</ul>
<p>Two more methods allow to programmatically add MIME type mappings:</p>
<ul>
- <li><code>registerMimeType(InputStream)</code> registers additional mappings from the given input stream which is expected to be formated in traditional <code>mime.types</code> file format (see below).</li>
- <li><code>registerMimeType(String, String...)</code> registers a single mapping for the give MIME type and the respective extensions.</li>
+<li><code>registerMimeType(InputStream)</code> registers additional mappings from the given input stream which is expected to be formated in traditional <code>mime.types</code> file format (see below).</li>
+<li><code>registerMimeType(String, String...)</code> registers a single mapping for the give MIME type and the respective extensions.</li>
</ul>
-<h2><a href="#the-sling-contentawaremimetypeservice" name="the-sling-contentawaremimetypeservice">The Sling ContentAwareMimeTypeService</a></h2>
+<h2><a href="#the-sling-contentawaremimetypeservice" id="the-sling-contentawaremimetypeservice">The Sling ContentAwareMimeTypeService</a></h2>
<p>For content-based mime type detection (as opposed to filename-based detection), the <code>org.apache.sling.commons.contentdetection</code> bundle provides the <code>ContentAwareMimeTypeService</code>, which takes an <code>InputStream</code> that's analyzed to detect its mime type, using Apache Tika by default:</p>
<ul>
- <li><code>getMimeType(String filename, InputStream content)</code> -- given a filename and an <code>InputStream</code> that points to the file contents, this method first tries content-based detection using the stream, and falls back to filename-based detection if needed.</li>
+<li><code>getMimeType(String filename, InputStream content)</code> -- given a filename and an <code>InputStream</code> that points to the file contents, this method first tries content-based detection using the stream, and falls back to filename-based detection if needed.</li>
</ul>
-<h2><a href="#and-more-" name="and-more-">And More...</a></h2>
+<h2><a href="#and-more" id="and-more">And More...</a></h2>
<p>Besides the <code>MimeTypeService</code> provided by Apache Sling, there is actually more:</p>
<ul>
- <li>The <a href="/apidocs/sling6/org/apache/sling/api/SlingHttpServletRequest.html"><code>SlingHttpServletRequest</code></a> provides the <code>getResponseContentType()</code> method, which returns the preferred <em>Content-Type</em> for the response based on the requests extension. This method is implemented by Apache Sling using the <code>MimeTypeService</code>. So servlets and scripts may just call this method to set the content type of the response to the desired value.</li>
- <li>Each Servlet (and JSP scripts) is initialized by Apache Sling with a <code>ServletContext</code> instance whose implementation of the <code>getMimeType(String)</code> effectively calls the <code>MimeTypeService.getMimeType(String)</code> method.</li>
- <li>The Scripting support infrastructure of Sling sets the response content type on behalf of the script to the default value as returned by the <code>SlingHttpServletRequest.getResponseContentType()</code> method. At the same time the response character set is also set to <code>UTF-8</code> for <em>text</em> content types.</li>
+<li>The <a href="/apidocs/sling6/org/apache/sling/api/SlingHttpServletRequest.html"><code>SlingHttpServletRequest</code></a> provides the <code>getResponseContentType()</code> method, which returns the preferred <em>Content-Type</em> for the response based on the requests extension. This method is implemented by Apache Sling using the <code>MimeTypeService</code>. So servlets and scripts may just call this method to set the content type of the response to the desired value.</li>
+<li>Each Servlet (and JSP scripts) is initialized by Apache Sling with a <code>ServletContext</code> instance whose implementation of the <code>getMimeType(String)</code> effectively calls the <code>MimeTypeService.getMimeType(String)</code> method.</li>
+<li>The Scripting support infrastructure of Sling sets the response content type on behalf of the script to the default value as returned by the <code>SlingHttpServletRequest.getResponseContentType()</code> method. At the same time the response character set is also set to <code>UTF-8</code> for <em>text</em> content types.</li>
</ul>
-<h2><a href="#configuring-mime-type-mappings" name="configuring-mime-type-mappings">Configuring MIME Type Mappings</a></h2>
+<h2><a href="#configuring-mime-type-mappings" id="configuring-mime-type-mappings">Configuring MIME Type Mappings</a></h2>
<p>The implementation of the <code>MimeTypeService</code> in the Apache Sling MIME type mapping support (<code>org.apache.sling.commons.mime</code>) bundle supports a numnber of ways to configure and extend the set of MIME type mappings:</p>
<ul>
- <li>Default configuration. The default configuration is based on the <a href="http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types"><code>mime.types</code></a> file maintained by Roy Fielding for the Apache httpd project and some extensions by Apache Sling.</li>
- <li>Bundle provided mappings. Bundles registered in the OSGi framework may contain MIME type mappings files <code>META-INF/mime.types</code> which are loaded automatically by the Apache Sling MIME type mapping support bundle.</li>
- <li>Configuration. Mappings may be supplied by configuration of the <code>MimeTypeService</code> implementation as the multi-value string property <code>mime.types</code>. Each value of the property corresponds to a line in a MIME type configuration file (see below for the format).</li>
- <li>Registered Mappings. Mappings may be registered with the <code>MimeTypeService.registerMapping</code> methods.</li>
- <li><a href="/apidocs/sling6/org/apache/sling/commons/mime/MimeTypeProvider.html"><code>MimeTypeProvider</code></a>. Additional mappings may be provided by service implementing the <code>MimeTypeProvider</code> interface. The <code>MimeTypeService</code> implementation will call these services in turn until a service returns a mapping provided there is no static configuration to responde to the mapping request.</li>
+<li>Default configuration. The default configuration is based on the <a href="http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types"><code>mime.types</code></a> file maintained by Roy Fielding for the Apache httpd project and some extensions by Apache Sling.</li>
+<li>Bundle provided mappings. Bundles registered in the OSGi framework may contain MIME type mappings files <code>META-INF/mime.types</code> which are loaded automatically by the Apache Sling MIME type mapping support bundle.</li>
+<li>Configuration. Mappings may be supplied by configuration of the <code>MimeTypeService</code> implementation as the multi-value string property <code>mime.types</code>. Each value of the property corresponds to a line in a MIME type configuration file (see below for the format).</li>
+<li>Registered Mappings. Mappings may be registered with the <code>MimeTypeService.registerMapping</code> methods.</li>
+<li><a href="/apidocs/sling6/org/apache/sling/commons/mime/MimeTypeProvider.html"><code>MimeTypeProvider</code></a>. Additional mappings may be provided by service implementing the <code>MimeTypeProvider</code> interface. The <code>MimeTypeService</code> implementation will call these services in turn until a service returns a mapping provided there is no static configuration to responde to the mapping request.</li>
</ul>
<p>Please note, that existing mappings cannot be overwritten later. Thus mappings have an inherent priority:</p>
<ol>
- <li>Mappings provided by the Apache httpd project's <code>mime.types</code> file</li>
- <li>Extensions by the Apache Sling MIME type mapping support bundle</li>
- <li>Bundles providing a <code>META-INF/mime.types</code> file in the order of their bundle-id (or startup order if started after the MIME type mapping support bundle)</li>
- <li>OSGi Configuration. Note that bundles started <em>after</em> the MIME type mapping support bundle may not overwrite mappings provided by the OSGi configuration. This may sounds like a problem, but in reality this should genrally not matter</li>
- <li>Mappings registered calling the <code>MimeTypeService.registerMimeType</code> method</li>
- <li>Mappings provided by <code>MimeTypeProvider</code> services</li>
+<li>Mappings provided by the Apache httpd project's <code>mime.types</code> file</li>
+<li>Extensions by the Apache Sling MIME type mapping support bundle</li>
+<li>Bundles providing a <code>META-INF/mime.types</code> file in the order of their bundle-id (or startup order if started after the MIME type mapping support bundle)</li>
+<li>OSGi Configuration. Note that bundles started <em>after</em> the MIME type mapping support bundle may not overwrite mappings provided by the OSGi configuration. This may sounds like a problem, but in reality this should genrally not matter</li>
+<li>Mappings registered calling the <code>MimeTypeService.registerMimeType</code> method</li>
+<li>Mappings provided by <code>MimeTypeProvider</code> services</li>
</ol>
-<h2><a href="#mime-type-mapping-file-format" name="mime-type-mapping-file-format">MIME Type Mapping File Format</a></h2>
+<h2><a href="#mime-type-mapping-file-format" id="mime-type-mapping-file-format">MIME Type Mapping File Format</a></h2>
<p>The file format for MIME type mapping files is rather simple:</p>
<ul>
- <li>The files are assumed to be encoded with the <em>ISO-8859-1</em> (aka Latin 1) character encoding</li>
- <li>The files consist of lines defining mappings where each line is terminated with either or both of a carriage return (CR, 0x0c) and line feed character (LF, 0x0a). There is no line continuation support *-la shell scripts or Java properties files.
-</li>
- <li>Empty lines and lines starting with a hash sign (<code>#</code>) are ignored</li>
- <li>Data lines consist of space (any whitespace matching the <code>\s</code> regular expression) separated values. The first value is the MIME type name and the remaining values defining mappings to file name extensions. The first listed file name extension is considered the <em>default mapping</em> and is returned by the <code>MimeTypeService.getExtension(String)</code> method. Entry lines consisting of just a mime type but no extensions are also (currently) ignored.</li>
+<li>The files are assumed to be encoded with the <em>ISO-8859-1</em> (aka Latin 1) character encoding</li>
+<li>The files consist of lines defining mappings where each line is terminated with either or both of a carriage return (CR, 0x0c) and line feed character (LF, 0x0a). There is no line continuation support *-la shell scripts or Java properties files.</li>
+<li>Empty lines and lines starting with a hash sign (<code>#</code>) are ignored</li>
+<li>Data lines consist of space (any whitespace matching the <code>\s</code> regular expression) separated values. The first value is the MIME type name and the remaining values defining mappings to file name extensions. The first listed file name extension is considered the <em>default mapping</em> and is returned by the <code>MimeTypeService.getExtension(String)</code> method. Entry lines consisting of just a mime type but no extensions are also (currently) ignored.</li>
</ul>
<p>THe data line format described here also applies to configuration provided by the values of the <code>mime.types</code> property of the MIME type service configuration. The file format description applies to all <code>META-INF/mime.types</code> files provided by the bundles as well as input streams supplied to the <code>MimeTypeService.registerMimeType(InputStream)</code> method.</p>
-<h2><a href="#web-console-plugin" name="web-console-plugin">Web Console Plugin</a></h2>
+<h2><a href="#web-console-plugin" id="web-console-plugin">Web Console Plugin</a></h2>
<p>The Apache Sling MIME type mapping support bundle implements a plugin for the Apache Felix Web Console which may be consulted to investigate the current contents of the MIME type mapping tables.</p>
-<p><img src="/documentation/bundles/mimetypes.png" alt="Mime Types Web Console Plugin" /></p></section></div></div>
+<p><img src="/documentation/bundles/mimetypes.png" alt="Mime Types Web Console Plugin" /></p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/models.html b/documentation/bundles/models.html
index b7a7faf..95fd637 100644
--- a/documentation/bundles/models.html
+++ b/documentation/bundles/models.html
@@ -117,18 +117,18 @@
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
<p>Many Sling projects want to be able to create model objects - POJOs which are automatically mapped from Sling objects, typically resources, but also request objects. Sometimes these POJOs need OSGi services as well.</p>
-<h1><a href="#design-goals" name="design-goals">Design Goals</a></h1>
+<h1><a href="#design-goals" id="design-goals">Design Goals</a></h1>
<ul>
- <li>Entirely annotation driven. "Pure" POJOs.</li>
- <li>Use standard annotations where possible.</li>
- <li>Pluggable</li>
- <li>OOTB, support resource properties (via ValueMap), SlingBindings, OSGi services, request attributes</li>
- <li>Adapt multiple objects - minimal required Resource and SlingHttpServletRequest</li>
- <li>Client doesn't know/care that these objects are different than any other adapter factory</li>
- <li>Support both classes and interfaces.</li>
- <li>Work with existing Sling infrastructure (i.e. not require changes to other bundles).</li>
+<li>Entirely annotation driven. "Pure" POJOs.</li>
+<li>Use standard annotations where possible.</li>
+<li>Pluggable</li>
+<li>OOTB, support resource properties (via ValueMap), SlingBindings, OSGi services, request attributes</li>
+<li>Adapt multiple objects - minimal required Resource and SlingHttpServletRequest</li>
+<li>Client doesn't know/care that these objects are different than any other adapter factory</li>
+<li>Support both classes and interfaces.</li>
+<li>Work with existing Sling infrastructure (i.e. not require changes to other bundles).</li>
</ul>
-<h1><a href="#basic-usage" name="basic-usage">Basic Usage</a></h1>
+<h1><a href="#basic-usage" id="basic-usage">Basic Usage</a></h1>
<p>In the simplest case, the class is annotated with <code>@Model</code> and the adaptable class. Fields which need to be injected are annotated with <code>@Inject</code>:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=Resource.class)
public class MyModel {
@@ -137,11 +137,11 @@ public class MyModel {
private String propertyName;
}
</code></pre>
-<p>In this case, a property named "propertyName" will be looked up from the Resource (after first adapting it to a <code>ValueMap</code>) and it is injected.</p>
+<p>In this case, a property named "propertyName" will be looked up from the Resource (after first adapting it to a <code>ValueMap</code>) and it is injected.</p>
<p>For an interface, it is similar:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=Resource.class)
public interface MyModel {
-
+
@Inject
String getPropertyName();
}
@@ -169,8 +169,8 @@ public class MyModel {
</code></pre>
<p>Alternatively it is possible to list all classes individually that are Sling Models classes via the <code>Sling-Model-Classes</code> header.</p>
<p>If you use the Sling Models bnd plugin all required bundle headers are generated automatically at build time (see chapter 'Registration of Sling Models classes via bnd plugin' below).</p>
-<h1><a href="#client-code" name="client-code">Client Code</a></h1>
-<h2><a href="#adaptto-" name="adaptto-">adaptTo()</a></h2>
+<h1><a href="#client-code" id="client-code">Client Code</a></h1>
+<h2><a href="#adaptto" id="adaptto">adaptTo()</a></h2>
<p>Client code doesn't need to be aware that Sling Models is being used. It just uses the Sling Adapter framework:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->MyModel model = resource.adaptTo(MyModel.class)
</code></pre>
@@ -178,11 +178,11 @@ public class MyModel {
<pre><code><!-- TODO syntax marker (::jsp) disabled --><sling:adaptTo adaptable="${resource}" adaptTo="org.apache.sling.models.it.models.MyModel" var="model"/>
</code></pre>
<p>Or</p>
-<pre><code><!-- TODO syntax marker (::jsp) disabled -->${sling:adaptTo(resource, 'org.apache.sling.models.it.models.MyModel')}
+<pre><code><!-- TODO syntax marker (::jsp) disabled -->${sling:adaptTo(resource, 'org.apache.sling.models.it.models.MyModel')}
</code></pre>
<p>As with other AdapterFactories, if the adaptation can't be made for any reason, <code>adaptTo()</code> returns null.</p>
-<h2><a href="#modelfactory-since-1-2-0-" name="modelfactory-since-1-2-0-">ModelFactory (since 1.2.0)</a></h2>
-<p><em>See also <a href="https://issues.apache.org/jira/browse/SLING-3709">SLING-3709</a></em></p>
+<h2><a href="#modelfactory-since-120" id="modelfactory-since-120">ModelFactory (since 1.2.0)</a></h2>
+<p><em>See also <a href="https://issues.apache.org/jira/browse/SLING-3709">SLING-3709</a></em></p>
<p>Since Sling Models 1.2.0 there is another way of instantiating models. The OSGi service <code>ModelFactory</code> provides a method for instantiating a model that throws exceptions. This is not allowed by the Javadoc contract of the adaptTo method. That way <code>null</code> checks are not necessary and it is easier to see why instantiation of the model failed.</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->try {
MyModel model = modelFactory.createModel(object, MyModel.class);
@@ -193,23 +193,23 @@ public class MyModel {
}
</code></pre>
<p>In addition <code>ModelFactory</code> provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable.</p>
-<h2><a href="#usage-in-htl" name="usage-in-htl">Usage in HTL</a></h2>
+<h2><a href="#usage-in-htl" id="usage-in-htl">Usage in HTL</a></h2>
<p><a href="../scripting/scripting-htl.html#sling-models-use-provider">Sling Models Use Provider</a> (internally uses the <code>ModelFactory</code> from above).</p>
-<h1><a href="#other-options" name="other-options">Other Options</a></h1>
-<h2><a href="#names" name="names">Names</a></h2>
+<h1><a href="#other-options" id="other-options">Other Options</a></h1>
+<h2><a href="#names" id="names">Names</a></h2>
<p>If the field or method name doesn't exactly match the property name, <code>@Named</code> can be used:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=Resource.class)
public class MyModel {
-
+
@Inject @Named("secondPropertyName")
private String otherName;
}
</code></pre>
-<h2><a href="#optional-and-required" name="optional-and-required">Optional and Required</a></h2>
+<h2><a href="#optional-and-required" id="optional-and-required">Optional and Required</a></h2>
<p><code>@Inject</code>ed fields/methods are assumed to be required. To mark them as optional, use <code>@Optional</code>:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=Resource.class)
public class MyModel {
-
+
@Inject @Optional
private String otherName;
}
@@ -224,11 +224,11 @@ public class MyModel {
</code></pre>
<p>To still mark some fields/methods as being mandatory while relying on <code>defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL</code> for all other fields, the annotation <code>@Required</code> can be used.</p>
<p><code>@Optional</code> annotations are only evaluated when using the <code>defaultInjectionStrategy = DefaultInjectionStrategy.REQUIRED</code> (which is the default), <code>@Required</code> annotations only if using <code>defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL</code>.</p>
-<h2><a href="#defaults" name="defaults">Defaults</a></h2>
+<h2><a href="#defaults" id="defaults">Defaults</a></h2>
<p>A default value can be provided (for Strings & primitives):</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=Resource.class)
public class MyModel {
-
+
@Inject @Default(values="defaultValue")
private String name;
}
@@ -236,7 +236,7 @@ public class MyModel {
<p>Defaults can also be arrays:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=Resource.class)
public class MyModel {
-
+
@Inject @Default(intValues={1,2,3,4})
private int[] integers;
}
@@ -244,17 +244,17 @@ public class MyModel {
<p>OSGi services can be injected:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=Resource.class)
public class MyModel {
-
+
@Inject
private ResourceResolverFactory resourceResolverFactory;
}
</code></pre>
<p>In this case, the name is not used -- only the class name.</p>
-<h2><a href="#collections" name="collections">Collections</a></h2>
+<h2><a href="#collections" id="collections">Collections</a></h2>
<p>Lists and arrays are supported by some injectors. For the details look at the table given in <a href="#available-injectors">Available Injectors</a>:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=Resource.class)
public class MyModel {
-
+
@Inject
private List<Servlet> servlets;
}
@@ -277,35 +277,35 @@ public class MyModel {
+- address2
</code></pre>
<p>In this case, the <code>addresses</code> <code>List</code> will contain <code>address1</code> and <code>address2</code>.</p>
-<h2><a href="#osgi-service-filters" name="osgi-service-filters">OSGi Service Filters</a></h2>
+<h2><a href="#osgi-service-filters" id="osgi-service-filters">OSGi Service Filters</a></h2>
<p>OSGi injection can be filtered:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=SlingHttpServletRequest.class)
public class MyModel {
-
+
@Inject
private PrintWriter out;
-
+
@Inject
@Named("log")
private Logger logger;
-
+
@Inject
@Filter("(paths=/bin/something)")
private List<Servlet> servlets;
}
</code></pre>
-<h2><a href="#postconstruct-methods" name="postconstruct-methods">PostConstruct Methods</a></h2>
+<h2><a href="#postconstruct-methods" id="postconstruct-methods">PostConstruct Methods</a></h2>
<p>The <code>@PostConstruct</code> annotation can be used to add methods which are invoked upon completion of all injections:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=SlingHttpServletRequest.class)
public class MyModel {
-
+
@Inject
private PrintWriter out;
-
+
@Inject
@Named("log")
private Logger logger;
-
+
@PostConstruct
protected void sayHello() {
logger.info("hello");
@@ -314,11 +314,11 @@ public class MyModel {
</code></pre>
<p><code>@PostConstruct</code> methods in a super class will be invoked first. If a <code>@PostConstruct</code> method exists in a subclass with the same name as in the parent class, only the subclass method will be invoked. This is the case regardless of the scope of either method.</p>
<p>Since Sling Models Implementation 1.4.6, <code>@PostConstruct</code> methods may return a <code>false</code> boolean value in which case the model creation will fail without logging any exception (a message will be logged at the <code>DEBUG</code> level).</p>
-<h2><a href="#via" name="via">Via</a></h2>
+<h2><a href="#via" id="via">Via</a></h2>
<p>In some cases, a different object should be used as the adaptable instead of the original adaptable. This can be done using the <code>@Via</code> annotation. By default, this can be done using a JavaBean property of the adaptable:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=SlingHttpServletRequest.class)
public interface MyModel {
-
+
// will return request.getResource().getValueMap().get("propertyName", String.class)
@Inject @Via("resource")
String getPropertyName();
@@ -328,35 +328,35 @@ public interface MyModel {
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=Resource.class)
public interface MyModel {
- // will return resource.getChild("jcr:content").getValueMap().get("propertyName", String.class)
+ // will return resource.getChild("jcr:content").getValueMap().get("propertyName", String.class)
@Inject @Via(value = "jcr:content", type = ChildResource.class)
String getPropertyName();
}
</code></pre>
<p>See the <a href="#via-types-since-api-134implementation-140">Via Types</a> section below for details on the included types for <code>@Via</code>.</p>
-<h2><a href="#source" name="source">Source</a></h2>
+<h2><a href="#source" id="source">Source</a></h2>
<p>If there is ambiguity where a given injection could be handled by more than one injector, the <code>@Source</code> annotation can be used to define which injector is responsible:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=SlingHttpServletRequest.class)
public interface MyModel {
-
+
// Ensure that "resource" is retrived from the bindings, not a request attribute
@Inject @Source("script-bindings")
Resource getResource();
}
</code></pre>
-<h2><a href="#adaptations" name="adaptations">Adaptations</a></h2>
+<h2><a href="#adaptations" id="adaptations">Adaptations</a></h2>
<p>If the injected object does not match the desired type and the object implements the <code>Adaptable</code> interface, Sling Models will try to adapt it. This provides the ability to create rich object graphs. For example:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptables=Resource.class)
public interface MyModel {
-
+
@Inject
ImageModel getImage();
}
@Model(adaptables=Resource.class)
public interface ImageModel {
-
+
@Inject
String getPath();
}
@@ -377,242 +377,82 @@ public class MyModel {
}
</code></pre>
<p>Note: storing the original adaptable (request/resource) in a field is discouraged. Please see the note about <a href="#caching-self-reference-note">caching and self references</a> below.</p>
-<h2><a href="#sling-validation-since-1-2-0-" name="sling-validation-since-1-2-0-">Sling Validation (since 1.2.0)</a></h2>
-<a name="validation" />
-<p><em>See also <a href="https://issues.apache.org/jira/browse/SLING-4161">SLING-4161</a></em></p>
+<h2><a href="#sling-validation-since-120" id="sling-validation-since-120">Sling Validation (since 1.2.0)</a></h2>
+<p><a name="validation" /> <em>See also <a href="https://issues.apache.org/jira/browse/SLING-4161">SLING-4161</a></em></p>
<p>You can use the attribute <code>validation</code> on the Model annotation to call a validation service on the resource being used by the Sling model. That attribute supports three different values:</p>
<table>
- <thead>
- <tr>
- <th>Value </th>
- <th>Description </th>
- <th>Invalid validation model </th>
- <th>No validation model found </th>
- <th>Resource invalid according to model</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>DISABLED</code> (default) </td>
- <td>don't validate the resource bound to the Model </td>
- <td>Model instantiated </td>
- <td>Model instantiated </td>
- <td>Model instantiated</td>
- </tr>
- <tr>
- <td><code>REQUIRED</code> </td>
- <td>enforce validation of the resource bound to the Model </td>
- <td>Model not instantiated </td>
- <td>Model not instantiated </td>
- <td>Model not instantiated</td>
- </tr>
- <tr>
- <td><code>OPTIONAL</code> </td>
- <td>validate the resource bound to the Model (if a validation model is found) </td>
- <td>Model not instantiated </td>
- <td>Model instantiated </td>
- <td>Model not instantiated</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Value </th><th> Description </th><th> Invalid validation model </th><th> No validation model found </th><th> Resource invalid according to model</th></tr>
+</thead>
+<tbody>
+<tr><td><code>DISABLED</code> (default) </td><td> don't validate the resource bound to the Model </td><td> Model instantiated </td><td> Model instantiated </td><td> Model instantiated</td></tr>
+<tr><td><code>REQUIRED</code> </td><td> enforce validation of the resource bound to the Model </td><td> Model not instantiated </td><td> Model not instantiated </td><td> Model not instantiated</td></tr>
+<tr><td><code>OPTIONAL</code> </td><td> validate the resource bound to the Model (if a validation model is found) </td><td> Model not instantiated </td><td> Model instantiated </td><td> Model not instantiated</td></tr>
+</tbody>
</table>
<p>In case the model is not instantiated an appropriate error message is logged (if <code>adaptTo()</code> is used) or an appropriate exception is thrown (if <code>ModelFactory.createModel()</code> is used).</p>
<p>The only implementation for this Sling Models validation service is leveraging <a href="/documentation/bundles/validation.html">Sling Validation</a> and is located in the bundle <a href="https://github.com/apache/sling-org-apache-sling-models-validation-impl">org.apache.sling.models.validation-impl</a>. Validation is only working on models which are adapted from either <code>Resource</code> or <code>SlingHttpServletRequest</code> and if the Sling Validation Bundle is deployed.</p>
-<h1><a href="#custom-injectors" name="custom-injectors">Custom Injectors</a></h1>
+<h1><a href="#custom-injectors" id="custom-injectors">Custom Injectors</a></h1>
<p>To create a custom injector, simply implement the <code>org.apache.sling.models.spi.Injector</code> interface and register your implementation with the OSGi service registry. Please refer to the <a href="https://github.com/apache/sling-org-apache-sling-models-impl/tree/master/src/main/java/org/apache/sling/models/impl/injectors">standard injectors in Git</a> for examples.</p>
<p>Injectors are invoked in order of their service ranking, from lowest to highest. See the table below for the rankings of the standard injectors.</p>
-<h1><a href="#annotation-reference" name="annotation-reference">Annotation Reference</a></h1>
-<p><code>@Model</code> : declares a model class or interface</p>
-<p><code>@Inject</code> : marks a field or method as injectable</p>
-<p><code>@Named</code> : declare a name for the injection (otherwise, defaults based on field or method name).</p>
-<p><code>@Optional</code> : marks a field or method injection as optional</p>
-<p><code>@Source</code> : explictly tie an injected field or method to a particular injector (by name). Can also be on other annotations.</p>
-<p><code>@Filter</code> : an OSGi service filter</p>
-<p><code>@PostConstruct</code> : methods to call upon model option creation (only for model classes)</p>
-<p><code>@Via</code> : change the adaptable as the source of the injection</p>
-<p><code>@Default</code> : set default values for a field or method</p>
-<p><code>@Path</code> : only used together with the resource-path injector to specify the path of a resource</p>
-<p><code>@Exporters</code>/<code>@Exporter</code>/<code>@ExporterOptions</code>/<code>@ExporterOption</code> : See Exporter Framework section below</p>
+<h1><a href="#annotation-reference" id="annotation-reference">Annotation Reference</a></h1>
+<p><code>@Model</code> : declares a model class or interface</p>
+<p><code>@Inject</code> : marks a field or method as injectable</p>
+<p><code>@Named</code> : declare a name for the injection (otherwise, defaults based on field or method name).</p>
+<p><code>@Optional</code> : marks a field or method injection as optional</p>
+<p><code>@Source</code> : explictly tie an injected field or method to a particular injector (by name). Can also be on other annotations.</p>
+<p><code>@Filter</code> : an OSGi service filter</p>
+<p><code>@PostConstruct</code> : methods to call upon model option creation (only for model classes)</p>
+<p><code>@Via</code> : change the adaptable as the source of the injection</p>
+<p><code>@Default</code> : set default values for a field or method</p>
+<p><code>@Path</code> : only used together with the resource-path injector to specify the path of a resource</p>
+<p><code>@Exporters</code>/<code>@Exporter</code>/<code>@ExporterOptions</code>/<code>@ExporterOption</code> : See Exporter Framework section below</p>
<p>In addition all <a href="#injector-specific-annotations">injector-specific annotations</a>.</p>
-<h1><a href="#available-injectors" name="available-injectors">Available Injectors</a></h1>
+<h1><a href="#available-injectors" id="available-injectors">Available Injectors</a></h1>
<table>
- <thead>
- <tr>
- <th>Title </th>
- <th>Name (for <code>@Source</code>) </th>
- <th>Service Ranking </th>
- <th>Available Since (Implementation Version) </th>
- <th>Description </th>
- <th>Applicable To (including using <code>@Via</code>) </th>
- <th>Accepts Null Name? </th>
- <th>Array Support </th>
- <th>Parameterized Type Support</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>Script Bindings </td>
- <td><code>script-bindings</code> </td>
- <td>1000 </td>
- <td>1.0.0 </td>
- <td>Lookup objects in the script bindings object by name. </td>
- <td>A ServletRequest object which has the <code>Sling Bindings</code> attribute defined </td>
- <td>no </td>
- <td>no conversion is done </td>
- <td>If a parameterized type is passed, the bindings value must be of a compatible type of the parameterized type.</td>
- </tr>
- <tr>
- <td>Value Map </td>
- <td><code>valuemap</code> </td>
- <td>2000 </td>
- <td>1.0.0 </td>
- <td>Gets a property from a <code>ValueMap</code> by name. </td>
- <td>Any object which is or can be adapted to a <code>ValueMap</code></td>
- <td>no </td>
- <td>Primitive arrays wrapped/unwrapped as necessary. Wrapper object arrays are unwrapped/wrapped as necessary. </td>
- <td>Parameterized <code>List</code> and <code>Collection</code> injection points are injected by getting an array of the component type and creating an unmodifiable <code>List</code> from the array.</td>
- </tr>
- <tr>
- <td>Child Resources </td>
- <td><code>child-resources</code> </td>
- <td>3000 </td>
- <td>1.0.0 </td>
- <td>Gets a child resource by name. </td>
- <td><code>Resource</code> objects </td>
- <td>no </td>
- <td>none </td>
- <td>if a parameterized type <code>List</code> or <code>Collection</code> is passed, a <code>List<Resource></code> is returned (the contents of which may be adapted to the target type) filled with all child resources of the resource looked up by the given name.</td>
- </tr>
- <tr>
- <td>Request Attributes </td>
- <td><code>request-attributes</code> </td>
- <td>4000 </td>
- <td>1.0.0 </td>
- <td>Get a request attribute by name. </td>
- <td><code>ServletRequest</code> objects </td>
- <td>no </td>
- <td>no conversion is done </td>
- <td>If a parameterized type is passed, the request attribute must be of a compatible type of the parameterized type.</td>
- </tr>
- <tr>
- <td>OSGi Services </td>
- <td><code>osgi-services</code> </td>
- <td>5000 </td>
- <td>1.0.0 </td>
- <td>Lookup services based on class name. Since Sling Models Impl 1.2.8 (<a href="https://issues.apache.org/jira/browse/SLING-5664">SLING-5664</a>) the service with the highest service ranking is returned. In case multiple services are returned, they are ordered descending by their service ranking (i.e. the one with the highest ranking first). </td>
- <td>Any object </td>
- <td>yes </td>
- <td>yes </td>
- <td>Parameterized <code>List</code> and <code>Collection</code> injection points are injected by getting an array of the services and creating an unmodifiable <code>List</code> from the array.</td>
- </tr>
- <tr>
- <td>Resource Path </td>
- <td><code>resource-path</code> </td>
- <td>2500 </td>
- <td>1.1.0 </td>
- <td>Injects one or multiple resources. The resource paths are either given by <code>@Path</code> annotations, the element <code>path</code> or <code>paths</code> of the annotation <code>@ResourcePath</code> or by paths given through a resource property being referenced by either <code>@Named</code> or element <code>name</code> of the annotation <code>@ResourcePath</code>. </td>
- <td><code>Resource</code> or <code>SlingHttpServletRequest</code> objects </td>
- <td>yes </td>
- <td>yes </td>
- <td>none</td>
- </tr>
- <tr>
- <td>Self </td>
- <td><code>self</code> </td>
- <td><code>Integer.MAX_VALUE</code> </td>
- <td>1.1.0 </td>
- <td>Injects the adaptable object itself (if the class of the field matches or is a supertype). If the @Self annotation is present it is tried to adapt the adaptable to the field type. </td>
- <td>Any object </td>
- <td>yes </td>
- <td>none </td>
- <td>none</td>
- </tr>
- <tr>
- <td>Sling Object </td>
- <td><code>sling-object</code> </td>
- <td><code>Integer.MAX_VALUE</code> </td>
- <td>1.1.0 </td>
- <td>Injects commonly used sling objects if the field matches with the class: request, response, resource resolver, current resource, SlingScriptHelper. This works only if the adaptable can get the according information, i.e. all objects are available via <code>SlingHttpServletRequest</code> while <code>ResourceResolver</code> can only resolve the <code>ResourceResolver</code> object and nothing else. A discussion around this limitation can be found at <a href="https://issues.apache [...]
- <td><code>Resource</code>, <code>ResourceResolver</code> or <code>SlingHttpServletRequest</code> objects (not all objects can be resolved by all adaptables). </td>
- <td>yes </td>
- <td>none </td>
- <td>none</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Title </th><th> Name (for <code>@Source</code>) </th><th> Service Ranking </th><th> Available Since (Implementation Version) </th><th> Description </th><th> Applicable To (including using <code>@Via</code>) </th><th> Accepts Null Name? </th><th> Array Support </th><th> Parameterized Type Support</th></tr>
+</thead>
+<tbody>
+<tr><td>Script Bindings </td><td> <code>script-bindings</code> </td><td> 1000 </td><td> 1.0.0 </td><td> Lookup objects in the script bindings object by name. </td><td> A ServletRequest object which has the <code>Sling Bindings</code> attribute defined </td><td> no </td><td> no conversion is done </td><td> If a parameterized type is passed, the bindings value must be of a compatible type of the parameterized type.</td></tr>
+<tr><td>Value Map </td><td> <code>valuemap</code> </td><td> 2000 </td><td> 1.0.0 </td><td> Gets a property from a <code>ValueMap</code> by name. </td><td> Any object which is or can be adapted to a <code>ValueMap</code></td><td> no </td><td> Primitive arrays wrapped/unwrapped as necessary. Wrapper object arrays are unwrapped/wrapped as necessary. </td><td> Parameterized <code>List</code> and <code>Collection</code> i [...]
+<tr><td>Child Resources </td><td> <code>child-resources</code> </td><td> 3000 </td><td> 1.0.0 </td><td> Gets a child resource by name. </td><td> <code>Resource</code> objects </td><td> no </td><td> none </td><td> if a parameterized type <code>List</code> or <code>Collection</code> is passed, a <code>List<Resource></code> is returned (the contents of which may be adapted to the target type) filled with all child resources of [...]
+<tr><td>Request Attributes </td><td> <code>request-attributes</code> </td><td> 4000 </td><td> 1.0.0 </td><td> Get a request attribute by name. </td><td> <code>ServletRequest</code> objects </td><td> no </td><td> no conversion is done </td><td> If a parameterized type is passed, the request attribute must be of a compatible type of the parameterized type.</td></tr>
+<tr><td>OSGi Services </td><td> <code>osgi-services</code> </td><td> 5000 </td><td> 1.0.0 </td><td> Lookup services based on class name. Since Sling Models Impl 1.2.8 (<a href="https://issues.apache.org/jira/browse/SLING-5664">SLING-5664</a>) the service with the highest service ranking is returned. In case multiple services are returned, they are ordered descending by their service ranking (i.e. the one with the highest rank [...]
+<tr><td>Resource Path </td><td> <code>resource-path</code> </td><td> 2500 </td><td> 1.1.0 </td><td> Injects one or multiple resources. The resource paths are either given by <code>@Path</code> annotations, the element <code>path</code> or <code>paths</code> of the annotation <code>@ResourcePath</code> or by paths given through a resource property being referenced by either <code>@Named</code> or element <code>name</code> of t [...]
+<tr><td>Self </td><td> <code>self</code> </td><td> <code>Integer.MAX_VALUE</code> </td><td> 1.1.0 </td><td> Injects the adaptable object itself (if the class of the field matches or is a supertype). If the @Self annotation is present it is tried to adapt the adaptable to the field type. </td><td> Any object </td><td> yes </td><td> none </td><td> none</td></tr>
+<tr><td>Sling Object </td><td> <code>sling-object</code> </td><td> <code>Integer.MAX_VALUE</code> </td><td> 1.1.0 </td><td> Injects commonly used sling objects if the field matches with the class: request, response, resource resolver, current resource, SlingScriptHelper. This works only if the adaptable can get the according information, i.e. all objects are available via <code>SlingHttpServletRequest</code> while <code>ResourceResolver</ [...]
+</tbody>
</table>
-<h1><a href="#injector-specific-annotations" name="injector-specific-annotations">Injector-specific Annotations</a></h1>
+<h1><a href="#injector-specific-annotations" id="injector-specific-annotations">Injector-specific Annotations</a></h1>
<p><em>Introduced with <a href="https://issues.apache.org/jira/browse/SLING-3499">SLING-3499</a> in Sling Models Impl 1.0.6</em></p>
<p>Sometimes it is desirable to use customized annotations which aggregate the standard annotations described above. This will generally have the following advantages over using the standard annotations:</p>
<ul>
- <li>Less code to write (only one annotation is necessary in most of the cases)</li>
- <li>More robust (in case of name collisions among the different injectors, you make sure that the right injector is used)</li>
- <li>Better IDE support (because the annotations provide elements for each configuration which is available for that specific injector, i.e. <code>filter</code> only for OSGi services)</li>
+<li>Less code to write (only one annotation is necessary in most of the cases)</li>
+<li>More robust (in case of name collisions among the different injectors, you make sure that the right injector is used)</li>
+<li>Better IDE support (because the annotations provide elements for each configuration which is available for that specific injector, i.e. <code>filter</code> only for OSGi services)</li>
</ul>
<p>The follow annotations are provided which are tied to specific injectors:</p>
<table>
- <thead>
- <tr>
- <th>Annotation </th>
- <th>Supported Optional Elements </th>
- <th>Injector </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>@ScriptVariable</code> </td>
- <td><code>injectionStrategy</code> and <code>name</code> </td>
- <td><code>script-bindings</code> </td>
- <td>Injects the script variable defined via <a href="https://cwiki.apache.org/confluence/display/SLING/Scripting+variables">Sling Bindings</a>. If <code>name</code> is not set the name is derived from the method/field name.</td>
- </tr>
- <tr>
- <td><code>@ValueMapValue</code> </td>
- <td><code>injectionStrategy</code>, <code>name</code> and <code>via</code> </td>
- <td><code>valuemap</code> </td>
- <td>Injects a <code>ValueMap</code> value. If <code>via</code> is not set, it will automatically take <code>resource</code> if the adaptable is the <code>SlingHttpServletRequest</code>. If <code>name</code> is not set the name is derived from the method/field name.</td>
- </tr>
- <tr>
- <td><code>@ChildResource</code> </td>
- <td><code>injectionStrategy</code>, <code>name</code> and <code>via</code> </td>
- <td><code>child-resources</code> </td>
- <td>Injects a child resource by name. If <code>via</code> is not set, it will automatically take <code>resource</code> if the adaptable is the <code>SlingHttpServletRequest</code>. If <code>name</code> is not set the name is derived from the method/field name.</td>
- </tr>
- <tr>
- <td><code>@RequestAttribute</code> </td>
- <td><code>injectionStrategy</code>, <code>name</code> and <code>via</code> </td>
- <td><code>request-attributes</code> </td>
- <td>Injects a request attribute by name. If <code>name</code> is not set the name is derived from the method/field name.</td>
- </tr>
- <tr>
- <td><code>@ResourcePath</code> </td>
- <td><code>injectionStrategy</code>, <code>path</code>, and <code>name</code> </td>
- <td><code>resource-path</code> </td>
- <td>Injects a resource either by path or by reading a property with the given name.</td>
- </tr>
- <tr>
- <td><code>@OSGiService</code> </td>
- <td><code>injectionStrategy</code>, <code>filter</code> </td>
- <td><code>osgi-services</code> </td>
- <td>Injects an OSGi service by type. The <code>filter</code> can be used give an OSGi service filter.</td>
- </tr>
- <tr>
- <td><code>@Self</code> </td>
- <td><code>injectionStrategy</code> </td>
- <td><code>self</code> </td>
- <td>Injects the adaptable itself. If the field type does not match with the adaptable it is tried to adapt the adaptable to the requested type.</td>
- </tr>
- <tr>
- <td><code>@SlingObject</code> </td>
- <td><code>injectionStrategy</code> </td>
- <td><code>sling-object</code> </td>
- <td>Injects commonly used sling objects if the field matches with the class: request, response, resource resolver, current resource, SlingScriptHelper</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Annotation </th><th> Supported Optional Elements </th><th> Injector </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>@ScriptVariable</code> </td><td> <code>injectionStrategy</code> and <code>name</code> </td><td> <code>script-bindings</code> </td><td> Injects the script variable defined via <a href="https://cwiki.apache.org/confluence/display/SLING/Scripting+variables">Sling Bindings</a>. If <code>name</code> is not set the name is derived from the method/field name.</td></tr>
+<tr><td><code>@ValueMapValue</code> </td><td> <code>injectionStrategy</code>, <code>name</code> and <code>via</code> </td><td> <code>valuemap</code> </td><td> Injects a <code>ValueMap</code> value. If <code>via</code> is not set, it will automatically take <code>resource</code> if the adaptable is the <code>SlingHttpServletRequest</code>. If <code>name</code> is not set the name is derived from the method/field name.</td></tr>
+<tr><td><code>@ChildResource</code> </td><td> <code>injectionStrategy</code>, <code>name</code> and <code>via</code> </td><td> <code>child-resources</code> </td><td> Injects a child resource by name. If <code>via</code> is not set, it will automatically take <code>resource</code> if the adaptable is the <code>SlingHttpServletRequest</code>. If <code>name</code> is not set the name is derived from the method/field name.</td></tr>
+<tr><td><code>@RequestAttribute</code> </td><td> <code>injectionStrategy</code>, <code>name</code> and <code>via</code> </td><td> <code>request-attributes</code> </td><td> Injects a request attribute by name. If <code>name</code> is not set the name is derived from the method/field name.</td></tr>
+<tr><td><code>@ResourcePath</code> </td><td> <code>injectionStrategy</code>, <code>path</code>, and <code>name</code> </td><td> <code>resource-path</code> </td><td> Injects a resource either by path or by reading a property with the given name.</td></tr>
+<tr><td><code>@OSGiService</code> </td><td> <code>injectionStrategy</code>, <code>filter</code> </td><td> <code>osgi-services</code> </td><td> Injects an OSGi service by type. The <code>filter</code> can be used give an OSGi service filter.</td></tr>
+<tr><td><code>@Self</code> </td><td> <code>injectionStrategy</code> </td><td> <code>self</code> </td><td> Injects the adaptable itself. If the field type does not match with the adaptable it is tried to adapt the adaptable to the requested type.</td></tr>
+<tr><td><code>@SlingObject</code> </td><td> <code>injectionStrategy</code> </td><td> <code>sling-object</code> </td><td>Injects commonly used sling objects if the field matches with the class: request, response, resource resolver, current resource, SlingScriptHelper</td></tr>
+</tbody>
</table>
-<h2><a href="#hints" name="hints">Hints</a></h2>
+<h2><a href="#hints" id="hints">Hints</a></h2>
<p>Those annotations replace <code>@Via</code>, <code>@Filter</code>, <code>@Named</code>, <code>@Optional</code>, <code>@Required</code>, <code>@Source</code> and <code>@Inject</code>. Instead of using the deprecated annotation element <code>optional</code> you should rather use <code>injectionStrategy</code> with the values <code>DEFAULT</code>, <code>OPTIONAL</code> or <code>REQUIRED</code> (see also <a href="https://issues.apache.org/jira/browse/SLING-4155">SLING-4155</a>). <code>@De [...]
-<h2><a href="#custom-annotations" name="custom-annotations">Custom Annotations</a></h2>
+<h2><a href="#custom-annotations" id="custom-annotations">Custom Annotations</a></h2>
<p>To create a custom annotation, implement the <code>org.apache.sling.models.spi.injectorspecific.StaticInjectAnnotationProcessorFactory</code> interface. This interface may be implemented by the same class as implements an injector, but this is not strictly necessary. Please refer to the <a href="https://github.com/apache/sling-org-apache-sling-models-impl/tree/master/src/main/java/org/apache/sling/models/impl/injectors">injectors in Git</a> for examples.</p>
-<h1><a href="#specifying-an-alternate-adapter-class-since-1-1-0-" name="specifying-an-alternate-adapter-class-since-1-1-0-">Specifying an Alternate Adapter Class (since 1.1.0)</a></h1>
+<h1><a href="#specifying-an-alternate-adapter-class-since-110" id="specifying-an-alternate-adapter-class-since-110">Specifying an Alternate Adapter Class (since 1.1.0)</a></h1>
<p>By default, each model class is registered using its own implementation class as adapter. If the class has additional interfaces this is not relevant.</p>
<p>The <code>@Model</code> annotations provides an optional <code>adapters</code> attribute which allows specifying under which type(s) the model implementation should be registered in the Models Adapter Factory. Prior to <em>Sling Models Impl 1.3.10</em> only the given class names are used as adapter classes, since 1.3.10 the implementation class is always being registered implicitly as adapter as well (see <a href="https://issues.apache.org/jira/browse/SLING-6658">SLING-6658</a>). With [...]
<p>Example:</p>
@@ -623,27 +463,27 @@ public class MyModel implements MyService {
</code></pre>
<p>In this example a <code>Resource</code> can be adapted to a <code>MyService</code> interface, and the Sling Models implementation instantiates a <code>MyModel</code> class for this.</p>
<p>It is possible to have multiple models implementing the same interface. By default Sling Models will just take the first one ordered alphabetically by the class name. Applications can provide an OSGi service implementing the <code>ImplementationPicker</code> SPI interface which could use context to determine which implementation can be chosen, e.g. depending an a tenant or content path context. If multiple implementations of the <code>ImplementationPicker</code> interface are present, [...]
-<h1><a href="#associating-a-model-class-with-a-resource-type-since-1-3-0-" name="associating-a-model-class-with-a-resource-type-since-1-3-0-">Associating a Model Class with a Resource Type (since 1.3.0)</a></h1>
+<h1><a href="#associating-a-model-class-with-a-resource-type-since-130" id="associating-a-model-class-with-a-resource-type-since-130">Associating a Model Class with a Resource Type (since 1.3.0)</a></h1>
<p>The <code>@Model</code> annotation provides an optional <code>resourceType</code> attribute which allows for model classes to be associated with one or more resource types. This is used in three different ways.</p>
-<p>In the case of multiple model classes implementing the same interface, the class with the "closest" resource type will be used when adapting to the interface.</p>
+<p>In the case of multiple model classes implementing the same interface, the class with the "closest" resource type will be used when adapting to the interface.</p>
<p>The <code>ModelFactory</code> service interface has methods <code>Object getModelFromResource(Resource)</code> and <code>Object getModelFromRequest(SlingHttpServletRequest)</code> which will dynamically determine the adapter class based on the <code>Resource</code> using its type. In the case of the <code>SlingHttpServletRequest</code> method, it uses the request's <code>Resource</code> object (i.e. by calling <code>request.getResource()</code>)</p>
<p>The resource type is also used as part of the Exporter framework (see next section).</p>
-<h1><a href="#exporter-framework-since-1-3-0-" name="exporter-framework-since-1-3-0-">Exporter Framework (since 1.3.0)</a></h1>
+<h1><a href="#exporter-framework-since-130" id="exporter-framework-since-130">Exporter Framework (since 1.3.0)</a></h1>
<p>Sling Models objects can be exported to arbitrary Java objects through the Sling Models Exporter framework. Model objects can be programatically exported by calling the <code>ModelFactory</code> method <code>exportModel()</code>. This method takes as its arguments:</p>
<ul>
- <li>the model object</li>
- <li>an exporter name</li>
- <li>a target class</li>
- <li>a map of options</li>
+<li>the model object</li>
+<li>an exporter name</li>
+<li>a target class</li>
+<li>a map of options</li>
</ul>
-<p>The exact semantics of the exporting will be determined by an implementation of the <code>ModelExporter</code> service interface. </p>
+<p>The exact semantics of the exporting will be determined by an implementation of the <code>ModelExporter</code> service interface.</p>
<p>Sling Models currently includes a single exporter, using the Jackson framework, which is capable of serializing models as JSON or transforming them to <code>java.util.Map</code> objects. It is included in a dedicated bundle with the symbolic name <a href="https://github.com/apache/sling-org-apache-sling-models-jacksonexporter"><code>org.apache.sling.models.jacksonexporter</code></a>.</p>
<p>In addition, model objects can have servlets automatically registered for their resource type (if it is set) using the <code>@Exporter</code> annotation. For example, a model class with the annotation</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptable = Resource.class, resourceType = "myco/components/foo")
@Exporter(name = "jackson", extensions = "json")
</code></pre>
<p>results in the registration of a servlet with the resource type and extension specified and a selector of 'model' (overridable through the <code>@Exporter</code> annotation's <code>selector</code> attribute). When this servlet is invoked, the <code>Resource</code> will be adapted to the model, exported as a <code>java.lang.String</code> (via the named Exporter) and then returned to the client.</p>
-<h1><a href="#registration-of-sling-models-classes-via-bnd-plugin" name="registration-of-sling-models-classes-via-bnd-plugin">Registration of Sling Models classes via bnd plugin</a></h1>
+<h1><a href="#registration-of-sling-models-classes-via-bnd-plugin" id="registration-of-sling-models-classes-via-bnd-plugin">Registration of Sling Models classes via bnd plugin</a></h1>
<p>With the Sling Models bnd plugin it is possible to automatically generated the necessary bundle header to register the Sling Models classes contained in the Maven bundle project - either with maven-bundle-plugin or with bnd-maven-plugin. By default the plugin generates a <code>Sling-Model-Classes</code> header (only compatible with Sling Models Impl since version 1.3.4, see <a href="https://issues.apache.org/jira/browse/SLING-6308">SLING-6308</a>).</p>
<p>Example configuration:</p>
<pre><code><!-- TODO syntax marker (#!xml) disabled --><plugin>
@@ -672,8 +512,8 @@ public class MyModel implements MyService {
</instructions>
</configuration>
</code></pre>
-<h1><a href="#caching" name="caching">Caching</a></h1>
-<p>By default, Sling Models do not do any caching of the adaptation result and every request for a model class will result in a new instance of the model class. However, there are two notable cases when the adaptation result can be cached. The first case is when the adaptable extends the <code>SlingAdaptable</code> base class. Most significantly, this is the case for many <code>Resource</code> adaptables as <code>AbstractResource</code> extends <code>SlingAdaptable</code>. <code>SlingAda [...]
+<h1><a href="#caching" id="caching">Caching</a></h1>
+<p>By default, Sling Models do not do any caching of the adaptation result and every request for a model class will result in a new instance of the model class. However, there are two notable cases when the adaptation result can be cached. The first case is when the adaptable extends the <code>SlingAdaptable</code> base class. Most significantly, this is the case for many <code>Resource</code> adaptables as <code>AbstractResource</code> extends <code>SlingAdaptable</code>. <code>SlingAd [...]
<pre><code><!-- TODO syntax marker (::java) disabled -->// assume that resource is an instance of some subclass of AbstractResource
ModelClass object1 = resource.adaptTo(ModelClass.class); // creates new instance of ModelClass
ModelClass object2 = resource.adaptTo(ModelClass.class); // SlingAdaptable returns the cached instance
@@ -707,19 +547,19 @@ ModelClass object1 = request.adaptTo(ModelClass.class); // creates new instance
ModelClass object2 = modelFactory.createModel(request, ModelClass.class); // Sling Models returns the cached instance
assert object1 == object2;
</code></pre>
-<a name="caching-self-reference-note"></a>
-<h3><a href="#a-note-about-cache-true-and-using-the-self-injector" name="a-note-about-cache-true-and-using-the-self-injector">A note about cache = true and using the self injector</a></h3>
+<p><a name="caching-self-reference-note"></a></p>
+<h3><a href="#a-note-about-cache-true-and-using-the-self-injector" id="a-note-about-cache-true-and-using-the-self-injector">A note about cache = true and using the self injector</a></h3>
<p>In general, it is <strong>strongly</strong> discouraged to store a reference to the original adaptable using the <code>self</code> injector. Using implementation version 1.4.8 or below, storing the original adaptable in a Sling Model, can cause heap space exhaustion, crashing the JVM. Starting in version 1.4.10, storing the original adaptable will not crash the JVM, but it can cause unexpected behavior (e.g. a model being created twice, when it should be cached). The issue was first r [...]
<p>The problem can be avoided by discarding the original adaptable when it is no longer needed. This can be done by setting affected field(s) to <code>null</code> at the end of the <code>@PostConstruct</code> annotated method:</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Model(adaptable = SlingHttpServletRequest.class, cache = true)
public class CachableModelClass {
@Self
private SlingHttpServletRequest request;
-
+
@PostConstruct
private void init() {
... do something with request ...
-
+
this.request = null;
}
}
@@ -732,43 +572,29 @@ public class CachableModelClass {
}
}
</code></pre>
-<h1><a href="#via-types-since-api-1-3-4-implementation-1-4-0-" name="via-types-since-api-1-3-4-implementation-1-4-0-">Via Types (Since API 1.3.4/Implementation 1.4.0)</a></h1>
+<h1><a href="#via-types-since-api-134implementation-140" id="via-types-since-api-134implementation-140">Via Types (Since API 1.3.4/Implementation 1.4.0)</a></h1>
<p>As discussed in the <a href="#via">Via</a> section above, it is possible to select a different adaptable than the original value using the <code>@Via</code> annotation. The following standard types are provided (all types are in the package <code>org.apache.sling.models.annotations.via</code>)</p>
<table>
- <thead>
- <tr>
- <th><code>@Via</code> type value </th>
- <th>Description</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>BeanProperty</code> (default) </td>
- <td>Uses a JavaBean property from the adaptable.</td>
- </tr>
- <tr>
- <td><code>ChildResource</code> </td>
- <td>Uses a child resource from the adaptable, assuming the adaptable is a <code>Resource</code>. In case the adaptable is a <code>SlingHttpServletRequest</code> uses a wrapper overwriting the <code>getResource()</code> to point to the given child resource (<a href="https://issues.apache.org/jira/browse/SLING-7321">SLING-7321</a>).</td>
- </tr>
- <tr>
- <td><code>ForcedResourceType</code> </td>
- <td>Creates a wrapped resource with the provided resource type. If the adaptable is a <code>SlingHttpServletRequest</code>, a wrapped request is created as well to contain the wrapped resource.</td>
- </tr>
- <tr>
- <td><code>ResourceSuperType</code> </td>
- <td>Creates a wrapped resource with the resource type set to the adaptable's resource super type. If the adaptable is a <code>SlingHttpServletRequest</code>, a wrapped request is created as well to contain the wrapped resource.</td>
- </tr>
- </tbody>
+<thead>
+<tr><th><code>@Via</code> type value </th><th> Description</th></tr>
+</thead>
+<tbody>
+<tr><td><code>BeanProperty</code> (default) </td><td> Uses a JavaBean property from the adaptable.</td></tr>
+<tr><td><code>ChildResource</code> </td><td> Uses a child resource from the adaptable, assuming the adaptable is a <code>Resource</code>. In case the adaptable is a <code>SlingHttpServletRequest</code> uses a wrapper overwriting the <code>getResource()</code> to point to the given child resource (<a href="https://issues.apache.org/jira/browse/SLING-7321">SLING-7321</a>).</td></tr>
+<tr><td><code>ForcedResourceType</code> </td><td> Creates a wrapped resource with the provided resource type. If the adaptable is a <code>SlingHttpServletRequest</code>, a wrapped request is created as well to contain the wrapped resource.</td></tr>
+<tr><td><code>ResourceSuperType</code> </td><td> Creates a wrapped resource with the resource type set to the adaptable's resource super type. If the adaptable is a <code>SlingHttpServletRequest</code>, a wrapped request is created as well to contain the wrapped resource.</td></tr>
+</tbody>
</table>
-<h2><a href="#custom-via-type" name="custom-via-type">Custom Via Type</a></h2>
+<h2><a href="#custom-via-type" id="custom-via-type">Custom Via Type</a></h2>
<p>Defining your own type for the <code>@Via</code> annotation is a two step process. The first step is to create a marker class implementing the <code>@ViaProviderType</code> annotation. This class can be entirely empty, e.g.</p>
<pre><code><!-- TODO syntax marker (::java) disabled -->public class MyCustomProviderType implements ViaProviderType {}
</code></pre>
<p>The second step is to create an OSGi service implementing the <code>ViaProvider</code> interface. This interface defines two methods:</p>
<ul>
- <li><code>getType()</code> should return the marker class.</li>
- <li><code>getAdaptable()</code> should return the new adaptable or <code>ViaProvider.ORIGINAL</code> to indicate that the original adaptable should be used.</li>
-</ul></section></div></div>
+<li><code>getType()</code> should return the marker class.</li>
+<li><code>getAdaptable()</code> should return the new adaptable or <code>ViaProvider.ORIGINAL</code> to indicate that the original adaptable should be used.</li>
+</ul>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/nosql-resource-providers.html b/documentation/bundles/nosql-resource-providers.html
index 526a496..24aca1e 100644
--- a/documentation/bundles/nosql-resource-providers.html
+++ b/documentation/bundles/nosql-resource-providers.html
@@ -120,20 +120,20 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h2><a href="#introduction" name="introduction">Introduction</a></h2>
+<h2><a href="#introduction" id="introduction">Introduction</a></h2>
<p>Apache Sling provides resource-based access to NoSQL document stores like MongoDB and Couchbase via its Resource API using the NoSQL resource providers. This is possible in combination with a JCR-based repository (e.g. only on a special path in the resource tree), or a only persistence for the whole resource tree depending on the resource provider configuration.</p>
<p>The general concept of retrieving from and storing resource data in NoSQL document stores is the same independently from the NoSQL product used:</p>
<ul>
- <li>For each resource a structured document is stored (usually in JSON format)</li>
- <li>The path of the resource is the key of the document</li>
- <li>The properties of the resource are stored in a map-like form in the document</li>
- <li>Special mapping applies to convert special data types like numbers, dates and binary data to a format that can safely stored in the document event if the format is not natively supported (e.g. converting dates to strings and binary to base64)</li>
- <li>The Sling CRUD support defines a simple transaction model with buffering all changes in memory until a call to "commit()" persists them to the NoSQL database</li>
- <li>Iterating over child resources and deleting a resource including all descendants requires some basic query capabilities in the NoSQL store</li>
+<li>For each resource a structured document is stored (usually in JSON format)</li>
+<li>The path of the resource is the key of the document</li>
+<li>The properties of the resource are stored in a map-like form in the document</li>
+<li>Special mapping applies to convert special data types like numbers, dates and binary data to a format that can safely stored in the document event if the format is not natively supported (e.g. converting dates to strings and binary to base64)</li>
+<li>The Sling CRUD support defines a simple transaction model with buffering all changes in memory until a call to "commit()" persists them to the NoSQL database</li>
+<li>Iterating over child resources and deleting a resource including all descendants requires some basic query capabilities in the NoSQL store</li>
</ul>
-<p>All these general features are implemented in an abstraction layer called <a href="https://github.com/apache/sling/tree/trunk/contrib/nosql/generic">"Apache Sling NoSQL Generic Resource Provider"</a>, which is used by the resource provider implementations per NoSQL product. Those implementation than only implement a thin "adapter" which maps the resource data to the NoSQL product-specific storage formats and query capabilities, without having to care about all the complex resource pro [...]
-<p>This generic resource provider also contains a set of integration tests covering the most relevant resource read- and write usecases which can be used to test a NoSQL product-specific resource provider implementation and the underlying NoSQL database.</p>
-<h2><a href="#mongodb-nosql-resource-provider" name="mongodb-nosql-resource-provider">MongoDB NoSQL Resource Provider</a></h2>
+<p>All these general features are implemented in an abstraction layer called <a href="https://github.com/apache/sling/tree/trunk/contrib/nosql/generic">"Apache Sling NoSQL Generic Resource Provider"</a>, which is used by the resource provider implementations per NoSQL product. Those implementation than only implement a thin "adapter" which maps the resource data to the NoSQL product-specific storage formats and query capabilities, without having to care about all the [...]
+<p>This generic resource provider also contains a set of integration tests covering the most relevant resource read- and write usecases which can be used to test a NoSQL product-specific resource provider implementation and the underlying NoSQL database.</p>
+<h2><a href="#mongodb-nosql-resource-provider" id="mongodb-nosql-resource-provider">MongoDB NoSQL Resource Provider</a></h2>
<p>Resource provider for <a href="https://www.mongodb.org/">MongoDB</a> NoSQL database.</p>
<p>Tested with MongoDB Server 3.0.6 and MongoDB Java Driver 3.1.1.</p>
<p>Configuration example:</p>
@@ -143,10 +143,10 @@
database="sling"
collection="resources"
</code></pre>
-<p>See Apache Felix OSGi console for detailed documentation of the parameters. All resource data is stored in one Collection of one MongoDB database. Each resource is stored as a document with the path stored in an "_id" property.</p>
+<p>See Apache Felix OSGi console for detailed documentation of the parameters. All resource data is stored in one Collection of one MongoDB database. Each resource is stored as a document with the path stored in an "_id" property.</p>
<p>Source code: <a href="https://github.com/apache/sling/tree/trunk/contrib/nosql/mongodb-resourceprovider">Apache Sling NoSQL MongoDB Resource Provider</a></p>
-<p>Please note: there is an <a href="https://github.com/apache/sling/tree/trunk/contrib/extensions/mongodb">alternative MongoDB resource provider implementation</a> from 2012 which has less features, a slightly different concept for storing resource data (in multiple collections), and it does not use the "Generic Resource Provider".</p>
-<h2><a href="#couchbase-nosql-resource-provider" name="couchbase-nosql-resource-provider">Couchbase NoSQL Resource Provider</a></h2>
+<p>Please note: there is an <a href="https://github.com/apache/sling/tree/trunk/contrib/extensions/mongodb">alternative MongoDB resource provider implementation</a> from 2012 which has less features, a slightly different concept for storing resource data (in multiple collections), and it does not use the "Generic Resource Provider".</p>
+<h2><a href="#couchbase-nosql-resource-provider" id="couchbase-nosql-resource-provider">Couchbase NoSQL Resource Provider</a></h2>
<p>Resource provider for <a href="http://www.couchbase.com/">Couchbase</a> NoSQL database.</p>
<p>Tested with Couchbase Server 4.0.0 and Couchbase Java SDK 2.2.4. Please note: Couchbase 4 or higher is mandatory because N1QL support is required.</p>
<p>Configuration example:</p>
@@ -162,10 +162,11 @@ org.apache.sling.nosql.couchbase.client.CouchbaseClient.factory.config-default
<p>See Apache Felix OSGi console for detailed documentation of the parameters. All resource data is stored in one Couchbase bucket. Each resource is stored as a document with the path as key.</p>
<p>Source code: <a href="https://github.com/apache/sling/tree/trunk/contrib/nosql/couchbase-resourceprovider">Apache Sling NoSQL Couchbase Resource Provider</a></p>
<p>The resource provider requires and additional bundle <a href="https://github.com/apache/sling/tree/trunk/contrib/nosql/couchbase-client">Apache Sling NoSQL Couchbase Client</a> which wraps the Couchbase Java SDK (which itself is not an OSGi bundle), and ensures that the Couchbase Environment instance is used as a singleton in the VM.</p>
-<h2><a href="#example-launchpad" name="example-launchpad">Example Launchpad</a></h2>
+<h2><a href="#example-launchpad" id="example-launchpad">Example Launchpad</a></h2>
<p>An example launchpad is provided that contains the NoSQL resource providers configured as main resource provider at <code>/</code>.</p>
<p>Source code: <a href="https://github.com/apache/sling/tree/trunk/contrib/nosql/launchpad">Apache Sling NoSQL Launchpad</a></p>
-<p>See README for details how to start the launchpad.</p></section></div></div>
+<p>See README for details how to start the launchpad.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/org-apache-sling-junit-bundles.html b/documentation/bundles/org-apache-sling-junit-bundles.html
index e2d0f52..966f799 100644
--- a/documentation/bundles/org-apache-sling-junit-bundles.html
+++ b/documentation/bundles/org-apache-sling-junit-bundles.html
@@ -114,10 +114,10 @@
</li>
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
-<div class="row"><div><section><p>This is an overview of the Sling bundles that provide support for server-side JUnit tests. </p>
+<div class="row"><div><section><p>This is an overview of the Sling bundles that provide support for server-side JUnit tests.</p>
<p>The Maven modules below <a href="https://github.com/apache/sling-samples/tree/master/testing"><code>sling-samples/testing</code></a> provide different examples including HTTP-based and server-side teleported tests in a bundle module, running against a full Sling instance setup in the same Maven module.</p>
-<h2><a href="#org-apache-sling-junit-core-server-side-junit-tests-support" name="org-apache-sling-junit-core-server-side-junit-tests-support">org.apache.sling.junit.core: server-side JUnit tests support</a></h2>
-<p>This bundle provides a <code>JUnitServlet</code> that runs JUnit tests found in bundles. </p>
+<h2><a href="#orgapacheslingjunitcore-server-side-junit-tests-support" id="orgapacheslingjunitcore-server-side-junit-tests-support">org.apache.sling.junit.core: server-side JUnit tests support</a></h2>
+<p>This bundle provides a <code>JUnitServlet</code> that runs JUnit tests found in bundles.</p>
<div class="warning">
Note that the JUnitServlet does not require authentication, so it would allow any client to run tests. The servlet can be disabled by configuration if needed, but in general the `/system` path should not be accessible to website visitors anyway.
</div>
@@ -127,37 +127,37 @@ For tighter integration with Sling, the alternate `SlingJUnitServlet` is registe
<p>To make tests available to that servlet, the bundle that contains them must point to them with a <code>Sling-Test-Regexp</code> bundle header that defines a regular expression that matches the test class names, like for example:</p>
<pre><code>Sling-Test-Regexp=com.example.*ServerSideTest
</code></pre>
-<h3><a href="#the-teleporterrule" name="the-teleporterrule">The TeleporterRule</a></h3>
-<p>The <code>TeleporterRule</code> supplied by this bundle (since V1.0.12) makes it easy to write such tests, as it takes care of all the mechanics of </p>
+<h3><a href="#the-teleporterrule" id="the-teleporterrule">The TeleporterRule</a></h3>
+<p>The <code>TeleporterRule</code> supplied by this bundle (since V1.0.12) makes it easy to write such tests, as it takes care of all the mechanics of</p>
<ol>
- <li>creating the test bundle including all necessary classes for execution</li>
- <li>adding the <code>Sling-Test-Regexp</code> header to the bundles manifest</li>
- <li>deploy the bundle on an Sling server (with the help of the customizer)</li>
- <li>calling the <code>JUnitServlet</code> from the client-side and report back the results</li>
- <li>uninstalling the test bundle</li>
+<li>creating the test bundle including all necessary classes for execution</li>
+<li>adding the <code>Sling-Test-Regexp</code> header to the bundles manifest</li>
+<li>deploy the bundle on an Sling server (with the help of the customizer)</li>
+<li>calling the <code>JUnitServlet</code> from the client-side and report back the results</li>
+<li>uninstalling the test bundle</li>
</ol>
<p>Most of these steps are done on the client-side by the org.apache.sling.junit.teleporter module (see below).</p>
-<p>Using this rule the server-side tests can be mixed with other tests in the source code if that's convenient, it just requires the <code>junit.core</code> and <code>junit.teleporter</code> modules described on this page to create such tests. </p>
+<p>Using this rule the server-side tests can be mixed with other tests in the source code if that's convenient, it just requires the <code>junit.core</code> and <code>junit.teleporter</code> modules described on this page to create such tests.</p>
<p>Here's a basic example of a server-side test that accesses OSGi services:</p>
<pre><code>public class BasicTeleporterTest {
@Rule
public final TeleporterRule teleporter = TeleporterRule.forClass(getClass(), "Launchpad");
-
+
@Test
public void testConfigAdmin() throws IOException {
final String pid = "TEST_" + getClass().getName() + UUID.randomUUID();
-
+
final ConfigurationAdmin ca = teleporter.getService(ConfigurationAdmin.class);
assertNotNull("Teleporter should provide a ConfigurationAdmin", ca);
-
+
final Configuration cfg = ca.getConfiguration(pid);
assertNotNull("Expecting to get a Configuration", cfg);
assertEquals("Expecting the correct pid", pid, cfg.getPid());
}
}
</code></pre>
-<p>That's all there is to it, the <code>TeleporterRule</code> takes care of the rest. </p>
+<p>That's all there is to it, the <code>TeleporterRule</code> takes care of the rest.</p>
<p>The test bundle being build and deployed through this rule usually happens quickly as the temporary bundle is very small. Both the client-side and server-side parts of the test can be debugged easily with the appropriate IDE settings.</p>
<p>The <code>Teleporter.getService</code> method takes an optional OSGi LDAP filter for service selection, like for example:</p>
<pre><code>final StringTransformer t = teleporter.getService(StringTransformer.class, "(mode=uppercase)");
@@ -170,152 +170,61 @@ public final TeleporterRule teleporter =
.withResources("/foo/", "/some/other/resource.txt");
</code></pre>
<p>which will embed all resources found under <code>/foo</code> as well as the <code>resource.txt</code> in the test bundle, making them available to the server-side tests.</p>
-<p>This teleporter mechanism is used in our integration tests, search for <code>TeleporterRule</code> in there for examples or look at the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/tree/master/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/teleporter"><code>integrationtest.teleporter</code></a> package. </p>
+<p>This teleporter mechanism is used in our integration tests, search for <code>TeleporterRule</code> in there for examples or look at the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/tree/master/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/teleporter"><code>integrationtest.teleporter</code></a> package.</p>
<p>As I write this the teleporter mechanism is quite new, I suspect there might be some weird interactions between things like <code>@AfterClass</code>, custom test runners and this mechanism but it works well to a growing number of tests in our <code>launchpad/integration-tests</code> module. Moving to JUnit <code>Rules</code> as much as possible, and combining them using JUnit's <code>RuleChain</code>, should help work around such limitations if they arise.</p>
-<h3><a href="#more-details-on-the-junitservlet" name="more-details-on-the-junitservlet">More details on the JUnitServlet</a></h3>
+<h3><a href="#more-details-on-the-junitservlet" id="more-details-on-the-junitservlet">More details on the JUnitServlet</a></h3>
<p>To try the JUnitServlet interactively, you can install a bundle that contains tests and a <code>Sling-Test-Regexp</code> bundle header that points to them, as described above. Or use the <code>TeleporterRule</code> and set a breakpoint in the tests execution, when the test bundle in installed and listed by the test servlet.</p>
<p>To list the available tests, open <code>/system/sling/junit/</code> in your browser. The servlet shows available tests and allows you to execute them via a POST request.</p>
<p>Adding a path allows you to select a specific subset of tests, as in <code>/system/sling/junit/org.apache.sling.junit.remote.html</code></p>
-<p>The JUnitServlet provides various output formats, including in particular JSON, see <code>/system/sling/junit/.json</code> for example.</p>
-<h2><a href="#org-apache-sling-junit-teleporter-client-side-teleporterrule-support" name="org-apache-sling-junit-teleporter-client-side-teleporterrule-support">org.apache.sling.junit.teleporter: client-side TeleporterRule support</a></h2>
+<p>The JUnitServlet provides various output formats, including in particular JSON, see <code>/system/sling/junit/.json</code> for example.</p>
+<h2><a href="#orgapacheslingjunitteleporter-client-side-teleporterrule-support" id="orgapacheslingjunitteleporter-client-side-teleporterrule-support">org.apache.sling.junit.teleporter: client-side TeleporterRule support</a></h2>
<p>This module provides the <code>ClientSideTeleporter</code> which the <code>TeleporterRule</code> uses to package the server-side tests in bundles that's installed temporarily on the test server. Almost all steps described above in <a href="#the-teleporterrule">The TeleporterRule</a> are being performed by this module.</p>
<p>This module is not a bundle, as it's used on the client only, as a dependency when running the tests.</p>
-<h3><a href="#teleporterrule-customizer" name="teleporterrule-customizer">TeleporterRule.Customizer</a></h3>
+<h3><a href="#teleporterrulecustomizer" id="teleporterrulecustomizer">TeleporterRule.Customizer</a></h3>
<p>A <code>TeleporterRule.Customizer</code> is used to setup the <code>ClientSideTeleporter</code>. That customizer is instantiated dynamically based on a String passed to the <code>TeleporterRule.forClass</code> method as 2nd parameter. As an example from our <code>launchpad/integration-tests</code> module, this call</p>
<pre><code>TeleporterRule.forClass(getClass(), "Launchpad:author");
</code></pre>
-<p>causes the <code>TeleporterRule</code> to use the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/blob/master/src/main/java/org/apache/sling/junit/teleporter/customizers/LaunchpadCustomizer.java">org.apache.sling.junit.teleporter.customizers.LaunchpadCustomizer</a> class to setup the <code>ClientSideTeleporter</code>, and passes the "author" string to it as an option. Although our current <code>LaunchpadCustomizer</code> does not use this options [...]
+<p>causes the <code>TeleporterRule</code> to use the <a href="https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/blob/master/src/main/java/org/apache/sling/junit/teleporter/customizers/LaunchpadCustomizer.java">org.apache.sling.junit.teleporter.customizers.LaunchpadCustomizer</a> class to setup the <code>ClientSideTeleporter</code>, and passes the "author" string to it as an option. Although our current <code>LaunchpadCustomizer</code> does not use thi [...]
<p>The options string can also use a full class name instead of the <code>Launchpad</code> short form used here, if needed. The part of that string that follows the first colon is passed to the customizer as is.</p>
-<p>Using Strings for customization reduces the coupling with the <code>junit.core</code> bundle, as it does not need to know those classes which are used only on the client side when running tests. </p>
-<p>If <code>TeleporterRule.forClass(getClass())</code> is used (the method without an additional 2nd parameter) the default customizer is used (<a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a>, since version 1.0.8). </p>
+<p>Using Strings for customization reduces the coupling with the <code>junit.core</code> bundle, as it does not need to know those classes which are used only on the client side when running tests.</p>
+<p>If <code>TeleporterRule.forClass(getClass())</code> is used (the method without an additional 2nd parameter) the default customizer is used (<a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a>, since version 1.0.8).</p>
<p>The following customizers are currently used in Sling</p>
-<h3><a href="#default-customizer" name="default-customizer">Default Customizer</a></h3>
+<h3><a href="#default-customizer" id="default-customizer">Default Customizer</a></h3>
<p><em><a href="https://github.com/apache/sling-org-apache-sling-junit-teleporter/blob/master/src/main/java/org/apache/sling/testing/teleporter/client/DefaultPropertyBasedCustomizer.java">DefaultPropertyBasedCustomizer.java</a></em> is used by default when no other customizer is referenced in <code>TeleporterRule.forClass(getClass())</code>. It relies on the following system properties:</p>
<table>
- <thead>
- <tr>
- <th>Property Name </th>
- <th>Description </th>
- <th>Mandatory to set </th>
- <th>Default value </th>
- <th>Since version </th>
- <th>Related JIRA </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>ClientSideTeleporter.baseUrl</code> </td>
- <td>base url of the Sling Server to which to deploy. </td>
- <td>yes </td>
- <td>(-) </td>
- <td>1.0.8 </td>
- <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
- </tr>
- <tr>
- <td><code>ClientSideTeleporter.includeDependencyPrefixes</code> </td>
- <td>comma-separated list of package prefixes for classes referenced from the IT. Only the classes having one of the given package prefix are included in the bundle being deployed to the given Sling instance together with the IT class itself. They are only included though in case they are referenced! If this is not set, no referenced classes will be included. </td>
- <td>no </td>
- <td>(-) </td>
- <td>1.0.8 </td>
- <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
- </tr>
- <tr>
- <td><code>ClientSideTeleporter.excludeDependencyPrefixes</code> </td>
- <td>comma-separated list of package prefixes for classes referenced from the IT. Classes having one of the given package prefix will not be included in the bundle being deployed to the given Sling instance together with the IT class itself. This takes precedence over the <code>ClientSideTeleporter.includeDependencyPrefixes</code>. </td>
- <td>no </td>
- <td>(-) </td>
- <td>1.0.8 </td>
- <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
- </tr>
- <tr>
- <td><code>ClientSideTeleporter.embedClasses</code> </td>
- <td>comma-separated list of fully qualified class names which should be embedded in the test bundle. Use this only for classes which are not detected automatically by the Maven Dependency Analyzer but still should be embedded in the test bundle </td>
- <td>no </td>
- <td>(-) </td>
- <td>1.0.8 </td>
- <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
- </tr>
- <tr>
- <td><code>ClientSideTeleporter.embedClassesDirectories</code> </td>
- <td>comma-separated list directories containing class files which should be embedded in the test bundle. Use this only for classes which are not detected automatically by the Maven Dependency Analyzer but still should be embedded in the test bundle </td>
- <td>no </td>
- <td>(-) </td>
- <td>1.0.12 </td>
- <td><a href="https://issues.apache.org/jira/browse/SLING-6551">SLING-6551</a> </td>
- </tr>
- <tr>
- <td><code>ClientSideTeleporter.additionalBundleHeaders</code> </td>
- <td>comma-separated list of entries in the format <code><name>:<value></code> which should be added to the test bundle as additional headers </td>
- <td>no </td>
- <td>(-) </td>
- <td>1.0.12 </td>
- <td><a href="https://issues.apache.org/jira/browse/SLING-6558">SLING-6558</a> </td>
- </tr>
- <tr>
- <td><code>ClientSideTeleporter.testReadyTimeoutSeconds</code> </td>
- <td>how long to wait for our test to be ready on the server-side in seconds, after installing the test bundle. </td>
- <td>no </td>
- <td><code>12</code> </td>
- <td>1.0.8 </td>
- <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
- </tr>
- <tr>
- <td><code>ClientSideTeleporter.serverUsername</code> </td>
- <td>the username with which to send requests to the Sling server. </td>
- <td>no </td>
- <td><code>admin</code> </td>
- <td>1.0.8 </td>
- <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
- </tr>
- <tr>
- <td><code>ClientSideTeleporter.serverPassword</code> </td>
- <td>the password with which to send requests to the Sling server. </td>
- <td>no </td>
- <td><code>admin</code> </td>
- <td>1.0.8 </td>
- <td><a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td>
- </tr>
- <tr>
- <td><code>ClientSideTeleporter.enableLogging</code> </td>
- <td>set to <code>true</code> to log the tasks being performed by the teleporter. Useful for debugging. </td>
- <td>no </td>
- <td><code>false</code> </td>
- <td>1.0.12 </td>
- <td><a href="https://issues.apache.org/jira/browse/SLING-6546">SLING-6546</a> </td>
- </tr>
- <tr>
- <td><code>ClientSideTeleporter.preventToUninstallBundle</code> </td>
- <td>set to <code>true</code> to not automatically uninstall the test bundle after test execution. Useful for debugging. </td>
- <td>no </td>
- <td><code>false</code> </td>
- <td>1.0.12 </td>
- <td><a href="https://issues.apache.org/jira/browse/SLING-6546">SLING-6546</a> </td>
- </tr>
- <tr>
- <td><code>ClientSideTeleporter.testBundleDirectory</code> </td>
- <td>if set the test bundles are being persisted (before being installed) within the given directory name. If the directory does not exist, it will be automatically created. Useful for debugging. Recommended value <code>${project.build.directory}/test-bundles</code>. </td>
- <td>no </td>
- <td>(-) </td>
- <td>1.0.12 </td>
- <td><a href="https://issues.apache.org/jira/browse/SLING-6546">SLING-6546</a> </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Property Name </th><th> Description </th><th> Mandatory to set </th><th> Default value </th><th> Since version </th><th> Related JIRA </th></tr>
+</thead>
+<tbody>
+<tr><td> <code>ClientSideTeleporter.baseUrl</code> </td><td> base url of the Sling Server to which to deploy. </td><td> yes </td><td> (-) </td><td> 1.0.8 </td><td> <a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td></tr>
+<tr><td> <code>ClientSideTeleporter.includeDependencyPrefixes</code> </td><td> comma-separated list of package prefixes for classes referenced from the IT. Only the classes having one of the given package prefix are included in the bundle being deployed to the given Sling instance together with the IT class itself. They are only included though in case they are referenced! If this is not set, no referenced classes will be included. </td><td> no </td><td> (-) </td><td> 1.0.8 </td><td> <a [...]
+<tr><td> <code>ClientSideTeleporter.excludeDependencyPrefixes</code> </td><td> comma-separated list of package prefixes for classes referenced from the IT. Classes having one of the given package prefix will not be included in the bundle being deployed to the given Sling instance together with the IT class itself. This takes precedence over the <code>ClientSideTeleporter.includeDependencyPrefixes</code>. </td><td> no </td><td> (-) </td><td> 1.0.8 </td><td> <a href="https://issues.apache. [...]
+<tr><td> <code>ClientSideTeleporter.embedClasses</code> </td><td> comma-separated list of fully qualified class names which should be embedded in the test bundle. Use this only for classes which are not detected automatically by the Maven Dependency Analyzer but still should be embedded in the test bundle </td><td> no </td><td> (-) </td><td> 1.0.8 </td><td> <a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td></tr>
+<tr><td> <code>ClientSideTeleporter.embedClassesDirectories</code> </td><td> comma-separated list directories containing class files which should be embedded in the test bundle. Use this only for classes which are not detected automatically by the Maven Dependency Analyzer but still should be embedded in the test bundle </td><td> no </td><td> (-) </td><td> 1.0.12 </td><td> <a href="https://issues.apache.org/jira/browse/SLING-6551">SLING-6551</a> </td></tr>
+<tr><td> <code>ClientSideTeleporter.additionalBundleHeaders</code> </td><td> comma-separated list of entries in the format <code><name>:<value></code> which should be added to the test bundle as additional headers </td><td> no </td><td> (-) </td><td> 1.0.12 </td><td> <a href="https://issues.apache.org/jira/browse/SLING-6558">SLING-6558</a> </td></tr>
+<tr><td> <code>ClientSideTeleporter.testReadyTimeoutSeconds</code> </td><td> how long to wait for our test to be ready on the server-side in seconds, after installing the test bundle. </td><td> no </td><td> <code>12</code> </td><td> 1.0.8 </td><td> <a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td></tr>
+<tr><td> <code>ClientSideTeleporter.serverUsername</code> </td><td> the username with which to send requests to the Sling server. </td><td> no </td><td> <code>admin</code> </td><td> 1.0.8 </td><td> <a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td></tr>
+<tr><td> <code>ClientSideTeleporter.serverPassword</code> </td><td> the password with which to send requests to the Sling server. </td><td> no </td><td> <code>admin</code> </td><td> 1.0.8 </td><td> <a href="https://issues.apache.org/jira/browse/SLING-5677">SLING-5677</a> </td></tr>
+<tr><td> <code>ClientSideTeleporter.enableLogging</code> </td><td> set to <code>true</code> to log the tasks being performed by the teleporter. Useful for debugging. </td><td> no </td><td> <code>false</code> </td><td> 1.0.12 </td><td> <a href="https://issues.apache.org/jira/browse/SLING-6546">SLING-6546</a> </td></tr>
+<tr><td> <code>ClientSideTeleporter.preventToUninstallBundle</code> </td><td> set to <code>true</code> to not automatically uninstall the test bundle after test execution. Useful for debugging. </td><td> no </td><td> <code>false</code> </td><td> 1.0.12 </td><td> <a href="https://issues.apache.org/jira/browse/SLING-6546">SLING-6546</a> </td></tr>
+<tr><td> <code>ClientSideTeleporter.testBundleDirectory</code> </td><td> if set the test bundles are being persisted (before being installed) within the given directory name. If the directory does not exist, it will be automatically created. Useful for debugging. Recommended value <code>${project.build.directory}/test-bundles</code>. </td><td> no </td><td> (-) </td><td> 1.0.12 </td><td> <a href="https://issues.apache.org/jira/browse/SLING-6546">SLING-6546</a> </td></tr>
+</tbody>
</table>
<p>The provisioning of an appropriate instance can be done with the <a href="/documentation/development/slingstart.html">slingstart-maven-plugin</a>. An example for that is given at <a href="https://github.com/apache/sling-samples/tree/master/testing/module-with-it"><code>sling-samples/testing/module-with-it</code></a>. Since <code>slingstart-maven-plugin</code> 1.5.0 it is possible to bootstrap a Sling Server from a <code>model.txt</code> below <code>src/test/provisioning</code> indepen [...]
-<h4><a href="#launchpadcustomizer" name="launchpadcustomizer">LaunchpadCustomizer</a></h4>
+<h4><a href="#launchpadcustomizer" id="launchpadcustomizer">LaunchpadCustomizer</a></h4>
<p>The <em><a href="https://github.com/apache/sling-org-apache-sling-launchpad-integration-tests/blob/master/src/main/java/org/apache/sling/junit/teleporter/customizers/LaunchpadCustomizer.java"><code>LaunchpadCustomizer.java</code></a></em> only verifies that a Sling instance is ready at a given port and configures the <code>ClientSideTeleporter</code> to deploy to <code>http://localhost:8080</code> with the credentials <code>admin</code>:<code>admin</code>. <code>LaunchpadCustomizer</c [...]
-<h4>BWIT_TeleporterCustomizer</h4>
+<h4><a href="#bwit-teleportercustomizer" id="bwit-teleportercustomizer">BWIT_TeleporterCustomizer</a></h4>
<p>The <em><a href="https://github.com/apache/sling-samples/tree/master/testing/bundle-with-it/src/test/java/org/apache/sling/junit/teleporter/customizers/BWIT_TeleporterCustomizer.java"><code>BWIT_TeleporterCustomizer.java</code></a></em> relies on <code>SlingTestBase</code> to set the server's base url and credentials. Additionally the test bundle is adjusted so that the API is not included in it (but rather referenced from another bundle). The bootstrapping of the Sling instance is tw [...]
<p>Those should give you an overview on what can be done with a customizer and decide whether you need to write your own one or using the default customizer is just enough.</p>
-<h2><a href="#org-apache-sling-junit-healthcheck-run-junit-tests-as-sling-health-checks" name="org-apache-sling-junit-healthcheck-run-junit-tests-as-sling-health-checks">org.apache.sling.junit.healthcheck: run JUnit tests as Sling Health Checks</a></h2>
+<h2><a href="#orgapacheslingjunithealthcheck-run-junit-tests-as-sling-health-checks" id="orgapacheslingjunithealthcheck-run-junit-tests-as-sling-health-checks">org.apache.sling.junit.healthcheck: run JUnit tests as Sling Health Checks</a></h2>
<p>This bundle allows JUnit tests to run as <a href="/documentation/bundles/sling-health-check-tool.html">Sling Health Checks</a>, which can be useful when defining smoke tests for example, allowing them to be used both at build time and run time.</p>
-<p>See the <code>JUnitHealthCheck</code> class for details. </p>
-<h2><a href="#org-apache-sling-junit-scriptable-scriptable-server-side-tests" name="org-apache-sling-junit-scriptable-scriptable-server-side-tests">org.apache.sling.junit.scriptable: scriptable server-side tests</a></h2>
+<p>See the <code>JUnitHealthCheck</code> class for details.</p>
+<h2><a href="#orgapacheslingjunitscriptable-scriptable-server-side-tests" id="orgapacheslingjunitscriptable-scriptable-server-side-tests">org.apache.sling.junit.scriptable: scriptable server-side tests</a></h2>
<p>This bundle allows Sling scripts to be executed from the <code>JUnitServlet</code> as JUnit tests, as follows:</p>
<ul>
- <li>A node that has the <code>sling:Test</code> mixin is a scriptable test node.</li>
- <li>For security reasons, scriptable test nodes are only executed as tests if they are found under <code>/libs</code> or <code>/apps</code>, or more precisely under a path that's part of Sling's <code>ResourceResolver</code> search path.</li>
- <li>To execute a test, the scriptable tests provider makes an HTTP request to the test node's path, with a <code>.test.txt</code> selector and extension, and expects the output to contain only the string <code>TEST_PASSED</code>. Empty lines and comment lines starting with a hash sign (#) are ignored in the output, and other lines are reported as failures.</li>
+<li>A node that has the <code>sling:Test</code> mixin is a scriptable test node.</li>
+<li>For security reasons, scriptable test nodes are only executed as tests if they are found under <code>/libs</code> or <code>/apps</code>, or more precisely under a path that's part of Sling's <code>ResourceResolver</code> search path.</li>
+<li>To execute a test, the scriptable tests provider makes an HTTP request to the test node's path, with a <code>.test.txt</code> selector and extension, and expects the output to contain only the string <code>TEST_PASSED</code>. Empty lines and comment lines starting with a hash sign (#) are ignored in the output, and other lines are reported as failures.</li>
</ul>
<p>Here's a minimal example that sets up and executes a scriptable test:</p>
<pre><code>$ curl -u admin:admin -Fjcr:primaryNodeType=sling:Folder -Fsling:resourceType=foo -Fjcr:mixinTypes=sling:Test http://localhost:8080/apps/foo
@@ -337,9 +246,10 @@ TEST_PASSED
}
]
</code></pre>
-<p>Test failures would be included in this JSON representation - you can test that by modifying the script to fail and making the same request again. </p>
-<h2><a href="#org-apache-sling-junit-remote-obsolete" name="org-apache-sling-junit-remote-obsolete">org.apache.sling.junit.remote: obsolete</a></h2>
-<p>The <code>org.apache.sling.junit.remote</code> bundle provides utilities to run server-side JUnit tests, but using the newer <code>TeleporterRule</code> described above is much simpler. As a result, this bundle should only be needed for existing tests that were written using its mechanisms. </p></section></div></div>
+<p>Test failures would be included in this JSON representation - you can test that by modifying the script to fail and making the same request again.</p>
+<h2><a href="#orgapacheslingjunitremote-obsolete" id="orgapacheslingjunitremote-obsolete">org.apache.sling.junit.remote: obsolete</a></h2>
+<p>The <code>org.apache.sling.junit.remote</code> bundle provides utilities to run server-side JUnit tests, but using the newer <code>TeleporterRule</code> described above is much simpler. As a result, this bundle should only be needed for existing tests that were written using its mechanisms.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/osgi-installer.html b/documentation/bundles/osgi-installer.html
index a69693e..172c42b 100644
--- a/documentation/bundles/osgi-installer.html
+++ b/documentation/bundles/osgi-installer.html
@@ -114,70 +114,71 @@
</li>
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
-<div class="row"><div><section><h1><a href="#overview" name="overview">Overview</a></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>
+<div class="row"><div><section><h1><a href="#overview" id="overview">Overview</a></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>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><a href="#api" name="api">API</a></h2>
+<h2><a href="#api" id="api">API</a></h2>
<p>The installer API is defined by the <code>org.apache.sling.installer.api</code> package of the <a href="https://github.com/apache/sling-org-apache-sling-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><a href="#artifact-handling" name="artifact-handling">Artifact Handling</a></h2>
+<h2><a href="#artifact-handling" id="artifact-handling">Artifact Handling</a></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 bo [...]
<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><a href="#bundle-handling" name="bundle-handling">Bundle Handling</a></h2>
+<h2><a href="#bundle-handling" id="bundle-handling">Bundle Handling</a></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 bu [...]
<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><a href="#multi-version-support" name="multi-version-support">Multi-Version Support</a></h3>
+<h3><a href="#multi-version-support" id="multi-version-support">Multi-Version Support</a></h3>
<p>For now this feature is considered <strong>experimental</strong>, see <a href="https://issues.apache.org/jira/browse/SLING-9172">SLING-9172</a> and related tickets for details.</p>
<p>Starting with version 3.11.0 of the <code>org.apache.sling.installer.core</code> bundle, setting the System or Framework Property <code>sling.installer.experimental.multiversion=true</code> activates multi-version support.</p>
<p>When this option is active, the entity ID of each installable bundle also contains the version, enabling multiple versions of the same bundle to be installed.</p>
<p>In this case, changes to the installable candidates only affect the very same version of this bundle, leading to the following behavior:</p>
<ul>
- <li>Different versions of the same bundle are installed side-by-side in the OSGi framework, instead of installing only the highest version of each bundle.</li>
- <li>Removing an installable candidate only triggers uninstallation of the corresponding bundle version.</li>
- <li>Installed bundles are only updated if have SNAPSHOT versions.</li>
+<li>Different versions of the same bundle are installed side-by-side in the OSGi framework, instead of installing only the highest version of each bundle.</li>
+<li>Removing an installable candidate only triggers uninstallation of the corresponding bundle version.</li>
+<li>Installed bundles are only updated if have SNAPSHOT versions.</li>
</ul>
<p>This feature allows for providing multiple versions of the same Java packages, which was previously only possible by creating bundles with different symbolic names but providing the same packages, or by using other installation mechanisms.</p>
-<h3><a href="#versions-and-snapshots" name="versions-and-snapshots">Versions and Snapshots</a></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 o [...]
+<h3><a href="#versions-and-snapshots" id="versions-and-snapshots">Versions and Snapshots</a></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 [...]
<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><a href="#start-level-handling" name="start-level-handling">Start Level Handling</a></h2>
+<h2><a href="#start-level-handling" id="start-level-handling">Start Level Handling</a></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 [...]
<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>
+<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><a href="#plugins" name="plugins">Plugins</a></h2>
-<h3><a href="#factories" name="factories">Factories</a></h3>
+<h2><a href="#plugins" id="plugins">Plugins</a></h2>
+<h3><a href="#factories" id="factories">Factories</a></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/content-package-installer-factory.html">Content Package Installer Factory</a></li>
- <li><a href="/documentation/bundles/subsystem-installer-factory.html">Subsystem Installer Factory (deprecated)</a></li>
+<li><a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a></li>
+<li><a href="/documentation/bundles/content-package-installer-factory.html">Content Package Installer Factory</a></li>
+<li><a href="/documentation/bundles/subsystem-installer-factory.html">Subsystem Installer Factory (deprecated)</a></li>
</ul>
-<h3><a href="#providers" name="providers">Providers</a></h3>
+<h3><a href="#providers" id="providers">Providers</a></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>
+<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><a href="#health-check" name="health-check">Health Check</a></h2>
+<h2><a href="#health-check" id="health-check">Health Check</a></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 [...]
-<h3><a href="#bundles-installation-failure" name="bundles-installation-failure">Bundles Installation Failure</a></h3>
+<h3><a href="#bundles-installation-failure" id="bundles-installation-failure">Bundles Installation Failure</a></h3>
<p>The checked bundle was not installed because it has been installed in a newer version from some other location (might even be through some other provider). For further details please look at the OSGi Installer console at <code>/system/console/osgi-installer</code> and check for all bundles with the given symbolic name (=OSGi installer's resource id) and their according URLs.</p>
-<h3><a href="#configuration-installation-failure" name="configuration-installation-failure">Configuration Installation Failure</a></h3>
+<h3><a href="#configuration-installation-failure" id="configuration-installation-failure">Configuration Installation Failure</a></h3>
<p>The checked configuration was not installed because it is already installed from some other location (which has a higher priority). In this case you can see from where it has been installed by looking at the OSGi Installer console at <code>/system/console/osgi-installer</code> and check all configurations with the given PID and their according URLs.</p>
-<p>Due to <a href="https://issues.apache.org/jira/browse/SLING-7735">SLING-7735</a>, there might be false positives being reported by the health check, in case the configuration has already been deployed with exactly the same values in the system previously. In that case the OSGi Installer might also mark the resource as <code>IGNORED</code>. If you run into such an issue, you can fix it by removing the manually overwritten configurations: Just go to <code>/system/console/configMgr</code [...]
-<h3><a href="#limitations-of-the-health-check" name="limitations-of-the-health-check">Limitations of the health check</a></h3>
-<p>Currently the health check and the OSGi installer cannot detect if a deployed bundle/configuration has been overwritten (e.g. via API or the WebConsole). So even if an OSGi installer resource is marked as <code>INSTALLED</code> it might already have been overwritten. This limitation is tracked in <a href="https://issues.apache.org/jira/browse/SLING-7736">SLING-7736</a>.</p></section></div></div>
+<p>Due to <a href="https://issues.apache.org/jira/browse/SLING-7735">SLING-7735</a>, there might be false positives being reported by the health check, in case the configuration has already been deployed with exactly the same values in the system previously. In that case the OSGi Installer might also mark the resource as <code>IGNORED</code>. If you run into such an issue, you can fix it by removing the manually overwritten configurations: Just go to <code>/system/console/configMgr</code [...]
+<h3><a href="#limitations-of-the-health-check" id="limitations-of-the-health-check">Limitations of the health check</a></h3>
+<p>Currently the health check and the OSGi installer cannot detect if a deployed bundle/configuration has been overwritten (e.g. via API or the WebConsole). So even if an OSGi installer resource is marked as <code>INSTALLED</code> it might already have been overwritten. This limitation is tracked in <a href="https://issues.apache.org/jira/browse/SLING-7736">SLING-7736</a>.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html b/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html
index 403cdf6..1a02d5b 100644
--- a/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html
+++ b/documentation/bundles/output-rewriting-pipelines-org-apache-sling-rewriter.html
@@ -116,23 +116,23 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><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 [...]
-<h2><a href="#sax-pipelines" name="sax-pipelines">SAX Pipelines</a></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>
+<h2><a href="#sax-pipelines" id="sax-pipelines">SAX Pipelines</a></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>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>You can overwrite the configuration or contribute more specific configurations as outlined below in <a href="#configuring-a-processor">Configuring a Processor</a>. Only one pipeline is being picked based on the matching configuration with the highest order.</p>
-<h3><a href="#default-pipeline" name="default-pipeline">Default Pipeline</a></h3>
+<h3><a href="#default-pipeline" id="default-pipeline">Default Pipeline</a></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><a href="#implementing-pipeline-components" name="implementing-pipeline-components">Implementing Pipeline Components</a></h2>
+<h2><a href="#implementing-pipeline-components" id="implementing-pipeline-components">Implementing Pipeline Components</a></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 t [...]
<pre><code><!-- TODO syntax marker (::java) disabled -->@scr.component metatype="no"
@scr.service interface="TransformerFactory"
@scr.property value="pipeline.type" value="validator"
</code></pre>
<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><a href="#extending-the-pipeline" name="extending-the-pipeline">Extending the Pipeline</a></h2>
+<h2><a href="#extending-the-pipeline" id="extending-the-pipeline">Extending the Pipeline</a></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>
<pre><code><!-- TODO syntax marker (::java) disabled -->@scr.component metatype="no"
@@ -143,114 +143,37 @@
<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><a href="#implementing-a-processor" name="implementing-a-processor">Implementing a Processor</a></h2>
+<h2><a href="#implementing-a-processor" id="implementing-a-processor">Implementing a Processor</a></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>
<pre><code><!-- TODO syntax marker (::java) disabled -->@scr.component metatype="no"
@scr.service interface="ProcessorFactory"
@scr.property value="pipeline.type" value="uniqueName"
</code></pre>
-<h2><a href="#configuring-a-processor" name="configuring-a-processor">Configuring a Processor</a></h2>
-<p>The pipelines can be configured in the repository as a child resource of <code>/apps/<APPNAME>/config/rewriter/*</code> (or <code>/libs/<APPNAME>/config/rewriter/*</code>). (In fact the configured search paths of the resource resolver are observed.) Each resource can have the following properties:</p>
+<h2><a href="#configuring-a-processor" id="configuring-a-processor">Configuring a Processor</a></h2>
+<p>The pipelines can be configured in the repository as a child resource of <code>/apps/<APPNAME>/config/rewriter/*</code> (or <code>/libs/<APPNAME>/config/rewriter/*</code>). (In fact the configured search paths of the resource resolver are observed.) Each resource can have the following properties:</p>
<table>
- <thead>
- <tr>
- <th>Property </th>
- <th>Type </th>
- <th>Description </th>
- <th>Example Value </th>
- <th>Mandatory</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>generatorType</code> </td>
- <td>String </td>
- <td>The type of the generator. Identifies the generator being registered via service property <code>pipeline.type</code> of a service implementing a <code>GeneratorFactory</code> </td>
- <td><code>html-generator</code> </td>
- <td>yes</td>
- </tr>
- <tr>
- <td><code>transformerTypes</code> </td>
- <td>String[] </td>
- <td>The types of the transformers. Identifies the transformers being registered via service property <code>pipeline.type</code> of a service implementing a <code>TransformerFactory</code> </td>
- <td><code>link-rewriter</code> (Sling itself does not contain any TransformerFactories) </td>
- <td>no</td>
- </tr>
- <tr>
- <td><code>serializerType</code> </td>
- <td>String </td>
- <td>The type of the serializer. Identifies the serializer being registered via service property <code>pipeline.type</code> of a service implementing a <code>SerializerFactory</code> </td>
- <td><code>html-serializer</code> </td>
- <td>yes</td>
- </tr>
- <tr>
- <td><code>paths</code> </td>
- <td>String[] </td>
- <td>The paths this pipeline should run on (content paths). Only if the request's resource path starts with one of the given <code>paths</code> or one of the given paths is <code>*</code> the pipeline configuration is considered. </td>
- <td><code>/content/</code> </td>
- <td>no</td>
- </tr>
- <tr>
- <td><code>contentTypes</code> </td>
- <td>String[] </td>
- <td>The content types this pipeline should be used for . If no explicit content type is set on the response yet, <code>text/html</code> is assumed. May contain <code>*</code> values which match for all content types. Only if the response has one of the given content types the pipeline configuration is considered. </td>
- <td><code>text/html</code> </td>
- <td>no</td>
- </tr>
- <tr>
- <td><code>extensions</code> </td>
- <td>String </td>
- <td>The extensions this pipeline should be used for. Only if the request's extension is equal to one of the given extensions the pipeline configuration is considered. </td>
- <td><code>html</code> </td>
- <td>no</td>
- </tr>
- <tr>
- <td><code>resourceTypes</code> </td>
- <td>String[] </td>
- <td>The resource types this pipeline should be used for. Only if the request's resource type is equal (via <code>ResourceResolver.isResourceType(<request's resource>, <given resource type></code>) to one of the given resourceTypes the pipeline configuration is considered. </td>
- <td><code>myapp/customresourcetype</code> </td>
- <td>no</td>
- </tr>
- <tr>
- <td><code>unwrapResources</code> </td>
- <td>Boolean </td>
- <td>Check resource types of unwrapped resources as well if this is set to <code>true</code>. Available since 1.1.0 (<a href="https://issues.apache.org/jira/browse/SLING-5012">SLING-5012</a>). </td>
- <td><code>false</code> </td>
- <td>no</td>
- </tr>
- <tr>
- <td><code>selectors</code> </td>
- <td>String[] </td>
- <td>A set of selectors the pipeline should be used for. Each value is a single selector (i.e. must not contain <code>.</code>). Only if the request contains at least one selector which is equal to one of the given selectors, this pipeline configuration is considered. Available since 1.1.0 (<a href="https://issues.apache.org/jira/browse/SLING-3511">SLING-3511</a>) </td>
- <td><code>myselector</code> </td>
- <td>no</td>
- </tr>
- <tr>
- <td><code>order</code> </td>
- <td>Long </td>
- <td>The configurations are sorted by this order, order must be higher or equal to 0. The configuration with the highest order is tried first. Default value (if not set): 0 </td>
- <td>100 </td>
- <td>no</td>
- </tr>
- <tr>
- <td><code>enabled</code> </td>
- <td>Boolean </td>
- <td>Is this configuration active? (default yes) </td>
- <td><code>false</code> </td>
- <td>no</td>
- </tr>
- <tr>
- <td><code>processError</code> </td>
- <td>Boolean </td>
- <td>Only if this is set to <code>true</code> also error responses are processed by this pipeline configuration. Default <code>true</code> </td>
- <td><code>true</code> </td>
- <td>no</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Property </th><th> Type </th><th> Description </th><th> Example Value </th><th> Mandatory</th></tr>
+</thead>
+<tbody>
+<tr><td><code>generatorType</code> </td><td> String </td><td> The type of the generator. Identifies the generator being registered via service property <code>pipeline.type</code> of a service implementing a <code>GeneratorFactory</code> </td><td> <code>html-generator</code> </td><td> yes</td></tr>
+<tr><td><code>transformerTypes</code> </td><td> String[] </td><td> The types of the transformers. Identifies the transformers being registered via service property <code>pipeline.type</code> of a service implementing a <code>TransformerFactory</code> </td><td> <code>link-rewriter</code> (Sling itself does not contain any TransformerFactories) </td><td> no</td></tr>
+<tr><td><code>serializerType</code> </td><td> String </td><td> The type of the serializer. Identifies the serializer being registered via service property <code>pipeline.type</code> of a service implementing a <code>SerializerFactory</code> </td><td> <code>html-serializer</code> </td><td> yes</td></tr>
+<tr><td><code>paths</code> </td><td> String[] </td><td> The paths this pipeline should run on (content paths). Only if the request's resource path starts with one of the given <code>paths</code> or one of the given paths is <code>*</code> the pipeline configuration is considered. </td><td> <code>/content/</code> </td><td> no</td></tr>
+<tr><td><code>contentTypes</code> </td><td> String[] </td><td> The content types this pipeline should be used for . If no explicit content type is set on the response yet, <code>text/html</code> is assumed. May contain <code>*</code> values which match for all content types. Only if the response has one of the given content types the pipeline configuration is considered. </td><td> <code>text/html</code> </td><td> no</td></tr>
+<tr><td><code>extensions</code> </td><td> String </td><td> The extensions this pipeline should be used for. Only if the request's extension is equal to one of the given extensions the pipeline configuration is considered. </td><td> <code>html</code> </td><td> no</td></tr>
+<tr><td><code>resourceTypes</code> </td><td> String[] </td><td> The resource types this pipeline should be used for. Only if the request's resource type is equal (via <code>ResourceResolver.isResourceType(<request's resource>, <given resource type></code>) to one of the given resourceTypes the pipeline configuration is considered. </td><td> <code>myapp/customresourcetype</code> </td><td> no</td></tr>
+<tr><td><code>unwrapResources</code> </td><td> Boolean </td><td> Check resource types of unwrapped resources as well if this is set to <code>true</code>. Available since 1.1.0 (<a href="https://issues.apache.org/jira/browse/SLING-5012">SLING-5012</a>). </td><td> <code>false</code> </td><td> no</td></tr>
+<tr><td><code>selectors</code> </td><td> String[] </td><td> A set of selectors the pipeline should be used for. Each value is a single selector (i.e. must not contain <code>.</code>). Only if the request contains at least one selector which is equal to one of the given selectors, this pipeline configuration is considered. Available since 1.1.0 (<a href="https://issues.apache.org/jira/browse/SLING-3511">SLING-3511</a>) </td><td> <code>myselector</code> </td><td> no</td></tr>
+<tr><td><code>order</code> </td><td> Long </td><td> The configurations are sorted by this order, order must be higher or equal to 0. The configuration with the highest order is tried first. Default value (if not set): 0 </td><td> 100 </td><td> no</td></tr>
+<tr><td><code>enabled</code> </td><td> Boolean </td><td> Is this configuration active? (default yes) </td><td> <code>false</code> </td><td> no</td></tr>
+<tr><td><code>processError</code> </td><td> Boolean </td><td> Only if this is set to <code>true</code> also error responses are processed by this pipeline configuration. Default <code>true</code> </td><td> <code>true</code> </td><td> no</td></tr>
+</tbody>
</table>
<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 [...]
+<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 [...]
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/rendering-content-default-get-servlets.html b/documentation/bundles/rendering-content-default-get-servlets.html
index 1402179..9a5f416 100644
--- a/documentation/bundles/rendering-content-default-get-servlets.html
+++ b/documentation/bundles/rendering-content-default-get-servlets.html
@@ -120,38 +120,38 @@
Not all features of the <b>org.apache.sling.servlets.get</b> bundle are described below - this
page needs more work.
</div>
-<h1><a href="#default-get-and-head-servlets" name="default-get-and-head-servlets">Default GET and HEAD servlets</a></h1>
+<h1><a href="#default-get-and-head-servlets" id="default-get-and-head-servlets">Default GET and HEAD servlets</a></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>
+<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>
<p>If not otherwise mentioned for specific renderings the servlet does not support conditional requests as specified by <a href="https://tools.ietf.org/html/rfc7232">RFC 7232</a> (i.e. the <code>If-....</code> request headers are disregarded and the response will neither contain <code>ETag</code> nor <code>Last-Modified</code> headers).</p>
-<h1><a href="#default-renderings" name="default-renderings">Default renderings</a></h1>
-<h2><a href="#default-json-rendering" name="default-json-rendering">Default JSON rendering</a></h2>
+<h1><a href="#default-renderings" id="default-renderings">Default renderings</a></h1>
+<h2><a href="#default-json-rendering" id="default-json-rendering">Default JSON rendering</a></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>
+<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><a href="#default-html-rendering" name="default-html-rendering">Default HTML rendering</a></h2>
+<h2><a href="#default-html-rendering" id="default-html-rendering">Default HTML rendering</a></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><a href="#default-text-rendering" name="default-text-rendering">Default text rendering</a></h2>
+<h2><a href="#default-text-rendering" id="default-text-rendering">Default text rendering</a></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><a href="#default-xml-rendering" name="default-xml-rendering">Default XML rendering</a></h2>
+<h2><a href="#default-xml-rendering" id="default-xml-rendering">Default XML rendering</a></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><a href="#streamrendererservlet" name="streamrendererservlet">StreamRendererServlet</a></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>) based on the last-modified response header by evaluating the resource's modification date from <code>Resource.getResourceMetadata().getModificationTime()</code> and range req [...]
-<h2><a href="#redirectservlet" name="redirectservlet">RedirectServlet</a></h2>
+<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><a href="#streamrendererservlet" id="streamrendererservlet">StreamRendererServlet</a></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>) based on the last-modified response header by evaluating the resource's modification date from <code>Resource.getResourceMetadata().getModificationTime()</code> and range re [...]
+<h2><a href="#redirectservlet" id="redirectservlet">RedirectServlet</a></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><a href="#slinginfoservlet" name="slinginfoservlet">SlingInfoServlet</a></h2>
+<h2><a href="#slinginfoservlet" id="slinginfoservlet">SlingInfoServlet</a></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>
-<h2><a href="#jcr-versions-support" name="jcr-versions-support">JCR Versions Support</a></h2>
+<p>It is available at <code>/system/sling/info.sessionInfo</code> by default, and supports <code>.json</code> and <code>.txt</code> extensions.</p>
+<h2><a href="#jcr-versions-support" id="jcr-versions-support">JCR Versions Support</a></h2>
<p>The extensions created for <a href="https://issues.apache.org/jira/browse/SLING-848">SLING-848</a> and <a href="https://issues.apache.org/jira/browse/SLING-4318">SLING-4318</a> provide some access to JCR version management features, along with the <a href="/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html">Sling POST Servlet</a> versioning-related features.</p>
<p>Here's an example that demonstrates this.</p>
<p>Use the <a href="http://localhost:8080/system/console/configMgr/org.apache.sling.servlets.get.impl.version.VersionInfoServlet">org.apache.sling.servlets.get.impl.version.VersionInfoServlet</a> OSGi configuration to activate the <code>VersionInfoServlet</code> which supports the <code>.V.json</code> selector shown below. That servlet is disabled by default to make sure the configurable V selector doesn't interfere with existing applications.</p>
@@ -245,14 +245,15 @@ curl -s "http://localhost:8080/vtest.tidy.json;v=1.2"
"jcr:uuid": "3d55430b-2fa6-4562-b415-638fb6608c0e"
}
</code></pre>
-<h2><a href="#streaming-binaries-using-the-default-get-servlet" name="streaming-binaries-using-the-default-get-servlet">Streaming binaries using the default GET servlet</a></h2>
+<h2><a href="#streaming-binaries-using-the-default-get-servlet" id="streaming-binaries-using-the-default-get-servlet">Streaming binaries using the default GET servlet</a></h2>
<p>There are scenarios where it is useful to stream a binary resource using the default GET servlet. However, there is no API to select a specific servlet. We can still stream using the default GET servlet by taking advantage of the fact that it is also registered for the <em>res</em> extension. The code to do what would be:</p>
<pre><code>Resource toRender = /* code to obtain resource here */ null;
request
.getRequestDispatcher(toRender.getPath() + ".res")
.forward(request, response);
</code></pre>
-<p>See also <a href="https://issues.apache.org/jira/browse/SLING-8742">SLING-8742 - Allow overriding the extension when using the RequestDispatcher</a> for a discussion on providing an API for this use case. </p></section></div></div>
+<p>See also <a href="https://issues.apache.org/jira/browse/SLING-8742">SLING-8742 - Allow overriding the extension when using the RequestDispatcher</a> for a discussion on providing an API for this use case.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/repository-initialization.html b/documentation/bundles/repository-initialization.html
index d2a567b..be31339 100644
--- a/documentation/bundles/repository-initialization.html
+++ b/documentation/bundles/repository-initialization.html
@@ -125,7 +125,7 @@
<div class="row"><div><section><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><a href="#slingrepositoryinitializer" name="slingrepositoryinitializer">SlingRepositoryInitializer</a></h2>
+<h2><a href="#slingrepositoryinitializer" id="slingrepositoryinitializer">SlingRepositoryInitializer</a></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>
<pre><code>public interface SlingRepositoryInitializer {
public void processRepository(SlingRepository repo) throws Exception;
@@ -134,192 +134,192 @@
<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><a href="#the-repoinit-repository-initialization-language" name="the-repoinit-repository-initialization-language">The 'repoinit' Repository Initialization Language</a></h2>
+<h2><a href="#the-repoinit-repository-initialization-language" id="the-repoinit-repository-initialization-language">The 'repoinit' Repository Initialization Language</a></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>As I write this, the source code consists of <a href="https://github.com/apache?utf8=%E2%9C%93&q=sling+repoinit">three modules</a>: the parser, the JCR repoinit adapter module and the integration tests.</p>
+<p>As I write this, the source code consists of <a href="https://github.com/apache?utf8=%E2%9C%93&q=sling+repoinit">three modules</a>: the parser, the JCR repoinit adapter module and the integration tests.</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://github.com/apache/sling-org-apache-sling-repoinit-parser/tree/master/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>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>
<pre class="language-no-highlight">
+<pre><code>create service user user1, u-ser_2
+set ACL on /libs,/apps
+ allow jcr:read for user1,u-ser_2
- create service user user1, u-ser_2
- set ACL on /libs,/apps
- allow jcr:read for user1,u-ser_2
+ deny jcr:write for u-ser_2
+ deny jcr:lockManagement for user1
+ remove jcr:understand,some:other for u3
+end
- deny jcr:write for u-ser_2
- deny jcr:lockManagement for user1
- remove jcr:understand,some:other for u3
- end
+create service user bob_the_service
- create service user bob_the_service
+set ACL on /tmp
+ allow some:otherPrivilege for bob_the_service
+end
- set ACL on /tmp
- allow some:otherPrivilege for bob_the_service
- end
+# Nodetypes inside the path apply to just that path element
+create path /content/example.com(sling:Folder)
- # Nodetypes inside the path apply to just that path element
- create path /content/example.com(sling:Folder)
+# Nodetypes and mixins applied to just a path element
+# Specifying mixins require
+# o.a.s.repoinit.parser 1.2.0 and
+# o.a.s.jcr.repoinit 1.1.6
+create path /content/example.com(sling:Folder mixin mix:referenceable,mix:shareable)
- # Nodetypes and mixins applied to just a path element
- # Specifying mixins require
- # o.a.s.repoinit.parser 1.2.0 and
- # o.a.s.jcr.repoinit 1.1.6
- create path /content/example.com(sling:Folder mixin mix:referenceable,mix:shareable)
+# Mixins applied to just a path element
+create path /content/example.com(mixin mix:referenceable)
- # Mixins applied to just a path element
- create path /content/example.com(mixin mix:referenceable)
-
- # A nodetype in front is used as the default for all path elements
- create path (nt:unstructured) /var
+# A nodetype in front is used as the default for all path elements
+create path (nt:unstructured) /var
- set ACL for alice, bob,fred
- # remove is currently not supported by the jcr.repoinit module
- remove * on /
- allow jcr:read on /content,/var
- deny jcr:write on /content/example.com
- deny jcr:all on / nodetypes example:Page
- end
-
- 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/*)
+set ACL for alice, bob,fred
+ # remove is currently not supported by the jcr.repoinit module
+ remove * on /
+ allow jcr:read on /content,/var
+ deny jcr:write on /content/example.com
+ deny jcr:all on / nodetypes example:Page
+end
- # empty rep:glob means "apply to this node but not its children"
- # (requires o.a.s.jcr.repoinit 1.1.8)
- allow jcr:something on / restriction(rep:glob)
- end
+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/*)
- # Set repository level ACL
- # Setting repository level ACL require
- # o.a.s.repoinit.parser 1.2.0 and
- # o.a.s.jcr.repoinit 1.1.6
- set repository ACL for alice,bob
- allow jcr:namespaceManagement,jcr:nodeTypeDefinitionManagement
- end
-
- # Set repository level ACL (variant, see SLING-8619)
- # since
- # o.a.s.repoinit.parser 1.2.8 and
- # o.a.s.jcr.repoinit 1.1.14
- set ACL for alice,bob
- allow jcr:namespaceManagement on :repository
- end
-
- # Set principal-based access control (see SLING-8602)
- # since
- # o.a.s.repoinit.parser 1.2.8 and
- # o.a.s.jcr.repoinit 1.1.14
- # precondition for o.a.s.jcr.repoinit:
- # repository needs to support 'o.a.j.api.security.authorization.PrincipalAccessControlList'
- set principal ACL for alice,bob
- remove * on /libs,/apps
- allow jcr:read on /content,/var
- deny jcr:write on /content/example.com
-
- # Optional nodetypes clause
- deny jcr:lockManagement on /apps, /content nodetypes sling:Folder, nt:unstructured
-
- # nodetypes clause with restriction clause
- deny jcr:modifyProperties on /apps, /content nodetypes sling:Folder, nt:unstructured restriction(rep:itemNames,prop1,prop2)
-
- # multi value restriction
- allow jcr:addChildNodes on /apps restriction(rep:ntNames,sling:Folder,nt:unstructured)
-
- # multiple restrictions
- allow jcr:modifyProperties on /apps restriction(rep:ntNames,sling:Folder,nt:unstructured) restriction(rep:itemNames,prop1,prop2)
-
- # restrictions with glob patterns
- allow jcr:addChildNodes on /apps,/content restriction(rep:glob,/cat,/cat/,cat)
- allow jcr:addChildNodes on /apps,/content restriction(rep:glob,cat/,*,*cat)
- allow jcr:addChildNodes on /apps,/content restriction(rep:glob,/cat/*,*/cat,*cat/*)
- allow jcr:read on / restriction(rep:glob)
- end
+ # empty rep:glob means "apply to this node but not its children"
+ # (requires o.a.s.jcr.repoinit 1.1.8)
+ allow jcr:something on / restriction(rep:glob)
+end
+
+# Set repository level ACL
+# Setting repository level ACL require
+# o.a.s.repoinit.parser 1.2.0 and
+# o.a.s.jcr.repoinit 1.1.6
+set repository ACL for alice,bob
+ allow jcr:namespaceManagement,jcr:nodeTypeDefinitionManagement
+end
+
+# Set repository level ACL (variant, see SLING-8619)
+# since
+# o.a.s.repoinit.parser 1.2.8 and
+# o.a.s.jcr.repoinit 1.1.14
+set ACL for alice,bob
+ allow jcr:namespaceManagement on :repository
+end
+
+# Set principal-based access control (see SLING-8602)
+# since
+# o.a.s.repoinit.parser 1.2.8 and
+# o.a.s.jcr.repoinit 1.1.14
+# precondition for o.a.s.jcr.repoinit:
+# repository needs to support 'o.a.j.api.security.authorization.PrincipalAccessControlList'
+set principal ACL for alice,bob
+ remove * on /libs,/apps
+ allow jcr:read on /content,/var
+ deny jcr:write on /content/example.com
- # Set principal-based access control on repository level (see SLING-8602)
- # since
- # o.a.s.repoinit.parser 1.2.8 and
- # o.a.s.jcr.repoinit 1.1.14
- # precondition for o.a.s.jcr.repoinit:
- # repository needs to support 'o.a.j.api.security.authorization.PrincipalAccessControlList'
- set principal ACL for alice,bob
- allow jcr:namespaceManagement on :repository
- end
-
- # register namespace requires
- # o.a.s.repoinit.parser 1.0.4
- # and o.a.s.jcr.repoinit 1.0.2
- register namespace ( NSprefix ) uri:someURI/v1.42
+ # Optional nodetypes clause
+ deny jcr:lockManagement on /apps, /content nodetypes sling:Folder, nt:unstructured
- # register nodetypes in CND format
- # (same bundle requirements as register namespaces)
- #
- # The optional << markers are used when embedding
- # this in a Sling provisioning model, to avoid syntax errors
- #
- # The CND instructions are passed as is to the JCR
- # modules, so the full CND syntax is supported.
- #
- register nodetypes
- <<===
- << <slingevent='http://sling.apache.org/jcr/event/1.0'>
- <<
- << [slingevent:Event] > nt:unstructured, nt:hierarchyNode
- << - slingevent:topic (string)
- << - slingevent:properties (binary)
- ===>>
+ # nodetypes clause with restriction clause
+ deny jcr:modifyProperties on /apps, /content nodetypes sling:Folder, nt:unstructured restriction(rep:itemNames,prop1,prop2)
- create user demoUser with password {SHA-256} dc460da4ad72c482231e28e688e01f2778a88ce31a08826899d54ef7183998b5
+ # multi value restriction
+ allow jcr:addChildNodes on /apps restriction(rep:ntNames,sling:Folder,nt:unstructured)
- # disable service user
- create service user deprecated_service_user
- disable service user deprecated_service_user : "Disabled user to make an example"
+ # multiple restrictions
+ allow jcr:modifyProperties on /apps restriction(rep:ntNames,sling:Folder,nt:unstructured) restriction(rep:itemNames,prop1,prop2)
- create service user the-last-one
-
- disable service user svc1 : "This is the message"
+ # restrictions with glob patterns
+ allow jcr:addChildNodes on /apps,/content restriction(rep:glob,/cat,/cat/,cat)
+ allow jcr:addChildNodes on /apps,/content restriction(rep:glob,cat/,*,*cat)
+ allow jcr:addChildNodes on /apps,/content restriction(rep:glob,/cat/*,*/cat,*cat/*)
+ allow jcr:read on / restriction(rep:glob)
+end
- # Groups are supported since version 1.2.4, SLING-8219
- create group since124_A
- create group since124_B with path /path_B
- delete group since124_C
-
- # Manage principals in groups, requires
- # o.a.s.repoinit.parser 1.5.2
- # and o.a.s.jcr.repoinit 1.1.22
- add user1,user2 to group grpA
- remove user3,user5 from group grpB
-
- # ACLs on user homes, requires
- # o.a.s.repoinit.parser 1.4.2
- # o.a.s.jcr.repoinit 1.1.18
- set ACL on home(alice)
- allow jcr:read for alice, bob, carol
- end
+# Set principal-based access control on repository level (see SLING-8602)
+# since
+# o.a.s.repoinit.parser 1.2.8 and
+# o.a.s.jcr.repoinit 1.1.14
+# precondition for o.a.s.jcr.repoinit:
+# repository needs to support 'o.a.j.api.security.authorization.PrincipalAccessControlList'
+set principal ACL for alice,bob
+ allow jcr:namespaceManagement on :repository
+end
- set ACL for bob
- allow jcr:read on home(alice), /another/path, home(larry)
- end
-
- # Set node properties, requires
- # o.a.s.repoinit.parser 1.6.2
- # o.a.s.jcr.repoinit 1.1.24
- #
- # 'set' overwrites any existing value while
- # 'default' only sets the property if not set yet
- #
- # The paths must exist first, see "create path"
- set properties on /pathA, /path/B
- set sling:ResourceType{String} to /x/y/z
- default someInteger{Long} to 42
- set someFlag{Boolean} to true
- default someDate{Date} to "2020-03-19T11:39:33.437+05:30"
- set quotedMix to "quoted", non-quoted, "the last \" one"
- end
+# register namespace requires
+# o.a.s.repoinit.parser 1.0.4
+# and o.a.s.jcr.repoinit 1.0.2
+register namespace ( NSprefix ) uri:someURI/v1.42
+
+# register nodetypes in CND format
+# (same bundle requirements as register namespaces)
+#
+# The optional << markers are used when embedding
+# this in a Sling provisioning model, to avoid syntax errors
+#
+# The CND instructions are passed as is to the JCR
+# modules, so the full CND syntax is supported.
+#
+register nodetypes
+<<===
+<< <slingevent='http://sling.apache.org/jcr/event/1.0'>
+<<
+<< [slingevent:Event] > nt:unstructured, nt:hierarchyNode
+<< - slingevent:topic (string)
+<< - slingevent:properties (binary)
+===>>
+
+create user demoUser with password {SHA-256} dc460da4ad72c482231e28e688e01f2778a88ce31a08826899d54ef7183998b5
+
+# disable service user
+create service user deprecated_service_user
+disable service user deprecated_service_user : "Disabled user to make an example"
+
+create service user the-last-one
+
+disable service user svc1 : "This is the message"
+
+# Groups are supported since version 1.2.4, SLING-8219
+create group since124_A
+create group since124_B with path /path_B
+delete group since124_C
+
+# Manage principals in groups, requires
+# o.a.s.repoinit.parser 1.5.2
+# and o.a.s.jcr.repoinit 1.1.22
+add user1,user2 to group grpA
+remove user3,user5 from group grpB
+
+# ACLs on user homes, requires
+# o.a.s.repoinit.parser 1.4.2
+# o.a.s.jcr.repoinit 1.1.18
+set ACL on home(alice)
+ allow jcr:read for alice, bob, carol
+end
+
+set ACL for bob
+ allow jcr:read on home(alice), /another/path, home(larry)
+end
+
+# Set node properties, requires
+# o.a.s.repoinit.parser 1.6.2
+# o.a.s.jcr.repoinit 1.1.24
+#
+# 'set' overwrites any existing value while
+# 'default' only sets the property if not set yet
+#
+# The paths must exist first, see "create path"
+set properties on /pathA, /path/B
+ set sling:ResourceType{String} to /x/y/z
+ default someInteger{Long} to 42
+ set someFlag{Boolean} to true
+ default someDate{Date} to "2020-03-19T11:39:33.437+05:30"
+ set quotedMix to "quoted", non-quoted, "the last \" one"
+end
+</code></pre>
</pre>
-<h2><a href="#providing-repoinit-statements-from-the-sling-provisioning-model-or-other-urls" name="providing-repoinit-statements-from-the-sling-provisioning-model-or-other-urls">Providing repoinit statements from the Sling provisioning model or other URLs</a></h2>
+<h2><a href="#providing-repoinit-statements-from-the-sling-provisioning-model-or-other-urls" id="providing-repoinit-statements-from-the-sling-provisioning-model-or-other-urls">Providing repoinit statements from the Sling provisioning model or other URLs</a></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>
<pre class="language-no-highlight">
@@ -328,37 +328,37 @@
</pre>
<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><a href="#references-to-sling-provisioning-model-additional-sections" name="references-to-sling-provisioning-model-additional-sections">References to Sling Provisioning Model additional sections</a></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>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 (<em>text.url,text.format,model.section.name</em>) are used.</p>
+<h3><a href="#references-to-sling-provisioning-model-additional-sections" id="references-to-sling-provisioning-model-additional-sections">References to Sling Provisioning Model additional sections</a></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>
<pre class="language-no-highlight">
[:repoinit]
create path /repoinit/provisioningModelTest
-
- create service user provisioningModelUser
+<p>create service user provisioningModelUser</p>
</pre>
<p>To read repoinit statements from such an additional provisioning model section, the <code>RepositoryInitializer</code> configuration shown above uses references like</p>
<pre class="language-no-highlight">
model@repoinitTwo:context:/resources/provisioning/model.txt
</pre>
-<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>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><a href="#references-to-urls-providing-raw-repoinit-statements" name="references-to-urls-providing-raw-repoinit-statements">References to URLs providing raw repoinit statements</a></h3>
+<h3><a href="#references-to-urls-providing-raw-repoinit-statements" id="references-to-urls-providing-raw-repoinit-statements">References to URLs providing raw repoinit statements</a></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>
<pre class="language-no-highlight">
raw:classpath://some-repoinit-file.txt
</pre>
<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>
-<h2><a href="#providing-repoinit-statements-from-osgi-factory-configurations" name="providing-repoinit-statements-from-osgi-factory-configurations">Providing repoinit statements from OSGi factory configurations</a></h2>
+<h2><a href="#providing-repoinit-statements-from-osgi-factory-configurations" id="providing-repoinit-statements-from-osgi-factory-configurations">Providing repoinit statements from OSGi factory configurations</a></h2>
<p>From version 1.1.6 of the <code>org.apache.sling.jcr.repoinit</code> bundle, repoinit statements can also be provided by OSGi factory configurations which use the <code>org.apache.sling.jcr.repoinit.RepositoryInitializer</code> factory PID.</p>
<p>Such configurations have two optional fields:</p>
<ul>
- <li>A multi-value <code>references</code> field with each value providing the URL (as a String) of raw repoinit statements.</li>
- <li>A multi-value <code>scripts</code> field with each value providing repoinit statements as plain text in a String.</li>
-</ul></section></div></div>
+<li>A multi-value <code>references</code> field with each value providing the URL (as a String) of raw repoinit statements.</li>
+<li>A multi-value <code>scripts</code> field with each value providing repoinit statements as plain text in a String.</li>
+</ul>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/request-analysis.html b/documentation/bundles/request-analysis.html
index 85ede39..b869bc4 100644
--- a/documentation/bundles/request-analysis.html
+++ b/documentation/bundles/request-analysis.html
@@ -116,42 +116,43 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h2><a href="#introduction" name="introduction">Introduction</a></h2>
+<h2><a href="#introduction" id="introduction">Introduction</a></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="https://github.com/apache/sling-org-apache-sling-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>
+<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><a href="#web-console-integration" name="web-console-integration">Web Console Integration</a></h2>
+<h2><a href="#web-console-integration" id="web-console-integration">Web Console Integration</a></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>
+<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>
+<h2><a href="#analyzing-the-requesttrackertxt-file" id="analyzing-the-requesttrackertxt-file">Analyzing the <code>requesttracker.txt</code> file</a></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>
<pre><code>$ java -jar org.apache.sling.reqanalyzer-0.0.1-SNAPSHOT.jar requesttracker.txt
</code></pre>
<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>
+<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>
+<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>
</div>
</div>
diff --git a/documentation/bundles/resource-access-security.html b/documentation/bundles/resource-access-security.html
index 0bc0261..76da7fc 100644
--- a/documentation/bundles/resource-access-security.html
+++ b/documentation/bundles/resource-access-security.html
@@ -114,76 +114,62 @@
</li>
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
-<div class="row"><div><section><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 [...]
-<h2><a href="#summary" name="summary">Summary</a></h2>
+<div class="row"><div><section><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/LIC [...]
+<h2><a href="#summary" id="summary">Summary</a></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 [...]
-<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><a href="#how-to-use-resourceaccesssecurity" name="how-to-use-resourceaccesssecurity">How to use ResourceAccessSecurity</a></h2>
+<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 [...]
+<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><a href="#how-to-use-resourceaccesssecurity" id="how-to-use-resourceaccesssecurity">How to use ResourceAccessSecurity</a></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 sec [...]
-<h3><a href="#service-properties" name="service-properties">Service properties</a></h3>
+<h3><a href="#service-properties" id="service-properties">Service properties</a></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>
+<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><a href="#how-to-implement-resourceaccessgate" name="how-to-implement-resourceaccessgate">How to implement ResourceAccessGate</a></h3>
+<h3><a href="#how-to-implement-resourceaccessgate" id="how-to-implement-resourceaccessgate">How to implement ResourceAccessGate</a></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>
<pre><code><!-- TODO syntax marker (::java) disabled -->@Override
public boolean hasReadRestrictions(final ResourceResolver resourceResolver) {
- return true;
+ return true;
}
@Override
public GateResult canRead(final Resource resource) {
- GateResult returnValue = GateResult.CANT_DECIDE;
- if( whatever-condition ) {
- returnValue = GateResult.GRANTED;
- }
- else {
- returnValue = GateResult.DENIED;
- }
-
- return returnValue;
+ GateResult returnValue = GateResult.CANT_DECIDE;
+ if( whatever-condition ) {
+ returnValue = GateResult.GRANTED;
+ }
+ else {
+ returnValue = GateResult.DENIED;
+ }
+
+ return returnValue;
}
</code></pre>
<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><a href="#gateresult" name="gateresult">GateResult</a></h3>
+<h3><a href="#gateresult" id="gateresult">GateResult</a></h3>
<p>GateResult does have three states:</p>
<ul>
- <li>GateResult.GRANTED</li>
- <li>GateResult.DENIED</li>
- <li>GateResult.CANT_DECIDE</li>
+<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><a href="#actual-state-of-resourceaccesssecurity" name="actual-state-of-resourceaccesssecurity">Actual state of ResourceAccessSecurity</a></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>
+<h2><a href="#actual-state-of-resourceaccesssecurity" id="actual-state-of-resourceaccesssecurity">Actual state of ResourceAccessSecurity</a></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>
</div>
</div>
diff --git a/documentation/bundles/resource-editor.html b/documentation/bundles/resource-editor.html
index c611a47..38bbe05 100644
--- a/documentation/bundles/resource-editor.html
+++ b/documentation/bundles/resource-editor.html
@@ -114,26 +114,27 @@
</li>
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
-<div class="row"><div><section><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 [...]
+<div class="row"><div><section><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/LIC [...]
<p><img src="http://sling.apache.org/documentation/bundles/resource-editor-screenshot.png" alt="alt text" /></p>
-<h1><a href="#features" name="features">Features</a></h1>
+<h1><a href="#features" id="features">Features</a></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>
+<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><a href="#status" name="status">Status</a></h1>
+<h1><a href="#status" id="status">Status</a></h1>
<p>The features for the node tree are finished so far. Now the work on making properties editable begins.</p>
-<h1><a href="#installation" name="installation">Installation</a></h1>
+<h1><a href="#installation" id="installation">Installation</a></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>
+<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>
</div>
</div>
diff --git a/documentation/bundles/resource-filter.html b/documentation/bundles/resource-filter.html
index a0ed021..4a109c6 100644
--- a/documentation/bundles/resource-filter.html
+++ b/documentation/bundles/resource-filter.html
@@ -116,14 +116,14 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h2><a href="#introduction" name="introduction">Introduction</a></h2>
+<h2><a href="#introduction" id="introduction">Introduction</a></h2>
<p>Resource Filter bundle provides a number of services and utilities to identify and filter resources in a resource tree.</p>
-<h2><a href="#resource-stream" name="resource-stream">Resource Stream</a></h2>
+<h2><a href="#resource-stream" id="resource-stream">Resource Stream</a></h2>
<p><code>ResourceStream</code> is a general utility. It provides two functions. The first is access to a <code>Stream<Resource></code> which traverses a resource and it's subtree. The function takes a <code>Predicate<Resource></code> object which is used to select the child nodes to be part of the traversal.</p>
<pre><code>ResourceStream rs = new ResourceStream(resource);
</code></pre>
<p>In addition there is a <code>getChildren(Predicate)</code> method which returns a filtered list of children of the given resource.</p>
-<h2><a href="#resource-predicate-service" name="resource-predicate-service">Resource Predicate Service</a></h2>
+<h2><a href="#resource-predicate-service" id="resource-predicate-service">Resource Predicate Service</a></h2>
<p><code>ResourcePredicate</code> is a service that allows you to convert a string that defines a simple matching requirements into a <code>Predicate<Resource></code> for use with the Collections and the Streams Java API. In addition it also allows you to add parameters to the underlying context that the script will use.</p>
<pre><code>@Reference
ResourcePredicates rp;
@@ -133,233 +133,110 @@ resourceCollection.stream().filter(predicate).forEach(
resource -> System.out.println(resource.getPath())
);
</code></pre>
-<h2><a href="#resource-filter-stream" name="resource-filter-stream">Resource Filter Stream</a></h2>
+<h2><a href="#resource-filter-stream" id="resource-filter-stream">Resource Filter Stream</a></h2>
<p><code>ResourceFilterStream</code> combines the <code>ResourceStream</code> functionality with the <code>ResourcePredicates</code> service to provide an ability to define a <code>Stream<Resource></code> that follows specific child pages and looks for specific Resources as defined by the resources filter script. The ResourceStreamFilter is access by adaption.</p>
<pre><code>ResourceFilterStream rfs = resource.adaptTo(ResourceFilterStream.class);
rfs
- .setBranchSelector("[jcr:primaryType] == 'cq:Page'")
- .setChildSelector("[jcr:content/sling:resourceType] != 'apps/components/page/folder'")
+ .setBranchSelector("[jcr:primaryType] == 'cq:Page'")
+ .setChildSelector("[jcr:content/sling:resourceType] != 'apps/components/page/folder'")
.stream()
.collect(Collections.toList());
</code></pre>
-<h2><a href="#resourcefilter-scripting" name="resourcefilter-scripting">ResourceFilter Scripting</a></h2>
+<h2><a href="#resourcefilter-scripting" id="resourcefilter-scripting">ResourceFilter Scripting</a></h2>
<p>To ease the creation of a <code>Predicate<Resource></code> a scripting implementation was developed that was designed to be visually similar to JCRSQL use of property identification where a property is compared to one or more values.</p>
-<h3><a href="#operators" name="operators">Operators</a></h3>
+<h3><a href="#operators" id="operators">Operators</a></h3>
<table>
- <thead>
- <tr>
- <th>Name </th>
- <th>Comparison Type </th>
- <th>Description </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>and </td>
- <td>NA </td>
- <td>Logical AND </td>
- </tr>
- <tr>
- <td>&& </td>
- <td>NA </td>
- <td>Logical AND </td>
- </tr>
- <tr>
- <td>or </td>
- <td>NA </td>
- <td>Logical OR </td>
- </tr>
- <tr>
- <td>|| </td>
- <td>NA </td>
- <td>Logical OR </td>
- </tr>
- <tr>
- <td>== </td>
- <td>String </td>
- <td>Equal operator for Strings </td>
- </tr>
- <tr>
- <td>< </td>
- <td>Number </td>
- <td>Less than operator for Numbers </td>
- </tr>
- <tr>
- <td><= </td>
- <td>Number </td>
- <td>Less than or equal operator for Numbers </td>
- </tr>
- <tr>
- <td>> </td>
- <td>Number </td>
- <td>Greater than operator for Numbers </td>
- </tr>
- <tr>
- <td>>= </td>
- <td>Number </td>
- <td>Greater than or equal operator for Numbers </td>
- </tr>
- <tr>
- <td>!= </td>
- <td>String </td>
- <td>Is not equal to for Strings </td>
- </tr>
- <tr>
- <td>~= </td>
- <td>String - Regex </td>
- <td>Regex match against String </td>
- </tr>
- <tr>
- <td>less than </td>
- <td>Number </td>
- <td>less than operator for Numbers </td>
- </tr>
- <tr>
- <td>greater than </td>
- <td>Number </td>
- <td>greater than operator for Numbers </td>
- </tr>
- <tr>
- <td>is </td>
- <td>String </td>
- <td>Equal operator for Strings </td>
- </tr>
- <tr>
- <td>is not </td>
- <td>String </td>
- <td>Is not equal operator for Strings </td>
- </tr>
- <tr>
- <td>like </td>
- <td>String - Regex </td>
- <td>Regex match against String </td>
- </tr>
- <tr>
- <td>is like </td>
- <td>String - Regex </td>
- <td>Regex match against String </td>
- </tr>
- <tr>
- <td>not like </td>
- <td>String - Regex </td>
- <td>Regex does not match String </td>
- </tr>
- <tr>
- <td>contains </td>
- <td>String[] </td>
- <td>String[] contains all of items </td>
- </tr>
- <tr>
- <td>contains not </td>
- <td>String[] </td>
- <td>String[] does not contain all of the items </td>
- </tr>
- <tr>
- <td>contains any </td>
- <td>String[] </td>
- <td>String[] contains at least one of items </td>
- </tr>
- <tr>
- <td>contains not any </td>
- <td>String[] </td>
- <td>String[] does not contain any of the items </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Name </th><th> Comparison Type </th><th> Description </th></tr>
+</thead>
+<tbody>
+<tr><td> and </td><td> NA </td><td> Logical AND </td></tr>
+<tr><td> && </td><td> NA </td><td> Logical AND </td></tr>
+<tr><td> or </td><td> NA </td><td> Logical OR </td></tr>
+<tr><td>|| </td><td> NA </td><td> Logical OR </td></tr>
+<tr><td> == </td><td> String </td><td> Equal operator for Strings </td></tr>
+<tr><td> < </td><td> Number </td><td> Less than operator for Numbers </td></tr>
+<tr><td> <= </td><td> Number </td><td> Less than or equal operator for Numbers </td></tr>
+<tr><td> > </td><td> Number </td><td> Greater than operator for Numbers </td></tr>
+<tr><td> >= </td><td> Number </td><td> Greater than or equal operator for Numbers </td></tr>
+<tr><td> != </td><td> String </td><td> Is not equal to for Strings </td></tr>
+<tr><td> ~= </td><td> String - Regex </td><td> Regex match against String </td></tr>
+<tr><td> less than </td><td> Number </td><td> less than operator for Numbers </td></tr>
+<tr><td> greater than </td><td> Number </td><td> greater than operator for Numbers </td></tr>
+<tr><td> is </td><td> String </td><td> Equal operator for Strings </td></tr>
+<tr><td> is not </td><td> String </td><td> Is not equal operator for Strings </td></tr>
+<tr><td> like </td><td> String - Regex </td><td> Regex match against String </td></tr>
+<tr><td> is like </td><td> String - Regex </td><td> Regex match against String </td></tr>
+<tr><td> not like </td><td> String - Regex </td><td> Regex does not match String </td></tr>
+<tr><td> contains </td><td> String[] </td><td> String[] contains all of items </td></tr>
+<tr><td> contains not </td><td> String[] </td><td> String[] does not contain all of the items </td></tr>
+<tr><td> contains any </td><td> String[] </td><td> String[] contains at least one of items </td></tr>
+<tr><td> contains not any </td><td> String[] </td><td> String[] does not contain any of the items </td></tr>
+</tbody>
</table>
-<h3><a href="#logical-operators" name="logical-operators">Logical Operators</a></h3>
+<h3><a href="#logical-operators" id="logical-operators">Logical Operators</a></h3>
<p>The 'and' and 'or' operators are logical operators that string together conditions. 'And' operators take precedence. 'Or' operators evaluate from left to right</p>
-<h3><a href="#values" name="values">Values</a></h3>
+<h3><a href="#values" id="values">Values</a></h3>
<p>Values for comparison are obtained through multiple methods</p>
<table>
- <thead>
- <tr>
- <th>Method </th>
- <th>Description </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>Literal </td>
- <td>Single(') or double (") quoted text in the query will be interpreted as a String. Boolean values of <em>true</em> and <em>false</em> will be translated to a String. </td>
- </tr>
- <tr>
- <td>Property </td>
- <td>A String between square brackets '[',']'s will be interpreted as a property value and will be retrieved from the Resource using the get method </td>
- </tr>
- <tr>
- <td>Function </td>
- <td>A string followed by parens containing an optional comma separated list of values. </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Method </th><th> Description </th></tr>
+</thead>
+<tbody>
+<tr><td> Literal </td><td> Single(') or double (") quoted text in the query will be interpreted as a String. Boolean values of <em>true</em> and <em>false</em> will be translated to a String. </td></tr>
+<tr><td> Property </td><td> A String between square brackets '[',']'s will be interpreted as a property value and will be retrieved from the Resource using the get method </td></tr>
+<tr><td> Function </td><td> A string followed by parens containing an optional comma separated list of values. </td></tr>
+</tbody>
</table>
-<h3><a href="#types" name="types">Types</a></h3>
+<h3><a href="#types" id="types">Types</a></h3>
<p>All types are converted to either a String or a Number. For direct equivalence the comparison is done as a String. For relational comparisons the object will be adapted to a number.</p>
-<h3><a href="#dates-instants" name="dates-instants">Dates/Instants</a></h3>
+<h3><a href="#datesinstants" id="datesinstants">Dates/Instants</a></h3>
<p>Dates are special, there are multiple ways to enter a date.</p>
<p>In line, as part of the query, a date can be identified as a string that conforms to a standard ISO-8601 date time.</p>
<blockquote>
- <p>'2013-08-08T16:32:59.000'</p>
- <p>'2013-08-08T16:32:59'</p>
- <p>'2013-08-08T16:32'</p>
+<p>'2013-08-08T16:32:59.000'</p>
+<p>'2013-08-08T16:32:59'</p>
+<p>'2013-08-08T16:32'</p>
</blockquote>
<p>Are all valid date representations that are defaulting to the UTC timezone.</p>
<p>For a ISO8601 date with timezone offset use the date function.</p>
<blockquote>
- <p>date('2013-08-08T16:32:59.000+02:00')</p>
+<p>date('2013-08-08T16:32:59.000+02:00')</p>
</blockquote>
<p>If you need a different date format then the date function can accommodate that</p>
<blockquote>
- <p>date('2013-08-08','yyyy-MM-dd')</p>
+<p>date('2013-08-08','yyyy-MM-dd')</p>
</blockquote>
-<p>Or you can add your own custom Function </p>
+<p>Or you can add your own custom Function</p>
<p>Dates are transitionally represented as a java.util.Instant which is then converted to a String in ISO-8601 format or as a Long number based on the type of comparison. The number representing the time in milliseconds since the EPOCH UTC region</p>
-<h3><a href="#functions" name="functions">Functions</a></h3>
+<h3><a href="#functions" id="functions">Functions</a></h3>
<p>Functions provide additional functionality to the Filter language. A Function is written in the format</p>
<blockquote>
- <p>string '(' comma, separated, list() ')'</p>
+<p>string '(' comma, separated, list() ')'</p>
</blockquote>
<p>OOTB Functions are:</p>
<table>
- <thead>
- <tr>
- <th>Name </th>
- <th>Arguments </th>
- <th>Returns </th>
- <th>Description </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>name </td>
- <td>none </td>
- <td>String </td>
- <td>Provides the name of the resource </td>
- </tr>
- <tr>
- <td>date </td>
- <td>0 - 2 </td>
- <td>Instant </td>
- <td>First argument is string representation of the date, second argument is a standard Java DateFormat representation of the value. No argument returns the current time. </td>
- </tr>
- <tr>
- <td>path </td>
- <td>none </td>
- <td>String </td>
- <td>path of the tested resource </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Name </th><th> Arguments </th><th> Returns </th><th> Description </th></tr>
+</thead>
+<tbody>
+<tr><td> name </td><td> none </td><td> String </td><td> Provides the name of the resource </td></tr>
+<tr><td> date </td><td> 0 - 2 </td><td> Instant </td><td> First argument is string representation of the date, second argument is a standard Java DateFormat representation of the value. No argument returns the current time. </td></tr>
+<tr><td> path </td><td> none </td><td> String </td><td> path of the tested resource </td></tr>
+</tbody>
</table>
-<h3><a href="#parameters" name="parameters">Parameters</a></h3>
+<h3><a href="#parameters" id="parameters">Parameters</a></h3>
<p>The ResourceFilter and ResourceFilteStream can have key value pairs added so that the values may be used as part of the script resolution. Parameters are accessed by using the dollar sign '$'</p>
<pre><code>rfs.setBranchSelector("[jcr:content/sling:resourceType] != $type").addParam("type","apps/components/page/folder");
</code></pre>
-<h2><a href="#optimizing-traversals" name="optimizing-traversals">Optimizing Traversals</a></h2>
+<h2><a href="#optimizing-traversals" id="optimizing-traversals">Optimizing Traversals</a></h2>
<p>Similar to indexing in a query there are strategies that you can do within a tree traversal so that traversals can be done in an efficient manner across a large number of resources. The following strategies will assist in traversal optimization.</p>
-<h3><a href="#limit-traversal-paths" name="limit-traversal-paths">Limit traversal paths</a></h3>
+<h3><a href="#limit-traversal-paths" id="limit-traversal-paths">Limit traversal paths</a></h3>
<p>In a naive implementation of a tree traversal the traversal occurs across all nodes in the tree regardless of the ability of the tree structure to support the nodes that are being looked for. An example of this is a tree of Page resources that have have a child node of jcr:content which contains a subtree of data to define the page structure. If the jcr:content node is not capable of having a child resource of type Page and the goal of the traversal is to identify Page resources that [...]
-<h3><a href="#limit-memory-consumption" name="limit-memory-consumption">Limit memory consumption</a></h3>
-<p>The instantiation of a Resource object from the underlying ResourceResolver is a non trivial consumption of memory. When the focus of a tree traversal is obtaining information from thousands of Resources, an effective method is to extract the information as part of the stream processing or utilizing the forEach method of the ResourceStream object which allows the resource to be garbage collected in an efficient manner. </p></section></div></div>
+<h3><a href="#limit-memory-consumption" id="limit-memory-consumption">Limit memory consumption</a></h3>
+<p>The instantiation of a Resource object from the underlying ResourceResolver is a non trivial consumption of memory. When the focus of a tree traversal is obtaining information from thousands of Resources, an effective method is to extract the information as part of the stream processing or utilizing the forEach method of the ResourceStream object which allows the resource to be garbage collected in an efficient manner.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/resource-merger.html b/documentation/bundles/resource-merger.html
index 47eece5..1cefdf8 100644
--- a/documentation/bundles/resource-merger.html
+++ b/documentation/bundles/resource-merger.html
@@ -116,95 +116,63 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h1><a href="#introduction" name="introduction">Introduction</a></h1>
+<h1><a href="#introduction" id="introduction">Introduction</a></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>
+<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>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>
+<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>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><a href="#merge-properties" name="merge-properties">Merge Properties</a></h1>
+<h1><a href="#merge-properties" id="merge-properties">Merge Properties</a></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 m [...]
- </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 preceding 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 child resource order is not sufficient (see below).</td>
- </tr>
- </tbody>
+<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 [...]
+<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 preceding 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 child resource order is not sufficient (see below).</td></tr>
+</tbody>
</table>
-<h1><a href="#child-resource-order" name="child-resource-order">Child Resource Order</a></h1>
+<h1><a href="#child-resource-order" id="child-resource-order">Child Resource Order</a></h1>
<p>For a merged resource the order of its child resources is the following: First the ones from the underlying resource, then the ones from the overlying resources.</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 some more examples for more complicated merges look at <a href="https://issues.apache.org/jira/browse/SLING-6956">SLING-6956</a>). For example:</p>
<pre><code>base/
- +--child1
- +--child3
- +--child5
-
+ +--child1
+ +--child3
+ +--child5
+
overlay/
- +--child2
- +--child3
- +--child4
-
+ +--child2
+ +--child3
+ +--child4
+
resulting order: child1, child5, child2, child3, child4
</code></pre>
<p>You can overwrite that behaviour by leveraging the <code>sling:orderBefore</code> property.</p>
-<h1><a href="#resource-pickers" name="resource-pickers">Resource Pickers</a></h1>
-<h2><a href="#merging-resource-picker-overlay-approach-" name="merging-resource-picker-overlay-approach-">Merging Resource Picker (Overlay approach)</a></h2>
+<h1><a href="#resource-pickers" id="resource-pickers">Resource Pickers</a></h1>
+<h2><a href="#merging-resource-picker-overlay-approach" id="merging-resource-picker-overlay-approach">Merging Resource Picker (Overlay approach)</a></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>
+<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><a href="#example" name="example">Example</a></h3>
+<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><a href="#example" id="example">Example</a></h3>
<pre><code>/libs/sling/example (nt:folder)
+-- sling:resourceType = "some/resource/type"
+-- child1 (nt:folder)
@@ -213,7 +181,7 @@ resulting order: child1, child5, child2, child3, child4
| +-- property1 = "property from /libs/sling/example/child2"
+-- child3 (nt:folder)
| +-- property1 = "property from /libs/sling/example/child3"
-
+
/apps/sling/example (sling:Folder)
+-- property1 = "property added in apps"
@@ -234,29 +202,17 @@ resulting order: child1, child5, child2, child3, child4
| +-- property1 = "property from /libs/sling/example/child3"
| +-- property2 = "property from /apps/sling/example/child3"
</code></pre>
-<h2><a href="#overriding-resource-picker-override-approach-" name="overriding-resource-picker-override-approach-">Overriding Resource Picker (Override approach)</a></h2>
+<h2><a href="#overriding-resource-picker-override-approach" id="overriding-resource-picker-override-approach">Overriding Resource Picker (Override approach)</a></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>
+<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">SL [...]
+</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><a href="#example" name="example">Example</a></h3>
+<h3><a href="#example" id="example">Example</a></h3>
<pre><code>/apps/sling/base (nt:folder)
+-- child1 (nt:folder)
| +-- property1 = "property from /libs/sling/example/child1"
@@ -264,10 +220,10 @@ resulting order: child1, child5, child2, child3, child4
| +-- property1 = "property from /libs/sling/example/child2"
+-- child3 (nt:folder)
| +-- property1 = "property from /libs/sling/example/child3"
-
+
/apps/sling/example (sling:Folder)
- +-- sling:resourceSuperType = "/apps/sling/base"
+ +-- sling:resourceSuperType = "/apps/sling/base"
+-- property1 = "property added in /apps/sling/example"
+-- child1 (nt:folder)
| +-- sling:hideResource = true
@@ -285,7 +241,8 @@ resulting order: child1, child5, child2, child3, child4
+-- child3 (nt:folder)
| +-- property1 = "property from /libs/sling/example/child3"
| +-- property2 = "property from /apps/sling/example/child3"
-</code></pre></section></div></div>
+</code></pre>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/scheduler-service-commons-scheduler.html b/documentation/bundles/scheduler-service-commons-scheduler.html
index 573d0a0..f78c91c 100644
--- a/documentation/bundles/scheduler-service-commons-scheduler.html
+++ b/documentation/bundles/scheduler-service-commons-scheduler.html
@@ -118,10 +118,10 @@
<div class="note">
The notion of Job used in this context is a different one than the one used for <a href="/documentation/bundles/apache-sling-eventing-and-job-handling.html">Sling Jobs</a>. The main difference is that a scheduler's job is not persisted.
</div>
-<h2><a href="#examples-of-jobs-that-are-scheduled-by-leveraging-the-whiteboard-pattern" name="examples-of-jobs-that-are-scheduled-by-leveraging-the-whiteboard-pattern">Examples of jobs that are scheduled by leveraging the whiteboard pattern</a></h2>
+<h2><a href="#examples-of-jobs-that-are-scheduled-by-leveraging-the-whiteboard-pattern" id="examples-of-jobs-that-are-scheduled-by-leveraging-the-whiteboard-pattern">Examples of jobs that are scheduled by leveraging the whiteboard pattern</a></h2>
<p>The following examples show you how to define and schedule a job by leveraging the whiteboard pattern.</p>
-<h3><a href="#scheduling-with-a-cron-expression" name="scheduling-with-a-cron-expression">Scheduling with a cron expression</a></h3>
-<p>The cron expression format is described in the <a href="http://www.quartz-scheduler.org/documentation/quartz-2.x/tutorials/crontrigger.html#format">Quartz Cron Documentation</a> and requires either 6 or 7 fields separated by white space. The first field always indicates the second (not the minute). </p>
+<h3><a href="#scheduling-with-a-cron-expression" id="scheduling-with-a-cron-expression">Scheduling with a cron expression</a></h3>
+<p>The cron expression format is described in the <a href="http://www.quartz-scheduler.org/documentation/quartz-2.x/tutorials/crontrigger.html#format">Quartz Cron Documentation</a> and requires either 6 or 7 fields separated by white space. The first field always indicates the second (not the minute).</p>
<p>The following job is executed every minute by setting <em>scheduler.expression</em> to the cron expression <code>0 * * * * ?</code>:</p>
<pre><code>package sling.docu.examples;
@@ -136,16 +136,16 @@ import org.apache.felix.scr.annotations.Property;
@Property( name = "scheduler.expression", value = "0 * * * * ?")
public class ScheduledCronJob implements Runnable {
- /** Default log. */
+ /** Default log. */
protected final Logger log = LoggerFactory.getLogger(this.getClass());
-
+
public void run() {
- log.info("Executing a cron job (job#1) through the whiteboard pattern");
+ log.info("Executing a cron job (job#1) through the whiteboard pattern");
}
//
}
</code></pre>
-<h3><a href="#scheduling-at-periodic-times" name="scheduling-at-periodic-times">Scheduling at periodic times</a></h3>
+<h3><a href="#scheduling-at-periodic-times" id="scheduling-at-periodic-times">Scheduling at periodic times</a></h3>
<p>The following job is executed every ten seconds by setting <em>scheduler.period</em> to <em>10</em>:</p>
<pre><code>package sling.docu.examples;
@@ -160,20 +160,20 @@ import org.apache.felix.scr.annotations.Property;
@Property( name = "scheduler.period", longValue = 10)
public class ScheduledPeriodicJob implements Runnable {
- /** Default log. */
+ /** Default log. */
protected final Logger log = LoggerFactory.getLogger(this.getClass());
-
+
public void run() {
- log.info("Executing a perodic job (job#2) through the whiteboard pattern");
+ log.info("Executing a perodic job (job#2) through the whiteboard pattern");
}
//
}
</code></pre>
-<h3><a href="#preventing-concurrent-execution" name="preventing-concurrent-execution">Preventing concurrent execution</a></h3>
+<h3><a href="#preventing-concurrent-execution" id="preventing-concurrent-execution">Preventing concurrent execution</a></h3>
<p>By default, jobs can be concurrently executed. To prevent this, set the <em>scheduler.concurrent</em> property to <em>false</em>:</p>
<pre><code>@Property(name="scheduler.concurrent", boolValue=false)
</code></pre>
-<h3><a href="#scheduling-the-job-just-once-in-a-cluster" name="scheduling-the-job-just-once-in-a-cluster">Scheduling the job just once in a cluster</a></h3>
+<h3><a href="#scheduling-the-job-just-once-in-a-cluster" id="scheduling-the-job-just-once-in-a-cluster">Scheduling the job just once in a cluster</a></h3>
<p>If the same code/same services is executed on multiple nodes within a cluster, the same job might be scheduled on each instance. If this is not desired, the job can either be bound to the leader of the topology or a single instance (which one this is, is not further defined):</p>
<pre><code>@Property(name="scheduler.runOn", value="LEADER");
</code></pre>
@@ -181,37 +181,37 @@ public class ScheduledPeriodicJob implements Runnable {
<pre><code>@Property(name="scheduler.runOn", value="SINGLE");
</code></pre>
<p>Since in contrast to <a href="/documentation/bundles/apache-sling-eventing-and-job-handling.html">Sling Jobs</a> the scheduler queue is only held in memory, there will be no distribution of jobs. So if job '1' was scheduled on instance 'a' with the option to run on the leader only, but the leader is instance 'b', which hasn't the job in the queue, the job will never be executed by any instance!</p>
-<h2><a href="#the-scheduler-api" name="the-scheduler-api">The Scheduler API</a></h2>
+<h2><a href="#the-scheduler-api" id="the-scheduler-api">The Scheduler API</a></h2>
<p>The scheduler has methods to execute jobs periodically, based on a cron expression or at a given time. For more details please refer to the <a href="http://sling.apache.org/apidocs/sling6/org/apache/sling/commons/scheduler/Scheduler.html">javadocs</a>.</p>
-<h2><a href="#examples-of-scheduled-jobs-registered-through-the-scheduler-api" name="examples-of-scheduled-jobs-registered-through-the-scheduler-api">Examples of scheduled jobs registered through the scheduler API</a></h2>
+<h2><a href="#examples-of-scheduled-jobs-registered-through-the-scheduler-api" id="examples-of-scheduled-jobs-registered-through-the-scheduler-api">Examples of scheduled jobs registered through the scheduler API</a></h2>
<p>The following examples show you how to define and schedule a job that is registered through the scheduler api.</p>
-<h3><a href="#defining-the-job" name="defining-the-job">Defining the job</a></h3>
+<h3><a href="#defining-the-job" id="defining-the-job">Defining the job</a></h3>
<p>The following code sample defines a <em>job</em> object that writes a message in the logs:</p>
<pre><code>final Runnable job = new Runnable() {
- public void run() {
- log.info("Executing the job");
- }
+ public void run() {
+ log.info("Executing the job");
+ }
};
</code></pre>
-<h3><a href="#scheduling-with-a-cron-expression" name="scheduling-with-a-cron-expression">Scheduling with a cron expression</a></h3>
+<h3><a href="#scheduling-with-a-cron-expression" id="scheduling-with-a-cron-expression">Scheduling with a cron expression</a></h3>
<p>To execute the job as defined above at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday, you can use the <em>addJob()</em> method with the following parameters:</p>
<pre><code>String schedulingExpression = "0 15 10 ? * MON-FRI";
this.scheduler.addJob("myJob", job, null, schedulingExpression, true);
</code></pre>
-<p>Refer to http://www.docjar.com/docs/api/org/quartz/CronTrigger.html to define more scheduling expressions.</p>
-<h3><a href="#scheduling-at-periodic-times" name="scheduling-at-periodic-times">Scheduling at periodic times</a></h3>
+<p>Refer to http://www.docjar.com/docs/api/org/quartz/CronTrigger.html to define more scheduling expressions.</p>
+<h3><a href="#scheduling-at-periodic-times" id="scheduling-at-periodic-times">Scheduling at periodic times</a></h3>
<p>To execute the job as defined above every 3 minutes (180 seconds), you can use the <em>addPeriodicJob()</em> method with the following parameters:</p>
<pre><code>long period = 3*60; //the period is expressed in seconds
this.scheduler.addPeriodicJob("myJob", job, null, period, true);
</code></pre>
-<h3><a href="#scheduling-at-a-given-time" name="scheduling-at-a-given-time">Scheduling at a given time</a></h3>
+<h3><a href="#scheduling-at-a-given-time" id="scheduling-at-a-given-time">Scheduling at a given time</a></h3>
<p>To execute the job as defined above at a specific date (on January 10th 2020), you can use the <em>fireJobAt()</em> method with the following parameters:</p>
<pre><code>SimpleDateFormat formatter = new SimpleDateFormat("yyyy/MM/dd");
String date = "2020/01/10";
java.util.Date fireDate = formatter.parse(date);
this.scheduler.fireJobAt("myJob", job, null, fireDate);
</code></pre>
-<h3><a href="#a-service-scheduling-the-job-based-on-3-different-kinds-of-scheduling" name="a-service-scheduling-the-job-based-on-3-different-kinds-of-scheduling">A service scheduling the job based on 3 different kinds of scheduling</a></h3>
+<h3><a href="#a-service-scheduling-the-job-based-on-3-different-kinds-of-scheduling" id="a-service-scheduling-the-job-based-on-3-different-kinds-of-scheduling">A service scheduling the job based on 3 different kinds of scheduling</a></h3>
<p>The code implementing a service that simultaneously executes the job based on 3 different kinds of scheduling can look as follows:</p>
<pre><code>package sling.docu.examples;
@@ -233,60 +233,60 @@ import org.apache.felix.scr.annotations.Reference;
*/
@Component
public class HelloWorldScheduledService {
-
+
/** Default log. */
protected final Logger log = LoggerFactory.getLogger(this.getClass());
-
+
/** The scheduler for rescheduling jobs. */
@Reference
private Scheduler scheduler;
-
+
protected void activate(ComponentContext componentContext) throws Exception {
//case 1: with addJob() method: executes the job every minute
- String schedulingExpression = "0 * * * * ?";
- String jobName1 = "case1";
- Map<String, Serializable> config1 = new HashMap<String, Serializable>();
- boolean canRunConcurrently = true;
+ String schedulingExpression = "0 * * * * ?";
+ String jobName1 = "case1";
+ Map<String, Serializable> config1 = new HashMap<String, Serializable>();
+ boolean canRunConcurrently = true;
final Runnable job1 = new Runnable() {
public void run() {
- log.info("Executing job1");
+ log.info("Executing job1");
}
};
try {
- this.scheduler.addJob(jobName1, job1, config1, schedulingExpression, canRunConcurrently);
+ this.scheduler.addJob(jobName1, job1, config1, schedulingExpression, canRunConcurrently);
} catch (Exception e) {
job1.run();
}
-
+
//case 2: with addPeriodicJob(): executes the job every 3 minutes
String jobName2 = "case2";
- long period = 180;
- Map<String, Serializable> config2 = new HashMap<String, Serializable>();
+ long period = 180;
+ Map<String, Serializable> config2 = new HashMap<String, Serializable>();
final Runnable job2 = new Runnable() {
public void run() {
- log.info("Executing job2");
+ log.info("Executing job2");
}
};
try {
- this.scheduler.addPeriodicJob(jobName2, job2, config2, period, canRunConcurrently);
+ this.scheduler.addPeriodicJob(jobName2, job2, config2, period, canRunConcurrently);
} catch (Exception e) {
job2.run();
}
//case 3: with fireJobAt(): executes the job at a specific date (date of deployment + delay of 30 seconds)
String jobName3 = "case3";
- final long delay = 30*1000;
- final Date fireDate = new Date();
+ final long delay = 30*1000;
+ final Date fireDate = new Date();
fireDate.setTime(System.currentTimeMillis() + delay);
- Map<String, Serializable> config3 = new HashMap<String, Serializable>();
+ Map<String, Serializable> config3 = new HashMap<String, Serializable>();
final Runnable job3 = new Runnable() {
public void run() {
- log.info("Executing job3 at date: {} with a delay of: {} seconds", fireDate, delay/1000);
+ log.info("Executing job3 at date: {} with a delay of: {} seconds", fireDate, delay/1000);
}
};
try {
- this.scheduler.fireJobAt(jobName3, job3, config3, fireDate);
+ this.scheduler.fireJobAt(jobName3, job3, config3, fireDate);
} catch (Exception e) {
job3.run();
}
@@ -297,7 +297,8 @@ public class HelloWorldScheduledService {
}
}
-</code></pre></section></div></div>
+</code></pre>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/scripting.html b/documentation/bundles/scripting.html
index ce68e2e..9e0321b 100644
--- a/documentation/bundles/scripting.html
+++ b/documentation/bundles/scripting.html
@@ -116,107 +116,36 @@
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
<div class="row"><div><section><p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h2><a href="#sling-scripting-engines" name="sling-scripting-engines">Sling Scripting Engines</a></h2>
+<h2><a href="#sling-scripting-engines" id="sling-scripting-engines">Sling Scripting Engines</a></h2>
<p>Sling Scripting is build around Java Scripting API (JSR 223). It allows the easy development and usage of different scripting (aka templating) engines.</p>
<p>The script engines are managed in <code>SlingScriptEngineManager</code> (<a href="https://github.com/apache/sling-org-apache-sling-scripting-core">Scripting Core</a>).</p>
<table>
- <thead>
- <tr>
- <th>Engine </th>
- <th>Language Name </th>
- <th>Language Version </th>
- <th>Names </th>
- <th>Extensions </th>
- <th>Mime Types </th>
- <th>GitHub Repo(s) </th>
- <th>Documentation </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><a href="https://freemarker.apache.org">FreeMarker</a> </td>
- <td><code>FreeMarker</code> </td>
- <td><code>freemarker.template.Configuration#getVersion().toString()</code> </td>
- <td><code>FreeMarker</code><br><code>freemarker</code><br>(configurable) </td>
- <td><code>ftl</code><br>(configurable) </td>
- <td><code>text/x-freemarker</code><br>(configurable) </td>
- <td><a href="https://github.com/apache/sling-org-apache-sling-scripting-freemarker">sling-org-apache-sling-scripting-freemarker</a> </td>
- <td> </td>
- </tr>
- <tr>
- <td><a href="http://docs.groovy-lang.org/docs/next/html/documentation/template-engines.html#_gstringtemplateengine">Groovy (GString)</a> </td>
- <td><code>Groovy GString</code> </td>
- <td><code>org.codehaus.groovy.util.ReleaseInfo#getVersion()</code> </td>
- <td><code>GString</code><br><code>gstring</code><br>(configurable) </td>
- <td><code>gst</code><br>(configurable) </td>
- <td>(configurable) </td>
- <td><a href="https://github.com/apache/sling-org-apache-sling-scripting-groovy">sling-org-apache-sling-scripting-groovy</a> </td>
- <td> </td>
- </tr>
- <tr>
- <td><a href="https://github.com/adobe/htl-spec">HTL</a> </td>
- <td><code>The HTL Templating Language</code> </td>
- <td><code>1.4</code> </td>
- <td><code>htl</code><br><code>HTL</code><br><code>sightly</code> </td>
- <td><code>html</code> </td>
- <td> </td>
- <td><a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly">sling-org-apache-sling-scripting-sightly</a> </td>
- <td><a href="/documentation/bundles/scripting/scripting-htl.html">Scripting HTL</a> </td>
- </tr>
- <tr>
- <td>Java </td>
- <td><code>Java Servlet Compiler</code> </td>
- <td><code>1.5</code></td>
- <td><code>java</code><br><code>Java</code> </td>
- <td><code>java</code> </td>
- <td> </td>
- <td><a href="https://github.com/apache/sling-org-apache-sling-scripting-java">sling-org-apache-sling-scripting-java</a> </td>
- <td> </td>
- </tr>
- <tr>
- <td>JavaScript </td>
- <td><code>ECMAScript</code> </td>
- <td><code>partial ECMAScript 2015 support</code> </td>
- <td><code>rhino</code><br><code>Rhino</code><br><code>javascript</code><br><code>JavaScript</code><br><code>ecmascript</code><br><code>ECMAScript</code> </td>
- <td><code>esp</code><br><code>ecma</code> </td>
- <td><code>text/ecmascript</code><br><code>text/javascript</code><br><code>application/ecmascript</code><br><code>application/javascript</code> </td>
- <td><a href="https://github.com/apache/sling-org-apache-sling-scripting-javascript">sling-org-apache-sling-scripting-javascript</a> </td>
- <td> </td>
- </tr>
- <tr>
- <td><a href="https://projects.eclipse.org/projects/ee4j.jsp">JSP</a> </td>
- <td><code>Java Server Pages</code> </td>
- <td><code>2.1</code> </td>
- <td><code>jsp</code><br><code>JSP</code> </td>
- <td><code>jsp</code><br><code>jspf</code><br><code>jspx</code> </td>
- <td> </td>
- <td><a href="https://github.com/apache/sling-org-apache-sling-scripting-jsp">sling-org-apache-sling-scripting-jsp</a> </td>
- <td><a href="/documentation/bundles/scripting/scripting-jsp.html">Scripting JSP</a> </td>
- </tr>
- <tr>
- <td><a href="https://www.thymeleaf.org">Thymeleaf</a> </td>
- <td><code>Thymeleaf</code> </td>
- <td><code>version</code> from <a href="https://github.com/thymeleaf/thymeleaf/blob/3.0-master/src/main/resources/org/thymeleaf/thymeleaf.properties"><code>/org/thymeleaf/thymeleaf.properties</code></a> </td>
- <td><code>Thymeleaf</code><br><code>thymeleaf</code><br>(configurable) </td>
- <td><code>html</code><br>(configurable) </td>
- <td><code>text/html</code><br>(configurable) </td>
- <td><a href="https://github.com/apache/sling-org-apache-sling-scripting-thymeleaf">sling-org-apache-sling-scripting-thymeleaf</a> </td>
- <td><a href="/documentation/bundles/scripting/scripting-thymeleaf.html">Scripting Thymeleaf</a> </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Engine </th><th> Language Name </th><th> Language Version </th><th> Names </th><th> Extensions </th><th> Mime Types </th><th> GitHub Repo(s) </th><th> Documentation </th></tr>
+</thead>
+<tbody>
+<tr><td> <a href="https://freemarker.apache.org">FreeMarker</a> </td><td> <code>FreeMarker</code> </td><td> <code>freemarker.template.Configuration#getVersion().toString()</code> </td><td> <code>FreeMarker</code><br><code>freemarker</code><br>(configurable) </td><td> <code>ftl</code><br>(configurable) </td><td> <code>text/x-freemarker</code><br>(configurable) </td><td> <a href="https://github.com/apache/sling-org-apache-sling-scripting-freemarker">sling-org-apache-sling-scripting-freemar [...]
+<tr><td> <a href="http://docs.groovy-lang.org/docs/next/html/documentation/template-engines.html#_gstringtemplateengine">Groovy (GString)</a> </td><td> <code>Groovy GString</code> </td><td> <code>org.codehaus.groovy.util.ReleaseInfo#getVersion()</code> </td><td> <code>GString</code><br><code>gstring</code><br>(configurable) </td><td> <code>gst</code><br>(configurable) </td><td> (configurable) </td><td> <a href="https://github.com/apache/sling-org-apache-sling-scripting-groovy">sling-org- [...]
+<tr><td> <a href="https://github.com/adobe/htl-spec">HTL</a> </td><td> <code>The HTL Templating Language</code> </td><td> <code>1.4</code> </td><td> <code>htl</code><br><code>HTL</code><br><code>sightly</code> </td><td> <code>html</code> </td><td> </td><td> <a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly">sling-org-apache-sling-scripting-sightly</a> </td><td> <a href="/documentation/bundles/scripting/scripting-htl.html">Scripting HTL</a> </td></tr>
+<tr><td> Java </td><td> <code>Java Servlet Compiler</code> </td><td> <code>1.5</code></td><td> <code>java</code><br><code>Java</code> </td><td> <code>java</code> </td><td> </td><td> <a href="https://github.com/apache/sling-org-apache-sling-scripting-java">sling-org-apache-sling-scripting-java</a> </td><td> </td></tr>
+<tr><td> JavaScript </td><td> <code>ECMAScript</code> </td><td> <code>partial ECMAScript 2015 support</code> </td><td> <code>rhino</code><br><code>Rhino</code><br><code>javascript</code><br><code>JavaScript</code><br><code>ecmascript</code><br><code>ECMAScript</code> </td><td> <code>esp</code><br><code>ecma</code> </td><td> <code>text/ecmascript</code><br><code>text/javascript</code><br><code>application/ecmascript</code><br><code>application/javascript</code> </td><td> <a href="https:// [...]
+<tr><td> <a href="https://projects.eclipse.org/projects/ee4j.jsp">JSP</a> </td><td> <code>Java Server Pages</code> </td><td> <code>2.1</code> </td><td> <code>jsp</code><br><code>JSP</code> </td><td> <code>jsp</code><br><code>jspf</code><br><code>jspx</code> </td><td> </td><td> <a href="https://github.com/apache/sling-org-apache-sling-scripting-jsp">sling-org-apache-sling-scripting-jsp</a> </td><td> <a href="/documentation/bundles/scripting/scripting-jsp.html">Scripting JSP</a> </td></tr>
+<tr><td> <a href="https://www.thymeleaf.org">Thymeleaf</a> </td><td> <code>Thymeleaf</code> </td><td> <code>version</code> from <a href="https://github.com/thymeleaf/thymeleaf/blob/3.0-master/src/main/resources/org/thymeleaf/thymeleaf.properties"><code>/org/thymeleaf/thymeleaf.properties</code></a> </td><td> <code>Thymeleaf</code><br><code>thymeleaf</code><br>(configurable) </td><td> <code>html</code><br>(configurable) </td><td> <code>text/html</code><br>(configurable) </td><td> <a hre [...]
+</tbody>
</table>
<p>Several more engines are available but experimental or no longer maintained:</p>
<ul>
- <li>ESX</li>
- <li>JST</li>
- <li>Python</li>
- <li>Ruby</li>
- <li>Scala</li>
- <li>Velocity</li>
- <li>XProc</li>
+<li>ESX</li>
+<li>JST</li>
+<li>Python</li>
+<li>Ruby</li>
+<li>Scala</li>
+<li>Velocity</li>
+<li>XProc</li>
</ul>
-<h2><a href="#scripting-variables" name="scripting-variables">Scripting variables</a></h2>
-<p>See also <a href="https://cwiki.apache.org/confluence/display/SLING/Scripting+variables">Scripting variables</a> and <a href="https://cwiki.apache.org/confluence/display/SLING/Adding+New+Scripting+Variables">Adding New Scripting Variables</a>.</p></section></div></div>
+<h2><a href="#scripting-variables" id="scripting-variables">Scripting variables</a></h2>
+<p>See also <a href="https://cwiki.apache.org/confluence/display/SLING/Scripting+variables">Scripting variables</a> and <a href="https://cwiki.apache.org/confluence/display/SLING/Adding+New+Scripting+Variables">Adding New Scripting Variables</a>.</p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/scripting/scripting-htl.html b/documentation/bundles/scripting/scripting-htl.html
index fbb648e..74557eb 100644
--- a/documentation/bundles/scripting/scripting-htl.html
+++ b/documentation/bundles/scripting/scripting-htl.html
@@ -125,103 +125,70 @@
<div class="row"><div><section><p>The Apache Sling HTL Scripting Engine, <a href="https://issues.apache.org/jira/browse/SLING-6028">formerly known as Sightly</a>, is the reference implementation of the <a href="https://github.com/Adobe-Marketing-Cloud/htl-spec">HTML Template Language</a>.</p>
<p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h1><a href="#modules" name="modules">Modules</a></h1>
+<h1><a href="#modules" id="modules">Modules</a></h1>
<p>The Sling implementation is comprised of the following modules:</p>
<ol>
- <li><a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly-compiler"><code>org.apache.sling.scripting.sightly.compiler</code></a> - provides support for compiling HTML Template Language scripts into an Abstract Syntax Tree</li>
- <li><a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly-compiler-java"><code>org.apache.sling.scripting.sightly.compiler.java</code></a> - provides support for transpiling the Abstract Syntax Tree produced by the <code>org.apache.sling.scripting.sightly.compiler</code> module into Java source code</li>
- <li><a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly"><code>org.apache.sling.scripting.sightly</code></a> - the HTL Scripting Engine bundle</li>
- <li><a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly-js-provider"><code>org.apache.sling.scripting.sightly.js.provider</code></a> - the HTL JavaScript Use Provider, implementing support for the <code>use</code> JavaScript function</li>
- <li><a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly-models-provider"><code>org.apache.sling.scripting.sightly.models.provider</code></a> - <a href="https://sling.apache.org/documentation/bundles/models.html">Sling Models</a> Use Provider</li>
- <li><a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly-repl"><code>org.apache.sling.scripting.sightly.repl</code></a> - HTL Read-Eval-Print Loop Environment (REPL), useful for quickly prototyping scripts</li>
- <li><a href="https://github.com/apache/sling-htl-maven-plugin"><code>htl-maven-plugin</code></a> - M2Eclipse compatible HTL Maven Plugin that provides support for validating HTML Template Language scripts from projects during build time</li>
+<li><a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly-compiler"><code>org.apache.sling.scripting.sightly.compiler</code></a> - provides support for compiling HTML Template Language scripts into an Abstract Syntax Tree</li>
+<li><a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly-compiler-java"><code>org.apache.sling.scripting.sightly.compiler.java</code></a> - provides support for transpiling the Abstract Syntax Tree produced by the <code>org.apache.sling.scripting.sightly.compiler</code> module into Java source code</li>
+<li><a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly"><code>org.apache.sling.scripting.sightly</code></a> - the HTL Scripting Engine bundle</li>
+<li><a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly-js-provider"><code>org.apache.sling.scripting.sightly.js.provider</code></a> - the HTL JavaScript Use Provider, implementing support for the <code>use</code> JavaScript function</li>
+<li><a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly-models-provider"><code>org.apache.sling.scripting.sightly.models.provider</code></a> - <a href="https://sling.apache.org/documentation/bundles/models.html">Sling Models</a> Use Provider</li>
+<li><a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly-repl"><code>org.apache.sling.scripting.sightly.repl</code></a> - HTL Read-Eval-Print Loop Environment (REPL), useful for quickly prototyping scripts</li>
+<li><a href="https://github.com/apache/sling-htl-maven-plugin"><code>htl-maven-plugin</code></a> - M2Eclipse compatible HTL Maven Plugin that provides support for validating HTML Template Language scripts from projects during build time</li>
</ol>
-<h1><a href="#the-use-api" name="the-use-api">The Use-API</a></h1>
+<h1><a href="#the-use-api" id="the-use-api">The Use-API</a></h1>
<p>The <a href="https://github.com/Adobe-Marketing-Cloud/htl-spec/blob/1.2/SPECIFICATION.md#4-use-api">HTML Template Language Specification</a> explicitly defines two ways of implementing support for business logic objects:</p>
<ol>
- <li>
- <p>Java Use-API, through POJOs, that may optionally implement an <code>init</code> method:</p>
- <pre><code>/**
+<li>
+<p>Java Use-API, through POJOs, that may optionally implement an <code>init</code> method:</p>
+<pre><code>/**
* Initialises the Use bean.
*
* @param bindings All bindings available to the HTL scripts.
**/
public void init(javax.script.Bindings bindings);
</code></pre>
- </li>
- <li>
- <p>JavaScript Use-API, by using a standardised use function</p>
- <pre><code>/**
- * In the following example '/libs/dep1.js' and 'dep2.js' are optional
- * dependencies needed for this script's execution. Dependencies can
+</li>
+<li>
+<p>JavaScript Use-API, by using a standardised use function</p>
+<pre><code>/**
+ * In the following example '/libs/dep1.js' and 'dep2.js' are optional
+ * dependencies needed for this script's execution. Dependencies can
* be specified using an absolute path or a relative path to this
- * script's own path.
+ * script's own path.
*
* If no dependencies are needed the dependencies array can be omitted.
*/
-use(['dep1.js', 'dep2.js'], function (Dep1, Dep2) {
+use(['dep1.js', 'dep2.js'], function (Dep1, Dep2) {
// implement processing
- // define this Use object's behaviour
+ // define this Use object's behaviour
return {
propertyName: propertyValue
functionName: function () {}
}
});
</code></pre>
- </li>
+</li>
</ol>
<p>The HTL implementation from Sling provides the basic POJO support through the <a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly-compiler-java/blob/master/src/main/java/org/apache/sling/scripting/sightly/pojo/Use.java"><code>org.apache.sling.scripting.sightly.pojo.Use</code></a> interface and the <a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly/blob/master/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/Jav [...]
<p>However, the Sling implementation provides a few extensions to the Use-API.</p>
-<h2><a href="#sling-specific-use-api-extensions" name="sling-specific-use-api-extensions">Sling-specific Use-API Extensions</a></h2>
+<h2><a href="#sling-specific-use-api-extensions" id="sling-specific-use-api-extensions">Sling-specific Use-API Extensions</a></h2>
<p>A full HTL installation provides the following Use Providers, in the order of their priority (the higher the service ranking value, the higher the priority):</p>
<table>
- <thead>
- <tr>
- <th>Service Ranking </th>
- <th>Use Provider </th>
- <th>Bundle </th>
- <th>Functionality </th>
- <th>Observations</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>100</td>
- <td><a href="https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/engine/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/RenderUnitProvider.java"><code>RenderUnitProvider</code></a></td>
- <td><code>org.apache.sling.scripting.sightly</code></td>
- <td colspan="2">support for loading HTL templates through <code>data-sly-use</code></td>
- </tr>
- <tr>
- <td>95</td>
- <td><a href="https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/models-use-provider/src/main/java/org/apache/sling/scripting/sightly/models/impl/SlingModelsUseProvider.java"><code>SlingModelsUseProvider</code></a></td>
- <td><code>org.apache.sling.scripting.sightly.models.provider</code></td>
- <td colspan="2">support for loading <a href="https://sling.apache.org/documentation/bundles/models.html">Sling Models</a></td>
- </tr>
- <tr>
- <td>90</td>
- <td><a href="https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/engine/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/JavaUseProvider.java"><code>JavaUseProvider</code></a></td>
- <td><code>org.apache.sling.scripting.sightly</code></td>
- <td>support for loading Java objects such as: <ol><li>OSGi services</li><li>POJOs adaptable from <code>SlingHttpServletRequest</code> or <code>Resource</code></li><li>POJOs that implement <code>Use</code></li></ol></td>
- <td>The POJOs can be exported by bundles or can be backed by <code>Resources</code>. In the latter case the POJOs' package names should correspond to the backing resource's path; invalid Java characters which are valid path elements should be replaced by an underscore - <code>_</code>.</td>
- </tr>
- <tr>
- <td>80</td>
- <td><a href="https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/js-use-provider/src/main/java/org/apache/sling/scripting/sightly/js/impl/JsUseProvider.java"><code>JsUseProvider</code></a></td>
- <td><code>org.apache.sling.scripting.sightly.js.provider</code></td>
- <td>support for loading objects defined through the JavaScript <code>use</code> function</td>
- <td>The <code>org.apache.sling.scripting.sightly.js.provider</code> also provides a trimmed down <a href="https://github.com/apache/sling/tree/trunk/bundles/scripting/sightly/js-use-provider/src/main/resources/SLING-INF/libs/sling/sightly/js">asynchronous implementation</a> of the <code>Resource</code> API. However this was deprecated in <a href="https://issues.apache.org/jira/browse/SLING-4964">SLING-4964</a> (version 1.0.8 of the bundle) in favour of the synchronous API provided [...]
- </tr>
- <tr>
- <td>0 </td>
- <td><a href="https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/engine/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/ScriptUseProvider.java"><code>ScriptUseProvider</code></a></td>
- <td><code>org.apache.sling.scripting.sightly</code></td>
- <td colspan="2">support for loading objects returned by scripts interpreted by other Script Engines available on the platform</td>
- </tr>
- </tbody>
+<thead>
+<tr><th>Service Ranking </th><th> Use Provider </th><th> Bundle </th><th> Functionality </th><th>Observations</th></tr>
+</thead>
+<tbody>
+<tr><td>100</td><td><a href="https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/engine/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/RenderUnitProvider.java"><code>RenderUnitProvider</code></a></td><td><code>org.apache.sling.scripting.sightly</code></td><td colspan="2">support for loading HTL templates through <code>data-sly-use</code></td></tr>
+<tr><td>95</td><td><a href="https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/models-use-provider/src/main/java/org/apache/sling/scripting/sightly/models/impl/SlingModelsUseProvider.java"><code>SlingModelsUseProvider</code></a></td><td><code>org.apache.sling.scripting.sightly.models.provider</code></td><td colspan="2">support for loading <a href="https://sling.apache.org/documentation/bundles/models.html">Sling Models</a></td></tr>
+<tr><td>90</td><td><a href="https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/engine/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/JavaUseProvider.java"><code>JavaUseProvider</code></a></td><td><code>org.apache.sling.scripting.sightly</code></td><td>support for loading Java objects such as: <ol><li>OSGi services</li><li>POJOs adaptable from <code>SlingHttpServletRequest</code> or <code>Resource</code></li><li>POJOs that implement <code>Use< [...]
+<tr><td>80</td><td><a href="https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/js-use-provider/src/main/java/org/apache/sling/scripting/sightly/js/impl/JsUseProvider.java"><code>JsUseProvider</code></a></td><td><code>org.apache.sling.scripting.sightly.js.provider</code></td><td>support for loading objects defined through the JavaScript <code>use</code> function</td><td>The <code>org.apache.sling.scripting.sightly.js.provider</code> also provides a trimmed down <a href=" [...]
+<tr><td>0 </td><td><a href="https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/engine/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/ScriptUseProvider.java"><code>ScriptUseProvider</code></a></td><td><code>org.apache.sling.scripting.sightly</code></td><td colspan="2">support for loading objects returned by scripts interpreted by other Script Engines available on the platform</td></tr>
+</tbody>
</table>
<p>The <code>service.ranking</code> value of each Use Provider is configurable, allowing for fine tuning of the order in which the providers are queried when <code>data-sly-use</code> is called. However, in order to not affect core functionality the <code>RenderUnitProvider</code> should always have the highest ranking. If you need to configure the providers' service ranking head over to the configuration console at <a href="http://localhost:8080/system/console/configMgr">http://localhos [...]
-<h3><a href="#global-objects" name="global-objects">Global Objects</a></h3>
+<h3><a href="#global-objects" id="global-objects">Global Objects</a></h3>
<p>The following global objects are available to all Use objects, either as a request attribute or as a property made available in the <code>javax.script.Bindings</code> map or attached to the <code>this</code> context of the <code>use</code> function:</p>
<pre><code> currentNode // javax.jcr.Node
currentSession // javax.jcr.Session
@@ -235,7 +202,7 @@ use(['dep1.js', 'dep2.js'], function (Dep1, Dep2) {
response // org.apache.sling.api.SlingHttpServletResponse
sling // org.apache.sling.api.scripting.SlingScriptHelper
</code></pre>
-<h3><a href="#sling-models-use-provider" name="sling-models-use-provider">Sling Models Use Provider</a></h3>
+<h3><a href="#sling-models-use-provider" id="sling-models-use-provider">Sling Models Use Provider</a></h3>
<p>Loading a Sling Model can be done with the following code:</p>
<pre><code> <div data-sly-use.model3="org.example.models.Model3">
${model3.shine}
@@ -243,9 +210,9 @@ use(['dep1.js', 'dep2.js'], function (Dep1, Dep2) {
</code></pre>
<p>Depending on the implementation the above code would either load the implementation with the highest service ranking of <code>Model3</code> if <code>org.example.models.Model3</code> is an interface, or would load the model <code>org.example.models.Model3</code> if this is a concrete implementation.</p>
<p>It's important to note that this use provider will only load models that are adaptable from <code>SlingHttpServletRequest</code> or <code>Resource</code>.</p>
-<h4><a href="#passing-parameters" name="passing-parameters">Passing parameters</a></h4>
+<h4><a href="#passing-parameters" id="passing-parameters">Passing parameters</a></h4>
<p>Passed parameters will be made available to the Sling Model as request attributes. Assuming the following markup:</p>
-<pre><code> <div data-sly-use.model3="${'org.example.models.Model3' @ colour='red', path=resource.path}">
+<pre><code> <div data-sly-use.model3="${'org.example.models.Model3' @ colour='red', path=resource.path}">
${model3.shine}
</div>
</code></pre>
@@ -260,9 +227,9 @@ use(['dep1.js', 'dep2.js'], function (Dep1, Dep2) {
private String path;
}
</code></pre>
-<h3><a href="#java-use-provider" name="java-use-provider">Java Use Provider</a></h3>
+<h3><a href="#java-use-provider" id="java-use-provider">Java Use Provider</a></h3>
<p>The Java Use Provider can be used to load OSGi services, objects exported by bundles or backed by a <code>Resource</code>.</p>
-<h4><a href="#resource-backed-java-classes" name="resource-backed-java-classes">Resource-backed Java classes</a></h4>
+<h4><a href="#resource-backed-java-classes" id="resource-backed-java-classes">Resource-backed Java classes</a></h4>
<p>When objects are backed by <code>Resources</code> the Java Use Provider will automatically handle the compilation of these classes. The classes' package names should correspond to the path of the backing resource, making sure to replace illegal Java characters with underscores - <code>_</code>.</p>
<p><strong>Example:</strong> Assuming the following content structure:</p>
<pre><code> └── apps
@@ -285,9 +252,9 @@ use(['dep1.js', 'dep2.js'], function (Dep1, Dep2) {
</html>
</code></pre>
<p>The advantage of loading a bean using just the simple class name (e.g. <code>data-sly-use.page="PageBean"</code>) is that an inheriting component can overlay the <code>PageBean.java</code> file and provide a different logic. In this case the package name of the <code>PageBean</code> class will automatically be derived from the calling script's parent path (e.g. <code>apps.my_project.components.page</code>) - the bean doesn't even have to specify it. However, keep in mind tha [...]
-<h4><a href="#passing-parameters" name="passing-parameters">Passing parameters</a></h4>
+<h4><a href="#passing-parameters" id="passing-parameters">Passing parameters</a></h4>
<p>Passed parameters will be made available to the Use object as request attributes and, if the object implements the <a href="https://github.com/apache/sling-org-apache-sling-scripting-sightly-compiler-java/blob/master/src/main/java/org/apache/sling/scripting/sightly/pojo/Use.java"><code>org.apache.sling.scripting.sightly.pojo.Use</code></a> interface, through the <code>javax.script.Bindings</code> passed to the <code>init</code> method. Assuming the following markup:</p>
-<pre><code> <div data-sly-use.useObject="${'org.example.use.MyUseObject' @ colour='red', year=2016}">
+<pre><code> <div data-sly-use.useObject="${'org.example.use.MyUseObject' @ colour='red', year=2016}">
${useObject.shine}
</div>
</code></pre>
@@ -353,7 +320,7 @@ public class RequestAdapterFactory implements AdapterFactory {
}
}
</code></pre>
-<h3><a href="#javascript-use-provider" name="javascript-use-provider">JavaScript Use Provider</a></h3>
+<h3><a href="#javascript-use-provider" id="javascript-use-provider">JavaScript Use Provider</a></h3>
<p>The JavaScript Use Provider allows loading objects created through the <code>use</code> function, by evaluating scripts passed to <code>data-sly-use</code>. The JavaScript files are evaluated server-side by the <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino">Rhino</a> scripting engine, through the <code>org.apache.sling.scripting.javascript</code> implementation bundle. This allows you to mix JavaScript API with the Java API exported by the platform. For more [...]
<p><strong>Example:</strong> Assuming the following content structure:</p>
<pre><code> └── apps
@@ -376,7 +343,7 @@ public class RequestAdapterFactory implements AdapterFactory {
</html>
</code></pre>
<p>Similar to the Java Use Provider, loading the script using a relative path allows inheriting components to overlay just the Use script, without having to also overlay the calling HTL script.</p>
-<h4><a href="#global-objects" name="global-objects">Global Objects</a></h4>
+<h4><a href="#global-objects" id="global-objects">Global Objects</a></h4>
<p>Besides the global objects available to all Use Providers, the JavaScript Use Provider also provides the following global objects available in the context of the <code>use</code> function:</p>
<pre><code>console // basic wrapper on top of log, but without formatting / throwable support
exports // basic Java implementation of CommonJS - http://requirejs.org/docs/commonjs.html
@@ -388,17 +355,17 @@ sightly // the namespace object under which the asynchronous Resource-AP
use // the use function
</code></pre>
<p>With the exception of the <code>console</code> and <code>use</code> objects, all the other global objects implemented by the JavaScript Use Provider are present in order to support the asynchronous Resource-API implemented by <code>org.apache.sling.scripting.sightly.js.provider</code>. However, this was deprecated starting with version 1.0.8 - see <a href="https://issues.apache.org/jira/browse/SLING-4964">SLING-4964</a>.</p>
-<h4><a href="#passing-parameters" name="passing-parameters">Passing parameters</a></h4>
+<h4><a href="#passing-parameters" id="passing-parameters">Passing parameters</a></h4>
<p>Passed parameters will be made available to the Use object as properties of <code>this</code>. Assuming the following markup:</p>
-<pre><code> <div data-sly-use.logic="${'logic.js' @ colour='red', year=2017}">
- My colour is ${logic.colour ? logic.colour : 'not important'} and I'm from ${logic.year}
+<pre><code> <div data-sly-use.logic="${'logic.js' @ colour='red', year=2017}">
+ My colour is ${logic.colour ? logic.colour : 'not important'} and I'm from ${logic.year}
</div>
</code></pre>
<p>the object would be able to access the parameters like:</p>
<pre><code> use(function() {
- 'use strict';
+ 'use strict';
- var colour = this.colour || '';
+ var colour = this.colour || '';
var year = this.year || new Date().getFullYear();
return {
@@ -407,7 +374,7 @@ use // the use function
}
});
</code></pre>
-<h4><a href="#caveats" name="caveats">Caveats</a></h4>
+<h4><a href="#caveats" id="caveats">Caveats</a></h4>
<p>Since these scripts are evaluated server-side, by compiling JavaScript to Java, you need to pay attention when comparing primitive objects using the strict equal operator (<code>===</code>) since comparisons between JavaScript and Java objects with the same apparent value will return <code>false</code> (this also applies to the strict not-equal operator - <code>!==</code>).</p>
<p>Assuming the following HTL script:</p>
<pre><code> <ol data-sly-use.obj="logic.js" data-sly-list="${obj}">
@@ -421,51 +388,51 @@ use // the use function
return [
{
- code: 'new java.lang.String("apples") === "apples"',
+ code: 'new java.lang.String("apples") === "apples"',
result: new java.lang.String("apples") === "apples"
},
{
- code: 'new java.lang.String("apples") == "apples"',
+ code: 'new java.lang.String("apples") == "apples"',
result: new java.lang.String("apples") == "apples"
},
{
- code: 'new java.lang.String("apples") !== "apples"',
+ code: 'new java.lang.String("apples") !== "apples"',
result: new java.lang.String("apples") !== "apples"
},
{
- code: 'new java.lang.String("apples") != "apples"',
+ code: 'new java.lang.String("apples") != "apples"',
result: new java.lang.String("apples") != "apples"
},
{
- code: 'new java.lang.Integer(1) === 1',
+ code: 'new java.lang.Integer(1) === 1',
result: new java.lang.Integer(1) === 1
},
{
- code: 'new java.lang.Integer(1) == 1',
+ code: 'new java.lang.Integer(1) == 1',
result: new java.lang.Integer(1) == 1
},
{
- code: 'new java.lang.Integer(1) !== 1',
+ code: 'new java.lang.Integer(1) !== 1',
result: new java.lang.Integer(1) !== 1
},
{
- code: 'new java.lang.Integer(1) != 1',
+ code: 'new java.lang.Integer(1) != 1',
result: new java.lang.Integer(1) != 1
},
{
- code: 'java.lang.Boolean.TRUE === true',
+ code: 'java.lang.Boolean.TRUE === true',
result: java.lang.Boolean.TRUE === true
},
{
- code: 'java.lang.Boolean.TRUE == true',
+ code: 'java.lang.Boolean.TRUE == true',
result: java.lang.Boolean.TRUE == true
},
{
- code: 'java.lang.Boolean.TRUE !== true',
+ code: 'java.lang.Boolean.TRUE !== true',
result: java.lang.Boolean.TRUE !== true
},
{
- code: 'java.lang.Boolean.TRUE != true',
+ code: 'java.lang.Boolean.TRUE != true',
result: java.lang.Boolean.TRUE != true
}
];
@@ -494,13 +461,13 @@ use // the use function
...
}
- myObject ? 'this' : 'that'
+ myObject ? 'this' : 'that'
//should be replaced by
- myObject != null ? 'this' : 'that'
+ myObject != null ? 'this' : 'that'
</code></pre>
-<h3><a href="#script-use-provider" name="script-use-provider">Script Use Provider</a></h3>
+<h3><a href="#script-use-provider" id="script-use-provider">Script Use Provider</a></h3>
<p>The Script Use Provider allows loading objects evaluated by other script engines available on the platform. The same loading considerations as for the Java and JavaScript Use Providers apply.</p>
-<h3><a href="#picking-the-best-use-provider-for-a-project" name="picking-the-best-use-provider-for-a-project">Picking the best Use Provider for a project</a></h3>
+<h3><a href="#picking-the-best-use-provider-for-a-project" id="picking-the-best-use-provider-for-a-project">Picking the best Use Provider for a project</a></h3>
<p>The following table summarises the pros and cons for each Use Provider, with the obvious exception of the Render Unit Use Provider.</p>
<table>
<tr>
@@ -534,43 +501,44 @@ use // the use function
<ul>
<li>lacks flexibility in terms of component overlaying</li>
</ul>
-
- <p>Use-objects backed by <code>Resources</code>:</p>
- <ul>
- <li>cannot extend other Java objects</li>
- <li>the Java project might need a different setup to allow running unit tests, since the objects will be deployed like content</li>
- </ul>
- </td>
- </tr>
- <tr>
- <td>JavaScript Use Provider</td>
- <td>
- <ul>
- <li>allows JavaScript developers to develop component logic</li>
- <li>can be reused through the dependency mechanism provided by the <code>use</code> function</li>
- </ul>
- </td>
- <td>
- <ul>
- <li>harder to test and debug, relying mostly on end-to-end testing and console logging</li>
- <li>slower to execute than both Sling Models and Java Use-API objects</li>
- </ul>
- </td>
- </tr>
- <tr>
- <td>Script Use Provider</td>
- <td>
- <ul>
- <li>allows the usage of Use objects evaluated by other Script Engines available in the platform</li>
- </ul>
- </td>
- <td>
- <ul>
- <li>like in the case of the JavaScript Use Provider, the performance is influenced by the Script Engine's implementation</li>
- </ul>
- </td>
- </tr>
-</table></section></div></div>
+<pre><code> <p>Use-objects backed by <code>Resources</code>:</p>
+ <ul>
+ <li>cannot extend other Java objects</li>
+ <li>the Java project might need a different setup to allow running unit tests, since the objects will be deployed like content</li>
+ </ul>
+ </td>
+</tr>
+<tr>
+ <td>JavaScript Use Provider</td>
+ <td>
+ <ul>
+ <li>allows JavaScript developers to develop component logic</li>
+ <li>can be reused through the dependency mechanism provided by the <code>use</code> function</li>
+ </ul>
+ </td>
+ <td>
+ <ul>
+ <li>harder to test and debug, relying mostly on end-to-end testing and console logging</li>
+ <li>slower to execute than both Sling Models and Java Use-API objects</li>
+ </ul>
+ </td>
+</tr>
+<tr>
+ <td>Script Use Provider</td>
+ <td>
+ <ul>
+ <li>allows the usage of Use objects evaluated by other Script Engines available in the platform</li>
+ </ul>
+ </td>
+ <td>
+ <ul>
+ <li>like in the case of the JavaScript Use Provider, the performance is influenced by the Script Engine's implementation</li>
+ </ul>
+ </td>
+</tr>
+</code></pre>
+</table>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/scripting/scripting-jsp.html b/documentation/bundles/scripting/scripting-jsp.html
index d7faa7a..2d9a459 100644
--- a/documentation/bundles/scripting/scripting-jsp.html
+++ b/documentation/bundles/scripting/scripting-jsp.html
@@ -122,450 +122,431 @@
</li>
</ul>
</nav><script src='/res/jquery-3.2.1.min.js' type='text/javascript'></script><script src='/res/tocjs-1-1-2.js' type='text/javascript'></script><script type='text/javascript'>$(document).ready(function() { $('#generatedToC').toc({'selector':'h1[class!=title],h2,h3','ulClass':'menu-list'}); } );</script><div class="content is-marginless">
-<div class="row"><div><section><p>The Apache Sling JSP Scripting Engine is implemented by the <a href="https://github.com/apache/sling/tree/trunk/bundles/scripting/jsp"><code>org.apache.sling.scripting.jsp</code></a> bundle, based on the Jasper 2 JSP engine.</p>
-<p>On top of that Apache Sling also provides its own JSP Taglib, implemented by the <a href="https://github.com/apache/sling/tree/trunk/bundles/scripting/jsp-taglib"><code>org.apache.sling.scripting.jsp.taglib</code></a> bundle.</p>
-<p>The Sling Scripting JSP Taglib supports the use of Sling as an application in JSP pages. The Sling Taglib provides the ability to invoke JSP scripts, include Resources and interact with the Sling Repository, all with JSP tags and <a href="http://docs.oracle.com/javaee/6/tutorial/doc/gjddd.html">Expression Language (EL)</a> functions.</p>
-<h2><a href="#use" name="use">Use</a></h2>
+<div class="row"><div><section><p>The Apache Sling JSP Scripting Engine is implemented by the <a href="https://github.com/apache/sling/tree/trunk/bundles/scripting/jsp"><code>org.apache.sling.scripting.jsp</code></a> bundle, based on the Jasper 2 JSP engine.</p>
+<p>On top of that Apache Sling also provides its own JSP Taglib, implemented by the <a href="https://github.com/apache/sling/tree/trunk/bundles/scripting/jsp-taglib"><code>org.apache.sling.scripting.jsp.taglib</code></a> bundle.</p>
+<p>The Sling Scripting JSP Taglib supports the use of Sling as an application in JSP pages. The Sling Taglib provides the ability to invoke JSP scripts, include Resources and interact with the Sling Repository, all with JSP tags and <a href="http://docs.oracle.com/javaee/6/tutorial/doc/gjddd.html">Expression Language (EL)</a> functions.</p>
+<h2><a href="#use" id="use">Use</a></h2>
<p>Using the Sling Taglib in a JSP page is as simple as including the Taglib include in your JSP, with the correct URI for the version of the Sling Taglib installed.</p>
<pre><code><%@taglib prefix="sling" uri="http://sling.apache.org/taglibs/sling" %>
</code></pre>
-<p>Generally, the prefix to use is <code>sling</code>. Often applications include a global JSP file which includes the Sling Taglib and sets up all of the application variables and methods.</p>
+<p>Generally, the prefix to use is <code>sling</code>. Often applications include a global JSP file which includes the Sling Taglib and sets up all of the application variables and methods.</p>
<p>The Sling Taglib does not attempt to reproduce the functionality of other Tag Libraries, such as <a href="http://www.oracle.com/technetwork/java/index-jsp-135995.html">JSTL</a>; additional Tag Libraries may be required to fully leverage the Sling Taglib.</p>
-<h2><a href="#taglib-versions" name="taglib-versions">Taglib Versions</a></h2>
+<h2><a href="#taglib-versions" id="taglib-versions">Taglib Versions</a></h2>
<p>There have been a number of releases of the Sling Taglibs, including versions with different URIs.</p>
<table>
- <thead>
- <tr>
- <th>Taglib Version </th>
- <th>Bundle Version </th>
- <th>URI </th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>1.0 </td>
- <td>2.0.6 </td>
- <td>http://sling.apache.org/taglibs/sling/1.0 </td>
- </tr>
- <tr>
- <td>1.1 </td>
- <td>2.1.0 </td>
- <td>http://sling.apache.org/taglibs/sling/1.1 </td>
- </tr>
- <tr>
- <td>1.2 </td>
- <td>2.1.8 </td>
- <td>http://sling.apache.org/taglibs/sling/1.2 </td>
- </tr>
- <tr>
- <td>1.3 </td>
- <td>2.2.0 </td>
- <td>http://sling.apache.org/taglibs/sling </td>
- </tr>
- </tbody>
+<thead>
+<tr><th> Taglib Version </th><th> Bundle Version </th><th> URI </th></tr>
+</thead>
+<tbody>
+<tr><td> 1.0 </td><td> 2.0.6 </td><td> http://sling.apache.org/taglibs/sling/1.0 </td></tr>
+<tr><td> 1.1 </td><td> 2.1.0 </td><td> http://sling.apache.org/taglibs/sling/1.1 </td></tr>
+<tr><td> 1.2 </td><td> 2.1.8 </td><td> http://sling.apache.org/taglibs/sling/1.2 </td></tr>
+<tr><td> 1.3 </td><td> 2.2.0 </td><td> http://sling.apache.org/taglibs/sling </td></tr>
+</tbody>
</table>
<p>All releases from 1.3 onward are expected to use the URI <code>http://sling.apache.org/taglibs/sling</code> to ensure ease of upgrading to newer versions of the Taglib.</p>
-<h2><a href="#expression-language-functions" name="expression-language-functions">Expression Language Functions</a></h2>
+<h2><a href="#expression-language-functions" id="expression-language-functions">Expression Language Functions</a></h2>
<p>The Sling Taglib includes a number of Expression Language Functions which can be used to access the repository.</p>
-<h3><a href="#adaptto" name="adaptto">adaptTo</a></h3>
+<h3><a href="#adaptto" id="adaptto">adaptTo</a></h3>
<p>Adapts an Adaptable to another class.</p>
<ul>
- <li>Returns: <code>java.lang.Object</code></li>
- <li>Accepts:
- <ul>
- <li><code>org.apache.sling.api.adapter.Adaptable</code> - The object to adapt</li>
- <li><code>java.lang.String</code> - The name of the class to which to adapt the adaptable</li>
- </ul>
- </li>
- <li>Since: 1.3</li>
+<li>Returns: <code>java.lang.Object</code></li>
+<li>Accepts:
+<ul>
+<li><code>org.apache.sling.api.adapter.Adaptable</code> - The object to adapt</li>
+<li><code>java.lang.String</code> - The name of the class to which to adapt the adaptable</li>
+</ul>
+</li>
+<li>Since: 1.3</li>
</ul>
<p><em>Example Usage</em></p>
-<pre><code><c:set var="myProperties" value="${sling:adaptTo(resource,'org.apache.sling.api.resource.ValueMap')}" />
+<pre><code><c:set var="myProperties" value="${sling:adaptTo(resource,'org.apache.sling.api.resource.ValueMap')}" />
</code></pre>
-<h3><a href="#encode" name="encode">encode</a></h3>
-<p>Writes properly Cross Site Scripting (XSS) encoded text to the response using the OWASP ESAPI. Supports a number of encoding modes.</p>
-<ul>
- <li>Returns: <code>java.util.String</code> - An encoded text</li>
- <li>Accepts:
- <ul>
- <li><code>java.lang.String</code> - The text to encode</li>
- <li><code>java.lang.String</code> - The encoding mode, one of HTML, HTML_ATTR, XML, XML_ATTR, JS</li>
- </ul>
- </li>
- <li>Since: 1.4</li>
+<h3><a href="#encode" id="encode">encode</a></h3>
+<p>Writes properly Cross Site Scripting (XSS) encoded text to the response using the OWASP ESAPI. Supports a number of encoding modes.</p>
+<ul>
+<li>Returns: <code>java.util.String</code> - An encoded text</li>
+<li>Accepts:
+<ul>
+<li><code>java.lang.String</code> - The text to encode</li>
+<li><code>java.lang.String</code> - The encoding mode, one of HTML, HTML_ATTR, XML, XML_ATTR, JS</li>
+</ul>
+</li>
+<li>Since: 1.4</li>
</ul>
<p><em>Example Usage</em></p>
-<pre><code>${sling:encode('<script>alert("Bad Stuff!");</script>','HTML')}
+<pre><code>${sling:encode('<script>alert("Bad Stuff!");</script>','HTML')}
</code></pre>
-<h3><a href="#findresources" name="findresources">findResources</a></h3>
+<h3><a href="#findresources" id="findresources">findResources</a></h3>
<p>Searches for resources using the given query formulated in the given language.</p>
<ul>
- <li>Returns: <code>java.util.Iterator</code> - An Iterator of Resource objects matching the query.</li>
- <li>Accepts:
- <ul>
- <li><code>org.apache.sling.api.resource.ResourceResolver</code> - The Resource Resolver to use for the query.</li>
- <li><code>java.lang.String</code> - The query string to use to find the resources.</li>
- <li><code>java.lang.String</code> - The language in which the query is formulated.</li>
- </ul>
- </li>
- <li>Since: 1.3</li>
+<li>Returns: <code>java.util.Iterator</code> - An Iterator of Resource objects matching the query.</li>
+<li>Accepts:
+<ul>
+<li><code>org.apache.sling.api.resource.ResourceResolver</code> - The Resource Resolver to use for the query.</li>
+<li><code>java.lang.String</code> - The query string to use to find the resources.</li>
+<li><code>java.lang.String</code> - The language in which the query is formulated.</li>
+</ul>
+</li>
+<li>Since: 1.3</li>
</ul>
<p><em>Example Usage</em></p>
-<pre><code><c:forEach var="found" items="${sling:findResources(resourceResolver,'/jcr:root//*[jcr:contains(., 'Sling')] order by @jcr:score','xpath')">
+<pre><code><c:forEach var="found" items="${sling:findResources(resourceResolver,'/jcr:root//*[jcr:contains(., 'Sling')] order by @jcr:score','xpath')">
<li>${found.path}</li>
</c:forEach>
</code></pre>
-<h3><a href="#getabsoluteparent" name="getabsoluteparent">getAbsoluteParent</a></h3>
+<h3><a href="#getabsoluteparent" id="getabsoluteparent">getAbsoluteParent</a></h3>
<p>Method for retrieving an absolute parent resource.</p>
<ul>
- <li>Returns: <code>org.apache.sling.api.resource.Resource</code> - The parent resource at the specified level</li>
- <li>Accepts:
- <ul>
- <li><code>org.apache.sling.api.resource.Resource</code> - The current resource</li>
- <li><code>java.lang.String</code> - The absolute level for the parent resource to retrieve</li>
- </ul>
- </li>
- <li>Since: Bundle 2.3.0</li>
+<li>Returns: <code>org.apache.sling.api.resource.Resource</code> - The parent resource at the specified level</li>
+<li>Accepts:
+<ul>
+<li><code>org.apache.sling.api.resource.Resource</code> - The current resource</li>
+<li><code>java.lang.String</code> - The absolute level for the parent resource to retrieve</li>
+</ul>
+</li>
+<li>Since: Bundle 2.3.0</li>
</ul>
<p><em>Example Usage</em></p>
-<pre><code><c:set var="content" value="${sling:getAbsoluteParent(resource,'2')}" />
+<pre><code><c:set var="content" value="${sling:getAbsoluteParent(resource,'2')}" />
</code></pre>
-<h3><a href="#getparents" name="getparents">getParents</a></h3>
+<h3><a href="#getparents" id="getparents">getParents</a></h3>
<p>Function for retrieving all of the parent resources of a specified resource, returning them in hierarchy order.</p>
<ul>
- <li>Returns: <code>java.lang.Iterator</code> - an iterator of the parent resources in order</li>
- <li>Accepts:
- <ul>
- <li><code>org.apache.sling.api.resource.Resource</code> - The current resource for which to retrieve the parents</li>
- <li><code>java.lang.String</code> - The depth at which to start, for example given a path of: /content/page1/page2/page3 and a start depth of 3, the parents page2/page3 would be returned</li>
- </ul>
- </li>
- <li>Since: Bundle 2.3.0</li>
+<li>Returns: <code>java.lang.Iterator</code> - an iterator of the parent resources in order</li>
+<li>Accepts:
+<ul>
+<li><code>org.apache.sling.api.resource.Resource</code> - The current resource for which to retrieve the parents</li>
+<li><code>java.lang.String</code> - The depth at which to start, for example given a path of: /content/page1/page2/page3 and a start depth of 3, the parents page2/page3 would be returned</li>
+</ul>
+</li>
+<li>Since: Bundle 2.3.0</li>
</ul>
<p><em>Example Usage</em></p>
-<pre><code><c:set var="parents" value="${sling:getParents(resource,'2')}" />
+<pre><code><c:set var="parents" value="${sling:getParents(resource,'2')}" />
<c:forEach var="parent" items="${parents}">
<div>${parent.path}</div>
</c:forEach>
</code></pre>
-<h3><a href="#getrelativeresource" name="getrelativeresource">getRelativeResource</a></h3>
+<h3><a href="#getrelativeresource" id="getrelativeresource">getRelativeResource</a></h3>
<p>Gets the resource at the relative path to the provided resource.</p>
<ul>
- <li>Returns: <code>org.apache.sling.api.resource.Resource</code> - The resource at the relative path.</li>
- <li>Accepts:
- <ul>
- <li><code>org.apache.sling.api.resource.Resource</code> - The resource relative to which to find the path.</li>
- <li><code>java.lang.String</code> - The relative path at which to find the resource.</li>
- </ul>
- </li>
- <li>Since: 1.3</li>
+<li>Returns: <code>org.apache.sling.api.resource.Resource</code> - The resource at the relative path.</li>
+<li>Accepts:
+<ul>
+<li><code>org.apache.sling.api.resource.Resource</code> - The resource relative to which to find the path.</li>
+<li><code>java.lang.String</code> - The relative path at which to find the resource.</li>
+</ul>
+</li>
+<li>Since: 1.3</li>
</ul>
<p><em>Example Usage</em></p>
-<pre><code><c:set var="content" value="${sling:getRelativeResource(resource,'jcr:content')}" />
+<pre><code><c:set var="content" value="${sling:getRelativeResource(resource,'jcr:content')}" />
</code></pre>
-<h3><a href="#getresource" name="getresource">getResource</a></h3>
+<h3><a href="#getresource" id="getresource">getResource</a></h3>
<p>Method allow for the retrieval of resources.</p>
<ul>
- <li>Returns: <code>org.apache.sling.api.resource.Resource</code> - The resource at the path.</li>
- <li>Accepts:
- <ul>
- <li><code>org.apache.sling.api.resource.ResourceResolver</code> - The current resource resolver.</li>
- <li><code>java.lang.String</code> - The path at which to find the resource.</li>
- </ul>
- </li>
- <li>Since: 1.3</li>
+<li>Returns: <code>org.apache.sling.api.resource.Resource</code> - The resource at the path.</li>
+<li>Accepts:
+<ul>
+<li><code>org.apache.sling.api.resource.ResourceResolver</code> - The current resource resolver.</li>
+<li><code>java.lang.String</code> - The path at which to find the resource.</li>
+</ul>
+</li>
+<li>Since: 1.3</li>
</ul>
<p><em>Example Usage</em></p>
-<pre><code><c:set var="content" value="${sling:getResource(resourceResolver,'/content')}" />
+<pre><code><c:set var="content" value="${sling:getResource(resourceResolver,'/content')}" />
</code></pre>
-<h3><a href="#getvalue" name="getvalue">getValue</a></h3>
+<h3><a href="#getvalue" id="getvalue">getValue</a></h3>
<p>Gets the value of the specified key from the ValueMap and either coerses the value into the specified type or uses the specified type as a default depending on the parameter passed in.</p>
<p>If the third parameter is a class, the resulting value will be coersed into the class, otherwise, the third parameter is used as the default when retrieving the value from the <code>ValueMap</code>.</p>
<ul>
- <li>Returns: <code>java.lang.Object</code> - The value.</li>
- <li>Accepts:
- <ul>
- <li><code>org.apache.sling.api.resource.ValueMap</code> - The ValueMap from which to retrieve the value.</li>
- <li><code>java.lang.String</code> - The key for the value to retrieve</li>
- <li><code>java.lang.Object</code> - Either the default value or the class to which to coerce the value.</li>
- </ul>
- </li>
- <li>Since: 1.3</li>
+<li>Returns: <code>java.lang.Object</code> - The value.</li>
+<li>Accepts:
+<ul>
+<li><code>org.apache.sling.api.resource.ValueMap</code> - The ValueMap from which to retrieve the value.</li>
+<li><code>java.lang.String</code> - The key for the value to retrieve</li>
+<li><code>java.lang.Object</code> - Either the default value or the class to which to coerce the value.</li>
+</ul>
+</li>
+<li>Since: 1.3</li>
</ul>
<p><em>Example Usage</em></p>
-<pre><code><c:set var="content" value="${sling:getValue(properties,'jcr:title',resource.name)}" />
+<pre><code><c:set var="content" value="${sling:getValue(properties,'jcr:title',resource.name)}" />
</code></pre>
-<h3><a href="#haschildren" name="haschildren">hasChildren</a></h3>
+<h3><a href="#haschildren" id="haschildren">hasChildren</a></h3>
<p>Return true if the specified resource has child resources.</p>
<ul>
- <li>Returns: <code>java.lang.Boolean</code> - True if there are child resource of the specified resource</li>
- <li>Accepts:
- <ul>
- <li><code>org.apache.sling.api.resource.Resource</code> - The resource of which to check for children.</li>
- </ul>
- </li>
- <li>Since: 1.3</li>
+<li>Returns: <code>java.lang.Boolean</code> - True if there are child resource of the specified resource</li>
+<li>Accepts:
+<ul>
+<li><code>org.apache.sling.api.resource.Resource</code> - The resource of which to check for children.</li>
+</ul>
+</li>
+<li>Since: 1.3</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><c:if test="${sling:hasChildren(resource)">
<h1>Do Something</h1>
</c:if>
</code></pre>
-<h3><a href="#listchildren" name="listchildren">listChildren</a></h3>
+<h3><a href="#listchildren" id="listchildren">listChildren</a></h3>
<p>Method for allowing the invocation of the Sling Resource listChildren method.</p>
<ul>
- <li>Returns: <code>java.util.Iterator</code> - The children of the resource.</li>
- <li>Accepts:
- <ul>
- <li><code>org.apache.sling.api.resource.Resource</code> - The resource of which to list the children.</li>
- </ul>
- </li>
- <li>Since: 1.3</li>
+<li>Returns: <code>java.util.Iterator</code> - The children of the resource.</li>
+<li>Accepts:
+<ul>
+<li><code>org.apache.sling.api.resource.Resource</code> - The resource of which to list the children.</li>
+</ul>
+</li>
+<li>Since: 1.3</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><c:forEach var="child" items="${sling:listChildren(resource)">
<li>${child.path}</li>
</c:forEach>
</code></pre>
-<h2><a href="#tags" name="tags">Tags</a></h2>
+<h2><a href="#tags" id="tags">Tags</a></h2>
<p>The Sling Taglib includes a number of Tags which can be used to access the repository, handle the inclusion of scripts and manage requests.</p>
-<h3><a href="#adaptto" name="adaptto">adaptTo</a></h3>
+<h3><a href="#adaptto" id="adaptto">adaptTo</a></h3>
<p>Adapts adaptables to objects of other types.</p>
<ul>
- <li>Attributes
- <ul>
- <li>adaptable - The adaptable object to adapt.</li>
- <li>adaptTo - The class name to which to adapt the adaptable.</li>
- <li>var - The name of the variable to which to save the adapted object.</li>
- </ul>
- </li>
- <li>Since: 1.3</li>
+<li>Attributes
+<ul>
+<li>adaptable - The adaptable object to adapt.</li>
+<li>adaptTo - The class name to which to adapt the adaptable.</li>
+<li>var - The name of the variable to which to save the adapted object.</li>
+</ul>
+</li>
+<li>Since: 1.3</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><sling:adaptTo adaptable="${resource}" adaptTo="org.apache.sling.api.resource.ValueMap" var="myProps" />
</code></pre>
-<h3><a href="#call" name="call">call</a></h3>
+<h3><a href="#call" id="call">call</a></h3>
<p>Execute a script.</p>
<ul>
- <li>Attributes
- <ul>
- <li>flush - Whether to flush the output before including the target.</li>
- <li>script - The script to include.</li>
- <li>ignoreComponentHierarchy - Controls if the component hierarchy should be ignored for script resolution. If true, only the search paths are respected.</li>
- </ul>
- </li>
- <li>Since: 1.2</li>
+<li>Attributes
+<ul>
+<li>flush - Whether to flush the output before including the target.</li>
+<li>script - The script to include.</li>
+<li>ignoreComponentHierarchy - Controls if the component hierarchy should be ignored for script resolution. If true, only the search paths are respected.</li>
+</ul>
+</li>
+<li>Since: 1.2</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><sling:call script="myscript.jsp" />
</code></pre>
-<h3><a href="#defineobjects" name="defineobjects">defineObjects</a></h3>
+<h3><a href="#defineobjects" id="defineobjects">defineObjects</a></h3>
<p>Defines regularly used scripting variables. By default the following scripting variables are defined through this tag:</p>
<ul>
- <li><strong>slingRequest</strong>, SlingHttpServletRequest object, providing access to the HTTP request header information - extends the standard HttpServletRequest - and provides access to Sling-specific things like resource, path info, selector, etc.</li>
- <li><strong>slingResponse</strong>, SlingHttpServletResponse object, providing access for the HTTP response that is created by the server. This is currently the same as the HttpServletResponse from which it extends.</li>
- <li><strong>resourceResolver</strong>, Current ResourceResolver. Same as slingRequest.getResourceResolver().</li>
- <li><strong>sling</strong>, SlingScriptHelper, containing convenience methods for scripts, mainly sling.include('/some/other/resource') for including the responses of other resources inside this response (eg. embedding header html snippets) and sling.getService(foo.bar.Service.class) to retrieve OSGi services available in Sling (Class notation depending on scripting language).</li>
- <li><strong>resource</strong>, current Resource to handle, depending on the URL of the request. Same as slingRequest.getResource().</li>
- <li><strong>log</strong>, provides an SLF4J Logger for logging to the Sling log system from within scripts, eg. log.info("Executing my script").</li>
- <li><strong>currentNode</strong>, the underlying JCR node (if there is one) of the current resource.</li>
- <li><strong>bindings</strong>, provides access to the SlingBindings object for access to non-standard scripting variables.</li>
+<li><strong>slingRequest</strong>, SlingHttpServletRequest object, providing access to the HTTP request header information - extends the standard HttpServletRequest - and provides access to Sling-specific things like resource, path info, selector, etc.</li>
+<li><strong>slingResponse</strong>, SlingHttpServletResponse object, providing access for the HTTP response that is created by the server. This is currently the same as the HttpServletResponse from which it extends.</li>
+<li><strong>resourceResolver</strong>, Current ResourceResolver. Same as slingRequest.getResourceResolver().</li>
+<li><strong>sling</strong>, SlingScriptHelper, containing convenience methods for scripts, mainly sling.include('/some/other/resource') for including the responses of other resources inside this response (eg. embedding header html snippets) and sling.getService(foo.bar.Service.class) to retrieve OSGi services available in Sling (Class notation depending on scripting language).</li>
+<li><strong>resource</strong>, current Resource to handle, depending on the URL of the request. Same as slingRequest.getResource().</li>
+<li><strong>log</strong>, provides an SLF4J Logger for logging to the Sling log system from within scripts, eg. log.info("Executing my script").</li>
+<li><strong>currentNode</strong>, the underlying JCR node (if there is one) of the current resource.</li>
+<li><strong>bindings</strong>, provides access to the SlingBindings object for access to non-standard scripting variables.</li>
</ul>
<p>See also <a href="https://cwiki.apache.org/confluence/display/SLING/Scripting+variables#Scriptingvariables-JSP">Scripting variables in CMS</a></p>
<ul>
- <li>Attributes which allow to bind the according variables to other names than the default ones listed above.
- <ul>
- <li>requestName</li>
- <li>responseName</li>
- <li>resourceName</li>
- <li>nodeName</li>
- <li>logName</li>
- <li>resourceResolverName</li>
- <li>slingName</li>
- </ul>
- </li>
- <li>Since: 1.0</li>
+<li>Attributes which allow to bind the according variables to other names than the default ones listed above.
+<ul>
+<li>requestName</li>
+<li>responseName</li>
+<li>resourceName</li>
+<li>nodeName</li>
+<li>logName</li>
+<li>resourceResolverName</li>
+<li>slingName</li>
+</ul>
+</li>
+<li>Since: 1.0</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><sling:defineObjects />
</code></pre>
-<h3><a href="#encode" name="encode">encode</a></h3>
-<p>Writes properly Cross Site Scripting (XSS) encoded text to the response using the OWASP ESAPI. Supports a number of encoding modes.</p>
-<ul>
- <li>Attributes:
- <ul>
- <li>value - The text to encode</li>
- <li>default - a default text to use if the value is null or empty</li>
- <li>mode - The encoding mode, one of HTML, HTML_ATTR, XML, XML_ATTR, JS</li>
- </ul>
- </li>
- <li>Since: 1.4</li>
+<h3><a href="#encode" id="encode">encode</a></h3>
+<p>Writes properly Cross Site Scripting (XSS) encoded text to the response using the OWASP ESAPI. Supports a number of encoding modes.</p>
+<ul>
+<li>Attributes:
+<ul>
+<li>value - The text to encode</li>
+<li>default - a default text to use if the value is null or empty</li>
+<li>mode - The encoding mode, one of HTML, HTML_ATTR, XML, XML_ATTR, JS</li>
+</ul>
+</li>
+<li>Since: 1.4</li>
</ul>
<p><em>Example Usage</em></p>
-<pre><code><sling:encode value="<script>alert('Bad Stuff!');</script>" mode="HTML" />
+<pre><code><sling:encode value="<script>alert('Bad Stuff!');</script>" mode="HTML" />
</code></pre>
-<h3><a href="#eval" name="eval">eval</a></h3>
+<h3><a href="#eval" id="eval">eval</a></h3>
<p>Evaluates a script invocation and includes the result in the current page.</p>
<ul>
- <li>Attributes
- <ul>
- <li>flush - Whether to flush the output before including the target.</li>
- <li>script - The path to the script object to include in the current request processing. By default, the current resource is used for script resolving. This behaviour can be changed by specifying either resource, resourceType or ignoreResourceTypeHierarchy.</li>
- <li>resource - The resource object to include in the current request processing. This attribute is optional. If it is specified, resourceType should not be used. If both are used, resource takes precedence.</li>
- <li>resourceType - The resource type of a resource to include. This attribute is optional. If it is specified, resource should not be used. If both are used, resource takes precedence.</li>
- <li>ignoreResourceTypeHierarchy - Prevents using the resource type hierarchy for searching a script.</li>
- </ul>
- </li>
- <li>Since: 1.1</li>
+<li>Attributes
+<ul>
+<li>flush - Whether to flush the output before including the target.</li>
+<li>script - The path to the script object to include in the current request processing. By default, the current resource is used for script resolving. This behaviour can be changed by specifying either resource, resourceType or ignoreResourceTypeHierarchy.</li>
+<li>resource - The resource object to include in the current request processing. This attribute is optional. If it is specified, resourceType should not be used. If both are used, resource takes precedence.</li>
+<li>resourceType - The resource type of a resource to include. This attribute is optional. If it is specified, resource should not be used. If both are used, resource takes precedence.</li>
+<li>ignoreResourceTypeHierarchy - Prevents using the resource type hierarchy for searching a script.</li>
+</ul>
+</li>
+<li>Since: 1.1</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><sling:eval script="myscript.jsp" />
</code></pre>
-<h3><a href="#findresources" name="findresources">findResources</a></h3>
+<h3><a href="#findresources" id="findresources">findResources</a></h3>
<p>Tag for searching for resources using the given query formulated in the given language.</p>
<ul>
- <li>Attributes
- <ul>
- <li>query - The query string to find the resources.</li>
- <li>language - The query language to use.</li>
- <li>var - The name of the variable to which to save the resources.</li>
- </ul>
- </li>
- <li>Since: 1.3</li>
+<li>Attributes
+<ul>
+<li>query - The query string to find the resources.</li>
+<li>language - The query language to use.</li>
+<li>var - The name of the variable to which to save the resources.</li>
+</ul>
+</li>
+<li>Since: 1.3</li>
</ul>
<p><em>Example Usage</em></p>
-<pre><code><sling:findResources query="/jcr:root//*[jcr:contains(., 'Sling')] order by @jcr:score" language="xpath" var="resources" />
+<pre><code><sling:findResources query="/jcr:root//*[jcr:contains(., 'Sling')] order by @jcr:score" language="xpath" var="resources" />
</code></pre>
-<h3><a href="#forward" name="forward">forward</a></h3>
+<h3><a href="#forward" id="forward">forward</a></h3>
<p>Forwards a request to a resource rendering the current page</p>
<ul>
- <li>Attributes
- <ul>
- <li>resource - The resource object to forward the request to. Either resource or path must be specified. If both are specified, the resource takes precedences.</li>
- <li>path - The path to the resource object to forward the request to. If this path is relative it is appended to the path of the current resource whose script is forwarding the given resource. Either resource or path must be specified. If both are specified, the resource takes precedences.</li>
- <li>resourceType - The resource type of a resource to forward. If the resource to be forwarded is specified with the path attribute, which cannot be resolved to a resource, the tag may create a synthetic resource object out of the path and this resource type. If the resource type is set the path must be the exact path to a resource object. That is, adding parameters, selectors and extensions to the path is not supported if the resource type is set.</li>
- <li>replaceSelectors - When dispatching, replace selectors by the value provided by this option.</li>
- <li>addSelectors - When dispatching, add the value provided by this option to the selectors.</li>
- <li>replaceSuffix - When dispatching, replace the suffix by the value provided by this option.</li>
- </ul>
- </li>
- <li>Since: 1.0</li>
+<li>Attributes
+<ul>
+<li>resource - The resource object to forward the request to. Either resource or path must be specified. If both are specified, the resource takes precedences.</li>
+<li>path - The path to the resource object to forward the request to. If this path is relative it is appended to the path of the current resource whose script is forwarding the given resource. Either resource or path must be specified. If both are specified, the resource takes precedences.</li>
+<li>resourceType - The resource type of a resource to forward. If the resource to be forwarded is specified with the path attribute, which cannot be resolved to a resource, the tag may create a synthetic resource object out of the path and this resource type. If the resource type is set the path must be the exact path to a resource object. That is, adding parameters, selectors and extensions to the path is not supported if the resource type is set.</li>
+<li>replaceSelectors - When dispatching, replace selectors by the value provided by this option.</li>
+<li>addSelectors - When dispatching, add the value provided by this option to the selectors.</li>
+<li>replaceSuffix - When dispatching, replace the suffix by the value provided by this option.</li>
+</ul>
+</li>
+<li>Since: 1.0</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><sling:forward path="/content/aresource" resourceType="myapp/components/display" />
</code></pre>
-<h3><a href="#getcaconfigresource" name="getcaconfigresource">getCAConfigResource</a></h3>
+<h3><a href="#getcaconfigresource" id="getcaconfigresource">getCAConfigResource</a></h3>
<p>Retrieves Context-Aware Configuration resource for a specified resource, bucket and name.</p>
<ul>
- <li>Attributes
- <ul>
- <li>resource - The resource for which to retrieve CA Config</li>
- <li>bucket - The bucket name to retrieve for the config</li>
- <li>name - The config name to retrieve</li>
- <li>var - The name of the variable to which to save the CA config resource.</li>
- </ul>
- </li>
- <li>Since: Bundle 2.3.0</li>
+<li>Attributes
+<ul>
+<li>resource - The resource for which to retrieve CA Config</li>
+<li>bucket - The bucket name to retrieve for the config</li>
+<li>name - The config name to retrieve</li>
+<li>var - The name of the variable to which to save the CA config resource.</li>
+</ul>
+</li>
+<li>Since: Bundle 2.3.0</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><sling:getCAConfigResource resource="${resource}" bucket="site" name="templates" var="config" />
</code></pre>
-<h3><a href="#getcaconfigresources" name="getcaconfigresources">getCAConfigResources</a></h3>
+<h3><a href="#getcaconfigresources" id="getcaconfigresources">getCAConfigResources</a></h3>
<p>Retrieves Context-Aware Configuration resources for a specified resource, bucket and name.</p>
<ul>
- <li>Attributes
- <ul>
- <li>resource - The resource for which to retrieve CA Configs</li>
- <li>bucket - The bucket name to retrieve for the configs</li>
- <li>name - The config name to retrieve</li>
- <li>var - The name of the variable to which to save the CA config resources.</li>
- </ul>
- </li>
- <li>Since: Bundle 2.3.0</li>
+<li>Attributes
+<ul>
+<li>resource - The resource for which to retrieve CA Configs</li>
+<li>bucket - The bucket name to retrieve for the configs</li>
+<li>name - The config name to retrieve</li>
+<li>var - The name of the variable to which to save the CA config resources.</li>
+</ul>
+</li>
+<li>Since: Bundle 2.3.0</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><sling:getCAConfigResources resource="${resource}" bucket="site" name="templates" var="config" />
</code></pre>
-<h3><a href="#getparent" name="getparent">getParent</a></h3>
+<h3><a href="#getparent" id="getparent">getParent</a></h3>
<p>Retrieves the parent of the resource or the absolute parent at the level if specified.</p>
<ul>
- <li>Attributes
- <ul>
- <li>resource - The resource for which to retrieve the parent resource.</li>
- <li>level - The level of the parent resource to retrieve</li>
- <li>var - The name of the variable to which to save the parent resource.</li>
- </ul>
- </li>
- <li>Since: Bundle 2.3.0</li>
+<li>Attributes
+<ul>
+<li>resource - The resource for which to retrieve the parent resource.</li>
+<li>level - The level of the parent resource to retrieve</li>
+<li>var - The name of the variable to which to save the parent resource.</li>
+</ul>
+</li>
+<li>Since: Bundle 2.3.0</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><sling:getParent resource="${resource}" level="2" var="parent" />
</code></pre>
-<h3><a href="#getparents" name="getparents">getParents</a></h3>
+<h3><a href="#getparents" id="getparents">getParents</a></h3>
<p>Retrieves all of the parent resources of a specified resource, returning them in hierarchy order.</p>
<ul>
- <li>Attributes
- <ul>
- <li>resource - The resource for which to retrieve the parent resources.</li>
- <li>startDepth - The depth at which to start, for example given a path of: /content/page1/page2/page3 and a start depth of 3, the parents page2/page3 would be returned</li>
- <li>var - The name of the variable to which to save the parent resources.</li>
- </ul>
- </li>
- <li>Since: Bundle 2.3.0</li>
+<li>Attributes
+<ul>
+<li>resource - The resource for which to retrieve the parent resources.</li>
+<li>startDepth - The depth at which to start, for example given a path of: /content/page1/page2/page3 and a start depth of 3, the parents page2/page3 would be returned</li>
+<li>var - The name of the variable to which to save the parent resources.</li>
+</ul>
+</li>
+<li>Since: Bundle 2.3.0</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><sling:getProperties properties="${properties}" key="jcr:title" defaultValue="${resource.name}" var="title" />
</code></pre>
-<h3><a href="#getresource" name="getresource">getResource</a></h3>
+<h3><a href="#getresource" id="getresource">getResource</a></h3>
<p>Retrieves resources based on either an absolute path or a relative path and a base resource.</p>
<ul>
- <li>Attributes
- <ul>
- <li>base - The base resource under which to retrieve the child resource, will only be considered if a relative path is specified.</li>
- <li>path - The path of the resource to retrieve, if relative, the base resource must be specified.</li>
- <li>var - The name of the variable to which to save the resource.</li>
- </ul>
- </li>
- <li>Since: 1.3</li>
+<li>Attributes
+<ul>
+<li>base - The base resource under which to retrieve the child resource, will only be considered if a relative path is specified.</li>
+<li>path - The path of the resource to retrieve, if relative, the base resource must be specified.</li>
+<li>var - The name of the variable to which to save the resource.</li>
+</ul>
+</li>
+<li>Since: 1.3</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><sling:getResource base="${resource}" path="jcr:content" var="content" />
</code></pre>
-<h3><a href="#include" name="include">include</a></h3>
+<h3><a href="#include" id="include">include</a></h3>
<p>Includes a resource rendering into the current page.</p>
<ul>
- <li>Attributes
- <ul>
- <li>flush - Whether to flush the output before including the target.</li>
- <li>resource - The resource object to include in the current request processing. Either resource or path must be specified. If both are specified, the resource takes precedences.</li>
- <li>path - The path to the resource object to include in the current request processing. If this path is relative it is appended to the path of the current resource whose script is including the given resource. Either resource or path must be specified. If both are specified, the resource takes precedences.</li>
- <li>resourceType - The resource type of a resource to include. If the resource to be included is specified with the path attribute, which cannot be resolved to a resource, the tag may create a synthetic resource object out of the path and this resource type. If the resource type is set the path must be the exact path to a resource object. That is, adding parameters, selectors and extensions to the path is not supported if the resource type is set.</li>
- <li>replaceSelectors - When dispatching, replace selectors by the value provided by this option.</li>
- <li>addSelectors - When dispatching, add the value provided by this option to the selectors.</li>
- <li>replaceSuffix - When dispatching, replace the suffix by the value provided by this option.</li>
- <li>scope - If var is specified, what scope to store the variable in. (Since 1.3)</li>
- <li>var - variable name to store the resulting markup into (Since 1.3)</li>
- </ul>
- </li>
- <li>Since: 1.0</li>
+<li>Attributes
+<ul>
+<li>flush - Whether to flush the output before including the target.</li>
+<li>resource - The resource object to include in the current request processing. Either resource or path must be specified. If both are specified, the resource takes precedences.</li>
+<li>path - The path to the resource object to include in the current request processing. If this path is relative it is appended to the path of the current resource whose script is including the given resource. Either resource or path must be specified. If both are specified, the resource takes precedences.</li>
+<li>resourceType - The resource type of a resource to include. If the resource to be included is specified with the path attribute, which cannot be resolved to a resource, the tag may create a synthetic resource object out of the path and this resource type. If the resource type is set the path must be the exact path to a resource object. That is, adding parameters, selectors and extensions to the path is not supported if the resource type is set.</li>
+<li>replaceSelectors - When dispatching, replace selectors by the value provided by this option.</li>
+<li>addSelectors - When dispatching, add the value provided by this option to the selectors.</li>
+<li>replaceSuffix - When dispatching, replace the suffix by the value provided by this option.</li>
+<li>scope - If var is specified, what scope to store the variable in. (Since 1.3)</li>
+<li>var - variable name to store the resulting markup into (Since 1.3)</li>
+</ul>
+</li>
+<li>Since: 1.0</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><sling:include path="/content/aresource" resourceType="myapp/components/display" />
</code></pre>
-<h3><a href="#listchildren" name="listchildren">listChildren</a></h3>
+<h3><a href="#listchildren" id="listchildren">listChildren</a></h3>
<p>Lists the children of a Sling Resource.</p>
<ul>
- <li>Attributes
- <ul>
- <li>resource - The resource for which to retrieve the children.</li>
- <li>var - The name of the variable to which to save the child resources.</li>
- </ul>
- </li>
- <li>Since: 1.3</li>
+<li>Attributes
+<ul>
+<li>resource - The resource for which to retrieve the children.</li>
+<li>var - The name of the variable to which to save the child resources.</li>
+</ul>
+</li>
+<li>Since: 1.3</li>
</ul>
<p><em>Example Usage</em></p>
<pre><code><sling:listChildren resource="${resource}" var="children" />
-</code></pre></section></div></div>
+</code></pre>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/scripting/scripting-thymeleaf.html b/documentation/bundles/scripting/scripting-thymeleaf.html
index 31f87ca..e664c55 100644
--- a/documentation/bundles/scripting/scripting-thymeleaf.html
+++ b/documentation/bundles/scripting/scripting-thymeleaf.html
@@ -125,16 +125,16 @@
<div class="row"><div><section><p>Sling Scripting Thymeleaf is the scripting engine for <a href="http://www.thymeleaf.org"><em>Thymeleaf</em></a> (3.0) templates.</p>
<p><!-- TODO reactivate TOC once JBake moves to flexmark-java -->
</p>
-<h1><a href="#features" name="features">Features</a></h1>
+<h1><a href="#features" id="features">Features</a></h1>
<ul>
- <li>Supporting all of Thymeleaf's extension points: <a href="http://www.thymeleaf.org/apidocs/thymeleaf/3.0.0.RELEASE/org/thymeleaf/templateresolver/ITemplateResolver.html"><em>TemplateResolver</em></a>s, <a href="http://www.thymeleaf.org/apidocs/thymeleaf/3.0.0.RELEASE/org/thymeleaf/messageresolver/IMessageResolver.html"><em>MessageResolver</em></a>s, <a href="http://www.thymeleaf.org/apidocs/thymeleaf/3.0.0.RELEASE/org/thymeleaf/dialect/IDialect.html"><em>Dialect</em></a>s, <a hre [...]
- <li><code>SlingResourceTemplateResolver</code> customizable through <code>TemplateModeProvider</code></li>
- <li><code>ResourceBundleMessageResolver</code> backed by <code>ResourceBundleProvider</code> from <a href="https://sling.apache.org/documentation/bundles/internationalization-support-i18n.html">Sling i18n</a> customizable through optional <code>AbsentMessageRepresentationProvider</code></li>
- <li><code>PatternTemplateModeProvider</code> supporting <a href="https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html"><code>Pattern</code></a> configurations for all <a href="http://www.thymeleaf.org/apidocs/thymeleaf/3.0.0.RELEASE/org/thymeleaf/templatemode/TemplateMode.html">template modes</a> (<code>HTML</code>, <code>XML</code>, <code>TEXT</code>, <code>JAVASCRIPT</code>, <code>CSS</code> and <code>RAW</code>)</li>
- <li><code>SlingDialect</code></li>
- <li>Thymeleaf's <a href="http://www.thymeleaf.org/apidocs/thymeleaf/3.0.0.RELEASE/org/thymeleaf/ITemplateEngine.html"><code>TemplateEngine</code></a> registered as OSGi Service (<a href="http://www.thymeleaf.org/apidocs/thymeleaf/3.0.0.RELEASE/org/thymeleaf/ITemplateEngine.html"><code>ITemplateEngine</code></a>) for direct use</li>
+<li>Supporting all of Thymeleaf's extension points: <a href="http://www.thymeleaf.org/apidocs/thymeleaf/3.0.0.RELEASE/org/thymeleaf/templateresolver/ITemplateResolver.html"><em>TemplateResolver</em></a>s, <a href="http://www.thymeleaf.org/apidocs/thymeleaf/3.0.0.RELEASE/org/thymeleaf/messageresolver/IMessageResolver.html"><em>MessageResolver</em></a>s, <a href="http://www.thymeleaf.org/apidocs/thymeleaf/3.0.0.RELEASE/org/thymeleaf/dialect/IDialect.html">_Dialect_</a>s, <a href="http:/ [...]
+<li><code>SlingResourceTemplateResolver</code> customizable through <code>TemplateModeProvider</code></li>
+<li><code>ResourceBundleMessageResolver</code> backed by <code>ResourceBundleProvider</code> from <a href="https://sling.apache.org/documentation/bundles/internationalization-support-i18n.html">Sling i18n</a> customizable through optional <code>AbsentMessageRepresentationProvider</code></li>
+<li><code>PatternTemplateModeProvider</code> supporting <a href="https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html"><code>Pattern</code></a> configurations for all <a href="http://www.thymeleaf.org/apidocs/thymeleaf/3.0.0.RELEASE/org/thymeleaf/templatemode/TemplateMode.html">template modes</a> (<code>HTML</code>, <code>XML</code>, <code>TEXT</code>, <code>JAVASCRIPT</code>, <code>CSS</code> and <code>RAW</code>)</li>
+<li><code>SlingDialect</code></li>
+<li>Thymeleaf's <a href="http://www.thymeleaf.org/apidocs/thymeleaf/3.0.0.RELEASE/org/thymeleaf/ITemplateEngine.html"><code>TemplateEngine</code></a> registered as OSGi Service (<a href="http://www.thymeleaf.org/apidocs/thymeleaf/3.0.0.RELEASE/org/thymeleaf/ITemplateEngine.html"><code>ITemplateEngine</code></a>) for direct use</li>
</ul>
-<h1><a href="#installation" name="installation">Installation</a></h1>
+<h1><a href="#installation" id="installation">Installation</a></h1>
<p>For running Sling Scripting Thymeleaf with Sling's Launchpad some dependencies need to be resolved. This can be achieved by installing the following bundles:</p>
<pre><code>mvn:org.attoparser/attoparser/2.0.2.RELEASE
mvn:org.unbescape/unbescape/1.1.4.RELEASE
@@ -145,41 +145,38 @@ mvn:org.javassist/javassist/3.20.0-GA
<pre><code>karaf@root()> feature:install sling-scripting-thymeleaf
</code></pre>
<p><strong>Note:</strong> Sling Scripting Thymeleaf requires an implementation of OSGi Declarative Services 1.3 (e.g. <a href="http://felix.apache.org/documentation/subprojects/apache-felix-service-component-runtime.html">Apache Felix Service Component Runtime</a> 2.0.0 or greater)</p>
-<h1><a href="#configuration" name="configuration">Configuration</a></h1>
-<h2><a href="#apache-sling-scripting-thymeleaf-scriptenginefactory-" name="apache-sling-scripting-thymeleaf-scriptenginefactory-">Apache Sling Scripting Thymeleaf “ScriptEngineFactory”</a></h2>
+<h1><a href="#configuration" id="configuration">Configuration</a></h1>
+<h2><a href="#apache-sling-scripting-thymeleaf-scriptenginefactory" id="apache-sling-scripting-thymeleaf-scriptenginefactory">Apache Sling Scripting Thymeleaf “ScriptEngineFactory”</a></h2>
<p>By default Sling Scripting Thymeleaf's <em>ScriptEngineFactory</em> is configured for templates with extension <code>html</code> and mime type <code>text/html</code> and uses all of Thymeleaf's standard extensions either <em>also</em> or <em>exclusively</em>.</p>
<p><img src="Scripting-Thymeleaf-ScriptEngineFactory.png" alt="Apache Sling Scripting Thymeleaf “ScriptEngineFactory”" /></p>
-<h2><a href="#apache-sling-scripting-thymeleaf-sling-resource-templateresolver-" name="apache-sling-scripting-thymeleaf-sling-resource-templateresolver-">Apache Sling Scripting Thymeleaf “Sling Resource TemplateResolver”</a></h2>
+<h2><a href="#apache-sling-scripting-thymeleaf-sling-resource-templateresolver" id="apache-sling-scripting-thymeleaf-sling-resource-templateresolver">Apache Sling Scripting Thymeleaf “Sling Resource TemplateResolver”</a></h2>
<p>The <em>Sling Resource TemplateResolver</em> is configured to resolve templates with <em>use decoupled logic</em> enabled.</p>
<p><img src="Scripting-Thymeleaf-Sling-Resource-TemplateResolver.png" alt="Apache Sling Scripting Thymeleaf “Sling Resource TemplateResolver”" /></p>
-<h2><a href="#apache-sling-scripting-thymeleaf-pattern-templatemodeprovider-" name="apache-sling-scripting-thymeleaf-pattern-templatemodeprovider-">Apache Sling Scripting Thymeleaf “Pattern TemplateModeProvider”</a></h2>
+<h2><a href="#apache-sling-scripting-thymeleaf-pattern-templatemodeprovider" id="apache-sling-scripting-thymeleaf-pattern-templatemodeprovider">Apache Sling Scripting Thymeleaf “Pattern TemplateModeProvider”</a></h2>
<p>The <em>Pattern TemplateModeProvider</em> is configured to match template paths against default extensions for providing template modes (of course except no-op mode <code>RAW</code>).</p>
<p><img src="Scripting-Thymeleaf-Pattern-TemplateModeProvider.png" alt="Apache Sling Scripting Thymeleaf “Pattern TemplateModeProvider" /></p>
-<h2><a href="#apache-sling-scripting-thymeleaf-resourcebundle-messageresolver-" name="apache-sling-scripting-thymeleaf-resourcebundle-messageresolver-">Apache Sling Scripting Thymeleaf “ResourceBundle MessageResolver”</a></h2>
+<h2><a href="#apache-sling-scripting-thymeleaf-resourcebundle-messageresolver" id="apache-sling-scripting-thymeleaf-resourcebundle-messageresolver">Apache Sling Scripting Thymeleaf “ResourceBundle MessageResolver”</a></h2>
<p>The <em>ResourceBundle MessageResolver</em> is configured to use the message's key as absent message representation.</p>
<p><img src="Scripting-Thymeleaf-ResourceBundle-MessageResolver.png" alt="Apache Sling Scripting Thymeleaf “ResourceBundle MessageResolver”" /></p>
-<h1><a href="#sling-dialect" name="sling-dialect">Sling Dialect</a></h1>
+<h1><a href="#sling-dialect" id="sling-dialect">Sling Dialect</a></h1>
<p>Sling Scripting Thymeleaf comes with its own dialect using the <code>sling</code> prefix/namespace currently supporting the <em>include</em> feature known from <a href="/documentation/bundles/scripting/scripting-jsp.html">Sling Scripting JSP Taglib</a>.</p>
-<h2><a href="#include" name="include">include</a></h2>
-<p><code><header data-sling-include="${resource}" data-sling-resourceType="'example/page/header'" data-sling-unwrap="true"/></code></p>
+<h2><a href="#include" id="include">include</a></h2>
+<p><code><header data-sling-include="${resource}" data-sling-resourceType="'example/page/header'" data-sling-unwrap="true"/></code></p>
<p><code>include</code> - The resource object (<a href="http://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/Resource.html"><code>Resource</code></a>) or the path (<code>String</code>) of the resource object to include in the current request processing. If this path is relative it is appended to the path of the current resource whose script is including the given resource.</p>
-<h3>supported options (* = <a href="http://sling.apache.org/apidocs/sling7/org/apache/sling/api/request/RequestDispatcherOptions.html">RequestDispatcher option</a>)</h3>
+<h3><a href="#supported-options-requestdispatcher-option" id="supported-options-requestdispatcher-option">supported options (* = <a href="http://sling.apache.org/apidocs/sling7/org/apache/sling/api/request/RequestDispatcherOptions.html">RequestDispatcher option</a>)</a></h3>
<ul>
- <li><code>addSelectors</code> (<code>String</code>) *: When dispatching, add the value provided by this option to the selectors.
-</li>
- <li><code>replaceSelectors</code> (<code>String</code>) *: When dispatching, replace selectors by the value provided by this option.
-</li>
- <li><code>replaceSuffix</code> (<code>String</code>) *: When dispatching, replace the suffix by the value provided by this option.
-</li>
- <li><code>resourceType</code> (<code>String</code>) *: The resource type of a resource to include. If the resource to be included is specified with the path attribute, which cannot be resolved to a resource, the tag may create a synthetic resource object out of the path and this resource type. If the resource type is set the path must be the exact path to a resource object. That is, adding parameters, selectors and extensions to the path is not supported if the resource type is set.
-</li>
- <li><code>unwrap</code> (<code>Boolean</code>): removes the host element</li>
+<li><code>addSelectors</code> (<code>String</code>) *: When dispatching, add the value provided by this option to the selectors.</li>
+<li><code>replaceSelectors</code> (<code>String</code>) *: When dispatching, replace selectors by the value provided by this option.</li>
+<li><code>replaceSuffix</code> (<code>String</code>) *: When dispatching, replace the suffix by the value provided by this option.</li>
+<li><code>resourceType</code> (<code>String</code>) *: The resource type of a resource to include. If the resource to be included is specified with the path attribute, which cannot be resolved to a resource, the tag may create a synthetic resource object out of the path and this resource type. If the resource type is set the path must be the exact path to a resource object. That is, adding parameters, selectors and extensions to the path is not supported if the resource type is set.</li>
+<li><code>unwrap</code> (<code>Boolean</code>): removes the host element</li>
</ul>
-<h1><a href="#class-diagram" name="class-diagram">Class Diagram</a></h1>
+<h1><a href="#class-diagram" id="class-diagram">Class Diagram</a></h1>
<p><a href="Scripting-Thymeleaf-Class-Diagram.png"><img src="Scripting-Thymeleaf-Class-Diagram.png" alt="Class Diagram" /></a></p>
-<h1><a href="#sample" name="sample">Sample</a></h1>
+<h1><a href="#sample" id="sample">Sample</a></h1>
<p>The <a href="https://github.com/apache/sling-samples/tree/master/fling">Sling Fling Sample</a> is a sample using Sling Scripting Thymeleaf with <a href="/documentation/bundles/models.html">Sling Models</a> and <a href="/documentation/bundles/sling-query.html">Sling Query</a>.</p>
-<p><img src="sling-fling-sample.png" alt="Sling Fling Sample" /></p></section></div></div>
+<p><img src="sling-fling-sample.png" alt="Sling Fling Sample" /></p>
+</section></div></div>
</div>
</div>
</div>
diff --git a/documentation/bundles/servlet-helpers.html b/documentation/bundles/servlet-helpers.html
index 94c6b1e..33bb7bc 100644
--- a/documentation/bundles/servlet-helpers.html
... 19376 lines suppressed ...