incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r841833 [2/28] - in /websites/staging/sling/trunk/content: ./ site/ site/46-line-blog.data/ site/authentication.data/ site/documentation.data/ site/first-steps.data/ site/getting-and-building-sling.data/ site/how-to-manage-events-in-sling.d...
Date Wed, 12 Dec 2012 09:17:17 GMT
Added: websites/staging/sling/trunk/content/site/apache-sling-eventing-and-job-handling.html
==============================================================================
--- websites/staging/sling/trunk/content/site/apache-sling-eventing-and-job-handling.html (added)
+++ websites/staging/sling/trunk/content/site/apache-sling-eventing-and-job-handling.html Wed Dec 12 09:16:44 2012
@@ -0,0 +1,448 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+  <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">
+<P><B>Documentation</B><BR class="atl-forced-newline">
+<A href="getting-started.html" title="Getting Started">Getting Started</A><BR class="atl-forced-newline">
+<A href="the-sling-engine.html" title="The Sling Engine">The Sling Engine</A><BR class="atl-forced-newline">
+<A href="development.html" title="Development">Development</A><BR class="atl-forced-newline">
+<A href="bundles.html" title="Bundles">Bundles</A><BR class="atl-forced-newline">
+<A href="tutorials-how-tos.html" title="Tutorials & How-Tos">Tutorials &amp; How&#45;Tos</A><BR class="atl-forced-newline">
+<A href="configuration.html" title="Configuration">Configuration</A><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/apidocs/sling6/index.html" class="external-link" rel="nofollow">API docs</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.wiki" class="external-link" rel="nofollow">Wiki</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.faq" class="external-link" rel="nofollow">FAQ</A><BR class="atl-forced-newline"></P>
+
+<P><B>Project info</B><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/site/downloads.cgi" class="external-link" rel="nofollow">Downloads</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/licenses/" class="external-link" rel="nofollow">License</A><BR class="atl-forced-newline">
+<A href="contributing.html" title="Contributing">Contributing</A><BR class="atl-forced-newline">
+<A href="news.html" title="News">News</A><BR class="atl-forced-newline">
+<A href="links.html" title="Links">Links</A><BR class="atl-forced-newline">
+<A href="project-information.html" title="Project Information">Project Information</A><BR class="atl-forced-newline">
+<A href="https://issues.apache.org/jira/browse/SLING" class="external-link" rel="nofollow">Issue Tracker</A><BR class="atl-forced-newline">
+<A href="http://svn.apache.org/viewvc/sling/trunk" class="external-link" rel="nofollow">Browse Source Repository</A><BR class="atl-forced-newline">
+<A href="security.html" title="Security">Security</A><BR class="atl-forced-newline"></P>
+
+<P><B>Sponsorship</B><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/thanks.html" class="external-link" rel="nofollow">Thanks</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/sponsorship.html" class="external-link" rel="nofollow">Become a Sponsor</A><BR>
+<A href="http://www.apache.org/foundation/buy_stuff.html" class="external-link" rel="nofollow">Buy Stuff</A></P>
+
+
+  <IFRAME src="http://www.apache.org/ads/button.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="135"></IFRAME>
+  <P style="height: 135px"></P>
+    </DIV>
+    <DIV class="main">
+        <DIV class="breadcrump" style="font-size: 80%;">
+<A href="apache-sling.html" title="Apache Sling Website">Apache Sling Website</A>&nbsp;&gt;&nbsp;<A href="apache-sling.html" title="Apache Sling">Apache Sling</A>&nbsp;&gt;&nbsp;<A href="documentation.html" title="Documentation">Documentation</A>&nbsp;&gt;&nbsp;<A href="bundles.html" title="Bundles">Bundles</A>&nbsp;&gt;&nbsp;<A href="" title="Apache Sling Eventing and Job Handling">Apache Sling Eventing and Job Handling</A>
+        </DIV>
+<P><B>NOTE: This documentation is work in progress!</B></P>
+
+<H2><A name="ApacheSlingEventingandJobHandling-Overview"></A>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:</P>
+<UL>
+	<LI><A href="how-to-manage-events-in-sling.html" title="How to Manage Events in Sling">How to Manage Events in Sling</A></LI>
+	<LI><A href="scheduler-service-commons-scheduler.html" title="Scheduler Service (commons scheduler)">Scheduler Service &#40;commons scheduler&#41;</A></LI>
+</UL>
+
+
+<P>The Sling Event Supports adds the following services:</P>
+<UL>
+	<LI><A href="#ApacheSlingEventingandJobHandling-jobs">Jobs</A></LI>
+	<LI><A href="#ApacheSlingEventingandJobHandling-distributed">Distributed Events</A></LI>
+	<LI><A href="#ApacheSlingEventingandJobHandling-timed">Scheduled Events</A></LI>
+</UL>
+
+
+<P><A name="ApacheSlingEventingandJobHandling-jobs"></A></P>
+<H2><A name="ApacheSlingEventingandJobHandling-Jobs%28GuaranteeofProcessing%29"></A>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 &quot;fire event and forget about it&quot; 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 &quot;at the same time&quot; 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 <B>and</B> 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>
+
+<H3><A name="ApacheSlingEventingandJobHandling-JobProcessors"></A>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>
+
+<H3><A name="ApacheSlingEventingandJobHandling-ProcessingofJobs"></A>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>
+
+<H4><A name="ApacheSlingEventingandJobHandling-QueueConfigurations"></A>Queue Configurations</H4>
+
+<P>A queue configuration can have the following properties:</P>
+
+<DIV class="table-wrap">
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TD class="confluenceTd"> <B>Property Name</B>     </TD>
+<TD class="confluenceTd"> <B>Description</B> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>queue.name</EM>       </TD>
+<TD class="confluenceTd"> 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 class="confluenceTd"> <EM>queue.type</EM>       </TD>
+<TD class="confluenceTd"> The type of the queue: ORDERED, UNORDERED, TOPIC_ROUND_ROBIN, IGNORE, DROP </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>queue.topics</EM>       </TD>
+<TD class="confluenceTd"> 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 class="confluenceTd"> <EM>queue.maxparallel</EM>       </TD>
+<TD class="confluenceTd"> How many jobs can be processed in parallel? -1 for number of processors.</TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>queue.retries</EM>       </TD>
+<TD class="confluenceTd"> How often should the job be retried. -1 for endless retries. </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>queue.retrydelay</EM>       </TD>
+<TD class="confluenceTd"> The waiting time in milliseconds between job retries. </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>queue.priority</EM>       </TD>
+<TD class="confluenceTd"> The thread priority: NORM, MIN, or MAX </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>queue.runlocal</EM>       </TD>
+<TD class="confluenceTd"> Should the jobs only be processed on the cluster node they have been created? </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>queue.applicationids</EM>       </TD>
+<TD class="confluenceTd"> Optional list of application (cluster node) ids. If configured, these jobs are only processed on this application node.</TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>service.ranking</EM> </TD>
+<TD class="confluenceTd"> A ranking for this configuration.</TD>
+</TR>
+</TBODY></TABLE>
+</DIV>
+
+
+<P>The configurations are processed in order of their service ranking. The first matching queue configuration is used for the job.</P>
+
+<H4><A name="ApacheSlingEventingandJobHandling-OrderedQueues"></A>Ordered Queues</H4>
+
+<P>An ordered queue processes one job after the other.</P>
+
+<H4><A name="ApacheSlingEventingandJobHandling-UnorderedQueues"></A>Unordered Queues</H4>
+
+<P>Unordered queues process jobs in parallel.</P>
+
+<H4><A name="ApacheSlingEventingandJobHandling-TopicRoundRobinQueues"></A>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>
+
+<H4><A name="ApacheSlingEventingandJobHandling-IgnoringQueues"></A>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>
+
+<H4><A name="ApacheSlingEventingandJobHandling-DroppingQueues"></A>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>
+
+
+<H3><A name="ApacheSlingEventingandJobHandling-Persistence"></A>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:</P>
+<DIV class="table-wrap">
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TD class="confluenceTd"> <B>Property Name</B>     </TD>
+<TD class="confluenceTd"> <B>Description</B> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>event:topic</EM>       </TD>
+<TD class="confluenceTd"> The topic of the job </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>event:id</EM>          </TD>
+<TD class="confluenceTd"> The unique identifier of this job (optional).</TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>event:created</EM>     </TD>
+<TD class="confluenceTd"> The date and time when the event has been created (stored in the repository)</TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>event:application</EM> </TD>
+<TD class="confluenceTd"> The identifier of the node where the job was created </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>event:properties</EM>  </TD>
+<TD class="confluenceTd"> Serialized properties </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>event:finished</EM>    </TD>
+<TD class="confluenceTd"> The date and time when the job has been finished </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>event:processor</EM>   </TD>
+<TD class="confluenceTd"> The identifier of the node which processed the job (after successful processing) </TD>
+</TR>
+</TBODY></TABLE>
+</DIV>
+
+
+<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>
+
+
+
+<H3><A name="ApacheSlingEventingandJobHandling-DistributionofJobs"></A>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>
+
+<H2><A name="ApacheSlingEventingandJobHandling-UsagePatterns"></A>Usage Patterns</H2>
+
+<P>Based on some usage patterns, we discuss the functionality of the eventing mechanism.</P>
+
+<H3><A name="ApacheSlingEventingandJobHandling-SendingUserGeneratedEvents"></A>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:</P>
+<OL>
+	<LI>Client code generates event using OSGi API, if the <EM>event.distribute</EM> should be set, it is using the ~EventUtil.</LI>
+	<LI>Client code sends the event to the (local) event admin.</LI>
+	<LI>Event admin delivers the event locally.</LI>
+	<LI>Clustering event handler receives the event if <EM>event.distribute</EM> is present
+	<OL>
+		<LI>Event handler adds <EM>event.application</EM> and writes the event to the repository</LI>
+		<LI>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>.</LI>
+	</OL>
+	</LI>
+</OL>
+
+
+<H3><A name="ApacheSlingEventingandJobHandling-ProcessingJCREvents"></A>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:</P>
+<OL>
+	<LI>Client registers for JCR observation</LI>
+	<LI>JCR notifies the client for changes</LI>
+	<LI>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.</LI>
+	<LI>Client code sends the event to the (local) event admin</LI>
+	<LI>Event admin publishes the event locally</LI>
+	<LI>The distribution event handler does not set see the event as the <EM>event.distribute</EM> is not set.</LI>
+	<LI>The job event handler gets the event if it has the job topic
+	<OL>
+		<LI>The job event handler adds the <EM>event.application</EM> property and tries to write the job to the repository
+		<OL>
+			<LI>If no job with the topic and <EM>id</EM> property is in the repository, the event will be written and locked.</LI>
+			<LI>If an event with the topic and <EM>id</EM> property is in the repository then:
+			<OL>
+				<LI>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</LI>
+				<LI>If the <EM>event.application</EM> does not equal the current application node, the event is not distributed locally.</LI>
+			</OL>
+			</LI>
+			<LI>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.</LI>
+		</OL>
+		</LI>
+	</OL>
+	</LI>
+</OL>
+
+
+<H3><A name="ApacheSlingEventingandJobHandling-SendingScheduledEvents"></A>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>
+
+<H3><A name="ApacheSlingEventingandJobHandling-ReceivingOSGiEvents"></A>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-distributed"></A></P>
+<H2><A name="ApacheSlingEventingandJobHandling-DistributedEvents"></A>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>
+
+<H3><A name="ApacheSlingEventingandJobHandling-SourcesofEvents"></A>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:</P>
+<UL>
+	<LI>JCR observation events</LI>
+	<LI>Application generated events</LI>
+	<LI>Events from messaging systems (~JMS)</LI>
+	<LI>&quot;External events&quot;</LI>
+</UL>
+
+
+<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>
+
+<H3><A name="ApacheSlingEventingandJobHandling-WeightsofEvents"></A>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 &quot;simultanously&quot; 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>
+
+<H3><A name="ApacheSlingEventingandJobHandling-BasicPrinciples"></A>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 &quot;distributing everything to everywhere&quot; 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 <B>event</B> mechanism which should not be confused with a <B>messaging</B> 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 &quot;automatic&quot; 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>
+
+<H3><A name="ApacheSlingEventingandJobHandling-DistributedEvents"></A>Distributed Events</H3>
+
+<P>For distributed events two properties are defined (check the <EM>EventUtil</EM> class):</P>
+<UL>
+	<LI><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.</LI>
+	<LI><EM>event.application</EM> - An identifier for the current application node in the cluster. This information will be used to detect if an event has been created on different nodes. If the event has been created on the same node, the <EM>event.application</EM> is missing, if it is a remote event, the <EM>event.application</EM> contains the ID of the node, the event has been initially created. Use the <EM>EventUtil.isLocal(Event)</EM> method to detect if the event is a local or a distributed event.</LI>
+</UL>
+
+
+<P>While the <EM>event.distribute</EM> must be set by the sender of an event (if the event should be distributed), the <EM>event.application</EM> property is maintained by the event mechanism. Therefore a client sending an event should <B>never</B> set this information by itself. This will confuse the local event handlers and result in unexpected behaviour. On remote events the <EM>event.application</EM> is set by the event distribution mechanism.</P>
+
+<H3><A name="ApacheSlingEventingandJobHandling-EventDistributionAcrossApplicationNodes%28Cluster%29"></A>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>
+
+<H3><A name="ApacheSlingEventingandJobHandling-StoringEventsintheRepository"></A>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:</P>
+<DIV class="table-wrap">
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TD class="confluenceTd"> <B>Property Name</B>     </TD>
+<TD class="confluenceTd"> <B>Description</B> </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>event:topic</EM>       </TD>
+<TD class="confluenceTd"> The topic of the event </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>event:application</EM> </TD>
+<TD class="confluenceTd"> The identifier of the application node where the event was created </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>event:created</EM>     </TD>
+<TD class="confluenceTd"> The date and time when the event has been created (stored in the repository)</TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> <EM>event:properties</EM>  </TD>
+<TD class="confluenceTd"> Serialized properties (except the <EM>event.distribute</EM>, but including the <EM>event.application</EM>) </TD>
+</TR>
+</TBODY></TABLE>
+</DIV>
+
+
+<P>Each application is periodically removing old events from the repository (using the scheduler).</P>
+
+
+<P><A name="ApacheSlingEventingandJobHandling-timed"></A></P>
+<H3><A name="ApacheSlingEventingandJobHandling-SendingScheduledEvents"></A>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>
+
+<H3><A name="ApacheSlingEventingandJobHandling-ReceivingOSGiEvents"></A>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>
+
+<H2><A name="ApacheSlingEventingandJobHandling-Scheduler"></A>Scheduler</H2>
+
+<P>Each Sling based application will contain a scheduler service (which is based on the Quartz open source project).</P>
+
+<H2><A name="ApacheSlingEventingandJobHandling-UseCases"></A>Use Cases</H2>
+
+<H3><A name="ApacheSlingEventingandJobHandling-PostProcessing%28BusinessProcesses%29"></A>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>
+
+<H2><A name="ApacheSlingEventingandJobHandling-Scheduling"></A>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 <B>if</B> 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 class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+Last modified by justinedelson on 2010-10-19 10:23:46.0
+        </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>
+    </DIV>
+  </BODY>
+</HTML>
+

