incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r813967 [6/16] - /websites/staging/sling/trunk/content/
Date Sun, 22 Apr 2012 16:52:31 GMT
Added: websites/staging/sling/trunk/content/eventing-and-jobs.html
==============================================================================
--- websites/staging/sling/trunk/content/eventing-and-jobs.html (added)
+++ websites/staging/sling/trunk/content/eventing-and-jobs.html Sun Apr 22 16:52:28 2012
@@ -0,0 +1,497 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+  <head>
+    <title>Apache Sling - Eventing and Jobs</title>
+    <link rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+    <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </head>
+  <body>
+    <div class="title">
+      <div class="logo">
+        <a href="http://sling.apache.org/site/index.html">
+          <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+        </a>
+      </div>
+      <div class="header">
+        <a href="http://www.apache.org/">
+          <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+        </a>
+      </div>
+    </div>
+    
+    <div class="menu"> 
+      <h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="getting-started.html">Getting Started</a></li>
+<li><a href="the-sling-engine.html">The Sling Engine</a></li>
+<li><a href="development.html">Development</a></li>
+<li><a href="bundles.html">Bundles</a></li>
+<li><a href="tutorials-&amp;-how-tos.html">Tutorials &amp; How-Tos</a></li>
+<li><a href="configuration.html">Configuration</a></li>
+<li><a href="http://sling.apache.org/apidocs/sling5/index.html">API docs</a></li>
+<li><a href="http://s.apache.org/sling.wiki">Wiki</a></li>
+<li><a href="http://s.apache.org/sling.faq">FAQ</a></li>
+</ul>
+<h1 id="project-info">Project info</h1>
+<ul>
+<li><a href="http://sling.apache.org/site/downloads.cgi">Downloads</a></li>
+<li><a href="http://www.apache.org/licenses/">License</a></li>
+<li><a href="contributing.html">Contributing</a></li>
+<li><a href="news.html">News</a></li>
+<li><a href="links.html">Links</a></li>
+<li><a href="project-information.html">Project Information</a></li>
+<li><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a></li>
+<li><a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+<h1 id="sponsorship">Sponsorship</h1>
+<ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a></li>
+</ul>
+<iframe 
+    src="http://www.apache.org/ads/button.html"
+    style="border-width:0; float: left" frameborder="0" 
+    scrolling="no"
+    width="135" 
+    height="135">
+</iframe>
+    </div>
+    
+    <div class="main">
+      <div class="breadcrump" style="font-size: 80%;">
+		(TODO: breadcrumb here)
+      </div>
+      <h1 class="title">Eventing and Jobs</h1>
+      <div>
+	    <p><a name="EventingandJobs-Eventing,JobsandScheduling"></a></p>
+<h2 id="eventing-jobs-and-scheduling">Eventing, Jobs and Scheduling</h2>
+<p>Apache Sling provides some mechanisms and support for eventing, handling
+jobs and scheduling. </p>
+<p>To get some hands on code, you can refer to the following tutorials:
+<em> <a href="how-to-manage-events-in-sling.html">How to Manage Events in Sling</a>
+</em> <a href="scheduler-service-(commons-scheduler).html">Scheduler Service (commons scheduler)</a></p>
+<p><a name="EventingandJobs-PossibleUseCasesforEventing"></a></p>
+<h3 id="possible-use-cases-for-eventing">Possible Use Cases for Eventing</h3>
+<ul>
+<li>Workflow</li>
+<li>Post Processing (business processes)</li>
+<li>Caching</li>
+<li>Auditing</li>
+</ul>
+<p><a name="EventingandJobs-SourcesofEvents"></a></p>
+<h3 id="sources-of-events">Sources of Events</h3>
+<p>There is a variety of sources from which events can be send:
+<em> JCR observation events
+</em> Application generated events
+<em> Events from messaging systems (~JMS)
+</em> "External events"</p>
+<p>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.</p>
+<p><a name="EventingandJobs-WeightsofEvents"></a></p>
+<h3 id="weights-of-events">Weights of Events</h3>
+<p>We can distinguish two different weights of events, depending how they are
+distributed in a clustered environment:</p>
+<ul>
+<li>User generated events - these events are generated directly by some user
+action and are therefore started on one single node.</li>
+<li>Environment generated events (JCR events, scheduler events etc.) - these
+events are generated "simultaniously" on all nodes.</li>
+</ul>
+<p>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.</p>
+<p><a name="EventingandJobs-BasicPrinciples"></a></p>
+<h3 id="basic-principles">Basic Principles</h3>
+<p>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.</p>
+<p>The event mechanism will provide additional functionality making it easier
+for event receivers to decide if they should process an event. The event
+receiver can determine if the event is a local event or comming from a
+remote application node. Therefore a general rule of thumb is to process
+events only if they're local and just regard remote events as a FYI.</p>
+<p>The event mechanism is an <em>event</em> mechanism which should not be confused
+with a <em>messaging</em> 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.</p>
+<p>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.</p>
+<p>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).</p>
+<p><a name="EventingandJobs-EventMechanism"></a></p>
+<h2 id="event-mechanism">Event Mechanism</h2>
+<p>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.</p>
+<p>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.</p>
+<p>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).</p>
+<p>%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.</p>
+<p>The aim is to add all functionality on top of an existing event admin
+implementation. Therefore everything should be added by additional event
+handlers.</p>
+<p><a name="EventingandJobs-EventHandler"></a></p>
+<h2 id="event-handler">Event Handler</h2>
+<p>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.</p>
+<p><a name="EventingandJobs-Events"></a></p>
+<h2 id="events">Events</h2>
+<p>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:</p>
+<ul>
+<li>=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.</li>
+<li>=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.</li>
+</ul>
+<p>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 <em>never</em> 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.</p>
+<p><a name="EventingandJobs-EventDistributionAcrossApplicationNodes(Cluster)"></a></p>
+<h2 id="event-distribution-across-application-nodes-cluster">Event Distribution Across Application Nodes (Cluster)</h2>
+<p>The (local) event admin is the service distributing events locally. The
+Sling Distributing Event Handler is a registered event handler that is
+listening for events to be distributed. It distributes the events to remote
+application notes, 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.</p>
+<p>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.</p>
+<p>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.</p>
+<p>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.</p>
+<p><a name="EventingandJobs-StoringEventsintheRepository"></a></p>
+<h3 id="storing-events-in-the-repository">Storing Events in the Repository</h3>
+<p>Distributable events are stored in the repository, the repository will have
+a specific area (path) where all events are stored. </p>
+<p>Each event is stored as a separate node with the following properties:
+<table>
+<tr><td> <em>Property Name</em>     </td><td> <em>Description</em> </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></p>
+<p>Each application is periodically removing old events from the repository
+(using the scheduler).</p>
+<p><a name="EventingandJobs-Jobs(GuaranteeofProcessing)"></a></p>
+<h2 id="jobs-guarantee-of-processing">Jobs (Guarantee of Processing)</h2>
+<p>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.</p>
+<p>On the other hand, there are use cases where the guarantee of processing is
+a must and usually this comes with the requirement of processing this event
+exactly once. Typical examples are sending notification emails (or sms) or
+post processing of content (like thumbnail generation of images or
+documents).</p>
+<p>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.</p>
+<p>The event must have the following properties:
+<table>
+<tr><td> <em>Property Name</em>   </td><td> <em>Description</em> </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></p>
+<p>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.</p>
+<p>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.</p>
+<p>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)=.</p>
+<p>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.</p>
+<p>The job id is optional and can be used to update or reactivate jobs.</p>
+<p><a name="EventingandJobs-StoringJobsintheRepository"></a></p>
+<h3 id="storing-jobs-in-the-repository">Storing Jobs in the Repository</h3>
+<p>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 <em>and</em> 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.</p>
+<p>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).</p>
+<p>Each job is stored as a separate node with the following properties:
+<table>
+<tr><td> <em>Property Name</em>     </td><td> <em>Description</em> </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></p>
+<p>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=. </p>
+<p>Each application is periodically removing old jobs from the repository
+(using the scheduler).</p>
+<p><a name="EventingandJobs-DistributionofJobs"></a></p>
+<h3 id="distribution-of-jobs">Distribution of Jobs</h3>
+<p>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.</p>
+<p>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.</p>
+<p><a name="EventingandJobs-UsagePatterns"></a></p>
+<h2 id="usage-patterns">Usage Patterns</h2>
+<p>Based on some usage patterns, we discuss the functionality of the eventing
+mechanism.</p>
+<p><a name="EventingandJobs-SendingUserGeneratedEvents"></a></p>
+<h3 id="sending-user-generated-events">Sending User Generated Events</h3>
+<p>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.</p>
+<p>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.</p>
+<p>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=.</p>
+<p><a name="EventingandJobs-ProcessingJCREvents"></a></p>
+<h3 id="processing-jcr-events">Processing JCR Events</h3>
+<p>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.</p>
+<p>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.</p>
+<p><a name="EventingandJobs-SendingScheduledEvents"></a></p>
+<h3 id="sending-scheduled-events">Sending Scheduled Events</h3>
+<p>Scheduled events are OSGi events that have been created by the environemnt.
+They are generated on each application node of the cluster through an own
+scheduler instance. Sending these events works the same as sending events
+based on JCR events (see above).</p>
+<p>In most use cases a scheduler will send job events to ensure that exactly
+one application node is processing the event.</p>
+<p><a name="EventingandJobs-ReceivingOSGiEvents"></a></p>
+<h3 id="receiving-osgi-events">Receiving OSGi Events</h3>
+<p>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. </p>
+<p>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.</p>
+<p>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.</p>
+<p>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.</p>
+<p><a name="EventingandJobs-Scheduler"></a></p>
+<h2 id="scheduler">Scheduler</h2>
+<p>Each Sling based application will contain a scheduler service (which is
+based on the Quartz open source project).</p>
+<p><a name="EventingandJobs-UseCases"></a></p>
+<h2 id="use-cases">Use Cases</h2>
+<p><a name="EventingandJobs-PostProcessing(BusinessProcesses)"></a></p>
+<h3 id="post-processing-business-processes">Post Processing (Business Processes)</h3>
+<p>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.</p>
+<p>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).</p>
+<p>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.</p>
+<p><a name="EventingandJobs-Scheduling"></a></p>
+<h2 id="scheduling">Scheduling</h2>
+<p>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 <em>if</em> 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.</p>
+      </div>
+    </div>
+    
+    <div class="trademarkFooter"> 
+		Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+	</div>
+  </body>
+</html>

