Changes as per Stefan's notes in SLING-6955
Project: http://git-wip-us.apache.org/repos/asf/sling-site/repo Commit: http://git-wip-us.apache.org/repos/asf/sling-site/commit/f542b22e Tree: http://git-wip-us.apache.org/repos/asf/sling-site/tree/f542b22e Diff: http://git-wip-us.apache.org/repos/asf/sling-site/diff/f542b22e Branch: refs/heads/asf-site Commit: f542b22ea040c26c4a1064b93a1cf8ba7452463d Parents: 37a29a3 Author: Bertrand Delacretaz <[email protected]> Authored: Tue Jul 11 14:41:11 2017 +0200 Committer: Bertrand Delacretaz <[email protected]> Committed: Tue Jul 11 14:41:11 2017 +0200 ---------------------------------------------------------------------- contributing.html | 4 +- documentation.html | 14 +- documentation/bundles.html | 16 +-- ...esystem-resources-extensions-fsresource.html | 8 +- .../apache-sling-eventing-and-job-handling.html | 36 ++--- ...dle-resources-extensions-bundleresource.html | 8 +- .../configuration-installer-factory.html | 8 +- documentation/bundles/content-distribution.html | 38 +++--- .../content-loading-jcr-contentloader.html | 24 ++-- ...re-configuration-default-implementation.html | 14 +- .../context-aware-configuration-override.html | 10 +- .../context-aware-configuration-spi.html | 16 +-- .../context-aware-configuration.html | 76 ++++++----- documentation/bundles/datasource-providers.html | 20 ++- .../bundles/discovery-api-and-impl.html | 52 ++++---- documentation/bundles/dynamic-includes.html | 2 +- .../bundles/file-installer-provider.html | 12 +- .../internationalization-support-i18n.html | 6 +- .../bundles/jcr-installer-provider.html | 20 +-- documentation/bundles/log-tracers.html | 28 ++-- ...ng-permissions-jackrabbit-accessmanager.html | 14 +- ...users-and-groups-jackrabbit-usermanager.html | 28 ++-- ...tent-the-slingpostservlet-servlets-post.html | 92 ++++++------- documentation/bundles/metrics.html | 28 ++-- .../bundles/mime-type-support-commons-mime.html | 14 +- documentation/bundles/models.html | 130 ++++++++----------- .../bundles/nosql-resource-providers.html | 8 +- .../bundles/org-apache-sling-junit-bundles.html | 20 +-- documentation/bundles/osgi-installer.html | 24 ++-- ...ing-pipelines-org-apache-sling-rewriter.html | 21 ++- .../rendering-content-default-get-servlets.html | 18 +-- .../bundles/repository-initialization.html | 10 +- documentation/bundles/request-analysis.html | 4 +- .../bundles/resource-access-security.html | 15 +-- documentation/bundles/resource-editor.html | 6 +- documentation/bundles/resource-merger.html | 16 +-- .../scheduler-service-commons-scheduler.html | 24 ++-- documentation/bundles/scripting.html | 2 +- .../bundles/scripting/scripting-htl.html | 30 ++--- .../bundles/scripting/scripting-jsp.html | 44 +++---- .../bundles/scripting/scripting-thymeleaf.html | 22 ++-- documentation/bundles/servlet-helpers.html | 12 +- .../bundles/sling-health-check-tool.html | 20 +-- .../bundles/sling-oak-restrictions.html | 8 +- documentation/bundles/sling-pipes.html | 50 +++---- documentation/bundles/sling-query.html | 10 +- ...ling-settings-org-apache-sling-settings.html | 11 +- .../bundles/subsystem-installer-factory.html | 4 +- documentation/bundles/validation.html | 31 ++--- .../bundles/web-console-extensions.html | 8 +- documentation/configuration.html | 20 +-- documentation/development.html | 8 +- .../development/client-request-logging.html | 10 +- .../development/dependency-management.html | 6 +- documentation/development/embedding-sling.html | 18 +-- .../development/getting-and-building-sling.html | 38 +++--- documentation/development/hamcrest.html | 10 +- documentation/development/ide-tooling.html | 56 ++++---- .../ide-tooling-incremental-build.html | 14 +- documentation/development/issue-tracker.html | 10 +- documentation/development/jcr-mock.html | 19 ++- documentation/development/jsr-305.html | 22 ++-- documentation/development/logging.html | 99 ++++++-------- documentation/development/maven-archetypes.html | 12 +- .../development/maven-launchpad-plugin.html | 12 +- documentation/development/maven-usage.html | 9 +- .../development/maventipsandtricks.html | 12 +- documentation/development/osgi-mock.html | 37 +++--- .../development/release-management.html | 26 ++-- .../repository-based-development.html | 22 ++-- .../development/resourceresolver-mock.html | 12 +- documentation/development/sling-mock.html | 80 +++++------- .../development/sling-testing-tools.html | 22 ++-- documentation/development/slingstart.html | 44 +++---- documentation/development/version-policy.html | 30 ++--- documentation/getting-started.html | 2 +- .../discover-sling-in-15-minutes.html | 18 +-- documentation/legacy/logging.html | 16 +-- documentation/the-sling-engine.html | 8 +- documentation/the-sling-engine/adapters.html | 14 +- .../the-sling-engine/architecture.html | 16 +-- .../authentication/authentication-actors.html | 10 +- .../authentication-authenticationhandler.html | 8 +- .../form-based-authenticationhandler.html | 12 +- .../openid-authenticationhandler.html | 24 ++-- .../authentication-framework.html | 8 +- .../authentication/authentication-tasks.html | 4 +- .../the-sling-engine/dispatching-requests.html | 6 +- .../the-sling-engine/errorhandling.html | 8 +- documentation/the-sling-engine/filters.html | 12 +- .../mappings-for-resource-resolution.html | 35 +++-- .../the-sling-engine/request-listeners.html | 5 +- .../the-sling-engine/request-parameters.html | 8 +- documentation/the-sling-engine/resources.html | 40 +++--- .../service-authentication.html | 36 +++-- documentation/the-sling-engine/servlets.html | 28 ++-- .../sling-api-crud-support.html | 20 +-- .../the-sling-engine/sling-properties.html | 8 +- .../the-sling-engine/the-sling-launchpad.html | 18 +-- .../the-sling-engine/url-decomposition.html | 6 +- .../url-to-script-resolution.html | 14 +- .../wrap-or-decorate-resources.html | 8 +- .../tutorials-how-tos/46-line-blog.html | 14 +- ...tting-resources-and-properties-in-sling.html | 32 ++--- .../how-to-manage-events-in-sling.html | 38 ++---- .../installing-and-upgrading-bundles.html | 12 +- .../jackrabbit-persistence.html | 19 ++- .../testing-sling-based-applications.html | 29 ++--- downloads.html | 2 +- feed.xml | 4 +- index.html | 26 ++-- links.html | 14 +- news/sling-ide-tooling-11-released.html | 8 +- news/sling-launchpad-8-released.html | 16 +-- news/sling-launchpad-9-released.html | 20 +-- old-stuff/assembly.html | 22 ++-- old-stuff/request-processing.html | 10 +- .../run-modes-org-apache-sling-runmode.html | 13 +- .../scriptengineintegration/groovy-support.html | 4 +- .../xslt-processing-pipeline.html | 25 ++-- old-stuff/servlet-resolution.html | 16 +-- old-stuff/sling-api.html | 38 +++--- project-information.html | 26 ++-- ...che-sling-community-roles-and-processes.html | 18 +-- project-information/project-team.html | 10 +- project-information/security.html | 4 +- res/css/site.css | 5 + sitemap.html | 6 +- sitemap.xml | 6 +- 129 files changed, 1247 insertions(+), 1366 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/contributing.html ---------------------------------------------------------------------- diff --git a/contributing.html b/contributing.html index 6aaeb85..66b7c8c 100644 --- a/contributing.html +++ b/contributing.html @@ -76,9 +76,9 @@ <p>Apache Sling is a volunteer effort, so there is always plenty of work that needs to be accomplished. If you want to help support Sling, this page is intended as a starting point for specific contribution ideas. To further understand how the Sling community operates, refer to the Community Roles and Processes document and/or join the mailing lists.</p> <p>The Sling project organizes its "to do" list using the JIRA issue tracking system. Specific items from Sling's JIRA issue tracking system are highlighted on this page, but are not limited to it. The purpose of the list here is to highlight issues that are either more important or serve as good entry points for new contributors.</p> <p>It is important to point out that you do not need to be a programmer to contribute to Sling. As such, we will break out the list of issues below for non-programmers and programmers.</p> -<h2>Non-Programmers</h2> +<h2><a href="#non-programmers" name="non-programmers">Non-Programmers</a></h2> <p>Improve web site or documentation (e.g., create/propose FAQ entries). There is no specific JIRA issue for this task, but any contributions could be posted as new JIRA issues for the Documentation component.</p> -<h2>Programmers</h2> +<h2><a href="#programmers" name="programmers">Programmers</a></h2> <p>Implement support for various rendering technologies in Sling. Examples coming to mind are JSF and Wicket.</p></section></div></div> <div class="footer"> <div class="trademarkFooter"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation.html ---------------------------------------------------------------------- diff --git a/documentation.html b/documentation.html index e8938dc..faad9c5 100644 --- a/documentation.html +++ b/documentation.html @@ -74,7 +74,7 @@ Documentation </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h1>Overview</h1> +<h1><a href="#overview" name="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> @@ -86,9 +86,9 @@ <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>How you can contribute</h1> +<h1><a href="#how-you-can-contribute" name="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>How the documentation is generated</h1> +<h1><a href="#how-the-documentation-is-generated" name="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> @@ -97,14 +97,14 @@ <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>The Sling Website</h2> +<h2><a href="#the-sling-website" name="the-sling-website">The Sling Website</a></h2> <p>TODO this page needs to be adapted to the JBake site generation mechanisms.</p> -<h2>The Public Wiki</h2> +<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>The JavaDoc</h2> +<h2><a href="#the-javadoc" name="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 at <a href="http://svn.apache.org/repos/asf/sling/trunk/tooling/release/";>http://svn.apache.org/repos/asf/sling/trunk/tooling/release/</a> in <code>generate_javadoc_for_release.sh</code></p> <p>In addition every released bundle is released together with its JavaDoc (which is also pushed to Maven Central).</p> -<h2>The Maven Plugin Documentation</h2> +<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> <div class="footer"> <div class="trademarkFooter"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles.html ---------------------------------------------------------------------- diff --git a/documentation/bundles.html b/documentation/bundles.html index c3b2d36..70f9510 100644 --- a/documentation/bundles.html +++ b/documentation/bundles.html @@ -72,7 +72,7 @@ </div> <div class="main"> <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » </div> <h1> Bundles - </h1><div class="row"><div class="small-12 columns"><section class="wrap"><h2>Content</h2> + </h1><div class="row"><div class="small-12 columns"><section class="wrap"><h2><a href="#content" name="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> @@ -81,21 +81,21 @@ <li><a href="/documentation/bundles/validation.html">Validation</a></li> <li><a href="/documentation/bundles/repository-initialization.html">Repository Initialization</a></li> </ul> -<h2>Resource Providers</h2> +<h2><a href="#resource-providers" name="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 (extensions.bundleresource)</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>Users, Groups, Access, Permissions, ACLs on Resources</h2> +<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> <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> </ul> -<h2>OSGi Installer</h2> +<h2><a href="#osgi-installer" name="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> @@ -104,7 +104,7 @@ <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> </ul> -<h2>Development and Utilities</h2> +<h2><a href="#development-and-utilities" name="development-and-utilities">Development and Utilities</a></h2> <ul> <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> @@ -121,7 +121,7 @@ <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> </ul> -<h2>Content Presentation and Rendering</h2> +<h2><a href="#content-presentation-and-rendering" name="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> @@ -129,12 +129,12 @@ <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>Troubleshooting</h2> +<h2><a href="#troubleshooting" name="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> </ul> -<h2>Misc</h2> +<h2><a href="#misc" name="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> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html b/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html index 7ccb8af..5ad5fde 100644 --- a/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html +++ b/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html @@ -74,7 +74,7 @@ Accessing File System Resources (org.apache.sling.fsresource) </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>Introduction</h2> +<h2><a href="#introduction" name="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> @@ -82,21 +82,21 @@ <li>fsresource 2.x (<a href="https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/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://svn.apache.org/repos/asf/sling/branches/fsresource-1.x/";>branch</a>): compatible with Apache Sling API 2.4 and Apache Sling Resource Resolver 1.1.0 or above.</li> </ul> -<h2>Resource Types</h2> +<h2><a href="#resource-types" name="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> </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>Adapters</h2> +<h2><a href="#adapters" name="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> </ul> -<h2>Configuration</h2> +<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> <p>Which files are mounted depends on the 'File system layout' configuration parameter:</p> <ul> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/apache-sling-eventing-and-job-handling.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/apache-sling-eventing-and-job-handling.html b/documentation/bundles/apache-sling-eventing-and-job-handling.html index fe13f6c..58562e5 100644 --- a/documentation/bundles/apache-sling-eventing-and-job-handling.html +++ b/documentation/bundles/apache-sling-eventing-and-job-handling.html @@ -72,7 +72,7 @@ </div> <div class="main"> <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/bundles.html">Bundles</a> » </div> <h1> Apache Sling Eventing and Job Handling - </h1><div class="row"><div class="small-12 columns"><section class="wrap"><h2>Overview</h2> + </h1><div class="row"><div class="small-12 columns"><section class="wrap"><h2><a href="#overview" name="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> @@ -85,7 +85,7 @@ <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>Jobs (Guarantee of Processing)</h2> +<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> <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 there is no job consumer for a job, the job is never processed. However this is considered a deployment error.</p> @@ -115,9 +115,9 @@ </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>JobBuilder</h3> +<h3><a href="#jobbuilder" name="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>Scheduled Jobs</h3> +<h3><a href="#scheduled-jobs" name="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; @@ -141,7 +141,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>Job Consumers</h3> +<h3><a href="#job-consumers" name="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; @@ -160,10 +160,10 @@ public class MyComponent { } </code></pre> <p>The <em>Job</em> interface allows to query the topic, the payload and additional information about the current job. 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>Job Handling</h3> +<h3><a href="#job-handling" name="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>Queue Configurations</h4> +<h4><a href="#queue-configurations" name="queue-configurations">Queue Configurations</a></h4> <p>A queue configuration can have the following properties:</p> <table> <thead> @@ -208,25 +208,25 @@ public class MyComponent { </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>Ordered Queues</h4> +<h4><a href="#ordered-queues" name="ordered-queues">Ordered Queues</a></h4> <p>An ordered queue processes one job after the other.</p> -<h4>Unordered Queues (or Parallel queues)</h4> +<h4><a href="#unordered-queues-or-parallel-queues-" name="unordered-queues-or-parallel-queues-">Unordered Queues (or Parallel queues)</a></h4> <p>Unordered queues process jobs in parallel.</p> -<h4>Topic-Round-Robin Queues</h4> +<h4><a href="#topic-round-robin-queues" name="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>Job Distributing</h3> +<h3><a href="#job-distributing" name="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>Job Creation Patterns</h3> +<h3><a href="#job-creation-patterns" name="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>Jobs based on user action</h4> +<h4><a href="#jobs-based-on-user-action" name="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>Jobs based on observation / events</h4> +<h4><a href="#jobs-based-on-observation-events" name="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>Distributed Events</h2> +<h2><a href="#distributed-events" name="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>Basic Principles</h3> +<h3><a href="#basic-principles" name="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> @@ -235,10 +235,10 @@ public class MyComponent { <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 distributed event.</li> </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>Event Distribution Across Application Nodes (Cluster)</h3> +<h3><a href="#event-distribution-across-application-nodes-cluster-" name="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 locally.</p> <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>Sending Scheduled Events</h2> +<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> <div class="footer"> <div class="trademarkFooter"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/bundle-resources-extensions-bundleresource.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/bundle-resources-extensions-bundleresource.html b/documentation/bundles/bundle-resources-extensions-bundleresource.html index 8fe056d..23f4ed3 100644 --- a/documentation/bundles/bundle-resources-extensions-bundleresource.html +++ b/documentation/bundles/bundle-resources-extensions-bundleresource.html @@ -74,21 +74,21 @@ Bundle Resources (extensions.bundleresource) </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>Introduction</h2> +<h2><a href="#introduction" name="introduction">Introduction</a></h2> <p>The Bundle Resource Provider provides access to files/directories included in an OSGi bundle through the Sling <code>ResourceResolver</code>. </p> -<h2>Resource Types</h2> +<h2><a href="#resource-types" name="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 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> </ul> -<h2>Adapters</h2> +<h2><a href="#adapters" name="adapters">Adapters</a></h2> <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> </ul> -<h2>Configuration</h2> +<h2><a href="#configuration" name="configuration">Configuration</a></h2> <p>Providing bundles have a Bundle manifest header <code>Sling-Bundle-Resources</code> containing a list of absolute paths provided by the bundle. The paths are separated by comma or whitespace (SP, TAB, VTAB, CR, LF). </p> <p>Example (manifest.mf):</p> <pre><code>... http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/configuration-installer-factory.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/configuration-installer-factory.html b/documentation/bundles/configuration-installer-factory.html index 01c25b0..ac1e2b0 100644 --- a/documentation/bundles/configuration-installer-factory.html +++ b/documentation/bundles/configuration-installer-factory.html @@ -73,7 +73,7 @@ <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/bundles.html">Bundles</a> » </div> <h1> Configuration Installer Factory </h1><div class="row"><div class="small-12 columns"><section class="wrap"><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 file installer or the JCR installer.</p> -<h2>Configurations</h2> +<h2><a href="#configurations" name="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') </code></pre> @@ -85,7 +85,7 @@ com.acme.abc-default.cfg // Managed Service Factory, // creates an instance for com.acme.abc </code></pre> <p>If a configuration is modified, the file installer will write the configuration back to a file to ensure peristence across restarts (if <code>sling.fileinstall.writeback</code> is enabled).</p> -<h3>Property Files (.cfg)</h3> +<h3><a href="#property-files-cfg-" name="property-files-cfg-">Property Files (.cfg)</a></h3> <p>Configuration files ending in '.cfg' are plain property files (<code>java.util.Property</code>). The format is simple:</p> <pre><code>file ::= ( header | comment ) * header ::= <header> ( ':' | '=' ) <value> ( '\<nl> <value> ) * @@ -95,7 +95,7 @@ comment ::= '#' <any> <pre><code># default port ftp.port = 21 </code></pre> -<h3>Configuration Files (.config)</h3> +<h3><a href="#configuration-files-config-" name="configuration-files-config-">Configuration Files (.config)</a></h3> <p>Configuration files ending in '.config' use the format of the Apache Felix ConfigAdmin implementation. It allows to specify the type and cardinality of a configuration property and is not limited to string values.</p> <p>The first line of such a file might start with a comment line (a line starting with a #). Comments within the file are not allowed.</p> <p>The format is:</p> @@ -125,7 +125,7 @@ stringsimple ::= <quoted string representation of the value where both '& <li>'B' : Boolean</li> </ul> <p>A number of such .config files exist in the Sling codebase and can be used as examples.</p> -<h1>Project Info</h1> +<h1><a href="#project-info" name="project-info">Project Info</a></h1> <ul> <li>Configuration installer factory (<a href="http://svn.apache.org/repos/asf/sling/trunk/installer/factories/configuration";>org.apache.sling.installer.factory.configuration</a>)</li> </ul></section></div></div> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/content-distribution.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/content-distribution.html b/documentation/bundles/content-distribution.html index 2f3c206..4871a03 100644 --- a/documentation/bundles/content-distribution.html +++ b/documentation/bundles/content-distribution.html @@ -74,13 +74,13 @@ Content Distribution (org.apache.sling.distribution) </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>Introduction</h2> +<h2><a href="#introduction" name="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>Distribution usecases</h2> +<h2><a href="#distribution-usecases" name="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>Forward distribution</h3> +<h3><a href="#forward-distribution" name="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>Setup overview</h4> +<h4><a href="#setup-overview" name="setup-overview">Setup overview</a></h4> <ul> <li>one source instance <ul> @@ -93,7 +93,7 @@ </ul> </li> </ul> -<h4>Sample configuration</h4> +<h4><a href="#sample-configuration" name="sample-configuration">Sample configuration</a></h4> <ul> <li> <p>on source instance: one forward agent</p> @@ -109,9 +109,9 @@ </code></pre> </li> </ul> -<h3>Reverse distribution</h3> +<h3><a href="#reverse-distribution" name="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>Setup overview</h4> +<h4><a href="#setup-overview" name="setup-overview">Setup overview</a></h4> <ul> <li>one target instance <ul> @@ -125,7 +125,7 @@ </ul> </li> </ul> -<h4>Sample configuration</h4> +<h4><a href="#sample-configuration" name="sample-configuration">Sample configuration</a></h4> <ul> <li> <p>on target instance: one reverse agent</p> @@ -145,9 +145,9 @@ org.apache.sling.distribution.packaging.impl.exporter.AgentDistributionPackageEx </code></pre> </li> </ul> -<h3>Sync distribution</h3> +<h3><a href="#sync-distribution" name="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>Setup overview:</h4> +<h4><a href="#setup-overview-" name="setup-overview-">Setup overview:</a></h4> <ul> <li>one coordinator instance <ul> @@ -162,7 +162,7 @@ org.apache.sling.distribution.packaging.impl.exporter.AgentDistributionPackageEx </ul> </li> </ul> -<h4>Sample configuration</h4> +<h4><a href="#sample-configuration" name="sample-configuration">Sample configuration</a></h4> <ul> <li> <p>on coordinator instance: one sync agent</p> @@ -187,9 +187,9 @@ org.apache.sling.distribution.packaging.impl.importer.LocalDistributionPackageIm </code></pre> </li> </ul> -<h3>Multidatacenter sync distribution</h3> +<h3><a href="#multidatacenter-sync-distribution" name="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>Setup overview</h4> +<h4><a href="#setup-overview" name="setup-overview">Setup overview</a></h4> <ul> <li>one coordinator instance in each datacenter <ul> @@ -206,7 +206,7 @@ org.apache.sling.distribution.packaging.impl.importer.LocalDistributionPackageIm </ul> </li> </ul> -<h4>Sample configuration</h4> +<h4><a href="#sample-configuration" name="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> @@ -246,11 +246,11 @@ org.apache.sling.distribution.packaging.impl.importer.LocalDistributionPackageIm </code></pre> </li> </ul> -<h2>Additional options</h2> -<h3>How to trigger distribution over HTTP?</h3> -<h3>How to configure binary-less distribution?</h3> -<h3>How to configure priority paths?</h3> -<h3>How to configure error queues?</h3></section></div></div> +<h2><a href="#additional-options" name="additional-options">Additional options</a></h2> +<h3><a href="#how-to-trigger-distribution-over-http-" name="how-to-trigger-distribution-over-http-">How to trigger distribution over HTTP?</a></h3> +<h3><a href="#how-to-configure-binary-less-distribution-" name="how-to-configure-binary-less-distribution-">How to configure binary-less distribution?</a></h3> +<h3><a href="#how-to-configure-priority-paths-" name="how-to-configure-priority-paths-">How to configure priority paths?</a></h3> +<h3><a href="#how-to-configure-error-queues-" name="how-to-configure-error-queues-">How to configure error queues?</a></h3></section></div></div> <div class="footer"> <div class="trademarkFooter"> Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners. http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/content-loading-jcr-contentloader.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/content-loading-jcr-contentloader.html b/documentation/bundles/content-loading-jcr-contentloader.html index b753ada..4f8fc6e 100644 --- a/documentation/bundles/content-loading-jcr-contentloader.html +++ b/documentation/bundles/content-loading-jcr-contentloader.html @@ -73,7 +73,7 @@ <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/bundles.html">Bundles</a> » </div> <h1> Content Loading and Nodetype Support (jcr.contentloader) </h1><div class="row"><div class="small-12 columns"><section class="wrap"><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>Initial Content Loading</h2> +<h2><a href="#initial-content-loading" name="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 entries of the listed entries.</p> <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> @@ -193,7 +193,7 @@ </tr> </tbody> </table> -<h2>Loading initial content from bundles</h2> +<h2><a href="#loading-initial-content-from-bundles" name="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> @@ -202,12 +202,12 @@ <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>Directories</h3> +<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>Files</h3> +<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>XML Descriptor Files</h3> +<h3><a href="#xml-descriptor-files" name="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> <!-- @@ -262,7 +262,7 @@ </node> </node> </code></pre> -<h4>Using a custom XML format</h4> +<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> <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 --> @@ -287,7 +287,7 @@ ... </xsl:stylesheet> </code></pre> -<h3>JSON Descriptor Files</h3> +<h3><a href="#json-descriptor-files" name="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 @@ -340,11 +340,11 @@ } } </code></pre> -<h3>Extractors</h3> +<h3><a href="#extractors" name="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, like <code>ignoreImportProviders:="jar,zip"</code>. Please note that the value needs to be put into quotation marks if more than one value is used like in the example.</p> -<h3>Workspace Targetting</h3> +<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>Example: Load i18n JSON files</h3> +<h3><a href="#example-load-i18n-json-files" name="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 file node.</p> <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> @@ -369,7 +369,7 @@ </property> </node> </code></pre> -<h2>Declared Node Type Registration</h2> +<h2><a href="#declared-node-type-registration" name="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> @@ -378,7 +378,7 @@ <div class="warning"> Support for re-registration of node types is relatively limited. In Jackrabbit, for example, only "trivial" changes are allowed. </div> -<h3>Automated tests</h3> +<h3><a href="#automated-tests" name="automated-tests">Automated tests</a></h3> <p>The initial content found in the <a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/content/src/main/resources/content/sling-test";>sling-test folder of the launchpad initial content</a> is verified by the <a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/testing/src/test/java/org/apache/sling/launchpad/webapp/integrationtest/InitialContentTest.java";>InitialContentTest</a> when running the <em>launchpad/testing</em> integration tests.</p> <p>Those tests can be used as verified examples of initial content loading. Contributions are welcome to improve the coverage of those tests.</p></section></div></div> <div class="footer"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html ---------------------------------------------------------------------- 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 0baeeca..bda8341 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 @@ -74,15 +74,15 @@ Apache Sling Context-Aware Configuration - Default Implementation </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h1>About</h1> +<h1><a href="#about" name="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>Repository paths</h1> +<h1><a href="#repository-paths" name="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>Context paths</h1> +<h1><a href="#context-paths" name="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>Configuration resource resolving</h1> +<h1><a href="#configuration-resource-resolving" name="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> @@ -102,7 +102,7 @@ <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>Configuration persistence</h1> +<h1><a href="#configuration-persistence" name="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 @@ -120,7 +120,7 @@ <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>Resource inheritance</h1> +<h1><a href="#resource-inheritance" name="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> @@ -133,7 +133,7 @@ <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>Property inheritance</h1> +<h1><a href="#property-inheritance" name="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> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html ---------------------------------------------------------------------- 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 bdbbfab..5ca16c9 100644 --- a/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html +++ b/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html @@ -74,11 +74,11 @@ Apache Sling Context-Aware Configuration - Override </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h1>About</h1> +<h1><a href="#about" name="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>Override syntax</h1> +<h1><a href="#override-syntax" name="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} @@ -104,8 +104,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>Built-in override providers</h1> -<h2>Override via system properties</h2> +<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> <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> @@ -114,7 +114,7 @@ x.y.z.MyConfig={"prop1"="value1","prop2"=[1,2,3],& -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>Override via OSGi configuration</h2> +<h2><a href="#override-via-osgi-configuration" name="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> <div class="footer"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html ---------------------------------------------------------------------- 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 5e0d513..56485b9 100644 --- a/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html +++ b/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html @@ -74,10 +74,10 @@ Apache Sling Context-Aware Configuration - SPI </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h1>About</h1> +<h1><a href="#about" name="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>General principles</h1> +<h1><a href="#general-principles" name="general-principles">General principles</a></h1> <p>All SPIs share a common principle:</p> <ul> <li>Support multiple strategies at the same time</li> @@ -85,19 +85,19 @@ <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>Context Path Strategy</h1> +<h1><a href="#context-path-strategy" name="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>Configuration Resource Resolver Strategy</h1> +<h1><a href="#configuration-resource-resolver-strategy" name="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>Configuration Inheritance Strategy</h1> +<h1><a href="#configuration-inheritance-strategy" name="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>Configuration Persistence Strategy</h1> +<h1><a href="#configuration-persistence-strategy" name="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>Configuration Metadata Provider</h1> +<h1><a href="#configuration-metadata-provider" name="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>Configuration Override Provider</h1> +<h1><a href="#configuration-override-provider" name="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> <div class="footer">