Added: websites/staging/sling/trunk/content/site/apache-sling.html
==============================================================================
--- websites/staging/sling/trunk/content/site/apache-sling.html (added)
+++ websites/staging/sling/trunk/content/site/apache-sling.html Wed Dec 12 09:16:44 2012
@@ -0,0 +1,185 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+  <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">
+<P><B>Documentation</B><BR class="atl-forced-newline">
+<A href="getting-started.html" title="Getting Started">Getting Started</A><BR class="atl-forced-newline">
+<A href="the-sling-engine.html" title="The Sling Engine">The Sling Engine</A><BR class="atl-forced-newline">
+<A href="development.html" title="Development">Development</A><BR class="atl-forced-newline">
+<A href="bundles.html" title="Bundles">Bundles</A><BR class="atl-forced-newline">
+<A href="tutorials-how-tos.html" title="Tutorials & How-Tos">Tutorials &amp; How&#45;Tos</A><BR class="atl-forced-newline">
+<A href="configuration.html" title="Configuration">Configuration</A><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/apidocs/sling6/index.html" class="external-link" rel="nofollow">API docs</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.wiki" class="external-link" rel="nofollow">Wiki</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.faq" class="external-link" rel="nofollow">FAQ</A><BR class="atl-forced-newline"></P>
+
+<P><B>Project info</B><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/site/downloads.cgi" class="external-link" rel="nofollow">Downloads</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/licenses/" class="external-link" rel="nofollow">License</A><BR class="atl-forced-newline">
+<A href="contributing.html" title="Contributing">Contributing</A><BR class="atl-forced-newline">
+<A href="news.html" title="News">News</A><BR class="atl-forced-newline">
+<A href="links.html" title="Links">Links</A><BR class="atl-forced-newline">
+<A href="project-information.html" title="Project Information">Project Information</A><BR class="atl-forced-newline">
+<A href="https://issues.apache.org/jira/browse/SLING" class="external-link" rel="nofollow">Issue Tracker</A><BR class="atl-forced-newline">
+<A href="http://svn.apache.org/viewvc/sling/trunk" class="external-link" rel="nofollow">Browse Source Repository</A><BR class="atl-forced-newline">
+<A href="security.html" title="Security">Security</A><BR class="atl-forced-newline"></P>
+
+<P><B>Sponsorship</B><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/thanks.html" class="external-link" rel="nofollow">Thanks</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/sponsorship.html" class="external-link" rel="nofollow">Become a Sponsor</A><BR>
+<A href="http://www.apache.org/foundation/buy_stuff.html" class="external-link" rel="nofollow">Buy Stuff</A></P>
+
+
+  <IFRAME src="http://www.apache.org/ads/button.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="135"></IFRAME>
+  <P style="height: 135px"></P>
+    </DIV>
+    <DIV class="main">
+        <DIV class="breadcrump" style="font-size: 80%;">
+<A href="" title="Apache Sling Website">Apache Sling Website</A>&nbsp;&gt;&nbsp;<A href="" title="Apache Sling">Apache Sling</A>
+        </DIV>
+<H1><A name="ApacheSling-ApacheSlingBringingBacktheFun"></A>Apache Sling - Bringing Back the Fun</H1>
+
+<P><SPAN class="tm mark "><B>Apache Sling</B><SMALL><SUP>TM</SUP></SMALL></SPAN>
+ 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" title="Project Information">Project Information</A> page for more info.</P>
+
+<H1><A name="ApacheSling-ApacheSlinginfivebulletspoints"></A>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>
+
+
+<H1><A name="ApacheSling-ApacheSlinginahundredwords"></A>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" class="external-link" rel="nofollow">Java Content Repository</A>, such as <A href="http://jackrabbit.apache.org/" class="external-link" rel="nofollow">Apache Jackrabbit</A>, 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/" class="external-link" rel="nofollow">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" class="external-link" rel="nofollow">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>
+
+<H2><A name="ApacheSling-News"></A>News</H2>
+
+<P><UL>
+	<LI>New Release: Apache Sling Servlet Resolver 2.2.2 (December 10th, 2012)</LI>
+	<LI>New Releases: Apache Sling Settings 1.2.2, Apache Sling Auth Core 1.1.0, Apache Sling Commons Logservice 1.0.2, Apache Sling Installer Core 3.4.2, Apache Sling Scripting JSP 2.0.26, Apache Sling Commons Compiler 2.1.0, Apache Sling JCR Compiler 2.1.0, Apache Sling I18n 2.2.4, Apache Sling JCR Classloader 3.1.10, Apache Sling JCR Webdav 2.1.2, Apache Sling JCR Davex 1.1.0 (November 30th, 2012)</LI>
+	<LI>New Releases: Apache Sling Maven Launchpad Plugin 2.2.0, Apache Sling Commons OSGi 2.2.0, Apache Sling Launchpad Installer 1.2.0, Apache Sling Rewriter 1.0.4, Apache Sling Settings 1.2.0 (November 19th, 2012)</LI>
+	<LI>New Releases: Apache Sling API 2.3.0, Apache Sling Bundle Resource Provider 2.1.0, Apache Sling File System Resource Provider 1.1.0, Apache Sling JCR Resource 2.2.0, Apache Sling Resource Resolver 1.0.0, Apache Sling Servlets Get 2.1.4, Apache Sling Servlets Post 2.2.0, Apache Sling Servlets Resolver 2.2.0, Apache Sling Adapter 2.1.0, Apache Sling Commons Testing 2.0.12 (November 15th, 2012)</LI>
+	<LI>New Release: Apache Sling JSP Taglib 2.1.8, Apache Sling Installer Core 3.4.0, Apache Sling Installer API 1.0.0, Apache Sling Installer Console 1.0.0, Apache Sling JCR Wrapper 2.0.0 (October 29th, 2012)</LI>
+	<LI>New Releases: Apache Sling Installer Core 3.3.8, Apache Sling Launchpad Installer 1.1.4, and Apache Sling Maven Launchpad Plugin 2.1.2 (August 19th, 2012)</LI>
+</UL>
+</P>
+<UL>
+	<LI><A href="news.html" title="News">all news...</A></LI>
+</UL>
+
+
+<H2><A name="ApacheSling-History"></A>History</H2>
+
+<P>Sling started as an internal project at <A href="http://www.day.com/" class="external-link" rel="nofollow">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 &quot;Sling&quot; has been proposed by Roy Fielding who explained it like this:</P>
+
+<BLOCKQUOTE>
+<P>[The name is] 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.</P></BLOCKQUOTE>
+
+
+<H2><A name="ApacheSling-WhousesSling%3F"></A>Who uses Sling?</H2>
+
+<P>See <A href="http://cwiki.apache.org/SLING/who-is-using-sling-.html" class="external-link" rel="nofollow">Who is using Sling</A> on our public wiki.</P>
+
+<H2><A name="ApacheSling-Gettingstarted"></A>Getting started</H2>
+
+<P>If you prefer doing rather than reading, please proceed to <A href="discover-sling-in-15-minutes.html" title="Discover Sling in 15 minutes">Discover Sling in 15 minutes</A> or read through the recommended links in the <A href="getting-started.html" title="Getting Started">Getting Started</A> section, where you can quickly get started on your own instance of Sling.</P>
+
+<H2><A name="ApacheSling-Contents"></A>Contents</H2>
+
+<UL>
+	<LI><A href="documentation.html" title="Documentation">Documentation</A> &#45; Here you will find the documentation on Sling</LI>
+	<LI><A href="development.html" title="Development">Development</A> &ndash; Documentation on how to develop web applications with Sling and what tools you have at your disposal</LI>
+	<LI><A href="links.html" title="Links">Links</A></LI>
+	<LI><A href="http://cwiki.apache.org/SLING/" class="external-link" rel="nofollow">Wiki</A></LI>
+	<LI><A href="http://cwiki.apache.org/SLING/faq.html" class="external-link" rel="nofollow">FAQ</A></LI>
+	<LI><A href="project-information.html" title="Project Information">Project Information</A></LI>
+</UL>
+
+
+
+<H2><A name="ApacheSling-UseCasesforSling"></A>Use Cases for Sling</H2>
+
+
+<H4><A name="ApacheSling-Wiki"></A>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>
+
+
+
+<H4><A name="ApacheSling-DigitalAssetManagement"></A>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>
+
+
+
+<H4><A name="ApacheSling-WebContentManagement"></A>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>
+
+
+<H2><A name="ApacheSling-References"></A>References</H2>
+
+
+<H4><A name="ApacheSling-ApacheJackrabbit"></A>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/" class="external-link" rel="nofollow">Apache Jackrabbit</A> is provided out of the box.</P>
+
+<H4><A name="ApacheSling-OSGi"></A>OSGi</H4>
+
+<P>Sling is implemented as a series of <A href="http://www.osgi.org/" class="external-link" rel="nofollow">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>
+
+<H4><A name="ApacheSling-ApacheFelix"></A>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/" class="external-link" rel="nofollow">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 <A href="http://www.eclipse.org/equinox" class="external-link" rel="nofollow">Equinox</A> and <A href="http://www.knopflerfish.org/" class="external-link" rel="nofollow">Knopflerfish</A>.</P>
+        <DIV class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+Last modified by bdelacretaz on 2012-04-03 11:06:05.0
+        </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>
+    </DIV>
+  </BODY>
+</HTML>
+