Added: websites/staging/sling/trunk/content/filters.html
==============================================================================
--- websites/staging/sling/trunk/content/filters.html (added)
+++ websites/staging/sling/trunk/content/filters.html Sun Apr 22 16:52:28 2012
@@ -0,0 +1,310 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+  <head>
+    <title>Apache Sling - Filters</title>
+    <link rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+    <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </head>
+  <body>
+    <div class="title">
+      <div class="logo">
+        <a href="http://sling.apache.org/site/index.html">
+          <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+        </a>
+      </div>
+      <div class="header">
+        <a href="http://www.apache.org/">
+          <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+        </a>
+      </div>
+    </div>
+    
+    <div class="menu"> 
+      <h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="getting-started.html">Getting Started</a></li>
+<li><a href="the-sling-engine.html">The Sling Engine</a></li>
+<li><a href="development.html">Development</a></li>
+<li><a href="bundles.html">Bundles</a></li>
+<li><a href="tutorials-&amp;-how-tos.html">Tutorials &amp; How-Tos</a></li>
+<li><a href="configuration.html">Configuration</a></li>
+<li><a href="http://sling.apache.org/apidocs/sling5/index.html">API docs</a></li>
+<li><a href="http://s.apache.org/sling.wiki">Wiki</a></li>
+<li><a href="http://s.apache.org/sling.faq">FAQ</a></li>
+</ul>
+<h1 id="project-info">Project info</h1>
+<ul>
+<li><a href="http://sling.apache.org/site/downloads.cgi">Downloads</a></li>
+<li><a href="http://www.apache.org/licenses/">License</a></li>
+<li><a href="contributing.html">Contributing</a></li>
+<li><a href="news.html">News</a></li>
+<li><a href="links.html">Links</a></li>
+<li><a href="project-information.html">Project Information</a></li>
+<li><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a></li>
+<li><a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+<h1 id="sponsorship">Sponsorship</h1>
+<ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a></li>
+</ul>
+<iframe 
+    src="http://www.apache.org/ads/button.html"
+    style="border-width:0; float: left" frameborder="0" 
+    scrolling="no"
+    width="135" 
+    height="135">
+</iframe>
+    </div>
+    
+    <div class="main">
+      <div class="breadcrump" style="font-size: 80%;">
+		(TODO: breadcrumb here)
+      </div>
+      <h1 class="title">Filters</h1>
+      <div>
+	    <p><a name="Filters-ServletFilterSupport"></a></p>
+<h1 id="servlet-filter-support">Servlet Filter Support</h1>
+<p>Sling supports filter processing by applying filter chains to the requests
+before actually dispatching to the servlet or script for processing.
+Filters to be used in such filter processing are plain OSGi services of
+type <em>javax.servlet.Filter</em> which of course means that the services
+implement this interface.</p>
+<p>{note}</p>
+<p>See <a href="https://issues.apache.org/jira/browse/SLING-1213">SLING-1213</a>
+, [SLING-1734|https://issues.apache.org/jira/browse/SLING-1734]
+, and [Registering filters with Sling|http://markmail.org/message/quxhm7d5s6u66crr]
+ for more details.
+{note}</p>
+<p>For Sling to pick up a <em>javax.servlet.Filter</em> service for filter
+processing two service registration properties are inspected:</p>
+<table>
+<tr><th> Property </th><th> Type </th><th> Default Value </th><th> Valid Values </th><th> Description </th></tr>
+<tr><td> *sling.filter.scope* </td><td> *String*, {{String[](.html)
+}} or *Vector<String>* </td><td> *request* </td><td> *REQUEST*, *INCLUDE*,
+*FORWARD*, *ERROR*, *COMPONENT* </td><td> Indication of which chain the
+filter should be added to. This property is required. If it is missing from
+the service, the service is ignored because it is assumed another consumer
+will be interested in using the service. Any unknown values of this
+property are also ignored causing the service to be completely ignored if
+none of the values provided by the property are valid. See below for the
+description of the filter chains. </td></tr>
+<tr><td> *service.ranking* </td><td> *Integer* </td><td> *0* </td><td> Any *Integer* value </td><td>
+Indication of where to place the filter in the filter chain. The higher the
+number the earlier in the filter chain. This value may span the whole range
+of integer values. Two filters with equal *service.ranking* property
+value (explicitly set or default value of zero) will be ordered according
+to their *service.id* service property as described in section 5.2.5,
+Service Properties, of the OSGi Core Specification R 4.2. </td></tr>
+</table>
+
+<p><a name="Filters-FilterChains"></a></p>
+<h2 id="filter-chains">Filter Chains</h2>
+<p>Sling maintains five filter chains: request level, component level, include
+filters, forward filters and error filters. Except for the component level
+filter these filter chains correspond to the filter <em><dispatcher></em>
+configurations as defined for Servlet API 2.5 web applications (see section
+SRV.6.2.5 Filters and the RequestDispatcher).</p>
+<p>The following table summarizes when each of the filter chains is called and
+what value must be defined in the <em>sling.filter.scope</em> property to have a
+filter added to the respective chain:</p>
+<table>
+<tr><th> *sling.filter.scope* </th><th> Servlet API Correspondence </th><th> Description </th></tr>
+<tr><td> *REQUEST* </td><td> *REQUEST* </td><td> Filters are called once per request hitting
+Sling from the outside. These filters are called after the resource
+addressed by the request URL and the Servlet or script to process the
+request has been resolved before the *COMPONENT* filters (if any) and the
+Servlet or script are called. </td></tr>
+<tr><td> *INCLUDE* </td><td> *INCLUDE* </td><td> Filters are called upon calling the
+*RequestDispatcher.include* method after the included resource and the
+Servlet or script to process the include have been resolved before the
+Servlet or script is called. </td></tr>
+<tr><td> *FORWARD* </td><td> *FORWARD* </td><td> Filters are called upon calling the
+*RequestDispatcher.forward* method after the included resource and the
+Servlet or script to process the include have been resolved before the
+Servlet or script is called. </td></tr>
+<tr><td> *ERROR* </td><td> *ERROR* </td><td> Filters are called upon
+*HttpServletResponse.sendError* or any uncaught *Throwable* before
+resolving the error handler Servlet or script. </td></tr>
+<tr><td> *COMPONENT* </td><td> *REQUEST,INCLUDE,FORWARD* </td><td> The *COMPONENT* scoped
+filters are present for backwards compatibility with earlier Sling Engine
+releases. These filters will be called among the *INCLUDE* and
+*FORWARD* filters upon *RequestDispatcher.include* or
+*RequestDispatcher.forward* as well as before calling the request level
+Servlet or script after the *REQUEST* filters. </td></tr>
+</table>
+
+<p>Note on <em>INCLUDE</em> and <em>FORWARD</em> with respect to JSP tags: These filters
+are also called if the respective including (e.g. <em><jsp:include></em> or
+<em><sling:include></em>) or forwarding (e.g. <em><jsp:forward></em> or
+<em><sling:forward></em>) ultimately calls the <em>RequestDispatcher</em>.</p>
+<p><a name="Filters-FilterProcessing"></a></p>
+<h2 id="filter-processing">Filter Processing</h2>
+<p>Filter processing is part of the Sling request processing, which may be
+sketched as follows:</p>
+<table>
+<tr><td> _Request Level_ </td></tr>
+<tr><td> Authentication </td></tr>
+<tr><td> Resource Resolution </td></tr>
+<tr><td> Servlet/Script Resolution </td></tr>
+<tr><td> Request Level Filter Processing </td></tr>
+<tr><td> _Component Level_ </td></tr>
+</table>
+
+<p>The first step of request processing is the <em>Request Level</em> processing
+which is concerned with resolving the resource, finding the appropriate
+servlet and calling into the request level filter chain. The next step is
+the <em>Component Level</em> processing, calling into the component level filters
+before finally calling the servlet or script:</p>
+<table>
+<tr><td> _Component Level_ </td></tr>
+<tr><td> Component Level Filter Processing </td></tr>
+<tr><td> Call Servlet or Script </td></tr>
+</table>
+
+<p>When a servlet or script is including or forwarding to another resource for
+processing through the <em>RequestDispatcher</em> (or any JSP tag or other
+language feature ultimately using a <em>RequestDispatcher</em>) the following
+<em>Dispatch</em> processing takes place:</p>
+<table>
+<tr><td> _Dispatch_ </td></tr>
+<tr><td> Resolve the resource to dispatch to if not already defined when getting
+the *RequestDispatcher* </td></tr>
+<tr><td> Servlet/Script resolution </td></tr>
+<tr><td> Call include or forward filters depending on the kind of dispatch </td></tr>
+<tr><td> Call Servlet or Script </td></tr>
+</table>
+
+<p>As a consequence, request level filters will be called at most once during
+request processing (they may not be called at all if a filter earlier in
+the filter chain decides to terminate the request) while the component
+level, include, and forward filters may be called multiple times while
+processing a request.</p>
+<p><a name="Filters-Troubleshooting"></a></p>
+<h2 id="troubleshooting">Troubleshooting</h2>
+<p>Apart form the logs which tell you when filters are executed, two Sling
+plugins provide information about filters in the OSGi console.</p>
+<p><a name="Filters-RecentRequestsplugin"></a></p>
+<h3 id="recent-requests-plugin">Recent Requests plugin</h3>
+<p>The request traces provided at <em>/system/console/requests</em> contain
+information about filter execution, as in this example:</p>
+<p><DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Recent Requests plugin info</B></DIV><DIV class="codeContent panelContent">
+    0 (2010-09-08 15:22:38) TIMER_START{Request Processing}
+    ...
+    0 (2010-09-08 15:22:38) LOG Method=GET,
+PathInfo=/libs/wcm/core/content/siteadmin.html
+    3 (2010-09-08 15:22:38) LOG Applying request filters
+    3 (2010-09-08 15:22:38) LOG Calling filter:
+org.apache.sling.bgservlets.impl.BackgroundServletStarterFilter
+    3 (2010-09-08 15:22:38) LOG Calling filter:
+org.apache.sling.portal.container.internal.request.PortalFilter
+    3 (2010-09-08 15:22:38) LOG Calling filter:
+org.apache.sling.rewriter.impl.RewriterFilter
+    3 (2010-09-08 15:22:38) LOG Calling filter:
+com.day.cq.wcm.core.impl.WCMRequestFilter
+    3 (2010-09-08 15:22:38) LOG Calling filter:
+org.apache.sling.i18n.impl.I18NFilter
+    3 (2010-09-08 15:22:38) LOG Calling filter:
+com.day.cq.theme.impl.ThemeResolverFilter
+    3 (2010-09-08 15:22:38) LOG Calling filter:
+com.day.cq.wcm.foundation.forms.impl.FormsHandlingServlet
+    3 (2010-09-08 15:22:38) LOG Calling filter:
+org.apache.sling.engine.impl.debug.RequestProgressTrackerLogFilter
+    3 (2010-09-08 15:22:38) LOG Calling filter:
+com.day.cq.wcm.mobile.core.impl.redirect.RedirectFilter
+    3 (2010-09-08 15:22:38) LOG RedirectFilter did not redirect
+(MobileUtil.isMobileResource() returns false)
+    3 (2010-09-08 15:22:38) LOG Applying inner filters
+    3 (2010-09-08 15:22:38) LOG Calling filter:
+com.day.cq.wcm.core.impl.WCMComponentFilter
+    3 (2010-09-08 15:22:38) LOG Calling filter:
+com.day.cq.wcm.core.impl.WCMDebugFilter
+    3 (2010-09-08 15:22:38)
+TIMER_START{/libs/cq/ui/components/widget/html.jsp#0}
+    ...
+    8 (2010-09-08 15:22:38) TIMER_END{8,Request Processing} Request Processing</p>
+<p><a name="Filters-ConfigStatusplugin"></a></p>
+<h3 id="config-status-plugin">Config Status plugin</h3>
+<p>The configuration status page at <em>/system/console/config</em> includes the
+current list of active filters in its <em>Servlet Filters</em> category, as in
+this example:</p>
+<p><DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Config Status plugin info</B></DIV><DIV class="codeContent panelContent">
+    Current Apache Sling Servlet Filter Configuration</p>
+<div class="codehilite"><pre><span class="n">Request</span> <span class="n">Filters:</span>
+<span class="o">-</span><span class="mi">2147483648</span> <span class="p">:</span> <span class="n">class</span>
+</pre></div>
+
+
+<p>org.apache.sling.bgservlets.impl.BackgroundServletStarterFilter (2547)
+    -3000 : class
+org.apache.sling.portal.container.internal.request.PortalFilter (2562)
+    -2500 : class org.apache.sling.rewriter.impl.RewriterFilter (3365)
+    -2000 : class com.day.cq.wcm.core.impl.WCMRequestFilter (2548)
+    -700 : class org.apache.sling.i18n.impl.I18NFilter (2334)
+    -600 : class com.day.cq.theme.impl.ThemeResolverFilter (2244)
+    -600 : class com.day.cq.wcm.foundation.forms.impl.FormsHandlingServlet
+(2268)
+    0 : class
+org.apache.sling.engine.impl.debug.RequestProgressTrackerLogFilter (2402)
+    1000 : class com.day.cq.wcm.mobile.core.impl.redirect.RedirectFilter (3363)</p>
+<div class="codehilite"><pre><span class="n">Error</span> <span class="n">Filters:</span>
+<span class="o">---</span>
+
+<span class="n">Include</span> <span class="n">Filters:</span>
+<span class="o">-</span><span class="mi">200</span> <span class="p">:</span> <span class="n">class</span> <span class="n">com</span><span class="o">.</span><span class="n">day</span><span class="o">.</span><span class="n">cq</span><span class="o">.</span><span class="n">wcm</span><span class="o">.</span><span class="n">core</span><span class="o">.</span><span class="n">impl</span><span class="o">.</span><span class="n">WCMComponentFilter</span> <span class="p">(</span><span class="mi">2583</span><span class="p">)</span>
+<span class="mi">1000</span> <span class="p">:</span> <span class="n">class</span> <span class="n">com</span><span class="o">.</span><span class="n">day</span><span class="o">.</span><span class="n">cq</span><span class="o">.</span><span class="n">wcm</span><span class="o">.</span><span class="n">core</span><span class="o">.</span><span class="n">impl</span><span class="o">.</span><span class="n">WCMDebugFilter</span> <span class="p">(</span><span class="mi">2449</span><span class="p">)</span>
+
+<span class="n">Forward</span> <span class="n">Filters:</span>
+<span class="o">-</span><span class="mi">200</span> <span class="p">:</span> <span class="n">class</span> <span class="n">com</span><span class="o">.</span><span class="n">day</span><span class="o">.</span><span class="n">cq</span><span class="o">.</span><span class="n">wcm</span><span class="o">.</span><span class="n">core</span><span class="o">.</span><span class="n">impl</span><span class="o">.</span><span class="n">WCMComponentFilter</span> <span class="p">(</span><span class="mi">2583</span><span class="p">)</span>
+<span class="mi">1000</span> <span class="p">:</span> <span class="n">class</span> <span class="n">com</span><span class="o">.</span><span class="n">day</span><span class="o">.</span><span class="n">cq</span><span class="o">.</span><span class="n">wcm</span><span class="o">.</span><span class="n">core</span><span class="o">.</span><span class="n">impl</span><span class="o">.</span><span class="n">WCMDebugFilter</span> <span class="p">(</span><span class="mi">2449</span><span class="p">)</span>
+
+<span class="n">Component</span> <span class="n">Filters:</span>
+<span class="o">-</span><span class="mi">200</span> <span class="p">:</span> <span class="n">class</span> <span class="n">com</span><span class="o">.</span><span class="n">day</span><span class="o">.</span><span class="n">cq</span><span class="o">.</span><span class="n">wcm</span><span class="o">.</span><span class="n">core</span><span class="o">.</span><span class="n">impl</span><span class="o">.</span><span class="n">WCMComponentFilter</span> <span class="p">(</span><span class="mi">2583</span><span class="p">)</span>
+<span class="mi">1000</span> <span class="p">:</span> <span class="n">class</span> <span class="n">com</span><span class="o">.</span><span class="n">day</span><span class="o">.</span><span class="n">cq</span><span class="o">.</span><span class="n">wcm</span><span class="o">.</span><span class="n">core</span><span class="o">.</span><span class="n">impl</span><span class="o">.</span><span class="n">WCMDebugFilter</span> <span class="p">(</span><span class="mi">2449</span><span class="p">)</span>
+</pre></div>
+
+
+<p>The first numbers on those lines are the filter priorities, and the last
+number in parentheses is the OSGi service ID.</p>
+<p><a name="Filters-SupportinSlingEngine2.1.0"></a></p>
+<h2 id="support-in-sling-engine-210">Support in Sling Engine 2.1.0</h2>
+<p>Up to and including Sling Engine 2.1.0 support for Servlet Filters has been
+as follows:</p>
+<ul>
+<li>Any <em>javax.servlet.Filter</em> service is accepted as a filter for Sling
+unless the <em>pattern</em> property used by the <a href="http://felix.apache.org/site/apache-felix-http-service.html#ApacheFelixHTTPService-UsingtheWhiteboard">Apache Felix HttpService whiteboard support</a>
+ is set in the service registration properties.</li>
+<li>The <em>filter.scope</em> property is optional and supports the case-sensitive
+values <em>request</em> and <em>component</em>.</li>
+<li>Filter ordering is defined by the <em>filter.order</em> property whose default
+value is <em>Integer.MAX_VALUE</em> where smaller values have higher priority
+over higher values.</li>
+</ul>
+      </div>
+    </div>
+    
+    <div class="trademarkFooter"> 
+		Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+	</div>
+  </body>
+</html>

Added: websites/staging/sling/trunk/content/form-based-authenticationhandler.html
==============================================================================
--- websites/staging/sling/trunk/content/form-based-authenticationhandler.html (added)
+++ websites/staging/sling/trunk/content/form-based-authenticationhandler.html Sun Apr 22 16:52:28 2012
@@ -0,0 +1,283 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+  <head>
+    <title>Apache Sling - Form Based AuthenticationHandler</title>
+    <link rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+    <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </head>
+  <body>
+    <div class="title">
+      <div class="logo">
+        <a href="http://sling.apache.org/site/index.html">
+          <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+        </a>
+      </div>
+      <div class="header">
+        <a href="http://www.apache.org/">
+          <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+        </a>
+      </div>
+    </div>
+    
+    <div class="menu"> 
+      <h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="getting-started.html">Getting Started</a></li>
+<li><a href="the-sling-engine.html">The Sling Engine</a></li>
+<li><a href="development.html">Development</a></li>
+<li><a href="bundles.html">Bundles</a></li>
+<li><a href="tutorials-&amp;-how-tos.html">Tutorials &amp; How-Tos</a></li>
+<li><a href="configuration.html">Configuration</a></li>
+<li><a href="http://sling.apache.org/apidocs/sling5/index.html">API docs</a></li>
+<li><a href="http://s.apache.org/sling.wiki">Wiki</a></li>
+<li><a href="http://s.apache.org/sling.faq">FAQ</a></li>
+</ul>
+<h1 id="project-info">Project info</h1>
+<ul>
+<li><a href="http://sling.apache.org/site/downloads.cgi">Downloads</a></li>
+<li><a href="http://www.apache.org/licenses/">License</a></li>
+<li><a href="contributing.html">Contributing</a></li>
+<li><a href="news.html">News</a></li>
+<li><a href="links.html">Links</a></li>
+<li><a href="project-information.html">Project Information</a></li>
+<li><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a></li>
+<li><a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+<h1 id="sponsorship">Sponsorship</h1>
+<ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a></li>
+</ul>
+<iframe 
+    src="http://www.apache.org/ads/button.html"
+    style="border-width:0; float: left" frameborder="0" 
+    scrolling="no"
+    width="135" 
+    height="135">
+</iframe>
+    </div>
+    
+    <div class="main">
+      <div class="breadcrump" style="font-size: 80%;">
+		(TODO: breadcrumb here)
+      </div>
+      <h1 class="title">Form Based AuthenticationHandler</h1>
+      <div>
+	    <p><a name="FormBasedAuthenticationHandler-FormBasedAuthenticationHandler"></a></p>
+<h1 id="form-based-authenticationhandler">Form Based AuthenticationHandler</h1>
+<p>{toc:type=flat|separator=pipe|minLevel=2|maxLevel=3}</p>
+<p>The Form Based AuthenticationHandler has two authentication phases: The
+first phase is presenting a login form to the user and passing the entered
+user name and password to the server. The second phase is storing
+successful authentication in a Cookie or an HTTP Session.</p>
+<p>The implementation of the Form Based Authentication Handler follows the
+guidelines of the Servlet API 2.4 specification for <em>Form Based
+Authentication</em> in section SRV.12.5.3. Specifically the following
+requirements are implemented:</p>
+<ul>
+<li>For the initial form submission, the request URL must end with
+<em>/j_security_check</em> and the user name and password names must be
+<em>j_username</em> and <em>j_password</em>, resp.</li>
+<li>The authentication type as returned by
+<em>HttpServletRequest.getAuthType()</em> is set to
+<em>HttpServletRequest.FORM_AUTH</em>.</li>
+</ul>
+<p>The Form Based Authentication Handler is maintained in the <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/form">Sling SVN</a></p>
+<p><a name="FormBasedAuthenticationHandler-AuthenticationHandlerimplementation"></a></p>
+<h3 id="authenticationhandler-implementation">AuthenticationHandler implementation</h3>
+<ul>
+<li><em>extractCredentials</em> -- Prepares credentials for the form entered data
+or from the Cookie or HTTP Session attribute. Returns <em>null</em> if neither
+data is provided in the request</li>
+<li><em>requestCredentials</em> -- Redirects the client (browser) to the login
+form</li>
+<li><em>dropCredentials</em> -- Remove the Cookie or remove the HTTP Session
+attribute</li>
+</ul>
+<p><a name="FormBasedAuthenticationHandler-AuthenticationFeedbackHandlerimplementation"></a></p>
+<h3 id="authenticationfeedbackhandler-implementation">AuthenticationFeedbackHandler implementation</h3>
+<ul>
+<li><em>authenticationFailed</em> -- Remove the Cookie or remove the HTTP Session
+attribute</li>
+<li><em>authenticationSucceeded</em> -- Set (or update) the Cookie or HTTP Session
+attribute</li>
+</ul>
+<p><a name="FormBasedAuthenticationHandler-Phase1:FormSubmission"></a></p>
+<h3 id="phase-1-form-submission">Phase 1: Form Submission</h3>
+<p>The login form submitted in phase 1 to validate the user name and password
+must be provided in an HTTP <em>POST</em> request to an URL whose last segment
+is <em>j_security_check</em>. The request is ignored as a form submission if
+either the method is not <em>POST</em> or the last segment is no
+<em>j_security_check</em>.</p>
+<p>The form is rendered by redirecting the client to the URL indicated by the
+<em>form.login.form</em> configuration parameter. This redirection request may
+accompanyied by the following parameters:</p>
+<ul>
+<li><em>resource</em> -- The resource to which the user should be redirected after
+successful login. This request parameter should be submitted back to the
+server as the <em>resource</em> parameter.</li>
+<li><em>j_reason</em> -- This parameter indicates the reason for rendering the
+login form. If this parameter is set, it is set to <em>INVALID_CREDENTIALS</em>
+indicating a previous form submission presented invalid username and
+password or <em>TIMEOUT</em> indicating a login session has timed out. The login
+form servlet/script can present the user with an appropriate message.</li>
+</ul>
+<p>The Form Based Authentication Handlers supports the following request
+parameters submitted by the HTML form:</p>
+<ul>
+<li><em>j_username</em> -- Name of the user to authenticate</li>
+<li><em>j_password</em> -- Password to authenticate the user</li>
+<li><em>j_validate</em> -- Flag indicating whether to just validate the
+credentials</li>
+<li><em>resource</em> -- The location to go to on successful login</li>
+<li><em>sling.auth.redirect</em> -- The location to redirect to on successful
+login</li>
+</ul>
+<p>The <em>j_username</em> and <em>j_password</em> parameters are used to create a JCR
+<em>SimpleCredentials</em> object to log into the JCR Repository.</p>
+<p>The <em>j_validate</em> parameter may be used to implement login form submission
+using AJAX. If this parameter is set to <em>true</em> (case-insensitive) the
+credentials are used to login and after success or failure to return a
+status code:</p>
+<table>
+<tr><th> Status </th><th> Description </th></tr>
+<tr><td> *200 OK* </td><td> Authentication succeeded; credentials are valid for login;
+the Cookie or HTTP Session attribute is now set </td></tr>
+<tr><td> *403 FORBIDDEN* </td><td> Authentication failed; credentials are invalid for
+login; the Cookie or HTTP Session attribute is not set (if it was set, it
+is now cleared) </td></tr>
+</table>
+
+<p>If the <em>j_validate</em> parameter is not set or is set to any value other
+than <em>true</em>, the request processing depends on authentication success or
+failure:</p>
+<table>
+<tr><th> Authentication </th><th> Description </th></tr>
+<tr><td> Success </td><td> Client is redirected to the authenticated resource; the Cookie
+or HTTP Session attribute is now set. </td></tr>
+<tr><td> Failure </td><td> The request is redirected to the login form again; the Cookie
+or HTTP Session attribute is not set (if it was set, it is now cleared) </td></tr>
+</table>
+
+<p>The <em>resource</em> and <em>sling.auth.redirect</em> parameters provide similar
+functionality but with differing historical backgrounds. The <em>resource</em>
+parameter is based on the <em>resource</em> request attribute which is set by
+the login servlet to indicate the original target resource the client
+desired when it was forced to authenticate. The <em>sling.auth.redirect</em>
+parameter can be used by clients (applications like cURL or plain HTML
+forms) to request being redirected after successful login. If both
+parameters are set, the <em>sling.auth.redirect</em> parameter takes precedence.</p>
+<p>The Form Based Authentication Handler contains a <a href="http://http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/form/src/main/java/org/apache/sling/auth/form/impl/AuthenticationFormServlet.java">default form servlet</a>
+ and [HTML form template from|http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/form/src/main/resources/org/apache/sling/auth/form/impl/login.html]
+.</p>
+<p><a name="FormBasedAuthenticationHandler-Phase2:AuthenticatedRequests"></a></p>
+<h3 id="phase-2-authenticated-requests">Phase 2: Authenticated Requests</h3>
+<p>After the successful authentication of the user in phase 1, the
+authentication state is stored in a Cookie or an HTTP Session. The stored
+value is a security token with the following contents:</p>
+<div class="codehilite"><pre><span class="n">HmacSHA1</span><span class="p">(</span><span class="n">securetoken</span><span class="p">,</span>
+</pre></div>
+
+
+<p><securetokennumber><expirytime>@<userID>)@<securetokennumber><expirytime>@<userID></p>
+<p>The <em>securetoken</em> and <em>securetokennumber</em> are related in that an table
+of secure tokens is maintained where the <em>securetoken</em> is an entry in the
+table and the <em>securetokennumber</em> is the index in of the token in the
+table.</p>
+<p>The secure tokens are refreshed periodically causing the authentication
+state stored in the Cookie or the HTTP Session to be updated peridocally.
+This periodic update has two advantages:</p>
+<ul>
+<li>Login sessions time out after some period of inactivity: If a request
+is handled for an authentication state whose expiry time has passed, the
+request is considered unauthenticated.</li>
+<li>If a Cookie would be stolen or an HTTP Session be hijacked, the
+authentication state expires within a reasonable amount of time to try to
+prevent stealing the authentication.</li>
+</ul>
+<p>The authentication state may be transmitted with a Cookie which is
+configured as follows:</p>
+<ul>
+<li><em>Cookie Path</em> -- Set to the servlet context path</li>
+<li><em>Domain</em> -- See below</li>
+<li><em>Age</em> -- Set to -1 to indicate a session Cookie</li>
+<li><em>Secure</em> -- Set to the value returned by the
+<em>ServletRequest.isSecure()</em> method</li>
+</ul>
+<p>If the authentication state is kept in an HTTP Session the setup of the
+session ID cookie is maintained by the servlet container and is outside of
+the control of the Form Based AuthenticationHandler.</p>
+<p><a name="FormBasedAuthenticationHandler-Configuration"></a></p>
+<h3 id="configuration">Configuration</h3>
+<p>The Form Based Authentication Handler is configured with configuration
+provided by the OSGi Configuration Admin Service using the
+<em>org.apache.sling.formauth.FormAuthenticationHandler</em> service PID.</p>
+<table>
+<tr><th> Parameter </th><th> Default </th><th> Description </th></tr>
+<tr><td> *form.login.form* </td><td> */system/sling/form/login* </td><td> The URL (without any
+context path prefix) to redirect the client to to present the login form. </td></tr>
+<tr><td> *form.auth.storage* </td><td> *cookie* </td><td> The type of storage used to provide
+the authentication state. Valid values are *cookie* and *session*. The
+default value also applies if any setting other than the supported values
+is configured. </td></tr>
+<tr><td> *form.auth.name* </td><td> *sling.formauth* </td><td> The name of the Cookie or HTTP
+Session attribute providing the authentication state. </td></tr>
+<tr><td> *form.auth.timeout* </td><td> *30* </td><td>The number of minutes after which a login
+session times out. This value is used as the expiry time set in the
+authentication data. </td></tr>
+<tr><td> *form.credentials.name* </td><td> *sling.formauth* </td><td> The name of the
+*SimpleCredentials* attribute used to provide the authentication data to
+the *LoginModulePlugin*. </td></tr>
+<tr><td> *form.token.file* </td><td> *cookie-tokens.bin* </td><td> The name of the file used
+to persist the security tokens. </td></tr>
+<tr><td> *form.default.cookie.domain* </td><td> </td><td> The domain on which cookies will be
+set, unless overridden in the *AuthenticationInfo* object. </td></tr>
+</table>
+
+<p><em>Note:</em> The <em>form.token.file</em> parameter currently refers to a file stored
+in the file system. If the path is a relative path, the file is either
+stored in the Authentication Handler bundle private data area or -- if not
+possible -- below the location indicated by the <em>sling.home</em> framework
+property or -- if <em>sling.home</em> is not set -- the current working
+directory. In the future this file may be store in the JCR Repository to
+support clustering scenarios.</p>
+<p><a name="FormBasedAuthenticationHandler-SecurityConsiderations"></a></p>
+<h3 id="security-considerations">Security Considerations</h3>
+<p>Form Based Authentication has some limitations in terms of security:</p>
+<ol>
+<li>User name and password are transmitted in plain text in the initial form
+submission.</li>
+<li>The Cookie used to provide the authentication state or the HTTP Session
+ID may be stolen.</li>
+</ol>
+<p>To prevent eavesdroppers from sniffing the credentials or stealing the
+Cookie a secure transport layer should be used such as TLS/SSL, VPN or
+IPSec.</p>
+      </div>
+    </div>
+    
+    <div class="trademarkFooter"> 
+		Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+	</div>
+  </body>
+</html>

Added: websites/staging/sling/trunk/content/getting-and-building-sling.html
==============================================================================
--- websites/staging/sling/trunk/content/getting-and-building-sling.html (added)
+++ websites/staging/sling/trunk/content/getting-and-building-sling.html Sun Apr 22 16:52:28 2012
@@ -0,0 +1,370 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+  <head>
+    <title>Apache Sling - Getting and Building Sling</title>
+    <link rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+    <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </head>
+  <body>
+    <div class="title">
+      <div class="logo">
+        <a href="http://sling.apache.org/site/index.html">
+          <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+        </a>
+      </div>
+      <div class="header">
+        <a href="http://www.apache.org/">
+          <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+        </a>
+      </div>
+    </div>
+    
+    <div class="menu"> 
+      <h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="getting-started.html">Getting Started</a></li>
+<li><a href="the-sling-engine.html">The Sling Engine</a></li>
+<li><a href="development.html">Development</a></li>
+<li><a href="bundles.html">Bundles</a></li>
+<li><a href="tutorials-&amp;-how-tos.html">Tutorials &amp; How-Tos</a></li>
+<li><a href="configuration.html">Configuration</a></li>
+<li><a href="http://sling.apache.org/apidocs/sling5/index.html">API docs</a></li>
+<li><a href="http://s.apache.org/sling.wiki">Wiki</a></li>
+<li><a href="http://s.apache.org/sling.faq">FAQ</a></li>
+</ul>
+<h1 id="project-info">Project info</h1>
+<ul>
+<li><a href="http://sling.apache.org/site/downloads.cgi">Downloads</a></li>
+<li><a href="http://www.apache.org/licenses/">License</a></li>
+<li><a href="contributing.html">Contributing</a></li>
+<li><a href="news.html">News</a></li>
+<li><a href="links.html">Links</a></li>
+<li><a href="project-information.html">Project Information</a></li>
+<li><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a></li>
+<li><a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+<h1 id="sponsorship">Sponsorship</h1>
+<ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a></li>
+</ul>
+<iframe 
+    src="http://www.apache.org/ads/button.html"
+    style="border-width:0; float: left" frameborder="0" 
+    scrolling="no"
+    width="135" 
+    height="135">
+</iframe>
+    </div>
+    
+    <div class="main">
+      <div class="breadcrump" style="font-size: 80%;">
+		(TODO: breadcrumb here)
+      </div>
+      <h1 class="title">Getting and Building Sling</h1>
+      <div>
+	    <p><a name="GettingandBuildingSling-GettingandBuildingSling"></a></p>
+<h1 id="getting-and-building-sling">Getting and Building Sling</h1>
+<p>{excerpt}A quick guide for getting the Sling source, then building and
+running the resulting Sling instance; either without or with
+Eclipse.{excerpt}</p>
+<p>Sling can easily be built:
+<em> from the command line (using SVN and the Maven command line tool)
+</em> or using Eclipse</p>
+<p>Note that you don't <em>have</em> to build Sling yourself, if you don't need the
+bleeding-edge stuff you can get prebuilt binaries from the <a href="downloads.html">Downloads</a>
+ page.</p>
+<p>A full build of Sling takes 5-10 minutes on a recent computer once your
+local Maven repository is up to date. The first build may take much longer
+than that if you start with an empty local Maven repository, as Maven will
+then download its plugins and all the required dependencies.</p>
+<p><a name="GettingandBuildingSling-Prerequisites"></a></p>
+<h2 id="prerequisites">Prerequisites</h2>
+<p>Before you begin, you need to have the following tools installed on your
+system:
+<em> Java 5 or higher; Java 6 recommended
+</em> <a href="http://maven.apache.org">Maven</a>
+ 3.0.2 or later; enforced by the Sling parent pom</p>
+<p>If you want to set up Eclipse (not required to build Sling) you'll also
+need the following installed:
+<em> Eclipse (tested with 3.4.2 and 3.5.x on Win XP, SP3, 3.6.x on Win7, 3.7
+on MacOS X 10.6); just a plain installation of the platform runtime binary
+and the JDT will be adequate (you can install the IDE for Java Developers
+for convenience) 
+</em> M2Eclipse plugin for Eclipse (sonatype) -&gt; <a href="http://m2eclipse.sonatype.org/installing-m2eclipse.html">instructions</a>
+* <a href="http://www.polarion.com/products/svn/subversive.php">Subversive plugin</a>
+ or [Subclipse-plugin|http://subclipse.tigris.org]
+ for Eclipse</p>
+<p><a name="GettingandBuildingSling-EnvironmentSetup"></a></p>
+<h2 id="environment-setup">Environment Setup</h2>
+<p>The full build process requires quite a lot of resources, so you may run
+into limits. The following hints should show you what to setup before
+building Sling.</p>
+<p><a name="GettingandBuildingSling-JavaHeapSpace"></a></p>
+<h3 id="java-heap-space">Java Heap Space</h3>
+<ul>
+<li><em>Problem</em> - Build aborts with reports of {{java.lang.OutOfMemoryError:
+Java heap space}}. Alternatively the build may randomly fail during the
+integration tests.</li>
+<li><em>Platforms</em> - This happens on all platforms</li>
+<li><em>Fix</em> - Increase the values of the maximum heap and perm space for the
+build by setting or extending the <em>MAVEN_OPTS</em> environment variable.</li>
+</ul>
+<p>For 32bit platforms you should use</p>
+<div class="codehilite"><pre><span class="n">MAVEN_OPTS</span><span class="o">=</span><span class="s">&quot;-Xmx256M -XX:MaxPermSize=256m&quot;</span>
+</pre></div>
+
+
+<p>For 64bit platforms, you should use</p>
+<div class="codehilite"><pre><span class="n">MAVEN_OPTS</span><span class="o">=</span><span class="s">&quot;-Xmx512M -XX:MaxPermSize=512m&quot;</span>
+</pre></div>
+
+
+<p>For more information see <a href="https://issues.apache.org/jira/browse/SLING-443">SLING-443</a>
+ and [SLING-1782|https://issues.apache.org/jira/browse/SLING-1782]
+.</p>
+<p><a name="GettingandBuildingSling-EnvironmentVariableSpace"></a></p>
+<h3 id="environment-variable-space">Environment Variable Space</h3>
+<ul>
+<li>
+<p><em>Problem</em> - Build aborts when trying to launch the integration tests
+with the message</p>
+<p>[INFO]
+ Error while executing forked tests.; nested exception is
+org.apache.maven.surefire.booter.shade.org.codehaus.plexus.util.cli.CommandLineException:
+Error setting up environmental variables</p>
+<p>error=12, Not enough space</p>
+</li>
+</ul>
+<p>This problem is caused by insufficient swap space. When running the
+integration tests in the <em>launchpad/testing</em> modules, a process is
+launched by calling the <em>exec</em> system call. This copies the process
+(copy-on-write, though) and thus allocates as much virtual memory as is
+owned by the parent process. This may fail if swap space is exhausted.
+<em> </em>Platform<em> - OpenSolaris
+</em> <em>Fix</em> - If this issue persists you will need to check your system
+requirements and configuration with regard to swap, before taking action -
+if necessary.</p>
+<p><a name="GettingandBuildingSling-ConfiguringMaven"></a></p>
+<h2 id="configuring-maven">Configuring Maven</h2>
+<p>See <a href="maventipsandtricks.html">MavenTipsAndTricks</a>
+.</p>
+<p><a name="GettingandBuildingSling-GettingtheSlingSource"></a></p>
+<h2 id="getting-the-sling-source">Getting the Sling Source</h2>
+<p><a name="GettingandBuildingSling-WithSVN"></a></p>
+<h3 id="with-svn">With SVN</h3>
+<ol>
+<li>
+<p>Checkout Sling from the Repository.</p>
+<p>$ svn checkout http://svn.apache.org/repos/asf/sling/trunk sling</p>
+</li>
+</ol>
+<p><a name="GettingandBuildingSling-WithEclipseSubversiveorSubclipse"></a></p>
+<h3 id="with-eclipse-subversive-or-subclipse">With Eclipse Subversive or Subclipse</h3>
+<p>First note how simple the above SVN instructions are...but if you <em>really</em>
+want to do this, read on.</p>
+<p>If you use the Subversive plugin make sure you have installed the
+"Subversive Integration for M2Eclipse Project" which can be found under the
+following Eclipse update site: <a href="http://community.polarion.com/projects/subversive/download/integrations/update-site/">http://community.polarion.com/projects/subversive/download/integrations/update-site/</a>
+.</p>
+<p>Also, make sure that you have installed either the "Maven SCM handler for
+Subclipse" or the "Maven SCM handler for Subversive".</p>
+<p><a name="GettingandBuildingSling-Createanewworkspace"></a></p>
+<h4 id="create-a-new-workspace">Create a new workspace</h4>
+<p>It's best to create a new workspace for the sling project:
+1. Menu: File-&gt;Switch Workspace-&gt;Other...
+1. Enter a path for the new workspace and click OK
+1. When Eclipse has restarted it's time to adjust some configs
+1. Turn off automatic build (Menu: Project-&gt;Build Automatically)
+1. Go to menu: Eclipse-&gt;Preferences, in the preferences dialog select Java
+-&gt; Compiler -&gt; Errors/Warnings
+1. Expand the "Deprecated and restricted API" and change "Forbidden
+references (access rules)" from "Error" to "Warning"
+1. Click OK</p>
+<p><a name="GettingandBuildingSling-CheckouttheSlingsource"></a></p>
+<h4 id="checkout-the-sling-source">Checkout the Sling source</h4>
+<ol>
+<li>Menu: File-&gt;Import</li>
+<li>In the Import wizard select Maven-&gt;"Check out Maven Projects from SCM"</li>
+<li>Click next</li>
+<li>In the "SCM URL" field pick "SVN" and enter the url
+"http://svn.apache.org/repos/asf/sling/trunk"</li>
+<li>Click Finish</li>
+</ol>
+<p>Eclipse will now start to download the source and import the Maven
+projects. You might encounter some "Problem Occured" dialogs about "An
+internal error...", but just click OK on those and let Eclipse continue
+with the import. Be warned: This could take some time (it was 30 minutes on
+my laptop)!</p>
+<p>Possibly something in sling-builder might get a bit messed up (I didn't
+experience that problem, but Pontus reported it) then you can simply fix it
+with revert:
+1. In the Project Explorer right-click on the "sling-builder" project and
+select the Team-&gt;Revert... menu
+1. A couple of changes will be displayed
+1. Click OK</p>
+<p><a name="GettingandBuildingSling-BuildingSling"></a></p>
+<h2 id="building-sling">Building Sling</h2>
+<p><a name="GettingandBuildingSling-WiththeMavencommandlinetool"></a></p>
+<h3 id="with-the-maven-command-line-tool">With the Maven command line tool</h3>
+<ol>
+<li>
+<p>Enter the directory, then do a full build and local install (below are
+unix/linux commands, slightly different under windows)</p>
+<p>$ cd sling
+$ export MAVEN_OPTS="-Xmx256m -XX:MaxPermSize=128m"
+$ mvn -s /dev/null clean install</p>
+</li>
+</ol>
+<p>Note: On windows just leave out <em>/dev/null</em> and make sure you have an
+empty settings.xml file for maven (located in your user directory under
+.m2).
+1. Enter the <em>launchpad/builder</em> directory and launch Sling for the first
+time</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">cd</span> <span class="n">launchpad</span><span class="o">/</span><span class="n">builder</span>
+<span class="nv">$</span> <span class="nv">java</span> <span class="o">-</span><span class="n">jar</span> <span class="n">target</span><span class="o">/</span><span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling</span><span class="o">.</span><span class="n">launchpad</span><span class="o">-*-</span><span class="n">standalone</span><span class="o">.</span><span class="n">jar</span> <span class="o">-</span><span class="n">c</span> <span class="n">test</span> <span class="o">-</span><span class="n">f</span> <span class="o">-</span>
+</pre></div>
+
+
+<p>{note}
+When starting Sling inside the <em>launchpad/builder</em> folder you should not
+use the default Sling Home folder name <em>sling</em> because this folder is
+removed when running <em>mvn clean</em>.
+{note}</p>
+<p>Messages should now be printed to the console which is being used as the
+"log file"; the <em>-f</em> command line option is set to <em>-</em>, indicating
+the use of standard output as the log file. The <em>-c sling</em> command line
+option instructs Sling to use the <em>sling</em> directory in the current
+directory for its data store, which is the Apache Felix bundle archive, the
+Jackrabbit repository data and configuration. You may also specify another
+directory here, either a relative or absolute path name (See also <a href="configuration.html">Configuration</a>
+ for more information). 
+Use the <em>-h</em> option to see the list of flags and options.
+After all messages have been printed you should be able to open the Sling Management Console by pointing your web browser at {{<a href="http://localhost:8080/system/console">http://localhost:8080/system/console</a>
+}}. You will be prompted for a user name and password. Enter <em>admin</em> for
+both the user name and the password (this may be set on the <em>Configuration</em>
+page later). From this console, you can manage the installed bundles,
+modify configuration objects, dump a configuration status and see some
+system information.
+To stop Sling, just hit <em>Ctrl-C</em> in the console or click the <em>Stop</em>
+button on the <em>System Information</em> page of the Sling Management Console.</p>
+<p><a name="GettingandBuildingSling-WithM2Eclipse"></a></p>
+<h3 id="with-m2eclipse">With M2Eclipse</h3>
+<ol>
+<li>Make sure you're in the Java perspective (Menu: Window-&gt;Open Perspective)</li>
+<li>Menu: Run-&gt;Run Configurations...</li>
+<li>In the Run Configurationa dialog right-click on "Maven Build" and select
+"New"</li>
+<li>Change Name to "Build Sling"</li>
+<li>Click "Browse Workspace..." and select "sling-builder"</li>
+<li>Enter "clean install" in Goals</li>
+<li>Click on the JRE tab</li>
+<li>Enter "-Xmx256m -XX:MaxPermSize=128m" in "VM arguments"</li>
+<li>Click Apply</li>
+<li>Click Run</li>
+</ol>
+<p><a name="GettingandBuildingSling-AlternativesetupinEclipsewithoutM2Eclipseplugin"></a></p>
+<h3 id="alternative-setup-in-eclipse-without-m2eclipse-plugin">Alternative setup in Eclipse without M2Eclipse plugin</h3>
+<p>In the case that you do not want to use the M2Eclipse plugin there's
+another setup that lets you have the automatic build turned on:
+1. Checkout the whole sling trunk (with subversive or the subclipse plugin)
+from SVN to a single project
+1. Then manually add all <em>src/main/java</em> and <em>src/test/java</em> of the
+bundles to the project as source folders
+1. Add all required libraries to the build path
+1. Now you can build either in Eclipse or even better use "mvn clean
+install" on the command line</p>
+<p>If you use "mvn clean install" to build Sling be sure you have set
+MAVEN_OPTS to "-Xmx384m -XX:PermSize=256m" otherwise you will probably get
+OutOfmemory errors.</p>
+<p>Congratulations ! You should now have a running Sling instance, that you
+can start playing around with.</p>
+<p><a name="GettingandBuildingSling-FurtherTipsandTricks"></a></p>
+<h2 id="further-tips-and-tricks">Further Tips and Tricks</h2>
+<p><a name="GettingandBuildingSling-DebugSlinginEclipse"></a></p>
+<h3 id="debug-sling-in-eclipse">Debug Sling in Eclipse</h3>
+<p>You can use remote debugging to debug Sling in Eclipse, here's a little
+How-To
+1. start Sling from the command line with</p>
+<div class="codehilite"><pre><span class="n">java</span> <span class="o">-</span><span class="n">Xmx384M</span>
+</pre></div>
+
+
+<p>-agentlib:jdwp=transport=dt_socket,address=30303,server=y,suspend=n -jar
+org.apache.sling.launchpad.app-6-SNAPSHOT.jar</p>
+<ol>
+<li>Open Menu Run-&gt; Debug configurations</li>
+<li>Right-click on "Remote Java Applications"</li>
+<li>Choose "New"</li>
+<li>In the "Connect" tab choose the Eclipse Sling Project for the field
+"Project" with the browse button</li>
+<li>Let the Connection type be "Standard (Socket Attach)"</li>
+<li>The host should be localhost</li>
+<li>Set the Port to 30303</li>
+<li>On the source tab click the "Add" button</li>
+<li>Select "Java Project"</li>
+<li>Select all Sling projects and click OK</li>
+<li>Click "Debug"</li>
+</ol>
+<p>Now you should be able to set breakpoints, evaluate properties, and so on
+as usual.</p>
+<p><a name="GettingandBuildingSling-DebugMavenTestsinEclipse"></a></p>
+<h3 id="debug-maven-tests-in-eclipse">Debug Maven Tests in Eclipse</h3>
+<p>In the same way as you can debug the sling app, you are also able to debug
+a maven test. Just run the maven tests like this</p>
+<div class="codehilite"><pre><span class="n">mvn</span> <span class="o">-</span><span class="n">Dmaven</span><span class="o">.</span><span class="n">surefire</span><span class="o">.</span><span class="n">debug</span> <span class="n">test</span>
+</pre></div>
+
+
+<p>The tests will automatically pause and await a remote debugger on port
+5005. You can then attach to the running tests using Eclipse. You can setup
+a "Remote Java Application" launch configuration via the menu command "Run"</p>
+<blockquote>
+<p>"Open Debug Dialog..." (see above).
+For more information on this see the <a href="http://maven.apache.org/plugins/maven-surefire-plugin/examples/debugging.html">Maven Surefire Docu</a>
+.</p>
+</blockquote>
+<p><a name="GettingandBuildingSling-SimplewaytodevelopnewbundleinEclipseforSling"></a></p>
+<h3 id="simple-way-to-develop-new-bundle-in-eclipse-for-sling">Simple way to develop new bundle in Eclipse for Sling</h3>
+<p>The easiest way that I found is to create a new folder in the existing
+Eclipse workspace. After that you can follow these steps:
+<em> Start by copying and adapting an existing Sling pom.xml (eg. the pom.xml
+from the espblog sample)
+</em> Generate the Eclipse project files using mvn eclipse:eclipse
+<em> Choose File/Import in Eclipse and select "Existing projects into
+workspace"
+</em> Now you can create, edit and compile the files in Eclipse
+<em> To create the bundle jar and install it, just use the command line "mvn
+clean install" in the project directory
+</em> If you have a running Sling app you can install the bundle from the command line with "mvn -P autoInstallBundle clean install -Dsling.url=<a href="http://localhost:8080/system/console">http://localhost:8080/system/console</a>
+"</p>
+<p>If adding dependencies to the poms, run mvn eclipse:eclipse again and
+refresh the project in Eclipse. Debugging works as described above.</p>
+      </div>
+    </div>
+    
+    <div class="trademarkFooter"> 
+		Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+	</div>
+  </body>
+</html>



Mime
View raw message