You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by fm...@apache.org on 2012/04/22 18:52:16 UTC
svn commit: r1328899 [3/8] - in /sling/site/trunk: content/ templates/
Added: sling/site/trunk/content/dispatching-requests.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/dispatching-requests.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/dispatching-requests.mdtext (added)
+++ sling/site/trunk/content/dispatching-requests.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,240 @@
+Title: Dispatching Requests
+<a name="DispatchingRequests-RequestProcessing"></a>
+# Request Processing
+
+<a name="DispatchingRequests-Mainprocess"></a>
+## Main process
+
+The following steps should give you an overview how a request is processed
+in Sling. Details can be found under provided links.
+
+<a name="DispatchingRequests-Step1"></a>
+### Step 1
+
+The client sends the request
+
+<a name="DispatchingRequests-Step2"></a>
+### Step 2
+
+This step applies only if a Servlet Container is installed and Sling is
+embedded:
+Servlet Container gets request and forwards to OSGi HttpService
+
+<a name="DispatchingRequests-Step3"></a>
+### Step 3
+
+OSGi HttpService looks for responsible registered Servlet or resource (see
+102.4 of the OSGi compendium)
+
+<a name="DispatchingRequests-Step4"></a>
+### Step 4
+
+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
+
+<a name="DispatchingRequests-Step4a"></a>
+### Step 4a
+
+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.
+
+<a name="DispatchingRequests-Step4b"></a>
+### 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.
+
+<a name="DispatchingRequests-Step4c"></a>
+### 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).
+
+<a name="DispatchingRequests-Step5"></a>
+### 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.
+
+<a name="DispatchingRequests-Step6"></a>
+### 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](slingxsite:resources.html)
+ on the basis of the request by calling *ResourceResovler.resolve*
+through *RequestData.initResource* (see also [URL decomposition]
+)
+* Locate the servlet or script (see [Servlets](servlets.html)
+) by calling *ServletResolver.resolveServlet* through
+*RequestData.initServlet*
+
+<a name="DispatchingRequests-Step7"></a>
+### 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](filters.html)
+ for details).
+If any called filter doesn't call *FilterChain.doFilter* at the end of
+the *Filter.doFilter* method request processing stops here.
+
+<a name="DispatchingRequests-Step8"></a>
+### Step 8
+
+After having called all request level filters, the component level filters
+(registered with the property *filter.scope=component*, see [Filters](filters.html)
+ for details) are called.
+
+<a name="DispatchingRequests-Step9"></a>
+### Step 9
+
+After having called the component level filters, the request servlet or
+script is finally called to process the request.
+
+<a name="DispatchingRequests-Include/Forward"></a>
+## 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:
+
+<a name="DispatchingRequests-Step1"></a>
+### Step 1
+
+Code in the processing servlet or script calls
+*RequestDispatcher.include* or *RequestDispatcher.forward*.
+
+<a name="DispatchingRequests-Step2"></a>
+### Step 2
+
+The resource is resolved though ResourceResolver.getResource (if the
+RequestDispatcher has not been created with a resource already)
+
+<a name="DispatchingRequests-Step3"></a>
+### Step 3
+
+The servlet or script to handle the resource is resolved calling the
+*ServletResolver.resolverServlet* method.
+
+<a name="DispatchingRequests-Step4"></a>
+### Step 4
+
+The component level filters (registered with the property
+*filter.scope=component*) are called again (see [Filters](filters.html)
+ for details).
+
+<a name="DispatchingRequests-Step5"></a>
+### Step 5
+
+The servlet or script is called to process the request.
+
+Note that these steps are processed for every include or forward call.
+
+
+<a name="DispatchingRequests-IncludedRequestAttributes"></a>
+## Included Request Attributes
+
+When servlet or script is called as a result of
+*RequestDispatcher.include* the following request attributes are set:
+
+<table>
+<tr><td> Attribute Name
+</tr>
+Attribute Type | Description |
+<tr><td> *org.apache.sling.api.include.servlet*
+</tr>
+*javax.servlet.Servlet* | The name of the request attribute containing
+the *Servlet* which included the servlet currently being active. |
+<tr><td> *org.apache.sling.api.include.resource*
+</tr>
+*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. |
+<tr><td> *org.apache.sling.api.include.request_path_info*
+</tr>
+*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 |
+<tr><td> *javax.servlet.include.request_uri*
+</tr>
+*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.
+*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. |
+<tr><td> *javax.servlet.include.context_path*
+</tr>
+*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.
+*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. |
+<tr><td> *javax.servlet.include.servlet_path*
+</tr>
+*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.
+*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. |
+<tr><td> *javax.servlet.include.path_info*
+</tr>
+*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.
+*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.
+<tr><td> *javax.servlet.include.query_string*
+</tr>
+*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.
+*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. |
+</table>
+
+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*.
Added: sling/site/trunk/content/documentation.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/documentation.mdtext (added)
+++ sling/site/trunk/content/documentation.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,170 @@
+Title: Documentation
+<a name="Documentation-Documentation"></a>
+# Documentation
+
+The documentation is split into different parts:
+
+ * [Getting Started](getting-started.html)
+, the right place to start!
+ * [The Sling Engine](the-sling-engine.html)
+, all about the heart of Sling
+ * [Development](development.html)
+, how do I get and develop with Sling
+ * [Bundles](bundles.html)
+, which bundle delivers which features to Sling
+ * [Tutorials & How-Tos](tutorials-&-how-tos.html)
+ * [Wiki](http://cwiki.apache.org/SLING/)
+ * [Configuration](configuration.html)
+ * [API Doc](http://sling.apache.org/apidocs/sling5/index.html)
+
+
+<a name="Documentation-Howcanyoucontribute"></a>
+## How can you contribute
+
+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 [public wiki](http://cwiki.apache.org/SLING/)
+ or post your suggestions to the mailing list.
+
+
+<a name="Documentation-Howisthedocumentationgenerated"></a>
+## How is the documentation generated
+
+The basic documentation of Sling is made up of four parts:
+
+1. The Sling Site at http://sling.apache.org/ (you are here)
+1. The Public Wiki at http://cwiki.apache.org/SLING
+1. The JavaDoc
+1. The Bundle documentation
+
+This page is about how this documentation is maintained and who is allowed
+to do what.
+
+
+<a name="Documentation-TheSlingSite"></a>
+### The Sling Site
+
+<a name="Documentation-MainSite"></a>
+#### Main Site
+
+The main Sling Site is maintained in the Confluence Wiki Space
+_SLINGxSITE_. The content of this space is automatically synchronized with
+the web server with a simple shell script [^sling.sh](^sling.sh.html)
+ which is called regularly as per the following *crontab* entry:
+
+
+ # sync wiki autoexport to Sling site
+ 1 * * * * (/home/fmeschbe/sling.sh)
+
+
+Thus, after editing the site source in the Wiki, the rest happens
+automatically, it just takes some time -- in the order 2 hours or so --
+before the changes are visible at http://sling.apache.org/.
+
+Everybody is allowed to read the SLINGxSITE wiki and to add comments; but
+only committers of the Apache Sling project are allowed to edit the content
+and to manage the comments.
+
+The main site is located in the *site* folder below the Site URL [http://sling.apache.org/](http://sling.apache.org/)
+ to which users are redirected automatically.
+
+<a name="Documentation-SecondarySite"></a>
+#### Secondary Site
+
+The Sling site contains secondary site parts that are maintained in the
+Apache SVN repository at [http://svn.apache.org/repos/asf/sling/site](http://svn.apache.org/repos/asf/sling/site)
+. Updates to secondary parts of the site have to be done in the following
+steps:
+
+1. Checkout or update the [site](https://svn.apache.org/repos/asf/sling/site)
+ tree form SVN.
+
+
+ $ svn checkout https://svn.apache.org/repos/asf/sling/site
+
+
+2. Apply your changes.
+
+3. Commit the changes back into SVN.
+
+
+ $ svn commit -m"<enter your message here>"
+
+
+4. Login to *people.apache.org*
+
+
+ $ ssh people.apache.org
+
+
+5. Go to the location from where infrastructure mirroring is getting the
+actual sites and update from SVN.
+
+
+ $ cd /x1/www/sling.apache.org
+ $ svn update
+
+
+After some time, the updates will be synchronized to the web servers and
+can be accessed.
+
+
+<a name="Documentation-ThePublicWiki"></a>
+### The Public Wiki
+
+The public wiki of Sling is available at http://cwiki.apache.org/SLING and
+is maintained in the Confluence space _SLING_. This is a public wiki, in
+that after self-registration, everybody is allowed to edit content.
+
+
+<a name="Documentation-TheJavaDoc"></a>
+### The JavaDoc
+
+Up until now the JavaDoc of the Sling Bundles has not been published.
+
+I just polished the JavaDoc generation setup of Sling a bit, so that I
+could generate a first shot of aggregate JavaDocs. This draft can currently
+be found on my site at
+http://people.apache.org/~fmeschbe/slingdocs.762729/. This JavaDoc has been
+generated as follows:
+
+
+ $ svn export -r 762729
+http://svn.apache.org/repos/asf/incubator/sling/trunk sling
+ $ mvn -DexcludePackageNames="*.impl:*.internal:*.jsp:sun.misc:*.juli"
+org.apache.maven.plugins:maven-javadoc-plugin:2.5:aggregate
+
+
+I am still unsure whether it makes sense to generate aggregate JavaDoc for
+all (or part of) the bundles of Sling. See also below regarding the Sites.
+
+
+<a name="Documentation-TheBundleDocumentation"></a>
+### The Bundle Documentation
+
+Apart from the documentation of Sling on the Site and in the Wiki, it would
+also be thinkable that we accompany the source modules with some
+documentation and generate this using the Maven Site plugin. My tests so
+far for generating a multi-module site have not been very successful. But
+generating the site in a module-by-module manner might be a good thing, at
+least to get the per-module JavaDoc and some more code-oriented information
+like Surefire Reports, fixed bugs, etc.
+
+To prepare such Bundle Documentation I added a first shot at site
+generation setup to the parent project. For now, this includes the module's
+JavaDoc (of course), the Surefire reports and a report on the issues fixed
+(or open) with respect to some version. This site generation setup can be
+configured per module with two properties:
+
+<table>
+<tr><th> Property </th><th> Description </th></tr>
+<tr><td> *site.jira.version.id* </td><td> The ID of the JIRA version whose bugs are to
+be listed in the JIRA report. This is a number, such as 12313306 (Sling API
+version 2.0.4). </td></tr>
+<tr><td> *site.javadoc.exclude* </td><td> The Java packages to not include with the
+JavaDoc generation. By default all packages containing *impl* or
+*internal* in their name are excluded. To add more packages for
+exclusion, list them in the format suitable for the [*excludePackageNames*](http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#excludePackageNames)
+ property of the Maven JavaDoc plugin. For example, to exclude any *jsp*
+and *juli* packages (see the _scripting/jsp_ bundle), this property would
+be set to *\*.jsp:\*.juli*. </td></tr>
Added: sling/site/trunk/content/downloads.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/downloads.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/downloads.mdtext (added)
+++ sling/site/trunk/content/downloads.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,407 @@
+Title: Downloads
+<a name="Downloads-Downloads"></a>
+# Downloads
+
+To get the latest development release of Apache Sling, you can check out
+the [Source Code](project-information#projectinformation-source.html)
+ and [Getting and Building Sling]
+ yourself. Otherwise, the releases below are available for download. To
+install, just download and extract. These [KEYS|http://www.apache.org/dist/sling/KEYS]
+ can be used to verify the release archive.
+
+All Apache Sling products are distributed under the terms of The Apache
+Software License (version 2.0). See our [license](project-license.html)
+, or the LICENSE file included in each distribution.
+
+<a name="Downloads-Mirrors"></a>
+## Mirrors
+
+Use the links below to download binary or source distributions of Apache
+Sling from one of our mirrors.
+
+You are currently using *\[preferred\](preferred\.html)
+*. If you encounter a problem with this mirror, please select another
+mirror. If all mirrors are failing, there are backup mirrors (at the end of
+the mirrors list) that should be available.
+If the mirror displayed above is labeled _preferred_, then please reload
+this page by [clicking here](http://sling.apache.org/site/downloads.cgi)
+.
+
+{html}
+<form action="[location](location.html)
+" method="get" id="SelectMirror">
+Other mirrors: </P><select name="Preferred">
+[if-any http](if-any-http.html)
+[for http](for-http.html)
+<option value="[http]">[http]</option>[end]
+[end](end.html)
+[if-any ftp](if-any-ftp.html)
+[for ftp](for-ftp.html)
+<option value="[ftp]">[ftp]</option>[end]
+[end](end.html)
+[if-any backup](if-any-backup.html)
+[for backup](for-backup.html)
+<option value="[backup]">[backup] (backup)</option>[end]
+[end](end.html)
+</select>
+<input type="submit" value="Change"></input>
+</form>
+{html}
+
+
+
+
+<a name="Downloads-SlingApplication"></a>
+## Sling Application
+
+<table>
+<tr><th> Artifact </th><th> Version </th><th> Provides </th><th> Package </th></tr>
+<tr><td> Sling Standalone Application </td><td> 6 </td><td> A self-runnable Sling jar. </td><td>
+{downloadmirror:sling}org.apache.sling.launchpad-6-standalone.jar{downloadmirror}
+</td></tr>
+<tr><td> Sling Web Application </td><td> 6 </td><td> A ready-to run Sling webapp as a war file. </td><td>
+{downloadmirror:sling}org.apache.sling.launchpad-6.war{downloadmirror} </td></tr>
+
+
+{downloadmirror:sling}sling-6-source-release.zip{downloadmirror} |
+</table>
+
+If you want to experiment with bleeding edge code, [building Sling yourself](getting-and-building-sling.html)
+ is not that hard.
+
+If you are looking for previous releases of Apache Sling, have a look in
+the [archives](http://archive.apache.org/dist/sling/)
+. For previous incubator releases of Apache Sling, have a look in the [Incubator archives|http://archive.apache.org/dist/incubator/sling/]
+.
+
+
+<a name="Downloads-SlingComponents"></a>
+## Sling Components
+
+<table>
+<tr><th> Artifact </th><th> Version </th><th> Binary </th><th> Source </th></tr>
+<tr><td> Adapter </td><td> 2.0.12 </td><td>
+{slingdownload:jar}org.apache.sling.adapter-2.0.12{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.adapter-2.0.12-source-release{slingdownload}
+</td></tr>
+<tr><td> API </td><td> 2.2.4 </td><td>
+{slingdownload:jar}org.apache.sling.api-2.2.4{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.api-2.2.4-source-release{slingdownload}
+</td></tr>
+<tr><td> Auth Core </td><td> 1.0.6 </td><td>
+{slingdownload:jar}org.apache.sling.auth.core-1.0.6{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.auth.core-1.0.6-source-release{slingdownload}
+</td></tr>
+<tr><td> Auth Form </td><td> 1.0.4 </td><td>
+{slingdownload:jar}org.apache.sling.auth.form-1.0.4{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.auth.form-1.0.4-source-release{slingdownload}
+</td></tr>
+<tr><td> Auth OpenID </td><td> 1.0.2 </td><td>
+{slingdownload:jar}org.apache.sling.auth.openid-1.0.2{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.auth.openid-1.0.2-source-release{slingdownload}
+</td></tr>
+<tr><td> Auth Selector </td><td> 1.0.2 </td><td>
+{slingdownload:jar}org.apache.sling.auth.selector-1.0.2{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.auth.selector-1.0.2-source-release{slingdownload}
+</td></tr>
+<tr><td> Bundle Resource Provider </td><td> 2.0.6 </td><td>
+{slingdownload:jar}org.apache.sling.bundleresource.impl-2.0.6{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.bundleresource.impl-2.0.6-source-release{slingdownload}
+</td></tr>
+<tr><td> Commons Classloader </td><td> 1.2.4 </td><td>
+{slingdownload:jar}org.apache.sling.commons.classloader-1.2.4{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.commons.classloader-1.2.4-source-release{slingdownload}
+</td></tr>
+<tr><td> Commons Compiler </td><td> 2.0.2 </td><td>
+{slingdownload:jar}org.apache.sling.commons.compiler-2.0.2{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.commons.compiler-2.0.2-project{slingdownload}
+</td></tr>
+<tr><td> Commons Log </td><td> 3.0.0 </td><td>
+{slingdownload:jar}org.apache.sling.commons.log-3.0.0{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.commons.log-3.0.0-project{slingdownload}
+</td></tr>
+<tr><td> Commons Log Service </td><td> 1.0.0 </td><td>
+{slingdownload:jar}org.apache.sling.commons.logservice-1.0.0{slingdownload}
+</td><td>
+{slingdownload:bin}org.apache.sling.commons.logservice-1.0.0-project{slingdownload}
+</td></tr>
+<tr><td> Commons HTML </td><td> 1.0.0 </td><td>
+{slingdownload:jar}org.apache.sling.commons.html-1.0.0{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.commons.html-1.0.0-project{slingdownload}
+</td></tr>
+<tr><td> Commons JSON </td><td> 2.0.6 </td><td>
+{slingdownload:jar}org.apache.sling.commons.html-2.0.6{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.commons.html-2.0.6-project{slingdownload}
+</td></tr>
+<tr><td> Commons OSGi </td><td> 2.1.0 </td><td>
+{slingdownload:jar}org.apache.sling.commons.osgi-2.1.0{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.commons.osgi-2.1.0-source-release{slingdownload}
+</td></tr>
+<tr><td> Commons Scheduler </td><td> 2.3.4 </td><td>
+{slingdownload:jar}org.apache.sling.commons.scheduler-2.3.4{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.commons.scheduler-2.3.4-source-release{slingdownload}
+</td></tr>
+<tr><td> Commons Testing </td><td> 2.0.10 </td><td>
+{slingdownload:jar}org.apache.sling.commons.testing-2.0.10{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.commons.testing-2.0.10-source-release{slingdownload}
+</td></tr>
+<tr><td> Commons Threads </td><td> 3.1.0 </td><td>
+{slingdownload:jar}org.apache.sling.commons.threads-3.1.0{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.commons.threads-3.1.0-source-release{slingdownload}
+</td></tr>
+<tr><td> Engine </td><td> 2.2.4 </td><td>
+{slingdownload:jar}org.apache.sling.engine-2.2.4{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.engine-2.2.4-source-release{slingdownload}
+</td></tr>
+<tr><td> Event </td><td> 3.1.2 </td><td>
+{slingdownload:jar}org.apache.sling.event-3.1.2{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.event-3.1.2-source-release{slingdownload}
+</td></tr>
+<tr><td> Explorer </td><td> 1.0.2 </td><td>
+{slingdownload:jar}org.apache.sling.extensions.explorer-1.0.2{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.extensions.explorer-1.0.2-source-release{slingdownload}
+</td></tr>
+<tr><td> Failing Server-Side Tests </td><td> 1.0.6 </td><td>
+{slingdownload:jar}org.apache.sling.testing.samples.failingtests-1.0.6{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.testing.samples.failingtests-1.0.6-source-release{slingdownload}
+</td></tr>
+<tr><td> FileSystem Provider </td><td> 1.0.2 </td><td>
+{slingdownload:jar}org.apache.sling.fsresource-1.0.2{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.fsresource-1.0.2-source-release{slingdownload}
+</td></tr>
+<tr><td> GWT Integration </td><td> 3.0.0 </td><td>
+{slingdownload:jar}org.apache.sling.gwt.servlet-3.0.0{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.gwt.servlet-3.0.0-source-release{slingdownload}
+</td></tr>
+<tr><td> I18n </td><td> 2.2.0 </td><td>
+{slingdownload:jar}org.apache.sling.i18n-2.2.0{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.i18n-2.2.0-source-release{slingdownload}
+</td></tr>
+<tr><td> Installer Core </td><td> 3.3.4 </td><td>
+{slingdownload:jar}org.apache.sling.installer.core-3.3.4{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.installer.core-3.3.4-source-release{slingdownload}
+</td></tr>
+<tr><td> Installer Configuration Support </td><td> 1.0.4 </td><td>
+{slingdownload:jar}org.apache.sling.installer.factory.configuration-1.0.4{slingdownload}
+</td><td>
+{slingdownload:bin}org.apache.sling.installer.factory.configuration-1.0.4-source-release{slingdownload}
+</td></tr>
+<tr><td> Installer File Provider </td><td> 1.0.2 </td><td>
+{slingdownload:jar}org.apache.sling.installer.provider.file-1.0.2{slingdownload}
+</td><td>
+{slingdownload:bin}org.apache.sling.installer.provider.file-1.0.2-source-release{slingdownload}
+</td></tr>
+<tr><td> Installer JCR Provider </td><td> 3.1.2 </td><td>
+{slingdownload:jar}org.apache.sling.installer.provider.jcr-3.1.2{slingdownload}
+</td><td>
+{slingdownload:bin}org.apache.sling.installer.provider.jcr-3.1.2-source-release{slingdownload}
+</td></tr>
+<tr><td> JCR API </td><td> 2.1.0 </td><td>
+{slingdownload:jar}org.apache.sling.jcr.api-2.1.0{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.jcr.api-2.1.0-source-release{slingdownload}
+</td></tr>
+<tr><td> JCR Base </td><td> 2.1.2 </td><td>
+{slingdownload:jar}org.apache.sling.jcr.base-2.1.2{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.jcr.base-2.1.2-source-release{slingdownload}
+</td></tr>
+<tr><td> JCR ClassLoader </td><td> 3.1.4 </td><td>
+{slingdownload:jar}org.apache.sling.jcr.classloader-3.1.4{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.jcr.classloader-3.1.4-source-release{slingdownload}
+</td></tr>
+<tr><td> JCR ContentLoader </td><td> 2.1.4 </td><td>
+{slingdownload:jar}org.apache.sling.jcr.contentloader-2.1.4{slingdownload}
+</td><td>
+{slingdownload:bin}org.apache.sling.jcr.contentloader-2.1.4-source-release{slingdownload}
+</td></tr>
+<tr><td> JCR Compiler </td><td> 2.0.2 </td><td>
+{slingdownload:jar}org.apache.sling.jcr.compiler-2.0.2{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.jcr.compiler-2.0.2-project{slingdownload}
+</td></tr>
+<tr><td> JCR Jackrabbit AccessManager </td><td> 2.1.0 </td><td>
+{slingdownload:jar}org.apache.sling.jcr.jackrabbit.accessmanager-2.1.0{slingdownload}
+</td><td>
+{slingdownload:bin}org.apache.sling.jcr.jackrabbit.accessmanager-2.1.0-source-release{slingdownload}
+</td></tr>
+<tr><td> JCR Jackrabbit Server </td><td> 2.1.0 </td><td>
+{slingdownload:jar}org.apache.sling.jcr.jackrabbit.server-2.1.0{slingdownload}
+</td><td>
+{slingdownload:bin}org.apache.sling.jcr.jackrabbit.server-2.1.0-source-release{slingdownload}
+</td></tr>
+<tr><td> JCR Jackrabbit UserManager </td><td> 2.2.0 </td><td>
+{slingdownload:jar}org.apache.sling.jcr.jackrabbit.usermanager-2.2.0{slingdownload}
+</td><td>
+{slingdownload:bin}org.apache.sling.jcr.jackrabbit.usermanager-2.2.0-source-release{slingdownload}
+</td></tr>
+<tr><td> JCR Resource </td><td> 2.0.10 </td><td>
+{slingdownload:jar}org.apache.sling.jcr.resource-2.0.10{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.jcr.resource-2.0.10-project{slingdownload}
+</td></tr>
+<tr><td> JCR Prefs </td><td> 1.0.0 </td><td>
+{slingdownload:jar}org.apache.sling.jcr.prefs-1.0.0{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.jcr.prefs-1.0.0-project{slingdownload}
+</td></tr>
+<tr><td> JCR WebDAV </td><td> 2.1.0 </td><td>
+{slingdownload:jar}org.apache.sling.jcr.webdav-2.1.0{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.jcr.webdav-2.1.0-source-release{slingdownload}
+</td></tr>
+<tr><td> JCR DavEx </td><td> 2.1.0 </td><td>
+{slingdownload:jar}org.apache.sling.jcr.davex-1.0.0{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.jcr.davex-1.0.0-source-release{slingdownload}
+</td></tr>
+<tr><td> JCR Web Console Plugin </td><td> 1.0.0 </td><td>
+{slingdownload:jar}org.apache.sling.jcr.webconsole-1.0.0{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.jcr.webconsole-1.0.0-source-release{slingdownload}
+</td></tr>
+<tr><td> JUnit Core </td><td> 1.0.6 </td><td>
+{slingdownload:jar}org.apache.sling.junit.core-1.0.6{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.junit.core-1.0.6-source-release{slingdownload}
+</td></tr>
+<tr><td> JUnit Remote Tests Runners </td><td> 1.0.6 </td><td>
+{slingdownload:jar}org.apache.sling.junit.remote-1.0.6{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.junit.remote-1.0.6-source-release{slingdownload}
+</td></tr>
+<tr><td> JUnit Scriptable Tests Provider </td><td> 1.0.6 </td><td>
+{slingdownload:jar}org.apache.sling.junit.scriptable-1.0.6{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.junit.scriptable-1.0.6-source-release{slingdownload}
+</td></tr>
+<tr><td> Mime Type Service </td><td> 2.1.4 </td><td>
+{slingdownload:jar}org.apache.sling.commons.mime-2.1.4{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.commons.mime-2.1.4-source-release{slingdownload}
+</td></tr>
+<tr><td> Launchpad API </td><td> 1.1.0 </td><td>
+{slingdownload:jar}org.apache.sling.launchpad.api-1.1.0{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.launchpad.api-1.1.0-source-release{slingdownload}
+</td></tr>
+<tr><td> Launchpad Base </td><td> 2.3.0 </td><td>
+{slingdownload:jar}org.apache.sling.launchpad.base-2.3.0{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.launchpad.base-2.3.0-source-release{slingdownload}
+</td></tr>
+<tr><td> Launchpad Base - Application Launcher </td><td> 2.1.0 </td><td>
+{slingdownload:jar}org.apache.sling.launchpad.base-2.1.0-app{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.launchpad.base-2.1.0-source-release{slingdownload}
+</td></tr>
+<tr><td> Launchpad Base - Web Launcher </td><td> 2.1.0 </td><td>
+{slingdownload:war}org.apache.sling.launchpad.base-2.1.0-webapp{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.launchpad.base-2.1.0-source-release{slingdownload}
+</td></tr>
+<tr><td> Launchpad Content </td><td> 2.0.6 </td><td>
+{slingdownload:war}org.apache.sling.launchpad.content-2.0.6{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.launchpad.content-2.0.6-source-release{slingdownload}
+</td></tr>
+<tr><td> Launchpad Installer </td><td> 1.1.0 </td><td>
+{slingdownload:jar}org.apache.sling.launchpad.installer-1.1.0{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.launchpad.installer-1.1.0-source-release{slingdownload}
+</td></tr>
+<tr><td> Launchpad Integration Tests </td><td> 1.0.0 </td><td>
+{slingdownload:jar}org.apache.sling.launchpad.integration-tests-1.0.0{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.launchpad.integration-tests-1.0.0-source-release{slingdownload}
+</td></tr>
+<tr><td> Launchpad Testing Services </td><td> 2.0.8 </td><td>
+{slingdownload:jar}org.apache.sling.launchpad.test-services-2.0.8{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.launchpad.test-services-2.0.8-source-release{slingdownload}
+</td></tr>
+<tr><td> Launchpad Testing Services WAR </td><td> 2.0.8 </td><td>
+{slingdownload:war}org.apache.sling.launchpad.test-services-war-2.0.8{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.launchpad.test-services-war-2.0.8-source-release{slingdownload}
+</td></tr>
+<tr><td> Path-based RTP sample </td><td> 2.0.4 </td><td>
+{slingdownload:jar}org.apache.sling.samples.path-based.rtp-2.0.4{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.samples.path-based.rtp-2.0.4-source-release{slingdownload}
+</td></tr>
+<tr><td> Rewriter </td><td> 1.0.2 </td><td>
+{slingdownload:jar}org.apache.sling.rewriter-1.0.2{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.rewriter-1.0.2-source-release{slingdownload}
+</td></tr>
+<tr><td> Sample Integration Tests </td><td> 1.0.6 </td><td>
+{slingdownload:jar}org.apache.sling.testing.samples.integrationtests-1.0.6{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.testing.samples.integrationtests-1.0.6-source-release{slingdownload}
+</td></tr>
+<tr><td> Sample Server-Side Tests </td><td> 1.0.6 </td><td>
+{slingdownload:jar}org.apache.sling.testing.samples.sampletests-1.0.6{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.testing.samples.sampletests-1.0.6-source-release{slingdownload}
+</td></tr>
+<tr><td> Scripting API </td><td> 2.1.4 </td><td>
+{slingdownload:jar}org.apache.sling.scripting.api-2.1.4{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.scripting.api-2.1.4-source-release{slingdownload}
+</td></tr>
+<tr><td> Scripting Core </td><td> 2.0.20 </td><td>
+{slingdownload:jar}org.apache.sling.scripting.core-2.0.20{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.scripting.core-2.0.20-source-release{slingdownload}
+</td></tr>
+<tr><td> Scripting Java </td><td> 2.0.2 </td><td>
+{slingdownload:jar}org.apache.sling.scripting.java-2.0.2{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.scripting.java-2.0.2-project{slingdownload}
+</td></tr>
+<tr><td> Scripting JavaScript </td><td> 2.0.12 </td><td>
+{slingdownload:jar}org.apache.sling.scripting.javascript-2.0.12{slingdownload}
+</td><td>
+{slingdownload:bin}org.apache.sling.scripting.javascript-2.0.12-project{slingdownload}
+</td></tr>
+<tr><td> Scripting JSP </td><td> 2.0.20 </td><td>
+{slingdownload:jar}org.apache.sling.scripting.jsp-2.0.20{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.scripting.jsp-2.0.20-project{slingdownload}
+</td></tr>
+<tr><td> Scripting JSP Taglib </td><td> 2.1.6 </td><td>
+{slingdownload:jar}org.apache.sling.scripting.jsp.taglib-2.1.6{slingdownload}
+</td><td>
+{slingdownload:bin}org.apache.sling.scripting.jsp.taglib-2.1.6-project{slingdownload}
+</td></tr>
+<tr><td> Scripting JST </td><td> 2.0.4 </td><td>
+{slingdownload:jar}org.apache.sling.scripting.jst-2.0.4{slingdownload} </td><td>
+{slingdownload:bin}org.apache.sling.scripting.jst-2.0.4-project{slingdownload}
+</td></tr>
+<tr><td> Security </td><td> 1.0.0 </td><td>
+{slingdownload:jar}org.apache.sling.security-1.0.0{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.security-1.0.0-source-release{slingdownload}
+</td></tr>
+<tr><td> Servlets Get </td><td> 2.1.2 </td><td>
+{slingdownload:jar}org.apache.sling.servlets.get-2.1.2{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.servlets.get-2.1.2-source-release{slingdownload}
+</td></tr>
+<tr><td> Servlets Post </td><td> 2.1.0 </td><td>
+{slingdownload:jar}org.apache.sling.servlets.post-2.1.0{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.servlets.post-2.1.0-source-release{slingdownload}
+</td></tr>
+<tr><td> Servlets Resolver </td><td> 2.1.2 </td><td>
+{slingdownload:jar}org.apache.sling.servlets.resolver-2.1.2{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.servlets.resolver-2.1.2-source-release{slingdownload}
+</td></tr>
+<tr><td> Settings </td><td> 1.1.0 </td><td>
+{slingdownload:jar}org.apache.sling.settings-1.1.0{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.settings-1.1.0-source-release{slingdownload}
+</td></tr>
+<tr><td> Test Tools </td><td> 1.0.2 </td><td>
+{slingdownload:jar}org.apache.sling.testing.tools-1.0.2{slingdownload} </td><td>
+{slingdownload:zip}org.apache.sling.testing.tools-1.0.2-source-release{slingdownload}
+</td></tr>
+<tr><td> Thread Dumper </td><td> 0.2.2 </td><td>
+{slingdownload:jar}org.apache.sling.extensions.threaddump-0.2.2{slingdownload}
+</td><td>
+{slingdownload:bin}org.apache.sling.extensions.threaddump-0.2.2-source-release{slingdownload}
+</td></tr>
+<tr><td> Web Console Branding </td><td> 1.0.0 </td><td>
+{slingdownload:jar}org.apache.sling.extensions.webconsolebranding-1.0.0{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.extensions.webconsolebranding-1.0.0-source-release{slingdownload}
+</td></tr>
+<tr><td> Web Console Security Provider </td><td> 1.0.0 </td><td>
+{slingdownload:jar}org.apache.sling.extensions.webconsolesecurityprovider-1.0.0{slingdownload}
+</td><td>
+{slingdownload:zip}org.apache.sling.extensions.webconsolesecurityprovider-1.0.0-source-release{slingdownload}
+</td></tr>
Added: sling/site/trunk/content/embedding-sling.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/embedding-sling.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/embedding-sling.mdtext (added)
+++ sling/site/trunk/content/embedding-sling.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,257 @@
+Title: Embedding Sling
+<a name="EmbeddingSling-EmbeddingSling"></a>
+# Embedding Sling
+
+The Sling Launchpad Launcher can be used to embed the OSGi Framework
+startup in your own Java application. This functionality is implemented in
+the [Sling Launchpad Base project](http://svn.apache.org/repos/asf/sling/trunk/launchpad/base)
+. This project has the following features:
+
+* Builds three artifacts:
+** A standalone Java Application with the artifact qualifier _app_; e.g.
+*org.apache.sling.launchpad.base-2.3.1-SNAPSHOT-app.jar*
+** A Web Application with the artifact qualifier _webapp_; e.g
+*org.apache.sling.launchpad.base-2.3.1-SNAPSHOT-wepabb.war*
+** The primary artifact without an artifact qualifier; e.g.
+*org.apache.sling.launchpad.base-2.3.1-SNAPSHOT.jar*
+* Embeds the OSGi Framework (Apache Felix) in the primary artifact
+* Encapsulates the OSGi Framework in its own *URLClassLoader*
+* Supports Framework restart
+* Allows propagation of core setup functionality depending on the
+environment
+
+This page is about the internal details of the Sling Launchpad Base module.
+To get an outside overview of the Sling Launchpad you might want to refer
+to [The Sling Launchpad](the-sling-launchpad.html)
+ page.
+
+<a name="EmbeddingSling-Structure"></a>
+# Structure
+
+The Launcher is based on three parts:
+1. The external part which is for example the standalone Java application's
+main class or the servlet deployed into the servlet container
+1. The internal part which is the OSGi framework plus helper classes to
+control the framework and run initial installations
+1. The bridging part, which contains API common to the external and internal
+part.
+
+The external part uses the bridging part to create the class loader into
+which the internal part is loaded. The bidirectional communication between
+the external and internal part is implement based on two interfaces:
+
+* The *Launcher* interface is implemented by a class in the internal part
+which is loaded through the bridge class loader. This interface allows
+setting, starting and stopping of the framework.
+* The *Notifiable* interface is implemented by a class in the external
+part which instance is handed to the *Launcher* instance. This interface
+allows the internal part to communicate back to the external part, most
+notably to indicate that the framework has been stopped from within or that
+the framework has been updated and must be restarted.
+
+
+<a name="EmbeddingSling-TheBridgingPart"></a>
+# The Bridging Part
+
+The bridging part is provided in the
+*org.apache.sling.launchpad.base.shared* package:
+
+<table>
+<tr><td> Class </td><td> Description </td></tr>
+<tr><td> Launcher </td><td> The interface implemented by the internal class matching the
+external class being called to start/stop the framework. </td></tr>
+<tr><td> LauncherClassLoader </td><td> *URLClassLoader* implementing the class loader to
+load the internal part (along with the OSGi framework). This class loader
+only delegates to the parent class loader any packages not contained in the
+launchpad library (primary artifact of the Launchpad Base project). </td></tr>
+<tr><td> Loader </td><td> Helper class to find the launchpad library and to create the
+*LauncherClassLoader* with that library. This class is also used to
+actually load the *Launcher* implementation to be called from the
+external launcher class. </td></tr>
+<tr><td> Notifiable </td><td> The interface implemented in the external part and handed
+over to the internal part. </td></tr>
+<tr><td> SharedConstants </td><td> Constants naming various properties and classes. </td></tr>
+</table>
+
+
+<a name="EmbeddingSling-TheInternalPart"></a>
+# The Internal Part
+
+The main class from the internal class directly used is [*Sling*](http://svn.apache.org/repos/asf/sling/trunk/launchpad/base/src/main/java/org/apache/sling/launchpad/base/impl/Sling.java)
+ which instantiated to start the OSGi Framework. This class is responsible
+for setting up the environment to finally start the OSGi Framework:
+
+* Read the *sling.properties* file
+* Ensure the presence of the JMX MBeanServer service
+* Execute the bootstrap installations, updates and uninstallations
+
+The [*SlingFelix*](http://svn.apache.org/repos/asf/sling/trunk/launchpad/base/src/main/java/org/apache/sling/launchpad/base/impl/SlingFelix.java)
+ class extends the Apache Felix *Felix* class which is the actual OSGi
+framework implementation. We extend the class to be able to notify the
+*Notifiable* implementation and update the OSGi framework from within the
+OSGi framework by updating the system bundle.
+
+
+<a name="EmbeddingSling-TheExternalPart"></a>
+## The External Part
+
+The external part is comprised of a main class started from the environment
+-- main class of the Java applicaction or the servlet deployed in the
+servlet container -- and a corresponding delegate class located inside of
+the launchpad base library. This delegate class is instantiated by the
+*Loader* loading from the *LauncherClassLoader*.
+
+
+<a name="EmbeddingSling-StandaloneJavaApplication"></a>
+### Standalone Java Application
+
+The standalone Java Application makes use of three classes:
+
+<table>
+<tr><td> Class </td><td> Description </td></tr>
+<tr><td> Main </td><td> This is the main class whose *main* method is called by the Java
+VM. This class is itself the *Notifiable* and finds the *sling.home*
+location from the environment (command line parameter, system property, or
+environment variable). </td></tr>
+<tr><td> MainDelegate </td><td> This class is loaded by the *Loader* from the
+*LauncherClassLoader* to actually complete the initial setup before
+creating the *Sling* class to start the framework. </td></tr>
+<tr><td> ControlListener </td><td> This class is used by the *Main* class to open a
+server socket to be able to start and stop Sling as a server. This class
+allows for starting (opening the server socket), status check (connecting
+to the socket asking for status), and shutdown (connecting to the socket
+asking for shutdown). </td></tr>
+</table>
+
+At the moment these classes are not directly suitable to be embedded in an existing application (or custom application launcher framework) unless that embedding prepares command line arguments in a {{String[](.html)
+}} and calls the *Main.main* method. To allow for custom embeddings or
+extensions, the work distriubtions between the three classes should be
+refactored.
+
+<a name="EmbeddingSling-EmbeddingtheStandaloneJavaApplication"></a>
+### Embedding the Standalone Java Application
+
+{info}
+This work is being done as part of [SLING-2225](https://issues.apache.org/jira/browse/SLING-2225)
+ and will be officially available with the Sling Launchpad Base release
+2.4.0. If you want to use the embedding before the release, you have to
+checkout the source from [SVN|http://svn.apache.org/repos/asf/sling/trunk/launchpad/base]
+ and build yourself.
+{info}
+
+To embedd the Sling Launcher in an application, the *Main* class is
+extended from. To manage the launcher, the following API is available:
+
+<table>
+<tr><th> Method </th><th> Description </th></tr>
+<tr><td> *Main(Map<String, String> properties)* </td><td> Instantiates the Main class
+with the given configuration properties. These are properties which are
+used directly as overwrites to the configurations in the
+*sling.properties* file. There is no more conversion applied. </td></tr>
+<tr><td> *doControlCommand()* </td><td> Before starting the application for the first
+time, this method can be called to handle any control command action. </td></tr>
+<tr><td> *doStart()* </td><td> Starts the Sling Application using the provided
+configuration properties as overwrites. Also these properties (or the
+*sling.home* system property or the *SLING_HOME* environment variable
+are analyzed to get the value for the *sling.home* setting. </td></tr>
+<tr><td> *doStop()* </td><td> Stops the application started by the *doStart()* method.
+</td></tr>
+</table>
+
+
+<a name="EmbeddingSling-ExternalControloftheSlingApplication"></a>
+#### External Control of the Sling Application
+
+By using control actions, the Sling Launcher may open or connect to a
+control port to communicate. The *doControlAction()* method together with
+the *sling.control.action* and *sling.control.socket* properties is
+able to setup this communication.
+
+The *sling.control.socket* is either a normal port number, in which case
+the connection is opened on the *localhost* interface (usually
+127.0.0.1). Otheriwse, it may also be a value of the form _host:port_ where
+_host_ is the name or IP address of the interface to connect to and port is
+the port number. For security reasons it is suggested to not use an
+interface which is available remotely. So the default of *localhost* is
+usually the best choice.
+
+The *sling.control.action* takes either of three values:
+
+<table>
+<tr><td> *start* </td><td> Starts a server socket as specified by the
+*sling.control.socket* property. If the socket cannot be bound to
+(because the port is in use) an error message is printed. Using the
+*start* action only makes sense when starting the application. </td></tr>
+<tr><td> *stop* </td><td> The *stop* action is used to stop a running application. For
+that a connection is opened to the server running on the socket specified
+by the *sling.control.socket* property. On this connection the server is
+instructed to shut down. After executing the *stop* action, the Java
+application should be terminated. </td></tr>
+<tr><td> *status* </td><td> The *status* action is used to check the status of a
+running application. For that a connection is opened to the server running
+on the socket specified by the *sling.control.socket* property. On this
+connection the server is queried on its status. After executing the
+*stop* action, the Java application should be terminated. </td></tr>
+</table>
+
+
+<a name="EmbeddingSling-ConversionofCommandlineArgumentstoProperties"></a>
+#### Conversion of Commandline Arguments to Properties
+
+When calling the Main class through the JVM startup the {{Main.main(String[](.html)
+ args)}} methods is called which reads the command line arguments and
+converts them into a *Map<String, String>* suitable for the constructore
+as follows:
+
+<table>
+<tr><th> Command Line Argument </th><th> Properties Entry </th></tr>
+<tr><td> start </td><td> sling.control.action = "start" </td></tr>
+<tr><td> status </td><td> sling.control.action = "status" </td></tr>
+<tr><td> stop </td><td> sling.control.action = "stop" </td></tr>
+<tr><td> -c slinghome </td><td> sling.home = slinghome </td></tr>
+<tr><td> -l loglevel </td><td> org.apache.sling.commons.log.level = loglevel </td></tr>
+<tr><td> -f logfile </td><td> org.apache.sling.commons.log.file = logfile </td></tr>
+<tr><td> -a address </td><td> This command line argument is not supported yet and thus
+ignored </td></tr>
+<tr><td> -p port </td><td> org.osgi.service.http.port = port </td></tr>
+<tr><td> -j [ host ":" ](-host-":"-.html)
+ port </td><td> sling.control.socket = [ host ":" ]
+ port </td></tr>
+<tr><td> -h </td><td> This command line option is handled directly and not converted into
+the map </td></tr>
+</table>
+
+
+<a name="EmbeddingSling-WebApplication"></a>
+### Web Application
+
+The web application makes use of 5 classes:
+
+<table>
+<tr><td> Class </td><td> Description </td></tr>
+<tr><td> SlingServlet </td><td> This is the servlet registered in the *web.xml*
+descriptor and loaded by the servlet container into which Sling is
+deplyoed. This class locates the *sling.home* folder and loads the
+*SlingServletDelagate* to actually launch the framework. </td></tr>
+<tr><td> SlingSessionListener </td><td> This -- somewhat inappropriately named -- class is
+registered as a listener by the Sling *web.xml* descriptor. It is called
+by the servlet container and forwards events to the
+*SlingHttpSessionListenerDelegate* which in turn forwards the events to
+the respective Servlet API listener services registered in the OSGi
+Framework. </td></tr>
+<tr><td> SlingBridge </td><td> Simple extension of the *Sling* class which registers the
+system bundle's *BundleContext* as a servlet context attribute of the
+Sling web application. This allows Servlet Container bridging to properly
+work. </td></tr>
+<tr><td> SlingHttpSessionListenerDelegate </td><td> This class is loaded by the
+*LauncherClassLoader* called from the *SlingSessionListener*. It is
+called by the *SlingSessionListener* to forward servlet container events
+to registered Servlet API listener services. </td></tr>
+<tr><td> SlingServletDelegate </td><td> This class is loaded by the *Loader* from the
+*LauncherClassLoader* to actually complete the initial setup before
+creating the *SlingBridge* class to start the framework. </td></tr>
+</table>
+
+At the moment these classes, particularly the *SlingServlet* class, are
+not particularly well suited to be extended by a servlet slightly modifying
+the launcher.
Added: sling/site/trunk/content/errorhandling.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/errorhandling.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/errorhandling.mdtext (added)
+++ sling/site/trunk/content/errorhandling.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,93 @@
+Title: Errorhandling
+<a name="Errorhandling-HandlingErrors"></a>
+# Handling Errors
+
+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.
+
+The Sling Servlet Resolver bundle implements this interface by providing an
+elaborate mechanism to find the correct error handling script or servlet
+using the same algorithms as are used to select the scripts or servlets to
+handle regular requests.
+
+This page provides more information on how error handler scripts are
+selected and what is provided out of the box.
+
+
+<a name="Errorhandling-HTTPStatusCodes"></a>
+## HTTP Status Codes
+
+The Sling engine implements the *HttpServletResponse.sendError* methods
+by calling the {{ErrorHandler.handleError(int status, String message,
+SlingHttpServletRequest request, SlingHttpServletResponse response)}}
+method.
+
+The Servlet Resolver bundle implementation looks up a script to handle the
+status code as follows:
+
+ * 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:*
+
+ * 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*.
+
+
+<a name="Errorhandling-UncaughtThrowables"></a>
+## Uncaught Throwables
+
+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:*
+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.
+
+<a name="Errorhandling-DefaultHandler"></a>
+## Default Handler
+
+The Sling Servlet Resolver bundle provides a default error handler servlet
+which is used if the algorithms described above do not resolve to a handler
+script or servlet. The provided error handler servlet does the following:
+
+ * Print a descriptive message, which is the
+*javax.servlet.error.message* request attribute by default
+ * Print a stacktrace if the *javax.servlet.error.exception* is set
+ * Dump the request progress tracker
+
+Starting with Sling Servlet Resolver version 2.0.10 the default error
+handler servlet is looked up using the string *default* as the request
+extension and the provided default servlet is registered as
+*<prefix>/sling/servlet/errorhandler/default.servlet* where <prefix> is
+the last entry in the resource resolver search path, */libs* by default.
+
+Thus to overwrite the default error handler servlet provide a servlet or
+script for the *default* extension, for example
+*/apps/sling/servlet/errorhandler/default.groovy*.
Added: sling/site/trunk/content/eventing-and-jobs.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/eventing-and-jobs.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/eventing-and-jobs.mdtext (added)
+++ sling/site/trunk/content/eventing-and-jobs.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,482 @@
+Title: Eventing and Jobs
+<a name="EventingandJobs-Eventing,JobsandScheduling"></a>
+## Eventing, Jobs and Scheduling
+
+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](how-to-manage-events-in-sling.html)
+* [Scheduler Service (commons scheduler)](scheduler-service-(commons-scheduler).html)
+
+<a name="EventingandJobs-PossibleUseCasesforEventing"></a>
+### Possible Use Cases for Eventing
+* Workflow
+* Post Processing (business processes)
+* Caching
+* Auditing
+
+<a name="EventingandJobs-SourcesofEvents"></a>
+### 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)
+* "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.
+
+<a name="EventingandJobs-WeightsofEvents"></a>
+### Weights of Events
+
+We can distinguish two different weights of events, depending how they are
+distributed in a clustered environment:
+
+ * User generated events - these events are generated directly by some user
+action and are therefore started on one single node.
+ * Environment generated events (JCR events, scheduler events etc.) - these
+events are generated "simultaniously" on all nodes.
+
+External events, like incoming JMS events etc. might fall either into the
+first or the second category. The receiver of such events must have the
+knowledge about the weight of the event.
+
+<a name="EventingandJobs-BasicPrinciples"></a>
+### Basic Principles
+
+The foundation of the 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, however the sender must explicitly declare an event to be
+distributed. There are exceptions to "distributing everything to
+everywhere" as for example framework related events (bundle stopped,
+installed etc.) should not be distributed.
+
+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 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.
+
+The event handling should be made as transparent to the developer as
+possible. Therefore the additional code for a developer to make the
+eventing working in a clustered environment etc. should be kept to a
+minimum (which will hopefully reduce possible user errors).
+
+<a name="EventingandJobs-EventMechanism"></a>
+## Event Mechanism
+
+The event mechanism is leveraging the OSGi Event Admin Specification (OSGi
+Compendium 113). The event admin specification provides a sufficient base.
+It is based on the event publish and subscribe mechanism. Each event is
+associated with a topic and data. The data consists of custom key-value
+pairs where the keys are strings and the values can be any object. However,
+to work in distributed environments it is advisable to use only string and
+scalar types for data. If complex objects are required they have to be
+serializable.
+
+Events can either be send synchronously or asynchronously. It is up to the
+caller (the one sending the event) to decide this by choosing one of the
+provided methods.
+
+The OSGi API is very simple and leightweight - sending an event is just
+generating the event object and calling the event admin. Rceiving the event
+is implementing a single interface and declaring through properties which
+topics one is interested in. It's possible to add an additional filter
+(based on property values for example).
+
+%N The event handler should not take too much time to process the event.
+For example, the Apache Felix implementation of the event admin black lists
+an event handler if it takes more than 5 seconds to process the event -
+regardless if the event is sent synchronously or asynchronously. Therefore
+any heavier processing has to be done in the background. The event is just
+the trigger to start this. The job mechanism explained in this
+documentation is a good way of implementing this functionality for an event
+handler.
+
+The aim is to add all functionality on top of an existing event admin
+implementation. Therefore everything should be added by additional event
+handlers.
+
+<a name="EventingandJobs-EventHandler"></a>
+## Event Handler
+
+An event handler registers itself on a (set of) topic. It can also specify
+a filter for the events. This event handler is either notified
+synchronously or asynchronously depending on how the event has been sent.
+
+<a name="EventingandJobs-Events"></a>
+## Events
+
+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.
+
+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.
+
+<a name="EventingandJobs-EventDistributionAcrossApplicationNodes(Cluster)"></a>
+## 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.
+
+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.
+
+<a name="EventingandJobs-StoringEventsintheRepository"></a>
+### 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:
+<table>
+<tr><td> *Property Name* </td><td> *Description* </td></tr>
+<tr><td> =event:topic= </td><td> The topic of the event </td></tr>
+<tr><td> =event:application= </td><td> The identifier of the application node where the
+event was created </td></tr>
+<tr><td> =event:created= </td><td> The date and time when the event has been created
+(stored in the repository)
+</tr>
+<tr><td> =event:properties= </td><td> Serialized properties (except the
+=event.distribute=, but including the =event.application=) </td></tr>
+</table>
+
+Each application is periodically removing old events from the repository
+(using the scheduler).
+
+<a name="EventingandJobs-Jobs(GuaranteeofProcessing)"></a>
+## Jobs (Guarantee of Processing)
+
+In general, the eventing mechanism has no knowledge about the contents of
+an event. Therefore, it can't decide if an event must be processed by a
+node. 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
+processed the event.
+
+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.
+
+The event must have the following properties:
+<table>
+<tr><td> *Property Name* </td><td> *Description* </td></tr>
+<tr><td> =event.job.topic= </td><td> The topic of the job </td></tr>
+<tr><td> =event.job.id= </td><td> A unique identifier for this job (optional) </td></tr>
+</table>
+
+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.
+
+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.
+
+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.
+
+<a name="EventingandJobs-StoringJobsintheRepository"></a>
+### 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.
+
+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:
+<table>
+<tr><td> *Property Name* </td><td> *Description* </td></tr>
+<tr><td> =event:topic= </td><td> The topic of the job </td></tr>
+<tr><td> =event:application= </td><td> The identifier of the node where the job was
+created </td></tr>
+<tr><td> =event:processor= </td><td> The identifier of the node which processed the job
+</td></tr>
+<tr><td> =event:active= </td><td> Indicates if this job is active and should be
+processed(unlocked) or is currently processed (locked) </td></tr>
+<tr><td> =event:created= </td><td> The date and time when the event has been created
+(stored in the repository)
+</tr>
+<tr><td> =event:id= </td><td> The unique identifier of this job (optional).
+</tr>
+<tr><td> =event:properties= </td><td> Serialized properties </td></tr>
+<tr><td> =event:finished= </td><td> The date and time when the job has been finished </td></tr>
+</table>
+
+
+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).
+
+<a name="EventingandJobs-DistributionofJobs"></a>
+### 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.
+
+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.
+
+<a name="EventingandJobs-UsagePatterns"></a>
+## Usage Patterns
+
+Based on some usage patterns, we discuss the functionality of the eventing
+mechanism.
+
+<a name="EventingandJobs-SendingUserGeneratedEvents"></a>
+### 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 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 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=.
+
+<a name="EventingandJobs-ProcessingJCREvents"></a>
+### 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 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 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.
+
+<a name="EventingandJobs-SendingScheduledEvents"></a>
+### Sending Scheduled Events
+
+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).
+
+In most use cases a scheduler will send job events to ensure that exactly
+one application node is processing the event.
+
+<a name="EventingandJobs-ReceivingOSGiEvents"></a>
+### Receiving OSGi Events
+
+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.
+
+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.
+
+<a name="EventingandJobs-Scheduler"></a>
+## Scheduler
+
+Each Sling based application will contain a scheduler service (which is
+based on the Quartz open source project).
+
+<a name="EventingandJobs-UseCases"></a>
+## Use Cases
+
+<a name="EventingandJobs-PostProcessing(BusinessProcesses)"></a>
+### Post Processing (Business Processes)
+
+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).
+
+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.
+
+<a name="EventingandJobs-Scheduling"></a>
+## 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.