Added: websites/staging/sling/trunk/content/site/architecture.html
==============================================================================
--- websites/staging/sling/trunk/content/site/architecture.html (added)
+++ websites/staging/sling/trunk/content/site/architecture.html Wed Dec 12 09:16:44 2012
@@ -0,0 +1,172 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+  <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">
+<P><B>Documentation</B><BR class="atl-forced-newline">
+<A href="getting-started.html" title="Getting Started">Getting Started</A><BR class="atl-forced-newline">
+<A href="the-sling-engine.html" title="The Sling Engine">The Sling Engine</A><BR class="atl-forced-newline">
+<A href="development.html" title="Development">Development</A><BR class="atl-forced-newline">
+<A href="bundles.html" title="Bundles">Bundles</A><BR class="atl-forced-newline">
+<A href="tutorials-how-tos.html" title="Tutorials & How-Tos">Tutorials &amp; How&#45;Tos</A><BR class="atl-forced-newline">
+<A href="configuration.html" title="Configuration">Configuration</A><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/apidocs/sling6/index.html" class="external-link" rel="nofollow">API docs</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.wiki" class="external-link" rel="nofollow">Wiki</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.faq" class="external-link" rel="nofollow">FAQ</A><BR class="atl-forced-newline"></P>
+
+<P><B>Project info</B><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/site/downloads.cgi" class="external-link" rel="nofollow">Downloads</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/licenses/" class="external-link" rel="nofollow">License</A><BR class="atl-forced-newline">
+<A href="contributing.html" title="Contributing">Contributing</A><BR class="atl-forced-newline">
+<A href="news.html" title="News">News</A><BR class="atl-forced-newline">
+<A href="links.html" title="Links">Links</A><BR class="atl-forced-newline">
+<A href="project-information.html" title="Project Information">Project Information</A><BR class="atl-forced-newline">
+<A href="https://issues.apache.org/jira/browse/SLING" class="external-link" rel="nofollow">Issue Tracker</A><BR class="atl-forced-newline">
+<A href="http://svn.apache.org/viewvc/sling/trunk" class="external-link" rel="nofollow">Browse Source Repository</A><BR class="atl-forced-newline">
+<A href="security.html" title="Security">Security</A><BR class="atl-forced-newline"></P>
+
+<P><B>Sponsorship</B><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/thanks.html" class="external-link" rel="nofollow">Thanks</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/sponsorship.html" class="external-link" rel="nofollow">Become a Sponsor</A><BR>
+<A href="http://www.apache.org/foundation/buy_stuff.html" class="external-link" rel="nofollow">Buy Stuff</A></P>
+
+
+  <IFRAME src="http://www.apache.org/ads/button.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="135"></IFRAME>
+  <P style="height: 135px"></P>
+    </DIV>
+    <DIV class="main">
+        <DIV class="breadcrump" style="font-size: 80%;">
+<A href="apache-sling.html" title="Apache Sling Website">Apache Sling Website</A>&nbsp;&gt;&nbsp;<A href="apache-sling.html" title="Apache Sling">Apache Sling</A>&nbsp;&gt;&nbsp;<A href="documentation.html" title="Documentation">Documentation</A>&nbsp;&gt;&nbsp;<A href="the-sling-engine.html" title="The Sling Engine">The Sling Engine</A>&nbsp;&gt;&nbsp;<A href="" title="Architecture">Architecture</A>
+        </DIV>
+<H1><A name="Architecture-ArchitectureofSling"></A>Architecture of Sling</H1>
+
+<P>The following is a short list of high-lights of Sling:</P>
+
+<UL>
+	<LI><B><A href="#Architecture-OSGi">OSGi</A></B> &mdash; The Sling application is built as a series of OSGi bundles and makes heavy use of a number of OSGi core and compendium services.</LI>
+	<LI><B><A href="#Architecture-SlingAPI">Sling API</A></B> &mdash; To implement content based Web applications with Sling, an API has been defined, this extends the Servlet API and provides more functionality to work on the content.</LI>
+	<LI><B><A href="#Architecture-RequestProcessing">Request Processing</A></B> &mdash; Sling takes a unique approach to handling requests in that a request URL is first resolved to a resource, then based on the resource (and only the resource) it selects the actual servlet or script to handle the request.</LI>
+	<LI><B><A href="#Architecture-Resources">Resources</A></B> &mdash; The central mantra of Sling is the <B>Resource</B>, 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><B><A href="#Architecture-ServletsandScripts">Servlets and Scripts</A></B> &mdash; Servlets and Scripts are handled uniformly in that they are represented as resources themselves and are accessible by a resource path.</LI>
+	<LI><B><A href="#Architecture-Launchpad">Launchpad</A></B> &mdash; Sling uses a very thin launcher to integrate with an existing servlet container, launching Sling as a Web application or providing a main class to represent a standalone Java application.</LI>
+</UL>
+
+
+<P>The following sections elaborate on each of these highlights.</P>
+
+<H2><A name="Architecture-OSGi"></A>OSGi</H2>
+
+<P><A href="http://www.osgi.org/" class="external-link" rel="nofollow">OSGi</A> is a consortium that has developed a specification to build modular and extensible applications. This offers <A href="http://www.osgi.org/About/WhyOSGi" class="external-link" rel="nofollow">various benefits</A>. 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>
+
+<H3><A name="Architecture-OSGiFramework"></A>OSGi Framework</H3>
+
+<P>The OSGi Framework is made up of three layers &ndash; Module, Lifecycle, and Services &ndash; that define how extensible applications are built and deployed. The responsibilities of the layers are:</P>
+
+<UL>
+	<LI><B>Module</B> &mdash; 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 &ndash; <TT>Export-Package</TT> &ndash; and what a bundle requires to be operative &ndash; <TT>Import-Package</TT> and <TT>Require-Bundle</TT>.</LI>
+	<LI><B>Lifecycle</B> &mdash; The lifecycle layer defines the states a bundle may be in and describes the state changes. By providing a class, which implements the <TT>BundleActivator</TT> interface and which is named in the <TT>Bundle-Activator</TT> manifest header, a bundle may hook into the lifecycle process when the bundle is started and stopped.</LI>
+	<LI><B>Services</B> &mdash; For the application to be able to interact, the OSGi Core Specification defines the service layer. This describes a registry for services, which may be shared.</LI>
+</UL>
+
+
+
+<H3><A name="Architecture-CompendiumServices"></A>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><B>Log Service</B> &mdash; Sling comes with its own implementation of the OSGi Log Service specification. The respective bundle not only provides this implementation, it also exports the SLF4J, Log4J and Commons Logging APIs needed for the Sling application to perform logging.</LI>
+	<LI><B>Http Service</B> &mdash; Sling leverages the OSGi Http Service to hook into a servlet container to provide the Web Application Framework mechanism.</LI>
+	<LI><B>Configuration Admin Service</B> &mdash; To simplify configuration of services in Sling, the OSGi Configuration Admin service is used. This provides a uniform API to configure services and to build configuration management agents.</LI>
+	<LI><B>Metatype Service</B> &mdash; The OSGi Metatype Service defines a way to describe the data types. Sling uses this service to describe the configurations that may be created using the Configuration Admin Service. These meta type descriptions are used by configuration management agents to present to user interface to manage the configurations.</LI>
+	<LI><B>Event Admin Service</B> &mdash; Sling uses the OSGi EventAdmin service to dispatch events when scheduling tasks.</LI>
+	<LI><B>Declarative Services</B> &mdash; One of the most important (beside the Log Service) services used by Sling is the Declarative Services Specification. This specification defines how to declaratively create components and services to have the Declarative Services runtime actually manage the lifecycle, configuration and references of components.</LI>
+</UL>
+
+
+
+<H2><A name="Architecture-SlingAPI"></A>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" title="Sling API">Sling API</A> page for more information.</P>
+
+
+<H2><A name="Architecture-RequestProcessing"></A>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 <TT>Resource</TT> 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" title="Servlets">Servlets</A> page for more information.</P>
+
+
+<H2><A name="Architecture-Resources"></A>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 <TT>Resource</TT> instance actually is only a handle to the actual data. By virtue of the <TT>adaptTo(Class&lt;Type&gt;)</TT> method, a resource may be coerced into another data type, which may then be used while processing the request. Examples of data types are <TT>javax.jcr.Node</TT> and <TT>java.io.InputStream</TT>.</P>
+
+<P>See the <A href="resources.html" title="Resources">Resources</A> page for more information.</P>
+
+
+<H2><A name="Architecture-ServletsandScripts"></A>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 <TT>Resource.adaptTo(Class&lt;Type&gt;)</TT> 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 <TT>javax.servlet.Servlet</TT> 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 <TT>javax.jcr.Servlet</TT>. 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" title="Servlet Resolution">Servlet Resolution</A> page for more information.</P>
+
+
+
+<H2><A name="Architecture-Launchpad"></A>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 <TT>HttpService</TT> 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 <TT>HttpService</TT>. Regardless of how Sling is launched, the Felix implementation of the OSGi <TT>HttpService</TT> 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" title="Maven Launchpad Plugin">Maven Launchpad Plugin</A> page for information on how to do this.</P>
+
+<P>See <A href="the-sling-launchpad.html" title="The Sling Launchpad">The Sling Launchpad</A> for more information.</P>
+
+
+        <DIV class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+Last modified by aheimoz on 2010-11-12 08:16:36.0
+        </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>
+    </DIV>
+  </BODY>
+</HTML>
+

