incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r1500501 [1/2] - in /sling/site/trunk/content: ./ documentation/ documentation/bundles/ documentation/development/ documentation/the-sling-engine/ documentation/tutorials-how-tos/ old-stuff/scriptengineintegration/ res/ site/
Date Sun, 07 Jul 2013 18:49:53 GMT
Author: fmeschbe
Date: Sun Jul  7 18:49:51 2013
New Revision: 1500501

URL: http://svn.apache.org/r1500501
Log:
SLING-2002 Migrate a few more pages

- Fix formatting on CMS based pages
- Add permanent redirects for replaced pages
- Some pages actually redirect to the wiki (instead of the site)

Added:
    sling/site/trunk/content/extpaths.txt
    sling/site/trunk/content/res/pygments-friendly.css
Removed:
    sling/site/trunk/content/site/architecture.html
    sling/site/trunk/content/site/authentication.html
    sling/site/trunk/content/site/dispatching-requests.html
    sling/site/trunk/content/site/errorhandling.html
    sling/site/trunk/content/site/eventing-and-jobs.html
    sling/site/trunk/content/site/getting-resources-and-properties-in-sling.html
    sling/site/trunk/content/site/index.html
    sling/site/trunk/content/site/installing-and-upgrading-bundles.html
    sling/site/trunk/content/site/jackrabbit-persistence.html
    sling/site/trunk/content/site/mappings-for-resource-resolution.html
    sling/site/trunk/content/site/request-listeners.html
    sling/site/trunk/content/site/request-parameters.html
    sling/site/trunk/content/site/servlets.html
    sling/site/trunk/content/site/the-sling-engine.html
    sling/site/trunk/content/site/thoughts-on-release-management.html
    sling/site/trunk/content/site/thread-handling.html
    sling/site/trunk/content/site/tutorials-how-tos.html
    sling/site/trunk/content/site/url-decomposition.html
    sling/site/trunk/content/site/usecases.html
    sling/site/trunk/content/site/version-policy.html
    sling/site/trunk/content/site/web-console-extensions.html
    sling/site/trunk/content/site/webdav.html
    sling/site/trunk/content/site/wiki.html
    sling/site/trunk/content/site/wrap-or-decorate-resources.html
    sling/site/trunk/content/site/xslt-processing-pipeline.html
    sling/site/trunk/content/site/xstl-processing-pipeline.html
Modified:
    sling/site/trunk/content/documentation/bundles/web-console-extensions.mdtext
    sling/site/trunk/content/documentation/development/version-policy.mdtext
    sling/site/trunk/content/documentation/the-sling-engine.mdtext
    sling/site/trunk/content/documentation/the-sling-engine/architecture.mdtext
    sling/site/trunk/content/documentation/the-sling-engine/authentication.mdtext
    sling/site/trunk/content/documentation/the-sling-engine/dispatching-requests.mdtext
    sling/site/trunk/content/documentation/the-sling-engine/errorhandling.mdtext
    sling/site/trunk/content/documentation/the-sling-engine/eventing-and-jobs.mdtext
    sling/site/trunk/content/documentation/the-sling-engine/mappings-for-resource-resolution.mdtext
    sling/site/trunk/content/documentation/the-sling-engine/request-listeners.mdtext
    sling/site/trunk/content/documentation/the-sling-engine/request-parameters.mdtext
    sling/site/trunk/content/documentation/the-sling-engine/servlets.mdtext
    sling/site/trunk/content/documentation/the-sling-engine/url-decomposition.mdtext
    sling/site/trunk/content/documentation/the-sling-engine/wrap-or-decorate-resources.mdtext
    sling/site/trunk/content/documentation/tutorials-how-tos.mdtext
    sling/site/trunk/content/documentation/tutorials-how-tos/getting-resources-and-properties-in-sling.mdtext
    sling/site/trunk/content/documentation/tutorials-how-tos/installing-and-upgrading-bundles.mdtext
    sling/site/trunk/content/documentation/tutorials-how-tos/jackrabbit-persistence.mdtext
    sling/site/trunk/content/index.mdtext
    sling/site/trunk/content/old-stuff/scriptengineintegration/xslt-processing-pipeline.mdtext
    sling/site/trunk/content/site/.htaccess

Modified: sling/site/trunk/content/documentation/bundles/web-console-extensions.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/web-console-extensions.mdtext?rev=1500501&r1=1500500&r2=1500501&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/web-console-extensions.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/web-console-extensions.mdtext Sun Jul  7 18:49:51 2013
@@ -1,4 +1,3 @@
-translation_pending: true
 Title: Web Console Extensions
 
 The Apache Sling project provides two extensions to the [Apache Felix Web Console](http://felix.apache.org/site/apache-felix-web-console.html) (in addition to a number of plugins, of course):
@@ -28,7 +27,7 @@ The Security Provider is configured with
 
 | Property | Type | Default Value | Description
 |--|--|--|
-| `users` | `String`, `String[]({{ refs..path }})` or `Vector<String>` | admin | The list of users granted access to the Web Console |
-| `groups`| `String`, `String[]({{ refs..path }})` or `Vector<String>` | --- | The list of groups whose (direct or indirect) members are granted access to the Web Console |
+| `users` | `String`, `String[]` or `Vector<String>` | admin | The list of users granted access to the Web Console |
+| `groups`| `String`, `String[]` or `Vector<String>` | --- | The list of groups whose (direct or indirect) members are granted access to the Web Console |
 
 Note, that while the default value explicitly grants the *admin* user to access the Web Console it is suggested that system administrators define a special group and assign users with Web Console access to this group.
\ No newline at end of file

Modified: sling/site/trunk/content/documentation/development/version-policy.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/development/version-policy.mdtext?rev=1500501&r1=1500500&r2=1500501&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/development/version-policy.mdtext (original)
+++ sling/site/trunk/content/documentation/development/version-policy.mdtext Sun Jul  7 18:49:51 2013
@@ -1,4 +1,3 @@
-translation_pending: true
 Title: Version Policy
 Excerpt: This page is about how we assign versions to exported packages and bundles and defines when to increase which part of the version number.
 
@@ -12,11 +11,9 @@ Please note that this page is currently 
 
 ## Introduction
 
-In comments to SLING-1176 Ian Boston wrote:
+In comments to [SLING-1176](https://issues.apache.org/jira/browse/SLING-2944) Ian Boston wrote:
 
-{quote}
-The exports in bundle/api/pom.xml look like they might become problematic from a support point of view, although we probably can't avoid this. \[...\]({{ refs..path }}) \[The problem is the\] manual maintenance of the version numbers. (not a big problem but needs to be done)
-{quote}
+> The exports in bundle/api/pom.xml look like they might become problematic from a support point of view, although we probably can't avoid this. \[...\] \[The problem is the\] manual maintenance of the version numbers. (not a big problem but needs to be done)
 
 I agree, that this is a problem. So let me reasonate on this a bit ;-)
 
@@ -28,27 +25,27 @@ For Sling we have three kinds of version
 1. Sling Bundles
 1. Package Exports
 
-*Big Sling Releases*
+### Big Sling Releases
 
 For *Big Sling releases* we already have an ample solution in that we just use a single number increased from release to release. Just remember that a *Big Sling release* is a convenience release of existing released Sling bundles.
 
-*Sling Bundles*
+### Sling Bundles
 
 For *Sling Bundles* version numbers are just defined as the `<version>` element of the bundle's POM. The only restriction here is, that we decided to use even numbers for releases and odd numbers for SNAPSHOTs. Whether and when which version part is increased is not explicitly defined yet.
 
-*Package Exports*
+### Package Exports
 
 For *Package Exports* the situation is more problematic since there are a number of places to set exported package version number:
 
-  * In a `packageinfo` file inside the package (picked up by the Maven Bundle Plugin to set the export version)
-  * Explicitly in the `<Export-Package>` element of the Maven Bundle Plugin configuration
-  * By reference to the bundle version number using the `$\{pom.version`} variable.
-
-Upto now, we mostly used the `$\{pom.version` notation linking the exported package version to the bundle version. Over time this mechanism leads to a number of problems:
-
-  * For bundles with more than one package exported, the exported packages will evolve independently. As a consequence their versionin should also evolve independently. An example of such a bundle is the Sling API bundle of course.
-  * Linking the package export version number to the bundle version number confuses the actual semantics of both version numbers. The package export version number only indicates the version of the actual package while the bundle version number indicates a development state of the overall bundle. This will generally not be the same.
-  * The version of the exported package is increased on each bundle release, even though nothing may have changed on the export. In such a situation the version of the export should stay the same.
+* In a `packageinfo` file inside the package (picked up by the Maven Bundle Plugin to set the export version)
+* Explicitly in the `<Export-Package>` element of the Maven Bundle Plugin configuration
+* By reference to the bundle version number using the `${pom.version}` variable.
+
+Upto now, we mostly used the `${pom.version}` notation linking the exported package version to the bundle version. Over time this mechanism leads to a number of problems:
+
+* For bundles with more than one package exported, the exported packages will evolve independently. As a consequence their versionin should also evolve independently. An example of such a bundle is the Sling API bundle of course.
+* Linking the package export version number to the bundle version number confuses the actual semantics of both version numbers. The package export version number only indicates the version of the actual package while the bundle version number indicates a development state of the overall bundle. This will generally not be the same.
+* The version of the exported package is increased on each bundle release, even though nothing may have changed on the export. In such a situation the version of the export should stay the same.
 
 That said, the reuse of the bundle version as the package export version still is probably the correct thing to do for legacy library wrappers.
 
