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 [2/16] - /websites/staging/sling/trunk/content/
Date Sun, 22 Apr 2012 16:52:31 GMT
Added: websites/staging/sling/trunk/content/apache-sling-eventing-and-job-handling.html
==============================================================================
--- websites/staging/sling/trunk/content/apache-sling-eventing-and-job-handling.html (added)
+++ websites/staging/sling/trunk/content/apache-sling-eventing-and-job-handling.html Sun Apr 22 16:52:28 2012
@@ -0,0 +1,550 @@
+<!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 - Apache Sling Eventing and Job Handling</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">Apache Sling Eventing and Job Handling</h1>
+      <div>
+	    <p><em>NOTE: This documentation is work in progress!</em></p>
+<p><a name="ApacheSlingEventingandJobHandling-Overview"></a></p>
+<h2 id="overview">Overview</h2>
+<p>The Apache Sling Event Support bundle provides interesting services for
+advanced event handling and job processing. While this bundle leverages the
+OSGi EventAdmin, it provides a very powerful support for so called jobs: a
+job is a task which has to be performed by a component - the Sling job
+handling ensures that exactly one component performs this task.</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>The Sling Event Supports adds the following services:
+<em> <a href="#jobs.html">Jobs</a>
+</em> <a href="#distributed.html">Distributed Events</a>
+* <a href="#timed.html">Scheduled Events</a></p>
+<p>{anchor:jobs}
+<a name="ApacheSlingEventingandJobHandling-Jobs(GuaranteeofProcessing)"></a></p>
+<h2 id="jobs-guarantee-of-processing">Jobs (Guarantee of Processing)</h2>
+<p>In general, the eventing mechanism (OSGi EventAdmin) has no knowledge about
+the contents of an event. Therefore, it can't decide if an event is
+important and should be processed by someone. As the event mechanism is a
+"fire event and forget about it" algorithm, there is no way for an event
+admin to tell if someone has really processed the event. Processing of an
+event could fail, the server or bundle could be stopped etc.</p>
+<p>On the other hand, there are use cases where the guarantee of processing a
+job is a must and usually this comes with the requirement of processing
+this job exactly once. Typical examples are sending notification emails (or
+sms) or post processing of content (like thumbnail generation of images or
+documents).</p>
+<p>The Sling Event Support adds the notion of a job to the OSGi EventAdmin. A
+job is a special OSGi event that someone has to process (do the job). The
+job event has a special topic <em>org/apache/sling/event/job</em> to indicate that
+the event contains a job. These job events are consumed by the Sling Job
+Handler - it ensures that someone does the job! To support different jobs
+and different processors of such jobs, the real topic of the event is
+stored in the <em>event.job.topic</em> property of the original event. When a job
+event (event with the topic <em>org/apache/sling/event/job</em>) is received, a
+new event with the topic from the property <em>event.job.topic</em> is fired
+(Firing this event comes of course with a set of rules and constraints
+explained below).</p>
+<p>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 <em>event.job.topic</em>) and an optional job
+name, the <em>event.job.id</em> property. It is up to the client creating the
+event to ensure that the <em>event.job.id</em> property is unqiue <em>and</em> identical
+on all application nodes. If the job name is not provided for the job, then
+it is up to the client to ensure that the job event is only fired once.
+Usually for jobs generated based on user interaction, a unique job name is
+not required as the job is only created through the user interaction.</p>
+<p><a name="ApacheSlingEventingandJobHandling-JobProcessors"></a></p>
+<h3 id="job-processors">Job Processors</h3>
+<p>A job processor is a service consuming and processing a job. It listens for
+OSGi events with the job topic. The OSGi EventAdmin usually comes with a
+timeout for event handlers. An event handler must consume an OSGi event as
+fast as possible otherwise the handler might get a timeout and get
+blacklisted. Therefore a job processor should never directly process the
+job in the event handler method, but do this async.</p>
+<p>In addition the Sling Job Handler needs to get notified if someone is
+processing a job and when someone has finished processing this job.</p>
+<p>To make implementing such a job processor easier, there is the <em>JobUtil</em>
+utility class along with the <em>JobProcessor</em> interface. The <em>JobUtil</em> class
+has a helper method for this: <em>processJob(Event, JobProcessor)</em>. The job
+processor must implement the <em>JobProcessor</em> interface which consists of a
+single <em>process(Event)</em> method. When the event handler receives a job event
+through the OSGi EventAdmin, it calls <em>JobUtil.processJob(event, this)</em> and
+returns. This utility method takes care to notify the Sling Job Handler
+that someone is processing the job. Then the <em>process(Event)</em> method of the
+job processor is called in the background and when it returns, the Sling
+Job Handler is notified that the job is completed (or processing failed).</p>
+<p>If the job processor wants to do the background processing by itself or
+does not need background processing at all, it must signal starting and
+completition of the job by call <em>JobUtil.acknowledgeJob(Event),
+_JobUtil.finishedJob(event)</em> or _JobUtil.rescheduleJob(Event).</p>
+<p><a name="ApacheSlingEventingandJobHandling-ProcessingofJobs"></a></p>
+<h3 id="processing-of-jobs">Processing of Jobs</h3>
+<p>Incoming jobs are first persisted in the repository (for failover etc.) and
+then a job is put into a processing queue. There are different types of
+queues defining how the jobs are processed (one after the other, in
+parallel etc.).</p>
+<p>For managing queues, the Sling Job Handler uses the OSGi ConfigAdmin - it
+is possible to configure one or more queue configurations through the
+ConfigAdmin. One way of creating and configuring such configurations is the
+Apache Felix WebConsole.</p>
+<p><a name="ApacheSlingEventingandJobHandling-QueueConfigurations"></a></p>
+<h4 id="queue-configurations">Queue Configurations</h4>
+<p>A queue configuration can have the following properties:</p>
+<table>
+<tr><td> *Property Name*     </td><td> *Description* </td></tr>
+<tr><td> _queue.name_        </td><td> The name of the queue. If matching is used for
+topics, the value \{0\} can be used for replacing the matched part. </td></tr>
+<tr><td> _queue.type_        </td><td> The type of the queue: ORDERED, UNORDERED,
+TOPIC_ROUND_ROBIN, IGNORE, DROP </td></tr>
+<tr><td> _queue.topics_       </td><td> A list of topics processed by this queue. Either
+the concrete topic is specified or the topic string ends with /* or /. If a
+star is at the end all topics and sub topics match, with a dot only direct
+sub topics match. </td></tr>
+<tr><td> _queue.maxparallel_        </td><td> How many jobs can be processed in parallel?
+-1 for number of processors.</td></tr>
+<tr><td> _queue.retries_    </td><td> How often should the job be retried. -1 for
+endless retries. </td></tr>
+<tr><td> _queue.retrydelay_    </td><td> The waiting time in milliseconds between job
+retries. </td></tr>
+<tr><td> _queue.priority_    </td><td> The thread priority: NORM, MIN, or MAX </td></tr>
+<tr><td> _queue.runlocal_    </td><td> Should the jobs only be processed on the cluster
+node they have been created? </td></tr>
+<tr><td> _queue.applicationids_       </td><td> Optional list of application (cluster
+node) ids. If configured, these jobs are only processed on this application
+node.</td></tr>
+<tr><td> _service.ranking_ </td><td> A ranking for this configuration.</td></tr>
+</table>
+
+<p>The configurations are processed in order of their service ranking. The
+first matching queue configuration is used for the job.</p>
+<p><a name="ApacheSlingEventingandJobHandling-OrderedQueues"></a></p>
+<h4 id="ordered-queues">Ordered Queues</h4>
+<p>An ordered queue processes one job after the other.</p>
+<p><a name="ApacheSlingEventingandJobHandling-UnorderedQueues"></a></p>
+<h4 id="unordered-queues">Unordered Queues</h4>
+<p>Unordered queues process jobs in parallel.</p>
+<p><a name="ApacheSlingEventingandJobHandling-Topic-Round-RobinQueues"></a></p>
+<h4 id="topic-round-robin-queues">Topic-Round-Robin Queues</h4>
+<p>The jobs are processed in parallel. Scheduling of the jobs is based on the
+topic of the jobs. These are started by doing round-robin on the available
+topics.</p>
+<p><a name="ApacheSlingEventingandJobHandling-IgnoringQueues"></a></p>
+<h4 id="ignoring-queues">Ignoring Queues</h4>
+<p>A queue of type <em>ignoring</em> ignores this job. The job is persisted but not
+processed. This can be used to delay processing of some jobs. With a
+changed configuration and a restart of the Sling Job Handler the ignored
+jobs can be processed at a later time.</p>
+<p><a name="ApacheSlingEventingandJobHandling-DroppingQueues"></a></p>
+<h4 id="dropping-queues">Dropping Queues</h4>
+<p>A queue of type <em>drop</em> is dropping a job - which means it is not processed
+at all and directly discarded.</p>
+<p><a name="ApacheSlingEventingandJobHandling-Persistence"></a></p>
+<h3 id="persistence">Persistence</h3>
+<p>The job event handler listens for all job events (all events with the topic
+<em>org/apache/sling/event/job</em>) and will as a first step persist those events
+in the JCR repository. All job events are stored in a tree under the job
+root node <em>/var/eventing/jobs</em>. Persisting the job ensures proper handling
+in a clustered environment and allows failover handling after a bundle stop
+or server restart. Once a job has been processed by someone, the job will
+be removed from the repository.</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
+<em>event.job.topic</em> and job name (property <em>event.job.id</em>). If the event has
+already been written by some other application node, it's not written
+again.</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> <em>event:topic</em>       </td><td> The topic of the job </td></tr>
+<tr><td> <em>event:id</em>       </td><td> The unique identifier of this job (optional).
+</tr>
+<tr><td> <em>event:created</em>     </td><td> The date and time when the event has been created
+(stored in the repository)
+</tr>
+<tr><td> <em>event:application</em> </td><td> The identifier of the node where the job was
+created </td></tr>
+<tr><td> <em>event:properties</em>  </td><td> Serialized properties </td></tr>
+<tr><td> <em>event:finished</em>    </td><td> The date and time when the job has been finished </td></tr>
+<tr><td> <em>event:processor</em>   </td><td> The identifier of the node which processed the job
+(after successful processing) </td></tr>
+</table></p>
+<p>The failover of an application node is accomplished by locking. 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 <em>event:application</em> information and processes it
+accordingly. In this case the event gets the additional property
+<em>org/apache/sling/job/retry</em>. </p>
+<p>Each application is periodically removing old jobs from the repository
+(using the scheduler).</p>
+<p><a name="ApacheSlingEventingandJobHandling-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 <em>event.application</em>
+on the remote nodes. If the job event handler receives a job with the
+<em>event.application</em> 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 <em>event.application</em> when
+sending the event locally. All other application nodes will use the
+<em>event.application</em> stored in the repository when broadcasting the event
+locally.</p>
+<p><a name="ApacheSlingEventingandJobHandling-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="ApacheSlingEventingandJobHandling-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 <em>event.distribute</em> is not explicitly set, the
+event is only distributed localled.</p>
+<p>If the <em>event.distribute</em> 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 <em>event.distribute</em> and publish
+the event.</p>
+<p>The flow can be described as follows:
+1. Client code generates event using OSGi API, if the <em>event.distribute</em>
+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 <em>event.distribute</em> is
+present
+1. # Event handler adds <em>event.application</em> 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
+<em>event.application</em> (from the node where the event occured first) and
+cleared <em>event.distribute</em>.</p>
+<p><a name="ApacheSlingEventingandJobHandling-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
+<em>event.distribute</em> 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
+<em>event.distribute</em> is not set.
+1. The job event handler gets the event if it has the job topic
+1. # The job event handler adds the <em>event.application</em> property and tries to
+write the job to the repository
+1. ## If no job with the topic and <em>id</em> property is in the repository, the
+event will be written and locked.
+1. ## If an event with the topic and <em>id</em> property is in the repository then:
+1. ### If the <em>event.application</em> equals the current application node, the
+event is set to active (<em>event:active</em>) in the repository again and locked
+1. ### If the <em>event.application</em> 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
+<em>event:active</em> to false afterwards.</p>
+<p><a name="ApacheSlingEventingandJobHandling-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="ApacheSlingEventingandJobHandling-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 <em>event.application</em> property. If it is not
+set, it's a local event and the handler should process the event. If the
+<em>event.application</em> 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 <em>event.application</em> 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 <em>isLocalEvent(Event)</em> which
+checks the existance of the <em>event.application</em> property and returns <em>true</em>
+if it is absend.</p>
+<p>{anchor:distributed}
+<a name="ApacheSlingEventingandJobHandling-DistributedEvents"></a></p>
+<h2 id="distributed-events">Distributed Events</h2>
+<p>In addition to the job handling, the Sling Event support adds handling for
+distributed events. A distributed event is an OSGi event which is sent
+across JVM boundaries to a different VM. A potential use case is to
+broadcast information in a clustered environment.</p>
+<p><a name="ApacheSlingEventingandJobHandling-SourcesofEvents"></a></p>
+<h3 id="sources-of-events">Sources of Events</h3>
+<p>When it comes to application based on Sling, there is a variety of sources
+from which OSGi 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="ApacheSlingEventingandJobHandling-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 "simultanously" 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="ApacheSlingEventingandJobHandling-BasicPrinciples"></a></p>
+<h3 id="basic-principles">Basic Principles</h3>
+<p>The foundation of the distributed event mechanism is to distribute each
+event to every node in a clustered environment. The event distribution
+mechanism has no knowledge about the intent of the event and therefore is
+not able to make delivery decisions by itself. It is up to the sender to
+decide what should happen, 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 is additional support for such things, like job handling.</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="ApacheSlingEventingandJobHandling-DistributedEvents"></a></p>
+<h3 id="distributed-events_1">Distributed Events</h3>
+<p>For distributed events two properties are defined (check the <em>EventUtil</em>
+class):
+<em> <em>event.distribute</em> - this flag is set by the sender of an event to give a
+hint if the event should be distributed across instances. For example JCR
+observation based events are already distributed on all instances, so there
+is no further need to distribute them. If the flag is present, the event
+will be distributed. The value has currently no meaning, however the
+EventUtil method should be used to add this property. If the flag is absent
+the event is distributed locally only.</em> <em>event.application</em> - An identifier for the current application node in
+the cluster. This information will be used to detect if an event has been
+created on different nodes. If the event has been created on the same node,
+the <em>event.application</em> is missing, if it is a remote event, the
+<em>event.application</em> contains the ID of the node, the event has been
+initially created. Use the <em>EventUtil.isLocal(Event)</em> method to detect if
+the event is a local or a distributed event.</p>
+<p>While the <em>event.distribute</em> must be set by the sender of an event (if the
+event should be distributed), the <em>event.application</em> property is
+maintained by the event mechanism. Therefore a client sending an event
+should <em>never</em> set this information by itself. This will confuse the local
+event handlers and result in unexpected behaviour. On remote events the
+<em>event.application</em> is set by the event distribution mechanism.</p>
+<p><a name="ApacheSlingEventingandJobHandling-EventDistributionAcrossApplicationNodes(Cluster)"></a></p>
+<h3 id="event-distribution-across-application-nodes-cluster">Event Distribution Across Application Nodes (Cluster)</h3>
+<p>The (local) event admin is the service distributing events locally. The
+Sling Distributing Event Handler is a registered event handler that is
+listening for events to be distributed. It distributes the events to remote
+application notes, 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 <em>event.distribute</em> in the event
+properties (through <em>EventUtil</em>). This distribution mechanism has the
+advantage that the application nodes do not need to know each other and the
+distribution mechanism is independent from the used event admin
+implementation.</p>
+<p><a name="ApacheSlingEventingandJobHandling-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> <em>event:topic</em>       </td><td> The topic of the event </td></tr>
+<tr><td> <em>event:application</em> </td><td> The identifier of the application node where the
+event was created </td></tr>
+<tr><td> <em>event:created</em>     </td><td> The date and time when the event has been created
+(stored in the repository)
+</tr>
+<tr><td> <em>event:properties</em>  </td><td> Serialized properties (except the
+<em>event.distribute</em>, but including the <em>event.application</em>) </td></tr>
+</table></p>
+<p>Each application is periodically removing old events from the repository
+(using the scheduler).</p>
+<p>{anchor:timed}
+<a name="ApacheSlingEventingandJobHandling-SendingScheduledEvents"></a></p>
+<h3 id="sending-scheduled-events_1">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="ApacheSlingEventingandJobHandling-ReceivingOSGiEvents"></a></p>
+<h3 id="receiving-osgi-events_1">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 <em>event.application</em> property. If it is not
+set, it's a local event and the handler should process the event. If the
+<em>event.application</em> 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 <em>event.application</em> 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 <em>isLocalEvent(Event)</em> which
+checks the existance of the <em>event.application</em> property and returns <em>true</em>
+if it is absend.</p>
+<p><a name="ApacheSlingEventingandJobHandling-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="ApacheSlingEventingandJobHandling-UseCases"></a></p>
+<h2 id="use-cases">Use Cases</h2>
+<p><a name="ApacheSlingEventingandJobHandling-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 <em>CONTENT_ADDED</em>, <em>CONTENT_UPDATED</em> 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
+<em>topic</em> and <em>id</em> 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="ApacheSlingEventingandJobHandling-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 <em>java.lang.Runnable</em> or
+<em>org.quartz.job</em> is started through the whiteboard pattern <em>if</em> it either
+contains a configuration property <em>scheduler.expression</em> or
+<em>scheduler.period</em>. The job is started with the ~PID of the service - if
+the service has no PID, the configuration property <em>scheduler.name</em> 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/apache-sling.html
==============================================================================
--- websites/staging/sling/trunk/content/apache-sling.html (added)
+++ websites/staging/sling/trunk/content/apache-sling.html Sun Apr 22 16:52:28 2012
@@ -0,0 +1,224 @@
+<!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 - Apache 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">Apache Sling</h1>
+      <div>
+	    <p><a name="ApacheSling-ApacheSling-BringingBacktheFun"></a></p>
+<h1 id="apache-sling-bringing-back-the-fun">Apache Sling - Bringing Back the Fun</h1>
+<p>{tm}Apache Sling{tm} is an innovative web framework that is intended to
+bring back the fun to web development.</p>
+<p>Discussions about Sling happen on our mailing lists, see the <a href="project-information.html">Project Information</a>
+ page for more info.</p>
+<p><a name="ApacheSling-ApacheSlinginfivebulletspoints"></a></p>
+<h1 id="apache-sling-in-five-bullets-points">Apache Sling in five bullets points</h1>
+<ul>
+<li>REST based web framework</li>
+<li>Content-driven, using a JCR content repository</li>
+<li>Powered by OSGi</li>
+<li>Scripting inside, multiple languages (JSP, server-side javascript, Scala,
+etc.)</li>
+<li>Apache Open Source project</li>
+</ul>
+<p><a name="ApacheSling-ApacheSlinginahundredwords"></a></p>
+<h1 id="apache-sling-in-a-hundred-words">Apache Sling in a hundred words</h1>
+<p>Apache Sling is a web framework that uses a <a href="http://en.wikipedia.org/wiki/JSR-170">Java Content Repository</a>
+, such as [Apache Jackrabbit|http://jackrabbit.apache.org/]
+, to store and manage content.</p>
+<p>Sling applications use either scripts or Java servlets, selected based on
+simple name conventions, to process HTTP requests in a RESTful way.</p>
+<p>The embedded <a href="http://felix.apache.org/">Apache Felix</a>
+ OSGi framework and console provide a dynamic runtime environment, where
+code and content bundles can be loaded, unloaded and reconfigured at
+runtime.</p>
+<p>As the first web framework dedicated to <a href="http://jcp.org/en/jsr/detail?id=170">JSR-170</a>
+ Java Content Repositories, Sling makes it very simple to implement simple
+applications, while providing an enterprise-level framework for more
+complex applications. </p>
+<p><a name="ApacheSling-News"></a></p>
+<h2 id="news">News</h2>
+<p>{excerpt-include:News|nopanel=true}
+* <a href="news.html">all news...</a></p>
+<p><a name="ApacheSling-History"></a></p>
+<h2 id="history">History</h2>
+<p>Sling started as an internal project at <a href="http://www.day.com">Day Software</a>
+, and entered the Apache Incubator in September 2007. As of June, 17th,
+2009 Apache Sling is a top level project of the Apache Software Foundation.</p>
+<p>The name "Sling" has been proposed by Roy Fielding who explained it like
+this:</p>
+<p>{quote}
+[The name is](the-name-is.html)
+ Biblical in nature.  The story of David: the weapon he uses to slay the
+giant Goliath is a sling.  Hence, our David's [David Nuescheler, CTO of
+Day Software] favorite weapon.</p>
+<p>It is also the simplest device for delivering content very fast.
+{quote}</p>
+<p><a name="ApacheSling-WhousesSling?"></a></p>
+<h2 id="who-uses-sling">Who uses Sling?</h2>
+<p>See <a href="http://cwiki.apache.org/SLING/who-is-using-sling-.html">Who is using Sling</a>
+ on our public wiki.</p>
+<p><a name="ApacheSling-Gettingstarted"></a></p>
+<h2 id="getting-started">Getting started</h2>
+<p>If you prefer doing rather than reading, please proceed to <a href="discover-sling-in-15-minutes.html">Discover Sling in 15 minutes</a>
+ or read through the recommended links in the [Getting Started]
+ section, where you can quickly get started on your own instance of Sling.</p>
+<p><a name="ApacheSling-Contents"></a></p>
+<h2 id="contents">Contents</h2>
+<ul>
+<li><a href="documentation.html">Documentation</a>
+ - Here you will find the documentation on Sling</li>
+<li><a href="development.html">Development</a>
+ -- Documentation on how to develop web applications with Sling and what
+tools you have at your disposal</li>
+<li><a href="links.html">Links</a></li>
+<li><a href="http://cwiki.apache.org/SLING/">Wiki</a></li>
+<li><a href="http://cwiki.apache.org/SLING/faq.html">FAQ</a></li>
+<li><a href="project-information.html">Project Information</a></li>
+</ul>
+<p><a name="ApacheSling-UseCasesforSling"></a></p>
+<h2 id="use-cases-for-sling">Use Cases for Sling</h2>
+<p><a name="ApacheSling-Wiki"></a></p>
+<h4 id="wiki">Wiki</h4>
+<p>Day built a Wiki system on Sling. Each Wiki page is a node (with optional
+child nodes) in the repository. As a page is requested, the respective node
+is accessed and through the applying Component is rendered.</p>
+<p>Thanks to the JCR Mapping and the resolution of the Component from the
+mapped Content, the system does not care for what actual node is addressed
+as long as there is a Content mapping and a Component capable of handling
+the Content.</p>
+<p>Thus in the tradition of REST, the attachement of a Wiki page, which
+happens to be in a node nested below the wiki page node is easily accessed
+using the URL of the wiki page attaching the relative path of the
+attachement  ode. The system resolves the URL to the attachement Content
+and just calls the attachement's Component to spool the attachement.</p>
+<p><a name="ApacheSling-DigitalAssetManagement"></a></p>
+<h4 id="digital-asset-management">Digital Asset Management</h4>
+<p>Day has implemented a Digital Asset Management (DAM) Application based on
+Sling. Thanks to the flexibility of the Content/Component combo as well as
+the service registration/access functionality offered by OSGi, extending
+DAM for new content type is merely a matter of implementing one or two
+interfaces and registering the respective service(s).</p>
+<p>Again, the managed assets may be easily spooled by directly accessing them.</p>
+<p><a name="ApacheSling-WebContentManagement"></a></p>
+<h4 id="web-content-management">Web Content Management</h4>
+<p>Last but not least, Sling offers itself very well to implementing a Web
+Content Management system. Thanks to the flexibility of rendering the
+output - remember: the system does not care what to render, as long as the
+URL resolves to a Content object for which a Component exists, which is
+called to render the Content - providing support for Web Content authors
+(not PHP programmers but users out in the field) to build pages to their
+likings can easily be done.</p>
+<p><a name="ApacheSling-References"></a></p>
+<h2 id="references">References</h2>
+<p><a name="ApacheSling-ApacheJackrabbit"></a></p>
+<h4 id="apache-jackrabbit">Apache Jackrabbit</h4>
+<p>The main purpose of Sling is to develop a content-centric Web Application
+framework for Java Content Repository (JCR) based data stores. Sling is
+implemented - with the notable exception of JCR Node Type management -
+purely in terms of the JCR API and as such may use any JCR compliant
+repository. The default implementation for <a href="http://jackrabbit.apache.org">Apache Jackrabbit</a>
+ is provided out of the box.</p>
+<p><a name="ApacheSling-OSGi"></a></p>
+<h4 id="osgi">OSGi</h4>
+<p>Sling is implemented as a series of <a href="http://www.osgi.org">OSGi</a>
+ Bundles and makes extensive use of the OSGi functionality, such as
+lifecycle management and the service layer. In addition, Sling requires
+several OSGi compendium services to be available, such as the Log Service,
+Http Service, Configuration Admin Service, Metatype Service, and
+Declarative Services.</p>
+<p><a name="ApacheSling-ApacheFelix"></a></p>
+<h4 id="apache-felix">Apache Felix</h4>
+<p>While Sling does not require a specific OSGi framework implementation to
+run in, Sling is being developed using <a href="http://felix.apache.org">Apache Felix</a>
+ as the OSGi framework implementation. It has not been tested yet, but it
+is expected that Sling also operates perfectly inside other OSGi frameworks
+such as [Equinox|http://www.eclipse.org/equinox]
+ and [Knopflerfish|http://www.knopflerfish.org]
+.</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/architecture.html
==============================================================================
--- websites/staging/sling/trunk/content/architecture.html (added)
+++ websites/staging/sling/trunk/content/architecture.html Sun Apr 22 16:52:28 2012
@@ -0,0 +1,280 @@
+<!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 - Architecture</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">Architecture</h1>
+      <div>
+	    <p><a name="Architecture-ArchitectureofSling"></a></p>
+<h1 id="architecture-of-sling">Architecture of Sling</h1>
+<p>The following is a short list of high-lights of Sling:</p>
+<ul>
+<li>*<a href="#osgi.html">OSGi</a></li>
+<li>--- The Sling application is built as a series of OSGi bundles and makes
+heavy use of a number of OSGi core and compendium services.</li>
+<li>*<a href="#sling-api.html">#Sling API</a></li>
+<li>--- To implement content based Web applications with Sling, an API has
+been defined, this extends the Servlet API and provides more functionality
+to work on the content.</li>
+<li>*<a href="#request-processing.html">#Request Processing</a></li>
+<li>--- Sling takes a unique approach to handling requests in that a request
+URL is first resolved to a resource, then based on the resource (and only
+the resource) it selects the actual servlet or script to handle the
+request.</li>
+<li>*<a href="#resources.html">#Resources</a></li>
+<li>--- The central mantra of Sling is the <em>Resource</em>, which represents the
+resource addressed by any request URL. It is the resource that is first
+resolved when handling a request. Based on the resource, a first servlet or
+script is then accessed to actually handle the request.</li>
+<li>*<a href="#servlets-and-scripts.html">#Servlets and Scripts</a></li>
+<li>--- Servlets and Scripts are handled uniformly in that they are
+represented as resources themselves and are accessible by a resource path.</li>
+<li>*<a href="#launchpad.html">#Launchpad</a></li>
+<li>--- Sling uses a very thin launcher to integrate with an existing servlet
+container, launching Sling as a Web application or providing a main class
+to represent a standalone Java application.</li>
+</ul>
+<p>The following sections elaborate on each of these highlights.</p>
+<p><a name="Architecture-OSGi"></a></p>
+<h2 id="osgi">OSGi</h2>
+<p><a href="http://www.osgi.org">OSGi</a>
+ is a consortium that has developed a specification to build modular and
+extensible applications. This offers [various benefits|http://www.osgi.org/About/WhyOSGi]
+. We deal mainly with two parts of the specifications: The Core
+Specification, which defines the OSGi Framework and Core Services, and the
+Compendium Services Specification, which defines a host of services that
+extend the functionality of the OSGi Framework.</p>
+<p><a name="Architecture-OSGiFramework"></a></p>
+<h3 id="osgi-framework">OSGi Framework</h3>
+<p>The OSGi Framework is made up of three layers -- Module, Lifecycle, and
+Services -- that define how extensible applications are built and deployed.
+The responsibilities of the layers are:</p>
+<ul>
+<li><em>Module</em> --- Defines how a module, or a <em>Bundle</em> in OSGi-speak, is
+defined. Basically, a bundle is just a plain old JAR file, whose manifest
+file has some defined entries. These entries identify the bundle with a
+symbolic name, a version and more. In addition there are headers which
+define what a bundle provides -- <em>Export-Package</em> -- and what a bundle
+requires to be operative -- <em>Import-Package</em> and <em>Require-Bundle</em>.</li>
+<li><em>Lifecycle</em> --- The lifecycle layer defines the states a bundle may be in
+and describes the state changes. By providing a class, which implements the
+<em>BundleActivator</em> interface and which is named in the
+<em>Bundle-Activator</em> manifest header, a bundle may hook into the lifecycle
+process when the bundle is started and stopped.</li>
+<li><em>Services</em> --- For the application to be able to interact, the OSGi Core
+Specification defines the service layer. This describes a registry for
+services, which may be shared.</li>
+</ul>
+<p><a name="Architecture-CompendiumServices"></a></p>
+<h3 id="compendium-services">Compendium Services</h3>
+<p>Based on the OSGi Framework specification, the Compendium Services
+specification defines a (growing) number of extension services, which may
+be used by applications for various tasks. Of these Compendium Services,
+Sling is using just a small number:</p>
+<ul>
+<li><em>Log Service</em> --- Sling comes with its own implementation of the OSGi Log
+Service specification. The respective bundle not only provides this
+implementation, it also exports the SLF4J, Log4J and Commons Logging APIs
+needed for the Sling application to perform logging.</li>
+<li><em>Http Service</em> --- Sling leverages the OSGi Http Service to hook into a
+servlet container to provide the Web Application Framework mechanism.</li>
+<li><em>Configuration Admin Service</em> --- To simplify configuration of services
+in Sling, the OSGi Configuration Admin service is used. This provides a
+uniform API to configure services and to build configuration management
+agents.</li>
+<li><em>Metatype Service</em> --- The OSGi Metatype Service defines a way to
+describe the data types. Sling uses this service to describe the
+configurations that may be created using the Configuration Admin Service.
+These meta type descriptions are used by configuration management agents to
+present to user interface to manage the configurations.</li>
+<li><em>Event Admin Service</em> --- Sling uses the OSGi EventAdmin service to
+dispatch events when scheduling tasks.</li>
+<li><em>Declarative Services</em> --- One of the most important (beside the Log
+Service) services used by Sling is the Declarative Services Specification.
+This specification defines how to declaratively create components and
+services to have the Declarative Services runtime actually manage the
+lifecycle, configuration and references of components.</li>
+</ul>
+<p><a name="Architecture-SlingAPI"></a></p>
+<h2 id="sling-api">Sling API</h2>
+<p>The Sling API is an extension to the Servlet API which provides more
+functionality to interact with the Sling framework and also to extend Sling
+itself and to implement Sling applications.</p>
+<p>See the <a href="sling-api.html">Sling API</a>
+ page for more information.</p>
+<p><a name="Architecture-RequestProcessing"></a></p>
+<h2 id="request-processing">Request Processing</h2>
+<p>Traditional Web Application framework emply more or less elaborate methods
+to select a Servlet or Controller based on the request URL, which in turn
+tries to load some data (usually from a database) to act upon and finally
+to render the result somehow.</p>
+<p>Sling turns this processing around in that it places the data to act upon
+at the center and consequently uses the request URL to first resolve the
+data to process. This data is internally represented as an instance of the
+<em>Resource</em> interface. Based on this resource as well as the request
+method and more properties of the request URL a script or servlet is then
+selected to handle the request.</p>
+<p>See the <a href="servlets.html">Servlets</a>
+ page for more information.</p>
+<p><a name="Architecture-Resources"></a></p>
+<h2 id="resources">Resources</h2>
+<p>The Resource is one of the central parts of Sling. Extending from JCR's
+<em>Everything is Content</em>, Sling assumes <em>Everthing is a Resource</em>. Thus
+Sling is maintaining a virtual tree of resources, which is a merger of the
+actual contents in the JCR Repository and resources provided by so called
+resource providers.</p>
+<p>Each resource has a path by which it is addressed in the resource tree, a
+resource type and some resource metadata (such as file size, last
+modification time). It is important to understand, that a <em>Resource</em>
+instance actually is only a handle to the actual data. By virtue of the
+<em>adaptTo(Class<Type>)</em> method, a resource may be coerced into another
+data type, which may then be used while processing the request. Examples of
+data types are <em>javax.jcr.Node</em> and <em>java.io.InputStream</em>.</p>
+<p>See the <a href="resources.html">Resources</a>
+ page for more information.</p>
+<p><a name="Architecture-ServletsandScripts"></a></p>
+<h2 id="servlets-and-scripts">Servlets and Scripts</h2>
+<p>Scripts are usually provided as content in a JCR repository. But since
+Sling is using a resource tree, a script actually is represented as a
+Resource and may be provided from within a Bundle (by virtue of the bundle
+resource provider) or even from the platform file system (by virtue of the
+file system resource provider).</p>
+<p>Accessing scripts in the resource tree, allows for a very easy to
+understand mapping from resource type to some script path.</p>
+<p>Having found the script resource, we still need access to the appropriate
+script language implementation to evaluate the script. To this avail, Sling
+is making use of the <em>Resource.adaptTo(Class<Type>)</em> method: If a script
+language implementation is available for the extension of the script name
+an adaptor for the script resource can be found, which handles the
+evaluation of the script.</p>
+<p>Besides scripting languages, such as ECMAScript, Groovy, JSP, Sling also
+supports regular servlets. To be able to use servlets for request
+processing, such servlets must be registered as OSGi services for the
+<em>javax.servlet.Servlet</em> interface and provide a number of service
+registration properties, which are used to use the servlets. In fact
+servlets thus registered as OSGi services are mapped into the resource tree
+by means of a servlet resource provider. This resource provider mapps the
+servlets into the resource tree using the service registration properties
+to build one or more resource paths for the servlet.</p>
+<p>As a result of mapping servlets into the resource tree and the possibility
+to adapt resource to an adaptor data type, scripts and servlets may be
+handled completely transparently: The servlet resolver just looks for a
+resource matching the resource type and adapts the resource found to
+<em>javax.jcr.Servlet</em>. If the resource happens to be provided by a servlet
+resource provider, the adapter is of course the servlet itself. If the
+resource happens to be a script, the adapter is a servlet facade which
+internally calls the script language implementation to evaluate the script.</p>
+<p>See the <a href="servlet-resolution.html">Servlet Resolution</a>
+ page for more information.</p>
+<p><a name="Architecture-Launchpad"></a></p>
+<h2 id="launchpad">Launchpad</h2>
+<p>Sling may be launched as a standalone application using the Sling
+Application or as a Web Application running inside any Servlet API 2.4 or
+newer Servlet Container.</p>
+<p>The Sling Application is a standalone Java Application which is really
+small: Just the main class and some glue classes. The OSGi framework as
+well as the OSGi API libraries are packaged as a JAR file, which is loaded
+through a custom classloader. This enables to update the framework and/or
+OSGi API libraries from within Sling by updating the system bundle.</p>
+<p>The Sling Servlet is equally small as the Sling Application. It uses the
+Felix <em>HttpService</em> bridge as the glue between the servlet container and
+the OSGi framework.</p>
+<p>As we have seen, Sling may be launched as a standalone Java Application or
+as a Web Application inside any compliant Servlet Container. To hide the
+differences of the launching mechanism, Sling internally registers a
+Servlet with an OSGi <em>HttpService</em>. Regardless of how Sling is launched,
+the Felix implementation of the OSGi <em>HttpService</em> specification is used.
+When Sling is launched as a standalone Java Application, Felix HttpService
+uses an embedded version of the Jetty servlet container. When Sling is
+launched as a Web Application, the Felix HttpService Bridge is used.</p>
+<p>Optionally, PAX Web's implementation of HttpService can be used when Sling
+is launched as a standalone Java Application. See the <a href="maven-launchpad-plugin.html">Maven Launchpad Plugin</a>
+ page for information on how to do this.</p>
+<p>See <a href="the-sling-launchpad.html">The Sling Launchpad</a>
+ for more information.</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/assembly.html
==============================================================================
--- websites/staging/sling/trunk/content/assembly.html (added)
+++ websites/staging/sling/trunk/content/assembly.html Sun Apr 22 16:52:28 2012
@@ -0,0 +1,336 @@
+<!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 - Assembly</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">Assembly</h1>
+      <div>
+	    <p><a name="Assembly-Assembly:BundlingBundles"></a></p>
+<h1 id="assembly-bundling-bundles">Assembly: Bundling Bundles</h1>
+<p>{panel}
+The Assembly concept grew out of a need to bundle together a set of OSGi
+Bundles to deploy applications. The concept has been developped before the
+OSGi Deployment Package Service Specification has been published in the
+Release 4.1 Compendium Services Specification. It will have to be discussed
+whether the Assembly concept is dropped in favor of the Deplyoment Package
+Service.
+{panel}</p>
+<p><a name="Assembly-Introduction"></a></p>
+<h2 id="introduction">Introduction</h2>
+<p>This chapter discusses the units of deployment as well as the units of
+functionality. The following contents is based on the Module and Service
+specifications of the OSGi Service Platform Core Specification, Release 4
+but enhances functionality for ease of use and in terms of best practices.</p>
+<p>The term <em>Units of Deployment</em> describes the idea of packaging up
+functionality implemented by Java Classes into modules, so called
+<em>Bundles</em>. For bigger and more complicated applications the fine grained
+modularity of <em>Bundles</em> may be to complicated, so this chapter proposes an
+extension called <em>Assembly</em>. The goal of the <em>Assembly</em> specification
+presented below is to provide functionality to delivery a collection of
+bundles belonging together.</p>
+<p>The term <em>Units of Functionality</em> describes the idea of providing services
+implemented by Java Classes, so called <em>Services</em>. A <em>Service</em> is an
+abstraction and does not actually prescribe the implementation of specific
+interfaces. Instead the OSGi specification states how functionality may be
+provided to clients by registering objects implementing interfaces defining
+the functionality in terms of a Java API.</p>
+<p><a name="Assembly-Bundles"></a></p>
+<h2 id="bundles">Bundles</h2>
+<p>The core unit of deployment is the <em>Bundle</em>. The OSGi core specification
+defines a <em>Bundle</em> to be a Java Archive (JAR) file whose manifest - the
+<em>META-INF/MANIFEST.MF</em> file - contains specific headers identifying the
+bundle. Most manifest headers are optional with defined default values -
+only the <em>Bundle-SymbolicName</em> header is actually required and the
+<em>Bundle-ManifestVersion</em> header should be set to <em>2</em> to identify the
+bundle to be a R4 bundle. Other information defined in the manifest is the
+bundle version, the list of packages exported - provided to other bundles -
+and imported - used and required to be provided by other bundles. See
+chapter <em>3.2.1 Bundle Manifest Header</em> of the OSGi Service Platform Core
+Specification for a complete list of the defined bundle manifest headers.</p>
+<p>Bundles may be installed, updated , started, stopped and removed in an OSGi
+framework individually.</p>
+<p><a name="Assembly-Assemblies"></a></p>
+<h2 id="assemblies">Assemblies</h2>
+<p>For the deployment of bigger systems, the number of bundles may increase
+very quickly. To ease the management of products consisting of multiple
+bundles, this chapter introduces the <em>Assembly</em>. An Assembly is simply a
+collection of bundles deployed together. An Assembly - like a Bundle - is a
+JAR file whose manifest contains specific headers. In fact, an Assembly is
+just a standard bundle, with additional functionality.</p>
+<p>Assemblies are managed by the <em>Assembly Manager</em> which itself is a bundle
+installed into the framework.</p>
+<p><a name="Assembly-Assemblymanifestheaders"></a></p>
+<h3 id="assembly-manifest-headers">Assembly manifest headers</h3>
+<p>As an Assembly is a standard Bundle, all the defined Bundle manifest
+headers may be specified. In addition, for the <em>Assembly Manager</em> to
+recognize an assembly and for the OSGi Bundle Repository to support
+dependency resolution, the following manifest headers are defined. All
+headers are optional with documented default values except where noted.</p>
+<ul>
+<li><em>Assembly-Bundles</em> - The list of bundles contained in this assembly. See
+below for the definition of the syntax of this header. This header is
+required. The presence of this headers identifies an Assembly to the
+<em>Assembly Manager</em>.</li>
+<li><em>Assembly-BundleRepository</em> - A comma-separated list of URLs pointing to
+OSGi Bundle Repository descriptors. These bundle repositories will be used
+to install bundles listed in the <em>Assembly-Bundles</em> header. This header
+is optional with not default value.</li>
+</ul>
+<p><a name="Assembly-AssemblyLifecycle"></a></p>
+<h3 id="assembly-lifecycle">Assembly Lifecycle</h3>
+<p>An Assembly, like all bundles, may be in any of the defined bundle states:</p>
+<ul>
+<li><em>Installed</em> - The Assembly bundle has been installed into the system but
+not yet resolved. The <em>Assembly Manager</em> will try to install all bundles
+listed in the <em>Assembly-Bundles</em> header. The start levels of the bundles
+will be set according to the <em>startlevel</em> parameter. The bundles will not
+be started. If installation of one or more of the bundles fails, <em>Assembly
+Manager</em> logs an error message.</li>
+<li><em>Resolved</em> - The Assembly bundle is resolved, that is all imported
+packages are wired into the framework. The <em>Assembly Manager</em> does not
+handle this state change, rather the installed bundles will be resolved by
+the framework either automatically after installation or when started
+later.</li>
+<li><em>Started</em> - The Assembly bundle has been started by calling the
+<em>Bundle.start()</em> method. The <em>Assembly Manager</em> will start all newly
+installed and resolved bundles. Depending on the start level set on the
+bundle(s) and the current system start level, the bundles will only be
+permanently marked to start while actually starting the bundles may be
+delayed until the system enters the respective start level. If any bundle
+fails to start, an error message is logged.</li>
+<li><em>Stopped</em> - The Assembly bundle has been stopped by calling the
+<em>Bundle.stop()</em> method. All bundles belong to the Assembly and linked to
+the Assembly are also stopped.</li>
+<li><em>Unresolved</em> - The Assembly bundle has been unresolved by the system for
+any reason, possibly any missing dependencies. Assembly bundles entering
+this state are ignored by the <em>Assembly Manager</em>.</li>
+<li><em>Uninstalled</em> - The Assembly bundle is being uninstalled by calling the
+<em>Bundle.uninstall()</em> method. The <em>Assembly Manager</em> will (try to)
+uninstall all bundles listed in the <em>Assembly-Bundles</em> header.</li>
+<li><em>Updated</em> - The Assembly bundle will update all bundles installed
+previously according to the <em>Assembly-Bundles</em> header. If this header
+omits any bundle listed in the previous bundle version, the respective
+bundle is uninstalled from the system. If a bundle is already installed
+with the correct version, the installed bundle is not touched (It may
+though be uninstalled together with the Assembly Bundle if the Assembly
+Bundle is uninstalled).</li>
+</ul>
+<p><a name="Assembly-BundlesreferencedbymultipleAssemblyBundles"></a></p>
+<h3 id="bundles-referenced-by-multiple-assembly-bundles">Bundles referenced by multiple Assembly Bundles</h3>
+<p>It is conceivable, that bundles are listed in the <em>Assembly-Bundles</em>
+header of more than one Assembly Bundle. If this is the case, the following
+collision resolution takes place:</p>
+<ul>
+<li>If the version of the bundle installed by the first Assembly bundle
+handled matches the version specification of any later Assembly Bundle, the
+installed bundle is not touched. Otherwise, if the later Assembly Bundle
+lists a version specification, which is acceptable for the first Assembly
+Bundle, the installed bundle is updated to the required version. If the
+version specifications may not be matched one way or the other, the later
+Assembly Bundle fails to install.</li>
+<li>If the bundle is installed with a defined start level, the later
+Assembly Bundle will not overwrite the already set start level. If the
+start level has not been set yet it is set to the specified start level.</li>
+<li>Bundles installed through Assembly Bundles remain installed as long as
+there is at least one Assembly Bundle listing the bundle in the
+<em>Assembly-Bundles</em> header. As soon as there is no referring Assembly
+Bundle anymore, the bundle is uninstalled.</li>
+<li>Bundles not referred to by any Assembly Bundle are ignored by the
+<em>Assembly Manager</em>.</li>
+<li>Bundles installed through the <em>Assembly Manager</em> may be updated and/or
+uninstalled independently from their defining Assembly Bundle. If a bundle
+has been installed it will be reinstalled the next time the Assembly Bundle
+enters the <em>installed</em> state. If a bundle has been updated, it is not
+touched by the <em>Assembly Manager</em> as long as the updated version matches
+the version specification of the Assembly Bundle.</li>
+</ul>
+<p><a name="Assembly-BundleInstallation"></a></p>
+<h3 id="bundle-installation">Bundle Installation</h3>
+<p>When an Assembly is installed into the framework, the <em>Assembly Manager</em>
+checks to see whether the Assembly needs to be deployed. This is done by
+checking the bundles listed in the <em>Assembly-Bundles</em> header whether they
+are installed or not. All bundles not installed will be installed and
+started if requested so.</p>
+<p>The following BNF defines the syntax =Assembly-Bundles= header value:</p>
+<div class="codehilite"><pre><span class="n">Assembly</span><span class="o">-</span><span class="n">Bundles</span> <span class="o">=</span> <span class="n">Bundle</span> <span class="p">{</span> <span class="s">&quot;,&quot;</span> <span class="n">Bundle</span> <span class="p">}</span> <span class="o">.</span>
+<span class="n">Bundle</span> <span class="o">=</span> <span class="n">Symbolic</span><span class="o">-</span><span class="n">Name</span> <span class="p">{</span> <span class="s">&quot;;&quot;</span> <span class="n">Parameter</span> <span class="p">}</span> <span class="o">.</span>
+<span class="n">Symbolic</span><span class="o">-</span><span class="n">Name</span> <span class="o">=</span> <span class="sr">//</span> <span class="n">The</span> <span class="n">Bundle</span> <span class="n">symbolic</span> <span class="n">name</span> 
+<span class="n">Parameter</span> <span class="o">=</span> <span class="n">ParameterName</span> <span class="s">&quot;=&quot;</span> <span class="n">ParameterValue</span> <span class="o">.</span>
+</pre></div>
+
+
+<p>To control the selection and installation of bundles, the following
+parameters may be used:</p>
+<ul>
+<li><em>version</em> - The version of the bundle to install. This is a version range
+specification as per chapter 3.2.5 Version Ranges of the OSGi core
+specification. When this parameter is declared as a single version - eg.
+<em>1.2.3</em> - it is interpreted as the version range <em>~[1.2.3, &infin;~)</em>. The
+default value is <em>~[0.0.0,&infin;~)</em> to install the most recent version of
+the bundle available.</li>
+<li><em>startlevel</em> - The start level to set for the bundle. This may be any
+positive integer value. Default value is undefined to use the current
+initial bundle start level of the framework.</li>
+<li><em>entry</em> - The path of the Assembly Bundle entry providing the data to be
+installed.</li>
+<li><em>linked</em> - Defines whether the bundle should be started and stopped
+together with the Assembly to which the bundle belongs. Default value is
+<em>true</em>.</li>
+</ul>
+<p>If resolving the bundles results in more bundles to be downloaded from the
+bundle repository to resolve the dependency, these bundles are always
+automatically started and assigned a startlevel which is smaller than the
+smallest startlevel of any of the bundles listed.</p>
+<p><a name="Assembly-BundleLocation"></a></p>
+<h3 id="bundle-location">Bundle Location</h3>
+<p>Generally bundles to be installed with an Assembly Bundle are retrieved
+from an OSGi Bundle Repository. The <em>Assembly-BundleRepository</em> header
+may list additional URLs which will be temporarily used to resovle the
+bundles. Otherwise the system default bundle repositories will be used
+only.</p>
+<p>If a bundle is defined in the <em>Assembly-Bundles</em> header with an <em>entry</em>
+parameter, the respective entry is first looked for in the Assembly Bundle.
+If the entry exists, it is used as the bundle source to install. If no
+<em>entry</em> parameter is present for a declared bundle or the entry is
+missing, the OSGi Bundle Repository is used.</p>
+<p>Restrictions when packaging bundles with the Assembly:</p>
+<ul>
+<li><em>Dependency Resolution</em> - Any missing dependencies of the bundles to be
+installed will not be resolved. That is, if the bundles fail to resolve,
+the Assembly fails to install.</li>
+<li><em><em>version</em> Parameter</em> - The <em>version</em> parameter of the bundle
+installation declaration is ignored because any JAR file whose name matches
+the bundle symbolic name to be installed, is installed.</li>
+</ul>
+<p>If the <em>Assembly-BundleRepository</em> header contains a comma-separated list
+of URL to OSGi Bundle Repository descriptors and the OSGi Bundle Repository
+Service is available in the framework, the bundles declared in the
+<em>Assembly-Bundles</em> header are resolved through the OSGi Bundle Repository
+Service using the URL from the <em>Assembly-BundleRepository</em> header.</p>
+<p>If the bundles declare any dependencies, which may not be resolved by
+bundles already installed in the framework or by any of the bundles to be
+installed, the OSGi Bundle Repository is used to try to resolve these
+missing dependencies. If this resolution succeeds, installation of the
+Assembly succeeds. Any bundles not declared in the Assembly but installed
+due to this dependency resolution will not be assumed to belong to the
+Assembly. Hence, these bundles will not be uninstalled (or updated) if the
+Assembly is uninstalled (or updated).</p>
+<ul>
+<li><em>Example</em> - Assume the <em>Assembly-Bundles</em> header is set to
+<em>org.apache.sling.sample1;entry=path.jar,org.apache.sling.sample2</em>. The
+bundle <em>org.apache.sling.sample1</em> is then installed from the Assembly
+Bundle entry <em>path.jar</em>, while the bundle <em>org.apache.sling.sample2</em> is
+resolved in the OSGi Bundle Repository.</li>
+</ul>
+<p><a name="Assembly-BestPractices"></a></p>
+<h2 id="best-practices">Best Practices</h2>
+<p><a name="Assembly-SizeofBundles"></a></p>
+<h3 id="size-of-bundles">Size of Bundles</h3>
+<p>There is no fixed formula to calculate the best size for a bundle: It all
+depends on the contents and the intentions of the bundle and its
+programmer. The following list provides some hints:</p>
+<ul>
+<li>For ease of development follow the idea of <em>One Bundle - One Project</em></li>
+<li>Don't pack too much into a bundle but do not pack a single class into
+a bundle (unless you have a very good reason of course :-) )</li>
+<li>Do not mix and match everything into a bundle. Rather bundle things
+together which belong together, for example create separate bundles for a
+HTTP Client implementation and DB support classes</li>
+<li>Use similar heuristics to decide on the contents of a bundle as you
+would for the contents of a plain old JAR file.</li>
+</ul>
+<p><a name="Assembly-NomenestOmen"></a></p>
+<h3 id="nomen-est-omen">Nomen est Omen</h3>
+<p>The symbolic name of a bundle should reflect its contents. A bundle should
+generally only contain a single subtree in the virtual package tree. The
+symbolic name of the bundle should be the root package contained within.
+For example, consider a bundle containing the packages
+<em>org.apache.sling.sample</em>, <em>org.apache.sling.sample.impl</em>,
+<em>org.apache.sling.more</em>. The bundle would the be named
+<em>org.apache.sling.sample</em>.</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