Added: websites/staging/sling/trunk/content/site/assembly.html
==============================================================================
--- websites/staging/sling/trunk/content/site/assembly.html (added)
+++ websites/staging/sling/trunk/content/site/assembly.html Wed Dec 12 09:16:44 2012
@@ -0,0 +1,216 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+  <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">
+<P><B>Documentation</B><BR class="atl-forced-newline">
+<A href="getting-started.html" title="Getting Started">Getting Started</A><BR class="atl-forced-newline">
+<A href="the-sling-engine.html" title="The Sling Engine">The Sling Engine</A><BR class="atl-forced-newline">
+<A href="development.html" title="Development">Development</A><BR class="atl-forced-newline">
+<A href="bundles.html" title="Bundles">Bundles</A><BR class="atl-forced-newline">
+<A href="tutorials-how-tos.html" title="Tutorials & How-Tos">Tutorials &amp; How&#45;Tos</A><BR class="atl-forced-newline">
+<A href="configuration.html" title="Configuration">Configuration</A><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/apidocs/sling6/index.html" class="external-link" rel="nofollow">API docs</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.wiki" class="external-link" rel="nofollow">Wiki</A><BR class="atl-forced-newline">
+<A href="http://s.apache.org/sling.faq" class="external-link" rel="nofollow">FAQ</A><BR class="atl-forced-newline"></P>
+
+<P><B>Project info</B><BR class="atl-forced-newline">
+<A href="http://sling.apache.org/site/downloads.cgi" class="external-link" rel="nofollow">Downloads</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/licenses/" class="external-link" rel="nofollow">License</A><BR class="atl-forced-newline">
+<A href="contributing.html" title="Contributing">Contributing</A><BR class="atl-forced-newline">
+<A href="news.html" title="News">News</A><BR class="atl-forced-newline">
+<A href="links.html" title="Links">Links</A><BR class="atl-forced-newline">
+<A href="project-information.html" title="Project Information">Project Information</A><BR class="atl-forced-newline">
+<A href="https://issues.apache.org/jira/browse/SLING" class="external-link" rel="nofollow">Issue Tracker</A><BR class="atl-forced-newline">
+<A href="http://svn.apache.org/viewvc/sling/trunk" class="external-link" rel="nofollow">Browse Source Repository</A><BR class="atl-forced-newline">
+<A href="security.html" title="Security">Security</A><BR class="atl-forced-newline"></P>
+
+<P><B>Sponsorship</B><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/thanks.html" class="external-link" rel="nofollow">Thanks</A><BR class="atl-forced-newline">
+<A href="http://www.apache.org/foundation/sponsorship.html" class="external-link" rel="nofollow">Become a Sponsor</A><BR>
+<A href="http://www.apache.org/foundation/buy_stuff.html" class="external-link" rel="nofollow">Buy Stuff</A></P>
+
+
+  <IFRAME src="http://www.apache.org/ads/button.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="135"></IFRAME>
+  <P style="height: 135px"></P>
+    </DIV>
+    <DIV class="main">
+        <DIV class="breadcrump" style="font-size: 80%;">
+<A href="apache-sling.html" title="Apache Sling Website">Apache Sling Website</A>&nbsp;&gt;&nbsp;<A href="apache-sling.html" title="Apache Sling">Apache Sling</A>&nbsp;&gt;&nbsp;<A href="old-stuff.html" title="Old Stuff">Old Stuff</A>&nbsp;&gt;&nbsp;<A href="" title="Assembly">Assembly</A>
+        </DIV>
+<H1><A name="Assembly-Assembly%3ABundlingBundles"></A>Assembly: Bundling Bundles</H1>
+
+<DIV class="panel" style="border-width: 1px;"><DIV class="panelContent">
+<P>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.</P>
+</DIV></DIV>
+
+<H2><A name="Assembly-Introduction"></A>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>
+
+
+
+<H2><A name="Assembly-Bundles"></A>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 <TT>META-INF/MANIFEST.MF</TT> file - contains specific headers identifying the bundle. Most manifest headers are optional with defined default values - only the <TT>Bundle-SymbolicName</TT> header is actually required and the <TT>Bundle-ManifestVersion</TT> header should be set to <TT>2</TT> 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>
+
+
+
+<H2><A name="Assembly-Assemblies"></A>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>
+
+
+
+<H3><A name="Assembly-Assemblymanifestheaders"></A>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><B>Assembly-Bundles</B> - 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><B>Assembly-BundleRepository</B> - A comma-separated list of URLs pointing to OSGi Bundle Repository descriptors. These bundle repositories will be used to install bundles listed in the <TT>Assembly-Bundles</TT> header. This header is optional with not default value.</LI>
+</UL>
+
+
+
+
+<H3><A name="Assembly-AssemblyLifecycle"></A>Assembly Lifecycle</H3>
+
+<P>An Assembly, like all bundles, may be in any of the defined bundle states:</P>
+
+<UL>
+	<LI><B>Installed</B> - 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 <TT>Assembly-Bundles</TT> header. The start levels of the bundles will be set according to the <TT>startlevel</TT> 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><B>Resolved</B> - 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><B>Started</B> - The Assembly bundle has been started by calling the <TT>Bundle.start()</TT> 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><B>Stopped</B> - The Assembly bundle has been stopped by calling the <TT>Bundle.stop()</TT> method. All bundles belong to the Assembly and linked to the Assembly are also stopped.</LI>
+	<LI><B>Unresolved</B> - 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><B>Uninstalled</B> - The Assembly bundle is being uninstalled by calling the <TT>Bundle.uninstall()</TT> method. The <EM>Assembly Manager</EM> will (try to) uninstall all bundles listed in the <TT>Assembly-Bundles</TT> header.</LI>
+	<LI><B>Updated</B> - The Assembly bundle will update all bundles installed previously according to the <TT>Assembly-Bundles</TT> 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>
+
+
+
+
+<H3><A name="Assembly-BundlesreferencedbymultipleAssemblyBundles"></A>Bundles referenced by multiple Assembly Bundles</H3>
+
+<P>It is conceivable, that bundles are listed in the <TT>Assembly-Bundles</TT> 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 <TT>Assembly-Bundles</TT> 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>
+
+
+
+
+<H3><A name="Assembly-BundleInstallation"></A>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 <TT>Assembly-Bundles</TT> 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="preformatted panel" style="border-width: 1px;"><DIV class="preformattedContent panelContent">
+<PRE>Assembly-Bundles = Bundle { &quot;,&quot; Bundle } .
+Bundle = Symbolic-Name { &quot;;&quot; Parameter } .
+Symbolic-Name = // The Bundle symbolic name 
+Parameter = ParameterName &quot;=&quot; ParameterValue .
+</PRE>
+</DIV></DIV>
+
+<P>To control the selection and installation of bundles, the following parameters may be used:</P>
+
+<UL>
+	<LI><B>version</B> - 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><SUB>[1.2.3, &infin;</SUB>)</EM>. The default value is <EM><SUB>[0.0.0,&infin;</SUB>)</EM> to install the most recent version of the bundle available.</LI>
+	<LI><B>startlevel</B> - 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><B>entry</B> - The path of the Assembly Bundle entry providing the data to be installed.</LI>
+	<LI><B>linked</B> - Defines whether the bundle should be started and stopped together with the Assembly to which the bundle belongs. Default value is <TT>true</TT>.</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>
+
+
+<H3><A name="Assembly-BundleLocation"></A>Bundle Location</H3>
+
+<P>Generally bundles to be installed with an Assembly Bundle are retrieved from an OSGi Bundle Repository. The <TT>Assembly-BundleRepository</TT> 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 <TT>Assembly-Bundles</TT> header with an <TT>entry</TT> 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 <TT>entry</TT> 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><B>Dependency Resolution</B> - 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><B><TT>version</TT> Parameter</B> - The <TT>version</TT> 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 <TT>Assembly-BundleRepository</TT> 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 <TT>Assembly-Bundles</TT> header are resolved through the OSGi Bundle Repository Service using the URL from the <TT>Assembly-BundleRepository</TT> 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><B>Example</B> - Assume the <TT>Assembly-Bundles</TT> header is set to <TT>org.apache.sling.sample1;entry=path.jar,org.apache.sling.sample2</TT>. The bundle <TT>org.apache.sling.sample1</TT> is then installed from the Assembly Bundle entry <TT>path.jar</TT>, while the bundle <TT>org.apache.sling.sample2</TT> is resolved in the OSGi Bundle Repository.</LI>
+</UL>
+
+
+
+
+
+<H2><A name="Assembly-BestPractices"></A>Best Practices</H2>
+
+
+<H3><A name="Assembly-SizeofBundles"></A>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 <IMG class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/smile.gif" height="20" width="20" align="absmiddle" alt="" border="0"> )</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>
+
+
+
+<H3><A name="Assembly-NomenestOmen"></A>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 <TT>org.apache.sling.sample</TT>, <TT>org.apache.sling.sample.impl</TT>, <TT>org.apache.sling.more</TT>. The bundle would the be named <TT>org.apache.sling.sample</TT>.</P>
+        <DIV class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+Last modified by mykee on 2008-02-11 05:20:05.0
+        </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>
+    </DIV>
+  </BODY>
+</HTML>
+



Mime
View raw message