@@ -68,7 +65,7 @@ I am not sure ....
 
 This has not been discussed at large, but I would assume, that the POM is still the correct place to take note of the version of the exported packages.
 
-*Future*
+### Future
 
 The newest versions of the BND library also support an `@Export` annotation in the `package-info.java` pseudo class file. This pseudo class is supported starting with Java 5 to take package level annotations (like the `@Export` annotation) and as a replacement of the `package-info.html` file.
 
@@ -83,7 +80,7 @@ Using this syntax something like the fol
     import aQute.bnd.annotation.Export;
 
 
-See [Bnd Experimental](http://www.aqute.biz/Code/XBnd) for details. Unfortunately the current Maven Bundle Plugin version does not support updating to the most recent BND library versions due to incompatibilities.
+See [BND Versioning](http://www.aqute.biz/Bnd/Versioning) for details.
 
 
 ## Version Number Syntax
@@ -92,10 +89,10 @@ As a small reminder, this is how a versi
 
 Each segment captures a different intent:
 
-    * the major segment indicates breakage in the API
-    * the minor segment indicates *externally visible* changes
-    * the micro segment indicates bug fixes
-    * the qualifier segment is not generally used but may be used to convey more information about a particular build, such as a build time or an SVN revision number.
+* the major segment indicates breakage in the API
+* the minor segment indicates *externally visible* changes
+* the micro segment indicates bug fixes
+* the qualifier segment is not generally used but may be used to convey more information about a particular build, such as a build time or an SVN revision number.
 
 
 ## Evolution of Exported Package Versions
@@ -106,9 +103,9 @@ Segments are increased according to the 
 
 This requires committers to think well about changes they apply to exported packages:
 
-  * Removing interfaces, methods or constants is likely an API breakage and thus requires a major version increase. In Sling we try to prevent this from happening.
-  * Adding new methods to interfaces is likely just an *externally visible* change and thus requires a minor version increase
-  * Fixing a bug in an exported class just requires a minor version increase.
+* Removing interfaces, methods or constants is likely an API breakage and thus requires a major version increase. In Sling we try to prevent this from happening.
+* Adding new methods to interfaces is likely just an *externally visible* change and thus requires a minor version increase
+* Fixing a bug in an exported class just requires a minor version increase.
 
 JavaDoc updates generally do not constitute a reason to evolve the version number. The exception is that if the JavaDoc update is caused by a API limitation, it might be conceivable to increase the version number of the exported package. A decision on this will have to be taken on a case-by-case basis.
 
@@ -119,9 +116,9 @@ Version numbers of bundles evolve depend
 
 As a rule of thumb, the following reasons apply for increasing the segments of bundle version numbers:
 
-  * Increasing the major version number of any of the exported packages or restructuring the bundle such that major parts are removed from the bundle (and either completely removed or moved to other bundle(s)).
-  * Increasing the minor version number of any of the exported packages or refactoring the internal code or implementing a package exported by another bundle whose minor (or even major) version number has increased. Also functional extensions of the internal bundle classes consitutes a reason to increase the minor version number.
-  * Increasing the micro version number of any of the exported packages or bug fixes.
+* Increasing the major version number of any of the exported packages or restructuring the bundle such that major parts are removed from the bundle (and either completely removed or moved to other bundle(s)).
+* Increasing the minor version number of any of the exported packages or refactoring the internal code or implementing a package exported by another bundle whose minor (or even major) version number has increased. Also functional extensions of the internal bundle classes consitutes a reason to increase the minor version number.
+* Increasing the micro version number of any of the exported packages or bug fixes.
 
 Note, that this definition does not require the bundle and epxorted package version numbers to be synchronized in any way. While doing so might help in a first or second step, over time it will become close to impossible to keep the versions in sync. So rather than trying to keep the versions in sync, we should make sure, we increase the versions correctly.
 
@@ -141,6 +138,7 @@ To signal to users of evolving packages,
 A hypothetical evolution of version numbers shown on two packages and the bundle version might be as follows
 
 | Description | `api` package | `resource` package | bundle |
+|-|-|-|-|
 | Initial Release | 1.0.0 | 1.0.0 | 1.0.0 |
 | Bug fix in a `resource` class | 1.0.0 | 1.0.2 | 1.0.2 |
 | New API in the `resource` package | 1.0.0 | 1.1.0 | 1.1.0 |
@@ -155,6 +153,7 @@ An example of such a hybrid bundle is th
 A hypothetical evolution of version numbers shown on one exported package and the bundle version might be as follows
 
 | Description | `engine` package | bundle |
+|-|-|-|
 | Initial Release | 1.0.0 | 1.0.0 |
 | Bug fix in a `engine` class | 1.0.2 | 1.0.2 |
 | Bug fix in an internal calss | 1.0.2 | 1.0.4 |
@@ -174,8 +173,8 @@ For Pure Implementation Bundles only the
 
 When importing packages a version number will automatically be generated by the Maven Bundle Plugin as follows:
 
-  * If the providing package exports a package with an explicit version number, that exact version number will be used as the lower bound
-  * If such a lower bound exists, the upper bound is exclusive the next major version number.
+* If the providing package exports a package with an explicit version number, that exact version number will be used as the lower bound
+* If such a lower bound exists, the upper bound is exclusive the next major version number.
 
 For example if importing the `api` package exported at version 1.2.3, the `Import-Package` statement is generated as
 
@@ -196,14 +195,14 @@ For example implementing the `api` packa
 
 This allows for the implementation to work correctly with bug fixed package exports but as soon as there are any *externally visible* changes, the implementation bundle has to be adapted -- even if this just means increasing the upper version bound in the `Import-Package` statement thus guaranteeing compliance (again).
 
-*Future*
+### Future
 
-Recent versions of the BND library support automatic differntiation between use and implementation of API and to set the import version ranges accordingly. See [Bnd Experimental](http://www.aqute.biz/Code/XBnd) for details. Unfortunately the current Maven Bundle Plugin version does not support updating to the most recent BND library versions due to incompatibilities.
+Recent versions of the BND library support automatic differntiation between use and implementation of API and to set the import version ranges accordingly. See [BND Versioning](http://www.aqute.biz/Bnd/Versioning) for details.
 
 ## References
 
-[Version Numbers](http://markmail.org/thread/zshobgjwtqrncajt) -- The mail thread discussing version numbering
-[On Version Numbers](http://blog.meschberger.ch/2009/10/on-version-numbers.html) -- Blog about version numbers
-[Version Numbering](http://wiki.eclipse.org/index.php/Version_Numbering) -- An Eclipse paper on assigning version numbers. Very good read.
-[Semantic Versioning](http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf) -- An OSGi Alliance paper on semantic versioning.
-[Bnd Experimental](http://www.aqute.biz/Code/XBnd) -- Experimental extensions to the BND library; unfortunately these extensions are not yet usable with Maven Bundle Plugin 2.1.0 due to API changes in the BND library not supported by the plugin.
+* [Version Numbers](http://markmail.org/thread/zshobgjwtqrncajt) -- The mail thread discussing version numbering
+* [On Version Numbers](http://blog.meschberger.ch/2009/10/on-version-numbers.html) -- Blog about version numbers
+* [Version Numbering](http://wiki.eclipse.org/index.php/Version_Numbering) -- An Eclipse paper on assigning version numbers. Very good read.
+* [Semantic Versioning](http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf) -- An OSGi Alliance paper on semantic versioning.
+* [BND Versioning](http://www.aqute.biz/Bnd/Versioning) -- Describes how the BND library used by the Maven Bundle plugin supports package versioning

Modified: sling/site/trunk/content/documentation/the-sling-engine.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine.mdtext?rev=1500501&r1=1500500&r2=1500501&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine.mdtext (original)
+++ sling/site/trunk/content/documentation/the-sling-engine.mdtext Sun Jul  7 18:49:51 2013
@@ -1,4 +1,3 @@
-translation_pending: true
 Title: The Sling Engine
 
 ## General

Modified: sling/site/trunk/content/documentation/the-sling-engine/architecture.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/architecture.mdtext?rev=1500501&r1=1500500&r2=1500501&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/architecture.mdtext (original)
+++ sling/site/trunk/content/documentation/the-sling-engine/architecture.mdtext Sun Jul  7 18:49:51 2013
@@ -1,14 +1,13 @@
-translation_pending: true
 Title: Architecture
 
 The following is a short list of high-lights of Sling:
 
-* *[OSGi](#osgi)* --- The Sling application is built as a series of OSGi bundles and makes heavy use of a number of OSGi core and compendium services.
-* *[Sling API](#sling-api)* --- To implement content based Web applications with Sling, an API has been defined, this extends the Servlet API and provides more functionality to work on the content.
-* *[Request Processing](#request-processing)* --- Sling takes a unique approach to handling requests in that a request URL is first resolved to a resource, then based on the resource (and only the resource) it selects the actual servlet or script to handle the request.
-* *[Resources](#resources)* --- The central mantra of Sling is the *Resource*, which represents the resource addressed by any request URL. It is the resource that is first resolved when handling a request. Based on the resource, a first servlet or script is then accessed to actually handle the request.
-* *[Servlets and Scripts](#servlets-and-scripts)* --- Servlets and Scripts are handled uniformly in that they are represented as resources themselves and are accessible by a resource path.
-* *[Launchpad](#launchpad)* --- Sling uses a very thin launcher to integrate with an existing servlet container, launching Sling as a Web application or providing a main class to represent a standalone Java application.
+* **[OSGi](#osgi)** &mdash; The Sling application is built as a series of OSGi bundles and makes heavy use of a number of OSGi core and compendium services.
+* **[Sling API](#sling-api)** &mdash; To implement content based Web applications with Sling, an API has been defined, this extends the Servlet API and provides more functionality to work on the content.
+* **[Request Processing](#request-processing)** &mdash; Sling takes a unique approach to handling requests in that a request URL is first resolved to a resource, then based on the resource (and only the resource) it selects the actual servlet or script to handle the request.
+* **[Resources](#resources)** &mdash; The central mantra of Sling is the *Resource*, which represents the resource addressed by any request URL. It is the resource that is first resolved when handling a request. Based on the resource, a first servlet or script is then accessed to actually handle the request.
+* **[Servlets and Scripts](#servlets-and-scripts)** &mdash; Servlets and Scripts are handled uniformly in that they are represented as resources themselves and are accessible by a resource path.
+* **[Launchpad](#launchpad)** &mdash; Sling uses a very thin launcher to integrate with an existing servlet container, launching Sling as a Web application or providing a main class to represent a standalone Java application.
 
 The following sections elaborate on each of these highlights.
 
@@ -18,23 +17,23 @@ The following sections elaborate on each
 
 ### OSGi Framework
 
-The OSGi Framework is made up of three layers -- Module, Lifecycle, and Services -- that define how extensible applications are built and deployed. The responsibilities of the layers are:
+The OSGi Framework is made up of three layers &ndash; Module, Lifecycle, and Services &ndash; that define how extensible applications are built and deployed. The responsibilities of the layers are:
 
-* *Module* --- Defines how a module, or a *Bundle* in OSGi-speak, is defined. Basically, a bundle is just a plain old JAR file, whose manifest file has some defined entries. These entries identify the bundle with a symbolic name, a version and more. In addition there are headers which define what a bundle provides `Export-Package` and what a bundle requires to be operative `Import-Package` and `Require-Bundle`.
-* *Lifecycle* --- The lifecycle layer defines the states a bundle may be in and describes the state changes. By providing a class, which implements the `BundleActivator` interface and which is named in the `Bundle-Activator` manifest header, a bundle may hook into the lifecycle process when the bundle is started and stopped.
-* *Services* --- For the application to be able to interact, the OSGi Core Specification defines the service layer. This describes a registry for services, which may be shared.
+* **Module** &mdash; Defines how a module, or a *Bundle* in OSGi-speak, is defined. Basically, a bundle is just a plain old JAR file, whose manifest file has some defined entries. These entries identify the bundle with a symbolic name, a version and more. In addition there are headers which define what a bundle provides `Export-Package` and what a bundle requires to be operative `Import-Package` and `Require-Bundle`.
+* **Lifecycle** &mdash; The lifecycle layer defines the states a bundle may be in and describes the state changes. By providing a class, which implements the `BundleActivator` interface and which is named in the `Bundle-Activator` manifest header, a bundle may hook into the lifecycle process when the bundle is started and stopped.
+* **Services** &mdash; For the application to be able to interact, the OSGi Core Specification defines the service layer. This describes a registry for services, which may be shared.
 
 
 ### Compendium Services
 
 Based on the OSGi Framework specification, the Compendium Services specification defines a (growing) number of extension services, which may be used by applications for various tasks. Of these Compendium Services, Sling is using just a small number:
 
-* *Log Service* --- Sling comes with its own implementation of the OSGi Log Service specification. The respective bundle not only provides this implementation, it also exports the SLF4J, Log4J and Commons Logging APIs needed for the Sling application to perform logging.
-* *Http Service* --- Sling leverages the OSGi Http Service to hook into a servlet container to provide the Web Application Framework mechanism.
-* *Configuration Admin Service* --- To simplify configuration of services in Sling, the OSGi Configuration Admin service is used. This provides a uniform API to configure services and to build configuration management agents.
-* *Metatype Service* --- The OSGi Metatype Service defines a way to describe the data types. Sling uses this service to describe the configurations that may be created using the Configuration Admin Service. These meta type descriptions are used by configuration management agents to present to user interface to manage the configurations.
-* *Event Admin Service* --- Sling uses the OSGi EventAdmin service to dispatch events when scheduling tasks.
-* *Declarative Services* --- One of the most important (beside the Log Service) services used by Sling is the Declarative Services Specification. This specification defines how to declaratively create components and services to have the Declarative Services runtime actually manage the lifecycle, configuration and references of components.
+* **Log Service** &mdash; Sling comes with its own implementation of the OSGi Log Service specification. The respective bundle not only provides this implementation, it also exports the SLF4J, Log4J and Commons Logging APIs needed for the Sling application to perform logging.
+* **Http Service** &mdash; Sling leverages the OSGi Http Service to hook into a servlet container to provide the Web Application Framework mechanism.
+* **Configuration Admin Service** &mdash; To simplify configuration of services in Sling, the OSGi Configuration Admin service is used. This provides a uniform API to configure services and to build configuration management agents.
+* **Metatype Service** &mdash; The OSGi Metatype Service defines a way to describe the data types. Sling uses this service to describe the configurations that may be created using the Configuration Admin Service. These meta type descriptions are used by configuration management agents to present to user interface to manage the configurations.
+* **Event Admin Service** &mdash; Sling uses the OSGi EventAdmin service to dispatch events when scheduling tasks.
+* **Declarative Services** &mdash; One of the most important (beside the Log Service) services used by Sling is the Declarative Services Specification. This specification defines how to declaratively create components and services to have the Declarative Services runtime actually manage the lifecycle, configuration and references of components.
 
 
 ## Sling API

Modified: sling/site/trunk/content/documentation/the-sling-engine/authentication.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/authentication.mdtext?rev=1500501&r1=1500500&r2=1500501&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/authentication.mdtext (original)
+++ sling/site/trunk/content/documentation/the-sling-engine/authentication.mdtext Sun Jul  7 18:49:51 2013
@@ -1,19 +1,17 @@
-translation_pending: true
 Title: Authentication
 Excerpt:  How requests are authenticated.
 
 
 This section describes the framework provided by Sling to authenticate HTTP requests.
 
-Let's look at generic request processing of Sling: Sling is linked into the outside world by registering the Sling Main Servlet -- implemented by the `SlingMainServlet` class in the Sling Engine bundle -- with an OSGi `HttpService`. This registration is accompanyied with an implementation instance of the OSGi `HttpContext` interface, which defines a method to authenticate requests: `handleSecurity`.
+Let's look at generic request processing of Sling: Sling is linked into the outside world by registering the Sling Main Servlet &ndash; implemented by the `SlingMainServlet` class in the Sling Engine bundle &ndash; with an OSGi `HttpService`. This registration is accompanyied with an implementation instance of the OSGi `HttpContext` interface, which defines a method to authenticate requests: `handleSecurity`.
 
 This method is called by the OSGi HTTP Service implementation after the servlet has been selected to handle the request but before actually calling the servlet's `service` method.
 
-{section}
-{column}
-![Authentication Flow](authentication.png "Authentication Flow")
-{column}
-{column}
+<a href="authentication.png" style="float:left;padding-right:5%;width:30%;">
+    <img src="authentication.png" title="Authentication Flow" alt="Authentication Flow" width="30%">
+</a>
+
 1. First the OSGi HTTP Service implementation is analyzing the request URL to find a match for a servlet or resource registered with the HTTP Service.
 1. Now the HTTP Service implementation has to call the `handleSecurity` method of the `HttpContext` object with which the servlet or resource has been registered. This method returns `true` if the request should be serviced. If this method returns `false` the HTTP Service implementation terminates the request sending back any response which has been prepared by the `handleSecurity` method. Note, that the `handleSecurity` method must prepare the failure response sent to the client, the HTTP Service adds nothing here. If the `handleSecurity` method is successful, it must add two (or three) request attributes described below.
 1. When the `handleSecurity` method returns `true` the HTTP Service either calls the `Servlet.service` method or sends back the requested resource depending on whether a servlet or a resource has been selected in the first step.

Modified: sling/site/trunk/content/documentation/the-sling-engine/dispatching-requests.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/dispatching-requests.mdtext?rev=1500501&r1=1500500&r2=1500501&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/dispatching-requests.mdtext (original)
+++ sling/site/trunk/content/documentation/the-sling-engine/dispatching-requests.mdtext Sun Jul  7 18:49:51 2013
@@ -1,90 +1,55 @@
-translation_pending: true
 Title: Dispatching Requests
 
 ## Main process
 
 The following steps should give you an overview how a request is processed in Sling. Details can be found under provided links.
 
-### Step 1
+1. The client sends the request
 
-The client sends the request
+1. This step applies only if a Servlet Container is installed and Sling is embedded: Servlet Container gets request and forwards to OSGi HttpService
 
-### Step 2
+1. OSGi HttpService looks for responsible registered Servlet or resource (see 102.4 of the OSGi compendium)
 
-This step applies only if a Servlet Container is installed and Sling is embedded:
-Servlet Container gets request and forwards to OSGi HttpService
+1. OSGi HttpService calls `handleSecurity` of the HttpContext associated with the servlet/resource. In case of Sling this calls into SlingMainServlet.handleSecurity and then into SlingAuthenticator.authenticate
 
-### Step 3
+    1. SlingAuthenticator selects an authentication handler for the request and forwards the authenticate call. On success a `javax.jcr.Session` is created, the request attributes required by the HTTP Service spec are set (like `org.osgi.service.http.authentication.remote.user` and `org.osgi.service.http.authentication.type`and also the `javax.jcr.Session` which is used later is set in the request attributes.
+    On success, continue with step 5.
 
-OSGi HttpService looks for responsible registered Servlet or resource (see 102.4 of the OSGi compendium)
+    1. If authentication fails either an anonymous session is acquired (if anonymous is allowed per configuration) or the login method is called.
+    If anonymous is allowed, continue with step 5.
 
-### Step 4
+    1. The login method selects an AuthenticationHandler and forwards the login call to the AuthenticationHandler.requestAuthentication method to cause the client to authenticate. Request processing stops here (`SlingMainServlet.handleSecurity` returns false).
 
-OSGi HttpService calls `handleSecurity` of the HttpContext associated with the servlet/resource. In case of Sling this calls into SlingMainServlet.handleSecurity and then into SlingAuthenticator.authenticate
+1. After getting a response the HttpService either terminates the request (if authentication failed and `SlingMainServlet.handleSecurity` returned false) or continues by either spooling the resource or in the case of Sling calling the `SlingMainServlet.service` method.
 
-### Step 4a
+1. The `SlingMainServlet.service` method is the entry point into the Sling proper. This method sets up the request:
 
-SlingAuthenticator selects an authentication handler for the request and forwards the authenticate call. On success a `javax.jcr.Session` is created, the request attributes required by the HTTP Service spec are set (like `org.osgi.service.http.authentication.remote.user` and `org.osgi.service.http.authentication.type`and also the `javax.jcr.Session` which is used later is set in the request attributes.
-On success, continue with step 5.
+    * Wraps the `HttpServletRequest` and the `HttpServletResponse` into the `SlingHttpServletRequest` and the `SlingHttpServletResponse`
+    * Checks if Sling is ready for processing the request (checks at the moment for an existing ResourceResolverFactory service, a ServletResolver service and a MimeTypeService)
+    * Create the ResourceResolver based on the Session (by default creates a `JcrResourceResolver2`)
+    * Locate the [Resource]({{ refs.resources.path }}) on the basis of the request by calling `ResourceResovler.resolve` through `RequestData.initResource` (see also [URL decomposition]({{ refs.url-decomposition.path }}))
+    * Locate the servlet or script (see [Servlets]({{ refs.servlets.path }})) by calling `ServletResolver.resolveServlet` through `RequestData.initServlet`
 
-### Step 4b
-
-If authentication fails either an anonymous session is acquired (if anonymous is allowed per configuration) or the login method is called.
-If anonymous is allowed, continue with step 5.
-
-### Step 4c
-
-The login method selects an AuthenticationHandler and forwards the login call to the AuthenticationHandler.requestAuthentication method to cause the client to authenticate. Request processing stops here (`SlingMainServlet.handleSecurity` returns false).
-
-### Step 5
-
-After getting a response the HttpService either terminates the request (if authentication failed and `SlingMainServlet.handleSecurity` returned false) or continues by either spooling the resource or in the case of Sling calling the `SlingMainServlet.service` method.
-
-### Step 6
-
-The `SlingMainServlet.service` method is the entry point into the Sling proper. This method sets up the request:
-* Wraps the `HttpServletRequest` and the `HttpServletResponse` into the `SlingHttpServletRequest` and the `SlingHttpServletResponse`
-* Checks if Sling is ready for processing the request (checks at the moment for an existing ResourceResolverFactory service, a ServletResolver service and a MimeTypeService)
-* Create the ResourceResolver based on the Session (by default creates a `JcrResourceResolver2`)
-* Locate the [Resource]({{ refs.resources.path }}) on the basis of the request by calling `ResourceResovler.resolve` through `RequestData.initResource` (see also [URL decomposition])
-* Locate the servlet or script (see [Servlets]({{ refs.servlets.path }})) by calling `ServletResolver.resolveServlet` through `RequestData.initServlet`
-
-### Step 7
-
-After this setup, the request level filters are called (the ones registered as `javax.servlet.Filter` with the property `filter.scope=request`, see [Filters]({{ refs.filters.path }}) for details).
+1. After this setup, the request level filters are called (the ones registered as `javax.servlet.Filter` with the property `filter.scope=request`, see [Filters]({{ refs.filters.path }}) for details).
 If any called filter doesn't call `FilterChain.doFilter` at the end of the `Filter.doFilter` method request processing stops here.
 
-### Step 8
-
-After having called all request level filters, the component level filters (registered with the property `filter.scope=component`, see [Filters]({{ refs.filters.path }}) for details) are called.
+1. After having called all request level filters, the component level filters (registered with the property `filter.scope=component`, see [Filters]({{ refs.filters.path }}) for details) are called.
 
-### Step 9
-
-After having called the component level filters, the request servlet or script is finally called to process the request.
+1. After having called the component level filters, the request servlet or script is finally called to process the request.
 
 ## Include/Forward
 
 If a servlet or script is including another resource for processing through the `RequestDispatcher.include` or `RequestDispatcher.forward` (or any JSP or feature of another scripting language which relies on one of this two methods) the following processing takes place:
 
-### Step 1
-
-Code in the processing servlet or script calls `RequestDispatcher.include` or `RequestDispatcher.forward`.
-
-### Step 2
-
-The resource is resolved though ResourceResolver.getResource (if the RequestDispatcher has not been created with a resource already)
-
-### Step 3
-
-The servlet or script to handle the resource is resolved calling the `ServletResolver.resolverServlet` method.
+1. Code in the processing servlet or script calls `RequestDispatcher.include` or `RequestDispatcher.forward`.
 
-### Step 4
+1. The resource is resolved though ResourceResolver.getResource (if the RequestDispatcher has not been created with a resource already)
 
-The component level filters (registered with the property `filter.scope=component`) are called again (see [Filters]({{ refs.filters.path }}) for details).
+1. The servlet or script to handle the resource is resolved calling the `ServletResolver.resolverServlet` method.
 
-### Step 5
+1. The component level filters (registered with the property `filter.scope=component`) are called again (see [Filters]({{ refs.filters.path }}) for details).
 
-The servlet or script is called to process the request.
+1. The servlet or script is called to process the request.
 
 Note that these steps are processed for every include or forward call.
 
@@ -93,17 +58,17 @@ Note that these steps are processed for 
 
 When servlet or script is called as a result of `RequestDispatcher.include` the following request attributes are set:
 
-| Attribute Name | Attribute Type | Description |
-|-|-|-|
-| `org.apache.sling.api.include.servlet`| `javax.servlet.Servlet` | The name of the request attribute containing the `Servlet` which included the servlet currently being active. |
-| `org.apache.sling.api.include.resource`|`org.apache.sling.api.resource.Resource` | The name of the request attribute containing the `Resource` underlying the `Servlet` which included the servlet currently being active. |
-| `org.apache.sling.api.include.request*path*info`|`org.apache.sling.api.request.RequestPathInfo` | The name of the request attribute containing the `RequestPathInfo` underlying the `Servlet` which included the servlet currently being active |
-| `javax.servlet.include.request_uri`|`String` | The name of the request attribute containing the `HttpServletRequest.getRequestURI()` of the request which included the servlet currently being active underlying the `Servlet` which included the servlet currently being active.<br>*Note:* In Sling, the `HttpServletRequest.getRequestURI()` method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification. |
-| `javax.servlet.include.context_path`|`String` | The name of the request attribute containing the `HttpServletRequest.getContextPath()` of the request which included the servlet currently being active underlying the `Servlet` which included the servlet currently being active.<br>*Note:* In Sling, the `HttpServletRequest.getContextPath()` method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification. |
-| `javax.servlet.include.servlet_path`|`String` | The name of the request attribute containing the `HttpServletRequest.getServletPath()` of the request which included the servlet currently being active underlying the `Servlet` which included the servlet currently being active.<br>*Note:* In Sling, the `HttpServletRequest.getServletPath()` method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification. |
-| `javax.servlet.include.path_info`|`String` | The name of the request attribute containing the `HttpServletRequest.getPathInfo()` of the request which included the servlet currently being active underlying the `Servlet` which included the servlet currently being active.<br>*Note:* In Sling, the `HttpServletRequest.getPathInfo()` method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification.
-| `javax.servlet.include.query_string`|`String` | The name of the request attribute containing the `HttpServletRequest.getQueryString()` of the request which included the servlet currently being active underlying the `Servlet` which included the servlet currently being active.<br>*Note:* In Sling, the `HttpServletRequest.getQueryString()` method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification. |
+| Attribute Name <br> Attribute Type | Description |
+|-|-|
+| `org.apache.sling.api.include.servlet` <br> `javax.servlet.Servlet` | The name of the request attribute containing the `Servlet` which included the servlet currently being active. |
+| `org.apache.sling.api.include.resource` <br>`org.apache.sling.api.resource.Resource` | The name of the request attribute containing the `Resource` underlying the `Servlet` which included the servlet currently being active. |
+| `org.apache.sling.api.include.request_path_info` <br> `org.apache.sling.api.request.RequestPathInfo` | The name of the request attribute containing the `RequestPathInfo` underlying the `Servlet` which included the servlet currently being active |
+| `javax.servlet.include.request_uri` <br> `String` | The name of the request attribute containing the `HttpServletRequest.getRequestURI()` of the request which included the servlet currently being active underlying the `Servlet` which included the servlet currently being active.<br>**Note:** In Sling, the `HttpServletRequest.getRequestURI()` method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification. |
+| `javax.servlet.include.context_path` <br> `String` | The name of the request attribute containing the `HttpServletRequest.getContextPath()` of the request which included the servlet currently being active underlying the `Servlet` which included the servlet currently being active.<br>**Note:** In Sling, the `HttpServletRequest.getContextPath()` method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification. |
+| `javax.servlet.include.servlet_path` <br> `String` | The name of the request attribute containing the `HttpServletRequest.getServletPath()` of the request which included the servlet currently being active underlying the `Servlet` which included the servlet currently being active.<br>**Note:** In Sling, the `HttpServletRequest.getServletPath()` method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification. |
+| `javax.servlet.include.path_info` <br> `String` | The name of the request attribute containing the `HttpServletRequest.getPathInfo()` of the request which included the servlet currently being active underlying the `Servlet` which included the servlet currently being active.<br>**Note:** In Sling, the `HttpServletRequest.getPathInfo()` method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification.
+| `javax.servlet.include.query_string` <br> `String` | The name of the request attribute containing the `HttpServletRequest.getQueryString()` of the request which included the servlet currently being active underlying the `Servlet` which included the servlet currently being active.<br>**Note:** In Sling, the `HttpServletRequest.getQueryString()` method will always return the same result regardless of whether it is called from the client request processing servlet or script or from an included servlet or script. This request attribute is set for compatibility with the Servlet API specification. |
 
 Constants are defined in the `org.apache.sling.api.SlingConstants` class for these request attributes.
 
-*Note:* These request attributes are not set if the servlet or script is called to handle the request or as a result of `RequestDispatcher.forward`.
+**Note:** These request attributes are not set if the servlet or script is called to handle the request or as a result of `RequestDispatcher.forward`.

Modified: sling/site/trunk/content/documentation/the-sling-engine/errorhandling.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/errorhandling.mdtext?rev=1500501&r1=1500500&r2=1500501&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/errorhandling.mdtext (original)
+++ sling/site/trunk/content/documentation/the-sling-engine/errorhandling.mdtext Sun Jul  7 18:49:51 2013
@@ -1,4 +1,3 @@
-translation_pending: true
 Title: Errorhandling
 
 The Sling Engine includes support for handling uncaught `Throwable` as well as rendering custom HTTP status code pages. This is implemented by expecting a (single) `org.apache.sling.engine.servlets.ErrorHandler` service to which handling of uncaught `Throwable` and HTTP status responses are delegated.
@@ -33,7 +32,7 @@ The Servlet Resolver bundle implementati
   * The status code is converted to a string and used as the request extension. Any request extensions, selectors or suffixes from the actual request are ignored.
   * The same resource type hierarchy is followed to find the script as for regular script resolution. The difference is that for error handler scripts `sling/servlet/errorhandler` is used as the implied base resource type (as opposed to `sling/servlet/default` for regular script resolution.
 
-*Examples:*
+**Examples:**
 
   * An application provider my provide a default handler for the 404/NOT FOUND status. This script might be located in `/libs/sling/servlet/errorhandler/404.jsp`.
   * An programmer might provide a handler for the 403/FORBIDDEN status in `/apps/sling/servlet/errorhandler/403.esp`.
@@ -43,10 +42,10 @@ The Servlet Resolver bundle implementati
 
 To handle uncaught Throwables the simple name (`Class.getSimpleName()`) of the `Throwable` class is used as request extension. Similarly to the Java try-catch clauses the class hierarchy is supported. That is to handle an uncaught `FileNotFoundException`, the names `FileNotFoundException`, `IOException`, `Exception`, `Throwable` are checked for a Servlet and the first one found is then used. Again, the Serlvet may be a Servlet registered as an OSGi service or may be a plain script stored in the JCR repository or provided through some custom Resource provider.
 
-*Example:*
+**Example:**
 To register a catch-all handler for any uncaught Throwables you might create a script `/apps/sling/servlet/errorhandler/Throwable.esp`.
 
-*Note:* If no script or servlet to handle an uncaught `Throwable` is registered, the default handler kicks in, which sends back a 500/INTERNAL SERVER ERROR response containing the `Throwable` and the stack trace. This response is *not* handled by the HTTP Status Code handling described above because the response status is sent using `HttpServletResponse.setStatus(int, String)`. To prevent this default response you have to implement a catch-all handler for the `Throwable` class as shown in the example.
+**Note:** If no script or servlet to handle an uncaught `Throwable` is registered, the default handler kicks in, which sends back a 500/INTERNAL SERVER ERROR response containing the `Throwable` and the stack trace. This response is **not** handled by the HTTP Status Code handling described above because the response status is sent using `HttpServletResponse.setStatus(int, String)`. To prevent this default response you have to implement a catch-all handler for the `Throwable` class as shown in the example.
 
 ## Default Handler
 

Modified: sling/site/trunk/content/documentation/the-sling-engine/eventing-and-jobs.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/eventing-and-jobs.mdtext?rev=1500501&r1=1500500&r2=1500501&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/eventing-and-jobs.mdtext (original)
+++ sling/site/trunk/content/documentation/the-sling-engine/eventing-and-jobs.mdtext Sun Jul  7 18:49:51 2013
@@ -1,13 +1,14 @@
-translation_pending: true
 Title: Eventing, Jobs, and Scheulding
 
 Apache Sling provides some mechanisms and support for eventing, handling jobs and scheduling. 
 
 To get some hands on code, you can refer to the following tutorials:
+
 * [How to Manage Events in Sling]({{ refs.how-to-manage-events-in-sling.path }})
 * [Scheduler Service (commons scheduler)]({{ refs.scheduler-service-commons-scheduler.path }})
 
 ### Possible Use Cases for Eventing
+
 * Workflow
 * Post Processing (business processes)
 * Caching
@@ -16,9 +17,10 @@ To get some hands on code, you can refer
 ### Sources of Events
 
 There is a variety of sources from which events can be send:
+
 * JCR observation events
 * Application generated events
-* Events from messaging systems (~JMS)
+* Events from messaging systems (JMS)
 * "External events"
 
 The events can eiter be generated inside a current user context, e.g. when the user performs an action through the UI, or they can be out of a user context, e.g. for schedulded events. This leads to different weights of events.
@@ -38,7 +40,7 @@ The foundation of the event mechanism is
 
 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.
 
-The event mechanism is an *event* mechanism which should not be confused with a *messaging* mechanism. Events are received by the event mechanism and distributed to registered listeners. Concepts like durable listeners, guarantee of processing etc. are not part of the event mechanism itself. However, there will be additional support for such things, like job events.
+The event mechanism is an **event** mechanism which should not be confused with a **messaging** mechanism. Events are received by the event mechanism and distributed to registered listeners. Concepts like durable listeners, guarantee of processing etc. are not part of the event mechanism itself. However, there will be additional support for such things, like job events.
 
 The application should try to use application events instead of low level JCR events whereever possible. Therefore a bridging between JCR events and the event mechanism is required. However, a general "automatic" mapping will not be provided. It is up to the application to develop such a mapping on a per use case base. There might be some support to make the mapping easier.
 
@@ -64,32 +66,34 @@ An event handler registers itself on a (
 
 The type of the event is specified by the hierarchically organized topic. In order to provide clustering of JCR repositories and clustering of the sling based application instances, each event can contain the following properties - if they are absent, a default value is assumed:
 
-* =event.distribute= - 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.
-* =event.application= - 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 note, the =event.application= is missing, if it is a remote event, the =event.application= contains the ID of the node, the event has been initially created.
+* `event.distribute` &ndash; 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.
+* `event.application` &ndash; 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 note, the `event.application` is missing, if it is a remote event, the `event.application` contains the ID of the node, the event has been initially created.
 
-While the =event.distribute= must be set by the sender of an event (if the event should be distributed), the =event.application= property is maintained by the event mechanism. Therefore a client sending an event should *never* set this information by itself. This will confuse the local event handlers and result in unexpected behaviour. On remote events the =event.application= is set by the event distribution mechanism.
+While the `event.distribute` must be set by the sender of an event (if the event should be distributed), the `event.application` property is maintained by the event mechanism. Therefore a client sending an event should **never** set this information by itself. This will confuse the local event handlers and result in unexpected behaviour. On remote events the `event.application` is set by the event distribution mechanism.
 
 ## Event Distribution Across Application Nodes (Cluster)
 
 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, the JCR repository is used for distribution. The distributing event handler writes the events into the repository, the distributing event handlers on other application nodes get notified through observation and then distribute the read events locally.
 
-As mentioned above, the client sending an event has to mark an event to be distributed in a cluster by setting the =event.distribute= in the event properties (through ~EventUtil).
-The existance of this flag allows to register an event handler for all events having this flag. The event handler will add the =event.application= information and write the event into the repository. All other application nodes have an observer registered and get notified each time a new event is added to the repository. They'll read the event from the repository, clear the =event.distribute= and send this event locally and asynchronously.
+As mentioned above, the client sending an event has to mark an event to be distributed in a cluster by setting the `event.distribute` in the event properties (through EventUtil).
+The existance of this flag allows to register an event handler for all events having this flag. The event handler will add the `event.application` information and write the event into the repository. All other application nodes have an observer registered and get notified each time a new event is added to the repository. They'll read the event from the repository, clear the `event.distribute` and send this event locally and asynchronously.
 
-An event handler receiving such an event can distinguish it by checking the =event.application= property. If the property is not available, it is a local event - if the property is available it is a remote event.
+An event handler receiving such an event can distinguish it by checking the `event.application` property. If the property is not available, it is a local event - if the property is available it is a remote event.
 
-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. Defining the filter for the =event.distribute= is also very simple.
+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. Defining the filter for the `event.distribute` is also very simple.
 
 ### Storing Events in the Repository
 
 Distributable events are stored in the repository, the repository will have a specific area (path) where all events are stored. 
 
 Each event is stored as a separate node with the following properties:
-| *Property Name*     | *Description* |
-| =event:topic=       | The topic of the event |
-| =event:application= | The identifier of the application node where the event was created |
-| =event:created=     | The date and time when the event has been created (stored in the repository)
-| =event:properties=  | Serialized properties (except the =event.distribute=, but including the =event.application=) |
+
+| Property Name     | Description |
+|-|-|
+| `event:topic`       | The topic of the event |
+| `event:application` | The identifier of the application node where the event was created |
+| `event:created`     | The date and time when the event has been created (stored in the repository)
+| `event:properties`  | Serialized properties (except the `event.distribute`, but including the `event.application`) |
 
 Each application is periodically removing old events from the repository (using the scheduler).
 
@@ -99,50 +103,54 @@ In general, the eventing mechanism has n
 
 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 this event exactly once. Typical examples are sending notification emails (or sms) or post processing of content (like thumbnail generation of images or documents).
 
-We will call these events jobs to make clear that someone has to do something with the event (do the job). We will use a special topic =org/apache/sling/event/job= to indicate that the event contains a job, the real topic of the event is stored in the =event.job.topic= property. When a job event (event with the topic =org/apache/sling/event/job=) is received, a new event with the topic from the property =event.job.topic= is fired.
+We will call these events jobs to make clear that someone has to do something with the event (do the job). We will use a special topic `org/apache/sling/event/job` to indicate that the event contains a job, the real topic of the event is stored in the `event.job.topic` property. When a job event (event with the topic `org/apache/sling/event/job`) is received, a new event with the topic from the property `event.job.topic` is fired.
 
 The event must have the following properties:
-| *Property Name*   | *Description* |
-| =event.job.topic= | The topic of the job |
-| =event.job.id=    | A unique identifier for this job (optional) |
 
-The job event handler listens for all job events (all events with the topic =org/apache/sling/event/job=). The event handler will write the job event into the repository (into the job area), lock it, create a new event with the topic from the property =event.job.topic= and send the job event through the event admin. When the job is finished, the event listener will unlock the node from the repository.
+| Property Name   | Description |
+|-|-|
+| `event.job.topic` | The topic of the job |
+| `event.job.id`    | A unique identifier for this job (optional) |
 
-To avoid timeouts and black listing of event handlers, the job event handler does not assume that the job has been processed if the event could be sent successfully. It is the task of the event handler to notify the job event handler that it has processed the job. In addition, the job processing should be done in the background. The =EventUtil= class has a helper method for this: =processJob(Event, JobProcessor)=. The event handler must implement the =JobProcessor= interface which consists of a single =process(Event)= method. When the event handler receives a job event, it calls =EventUtil.processJob(event, this)= and returns. The =process(Event)= method is now called in the background and when it finishes, the job event handler is notified that the job is completed.
+The job event handler listens for all job events (all events with the topic `org/apache/sling/event/job`). The event handler will write the job event into the repository (into the job area), lock it, create a new event with the topic from the property `event.job.topic` and send the job event through the event admin. When the job is finished, the event listener will unlock the node from the repository.
 
-If the event handler wants to do the background processing by itself or does not need background processing at all, it must signal completition of the job by call =EventUtil.finishedJob(event)=.
+To avoid timeouts and black listing of event handlers, the job event handler does not assume that the job has been processed if the event could be sent successfully. It is the task of the event handler to notify the job event handler that it has processed the job. In addition, the job processing should be done in the background. The `EventUtil` class has a helper method for this: `processJob(Event, JobProcessor)`. The event handler must implement the `JobProcessor` interface which consists of a single `process(Event)` method. When the event handler receives a job event, it calls `EventUtil.processJob(event, this)` and returns. The `process(Event)` method is now called in the background and when it finishes, the job event handler is notified that the job is completed.
 
-By default an application node is queuing the jobs which means that only one job is processed at a time. If a job can be run in parallel on one application node, the property =event.job.parallel= should be set with any value.
+If the event handler wants to do the background processing by itself or does not need background processing at all, it must signal completition of the job by call `EventUtil.finishedJob(event)`.
+
+By default an application node is queuing the jobs which means that only one job is processed at a time. If a job can be run in parallel on one application node, the property `event.job.parallel` should be set with any value.
 
 The job id is optional and can be used to update or reactivate jobs.
 
 ### Storing Jobs in the Repository
 
-Jobs are stored in the repository in order to ensure that exactly one single application node is processing the job. The repository will have a specific area (path) where all jobs are stored. In order to distinguish a job which occured twice and a job which is generated at the same time on several nodes, each job can be uniquely identified by its topic (property =event.job.topic=) and the =event.job.id= property. It is up to the client who is creating the event to ensure that the =event.job.id= property is unqiue *and* identical on all application nodes. If the job id is not provided for the job, then it is up to the client to ensure that the job even is only fired once.
+Jobs are stored in the repository in order to ensure that exactly one single application node is processing the job. The repository will have a specific area (path) where all jobs are stored. In order to distinguish a job which occured twice and a job which is generated at the same time on several nodes, each job can be uniquely identified by its topic (property `event.job.topic`) and the `event.job.id` property. It is up to the client who is creating the event to ensure that the `event.job.id` property is unqiue **and** identical on all application nodes. If the job id is not provided for the job, then it is up to the client to ensure that the job even is only fired once.
 
-When the job event listener tries to write a job into the repository it will check if the repository already contains a job with the given topic =event.job.topic= and =event.job.id= property. If the event has already been written by some other application node, it's not written again. If the event has been written by the same node, it will be set to active again (=event:active= will be set to true and =event:created= will be updated).
+When the job event listener tries to write a job into the repository it will check if the repository already contains a job with the given topic `event.job.topic` and `event.job.id` property. If the event has already been written by some other application node, it's not written again. If the event has been written by the same node, it will be set to active again (`event:active` will be set to true and `event:created` will be updated).
 
 Each job is stored as a separate node with the following properties:
-| *Property Name*     | *Description* |
-| =event:topic=       | The topic of the job |
-| =event:application= | The identifier of the node where the job was created |
-| =event:processor=   | The identifier of the node which processed the job |
-| =event:active=      | Indicates if this job is active and should be processed(unlocked) or is currently processed (locked) |
-| =event:created=     | The date and time when the event has been created (stored in the repository)
-| =event:id=          | The unique identifier of this job (optional).
-| =event:properties=  | Serialized properties |
-| =event:finished=    | The date and time when the job has been finished |
+
+| Property Name     | Description |
+|-|-|
+| `event:topic`       | The topic of the job |
+| `event:application` | The identifier of the node where the job was created |
+| `event:processor`   | The identifier of the node which processed the job |
+| `event:active`      | Indicates if this job is active and should be processed(unlocked) or is currently processed (locked) |
+| `event:created`     | The date and time when the event has been created (stored in the repository)
+| `event:id`          | The unique identifier of this job (optional).
+| `event:properties`  | Serialized properties |
+| `event:finished`    | The date and time when the job has been finished |
 
 
-The failover of an application node is accomplished by locking and the =event:active= flag. If a job is locked in the repository a session scoped lock is used. If this application node dies, the lock dies as well. Each application node observes the JCR locking properties and therefore gets aware of unlocked event nodes with the active flag set to true. If an application node finds such a node, it locks it, updates the =event:application= information and processes it accordingly. In this case the event gets the additional property =org/apache/sling/job/retry=. 
+The failover of an application node is accomplished by locking and the `event:active` flag. If a job is locked in the repository a session scoped lock is used. If this application node dies, the lock dies as well. Each application node observes the JCR locking properties and therefore gets aware of unlocked event nodes with the active flag set to true. If an application node finds such a node, it locks it, updates the `event:application` information and processes it accordingly. In this case the event gets the additional property `org/apache/sling/job/retry`. 
 
 Each application is periodically removing old jobs from the repository (using the scheduler).
 
 ### Distribution of Jobs
 
-A job event is an event like any other. Therefore it is up to the client generating the event to decide if the event should be distributed. If the event is distributed, it will be distributed with a set =event.application= on the remote nodes. If the job event handler receives a job with the =event.application= property set, it will not try to write it into the repository. It will just broadcast this event asynchronously as a ~FYI event.
+A job event is an event like any other. Therefore it is up to the client generating the event to decide if the event should be distributed. If the event is distributed, it will be distributed with a set `event.application` on the remote nodes. If the job event handler receives a job with the `event.application` property set, it will not try to write it into the repository. It will just broadcast this event asynchronously as a FYI event.
 
-If a job event is created simultanously on all application nodes, the event will not be distributed. The application node that actually has the lock on the stored job in the repository will clear the =event.application= when sending the event locally. All other application nodes will use the =event.application= stored in the repository when broadcasting the event locally.
+If a job event is created simultanously on all application nodes, the event will not be distributed. The application node that actually has the lock on the stored job in the repository will clear the `event.application` when sending the event locally. All other application nodes will use the `event.application` stored in the repository when broadcasting the event locally.
 
 ## Usage Patterns
 
@@ -150,36 +158,38 @@ Based on some usage patterns, we discuss
 
 ### Sending User Generated Events
 
-If a user action results in an event, the event is only created on one single node in the cluster. The event object is generated and delivered to the OSGi event admin. If the =event.distribute= is not explicitly set, the event is only distributed localled.
+If a user action results in an event, the event is only created on one single node in the cluster. The event object is generated and delivered to the OSGi event admin. If the `event.distribute` is not explicitly set, the event is only distributed localled.
 
-If the =event.distribute= is the, the cluster event handler will write the event into the repository. All nodes in the cluster observe the repository area where all events are stored. If a new event is written into that area, each application node will get notified. It will create the event based on the information in the repository, clear the =event.distribute= and publish the event.
+If the `event.distribute` is the, the cluster event handler will write the event into the repository. All nodes in the cluster observe the repository area where all events are stored. If a new event is written into that area, each application node will get notified. It will create the event based on the information in the repository, clear the `event.distribute` and publish the event.
 
 The flow can be described as follows:
-1. Client code generates event using OSGi API, if the =event.distribute= should be set, it is using the ~EventUtil.
+
+1. Client code generates event using OSGi API, if the `event.distribute` should be set, it is using the EventUtil.
 1. Client code sends the event to the (local) event admin.
 1. Event admin delivers the event locally.
-1. Clustering event handler receives the event if =event.distribute= is present
-1. # Event handler adds =event.application= and writes the event to the repository
-1. # Remote repository observers get notified through JCR observation about the new event. They distribute the event locally with the =event.application= (from the node where the event occured first) and cleared =event.distribute=.
+1. Clustering event handler receives the event if `event.distribute` is present
+    1. Event handler adds `event.application` and writes the event to the repository
+    1. Remote repository observers get notified through JCR observation about the new event. They distribute the event locally with the `event.application` (from the node where the event occured first) and cleared `event.distribute`.
 
 ### Processing JCR Events
 
 JCR events are environment generated events and therefore are sent by the repository to each node in the cluster. In general, it is advisable to not built the application on the low level repository events but to use application events. Therefore the observer of the JCR event should create an OSGi event based on the changes in the repository. A decision has to be made if the event should be a job or a plain event.
 
 The flow can be described as follows:
+
 1. Client registers for JCR observation
 1. JCR notifies the client for changes
-1. Client generates OSGi event based on the JCR events (the =event.distribute= will not be set), it decides if it sends this event as a job.
+1. Client generates OSGi event based on the JCR events (the `event.distribute` will not be set), it decides if it sends this event as a job.
 1. Client code sends the event to the (local) event admin
 1. Event admin publishes the event locally
-1. The distribution event handler does not set see the event as the =event.distribute= is not set.
+1. The distribution event handler does not set see the event as the `event.distribute` is not set.
 1. The job event handler gets the event if it has the job topic
-1. # The job event handler adds the =event.application= property and tries to write the job to the repository
-1. ## If no job with the topic and =id= property is in the repository, the event will be written and locked.
-1. ## If an event with the topic and =id= property is in the repository then:
-1. ### If the =event.application= equals the current application node, the event is set to active (=event:active=) in the repository again and locked
-1. ### If the =event.application= does not equal the current application node, the event is not distributed locally.
-1. ## If the job could be locked in the repository, the job event handler delivers the job locally and synchronously and it unlocks the job and sets =event:active= to false afterwards.
+    1. The job event handler adds the `event.application` property and tries to write the job to the repository
+        1. If no job with the topic and `id` property is in the repository, the event will be written and locked.
+        1. If an event with the topic and `id` property is in the repository then:
+            1. If the `event.application` equals the current application node, the event is set to active (`event:active`) in the repository again and locked
+            1. If the `event.application` does not equal the current application node, the event is not distributed locally.
+        1. If the job could be locked in the repository, the job event handler delivers the job locally and synchronously and it unlocks the job and sets `event:active` to false afterwards.
 
 ### Sending Scheduled Events
 
@@ -191,11 +201,11 @@ In most use cases a scheduler will send 
 
 If you want to receive OSGi events, you can just follow the specification: receive it via a custom event handler which is registered on bundle start - a filter can be specified as a configuration property of the handler. 
 
-As we follow the principle of distributing each event to every registered handler, the handler has to decide if it will process the event. In order to avoid multiple processing of this event in a clustered environment, the event handler should check the =event.application= property. If it is not set, it's a local event and the handler should process the event. If the =event.application= is set, it's a remote event and the handler should not process the event. This is a general rule of thumb - however, it's up to the handler to make its decision either on =event.application= or any other information.
+As we follow the principle of distributing each event to every registered handler, the handler has to decide if it will process the event. In order to avoid multiple processing of this event in a clustered environment, the event handler should check the `event.application` property. If it is not set, it's a local event and the handler should process the event. If the `event.application` is set, it's a remote event and the handler should not process the event. This is a general rule of thumb - however, it's up to the handler to make its decision either on `event.application` or any other information.
 
 It is advisable to perform the local event check even in a non clustered environment as it makes the migration to a cluster later on much easier and there is nearly no performance overhead caused by the check.
 
-The ~EventUtil class provides an utility method =isLocalEvent(Event)= which checks the existance of the =event.application= property and returns =true= if it is absend.
+The EventUtil class provides an utility method `isLocalEvent(Event)` which checks the existance of the `event.application` property and returns `true` if it is absend.
 
 ## Scheduler
 
@@ -207,10 +217,10 @@ Each Sling based application will contai
 
 A typical example for post processing (or running a business process) is sending an email or creating thumbnails and extracting meta data from the content (like we do in DAM), which we will discuss here.
 
-An appropriate JCR observer will be registered. This observer detects when new content is put into the repository or when content is changed. In these cases it creates appropriate =CONTENT*ADDED=, =CONTENT*UPDATED= OSGi events from the JCR events. In order to ensure that these actions get processed accordingly, the event is send as a job (with the special job topic, the =topic= and =id= property).
+An appropriate JCR observer will be registered. This observer detects when new content is put into the repository or when content is changed. In these cases it creates appropriate `CONTENT_ADDED`, `CONTENT_UPDATED` OSGi events from the JCR events. In order to ensure that these actions get processed accordingly, the event is send as a job (with the special job topic, the `topic` and `id` property).
 
 The event admin now delivers these jobs to the registered handlers. The job event handler gets notified and (simplified version) sends the contained event synchronously. One of the handlers for these events is the post processing service in DAM. The job mechanism ensures that exactly one application node is post processing and that the process has to be finished even if the application node dies during execution.
 
 ## Scheduling
 
-The scheduler is a service which uses the open source Quartz library. The scheduler has methods to start jobs periodically or with a cron definition. In addition, a service either implementing =java.lang.Runnable= or =org.quartz.job= is started through the whiteboard pattern *if* it either contains a configuration property =scheduler.expression= or =scheduler.period=. The job is started with the ~PID of the service - if the service has no PID, the configuration property =scheduler.name= must be set.
+The scheduler is a service which uses the open source Quartz library. The scheduler has methods to start jobs periodically or with a cron definition. In addition, a service either implementing `java.lang.Runnable` or `org.quartz.job` is started through the whiteboard pattern **if** it either contains a configuration property `scheduler.expression` or `scheduler.period`. The job is started with the PID of the service - if the service has no PID, the configuration property `scheduler.name` must be set.



Mime
View raw message