You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bu...@apache.org on 2012/05/22 11:41:27 UTC
svn commit: r818667 [15/18] - in /websites/staging/sling/trunk/content: ./
authentication/ documentation/ documentation/bundles/
documentation/development/ documentation/getting-started/
documentation/the-sling-engine/ documentation/the-sling-engine/au...
Added: websites/staging/sling/trunk/content/documentation/tutorials-how-tos/jackrabbit-persistence.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/tutorials-how-tos/jackrabbit-persistence.html (added)
+++ websites/staging/sling/trunk/content/documentation/tutorials-how-tos/jackrabbit-persistence.html Tue May 22 09:41:22 2012
@@ -0,0 +1,177 @@
+<!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 - Jackrabbit Persistence</title>
+ <link rel="stylesheet" href="/css/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><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</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>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a>
+ </div>
+ <h1>Jackrabbit Persistence</h1>
+ <h1 id="jackrabbit-persistence">Jackrabbit Persistence</h1>
+<p>Out-of-the-box the embedded Jackrabbit repository used by Sling (the Embedded Jackrabbit Repository bundle) uses Derby to persist the JCR nodes and properties. For some applications or environments it may be required or required to replace Derby with another backing store such as PostgreSQL or Oracle.</p>
+<p>This page is based on the journey of Tony Giaccone to get Sling running with a PostgreSQL based Jackrabbit instance.</p>
+<h2 id="management-summary">Management Summary</h2>
+<p>To replace Derby as the persistence manager for Jackrabbit the following steps are required:</p>
+<ol>
+<li>Provide a JDBC driver for your database as an OSGi bundle</li>
+<li>Reconfigure Jackrabbit to use your database</li>
+<li>(Re-) Start the Embedded Jackrabbit bundle</li>
+</ol>
+<p>When you are not using the Derby persistence manager, you may safely remove the Derby bundle from your Sling instance.</p>
+<h2 id="jdbc-driver">JDBC Driver</h2>
+<p>The hardest thing to do is probably getting the JDBC driver for your database. One option is to look at the bundles provided by Spring Source in their repository at http://www.springsource.com/repository/.</p>
+<p>Another option is to create the bundle on your own using Peter Kriens' <a href="">BND Tool</a>:</p>
+<ol>
+<li>Get the JDBC driver for your database from the driver provider</li>
+<li>
+<p>Wrap the JDBC driver library into an OSGi bundle:</p>
+<h1 id="example-for-postgresql-jdbc-3-driver-84-701">Example for PostgreSQL JDBC 3 driver 8.4-701</h1>
+<p>$ java -jar bnd.jar wrap postgresql-8.4-701.jdbc3.jar
+$ mv postgresql-8.4-701.jdbc3.bar postgresql-8.4-701.jdbc3-bnd.jar</p>
+</li>
+<li>
+<p>Deploy the driver to your local Maven 2 Repository (Required if adding the JDBC driver to a Maven build, e.g. using the Sling Launchpad Plugin)</p>
+<p>$ mvn install:install-file -DgroupId=postgresql -DartifactId=postgresql -Dversion=8.4.701.jdbc3 \
+ -Dpackaging=jar -Dfile=postgresql-8.4-701.jdbc3-bnd.jar </p>
+</li>
+</ol>
+<p>Tony reports no success with the Spring Source bundle, whily the BND approach worked for the PostgreSQL JDBC driver.</p>
+<h2 id="replace-derby-in-a-running-sling-instance">Replace Derby in a running Sling Instance</h2>
+<p>To replace Derby in a running Sling instance follow these steps (e.g. through the Web Console at <code>/system/console</code>):</p>
+<ol>
+<li>Uninstall the Apache Derby bundle</li>
+<li>Install the JDBC bundle prepared in the first step</li>
+<li>Stop the Jackrabbit Embedded Repository bundle\
+This needs to be reconfigured and restarted anyway. So lets just stop it to prevent failures in the next step.</li>
+<li>Refresh the packages (click the <em>Refresh Packages</em> button)</li>
+</ol>
+<p>Alternatively, you may wish to stop Sling after uninstalling Derby and installing the JDBC bundle. Technically, this is not required, though.</p>
+<h2 id="reconfiguring-jackrabbit">Reconfiguring Jackrabbit</h2>
+<p>To actually use a persistence manager other than the default (Derby) persistence manager, you have to configure Jackrabbit to use it. Create a <code>repository.xml</code> file in the <code>sling/jackrabbit</code> folder before starting Sling for the first time. If the repository was already started, you can also modify the existing file.</p>
+<p>To prepare a repository.xml file before first startup, use the <code>[repository.xml]()</code> as a template and modify it by replacing the <code><PersistenceManager></code> elements to refer to the selected persistence manager.</p>
+<p>If the file already exists, you can modifiy this existing file and there is no need to get the original from the SVN repository.</p>
+<p>For example to use PostgreSQL instead of Derby modify the <code><PersistenceManager></code> elements as follows:</p>
+<div class="codehilite"><pre><span class="nt"><Repository></span>
+ ...
+ <span class="nt"><Workspace</span> <span class="na">name=</span><span class="s">"</span><span class="cp">${</span><span class="n">wsp</span><span class="o">.</span><span class="n">name</span><span class="cp">}</span><span class="s">"</span><span class="nt">></span>
+ ...
+ <span class="nt"><PersistenceManager</span> <span class="na">class=</span><span class="s">"org.apache.jackrabbit.core.persistence.bundle.PostgreSQLPersistenceManager"</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"driver"</span> <span class="na">value=</span><span class="s">"org.postgresql.Driver"/</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"url"</span> <span class="na">value=</span><span class="s">"jdbc:postgresql://localhost:5432/YOUR_DB_NAME_HERE"/</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"schema"</span> <span class="na">value=</span><span class="s">"postgresql"/</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"user"</span> <span class="na">value=</span><span class="s">"YOUR_USER_HERE"/</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"password"</span> <span class="na">value=</span><span class="s">"YOUR_PASSWORD_HERE"/</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"schemaObjectPrefix"</span> <span class="na">value=</span><span class="s">"jcr_</span><span class="cp">${</span><span class="n">wsp</span><span class="o">.</span><span class="n">name</span><span class="cp">}</span><span class="s">_"/</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"externalBLOBs"</span> <span class="na">value=</span><span class="s">"false"/</span><span class="nt">></span>
+ <span class="nt"></PersistenceManager></span>
+ ...
+ <span class="nt"></Workspace></span>
+
+ <span class="nt"><Versioning</span> <span class="na">rootPath=</span><span class="s">"</span><span class="cp">${</span><span class="n">rep</span><span class="o">.</span><span class="n">home</span><span class="cp">}</span><span class="s">/version"</span><span class="nt">></span>
+ ...
+ <span class="nt"><PersistenceManager</span> <span class="na">class=</span><span class="s">"org.apache.jackrabbit.core.persistence.bundle.PostgreSQLPersistenceManager"</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"driver"</span> <span class="na">value=</span><span class="s">"org.postgresql.Driver"/</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"url"</span> <span class="na">value=</span><span class="s">"jdbc:postgresql://localhost:5432/YOUR_DB_NAME_HERE"/</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"schema"</span> <span class="na">value=</span><span class="s">"postgresql"/</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"user"</span> <span class="na">value=</span><span class="s">"YOUR_USER_HERE"/</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"password"</span> <span class="na">value=</span><span class="s">"YOUR_PASSWORD_HERE"/</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"schemaObjectPrefix"</span> <span class="na">value=</span><span class="s">"version_"/</span><span class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span class="s">"externalBLOBs"</span> <span class="na">value=</span><span class="s">"false"/</span><span class="nt">></span>
+ <span class="nt"></PersistenceManager></span>
+ <span class="nt"></Versioning></span>
+ ...
+<span class="nt"></Repository></span>
+</pre></div>
+
+
+<p>Modify the <code>url</code>, <code>user</code>, and <code>password</code> parameters to match your database setup.</p>
+<p>If you reconfigure Jackrabbit to use the new persistence manager, the existing repository data in the <code>sling/jackrabbit</code> directory, except the <code>repository.xml</code> file, of course, should now be removed.</p>
+<p>Finally either start Sling or start the Jackrabbit Embedded Repository bundle.</p>
+<h2 id="credits">Credits</h2>
+<p>This description is based on Tony Giaccone's description <a href="">Swapping Postgres for Derby</a> sent to the Sling Users mailing list.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
+ </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/documentation/tutorials-how-tos/testing-sling-based-applications.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/tutorials-how-tos/testing-sling-based-applications.html (added)
+++ websites/staging/sling/trunk/content/documentation/tutorials-how-tos/testing-sling-based-applications.html Tue May 22 09:41:22 2012
@@ -0,0 +1,155 @@
+<!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 - Testing Sling-based applications</title>
+ <link rel="stylesheet" href="/css/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><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</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>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a>
+ </div>
+ <h1>Testing Sling-based applications</h1>
+ <h1 id="testing-sling-based-applications">Testing Sling-based applications</h1>
+<p>Automated testing of OSGi components and services can be challenging, as many of them depend on other services that must be present or simulated for testing.</p>
+<p>This page describes the various approaches that we use to test Sling itself, and introduces a number of tools that can help testing OSGi and HTTP-based applications.</p>
+<div class="toc">
+<ul>
+<li><a href="#testing-sling-based-applications">Testing Sling-based applications</a><ul>
+<li><a href="#unit-tests">Unit tests</a></li>
+<li><a href="#tests-that-use-a-jcr-repository">Tests that use a JCR repository</a></li>
+<li><a href="#mock-classes-and-services">Mock classes and services</a><ul>
+<li><a href="#side-note-injecting-services-in-private-fields">Side note: injecting services in private fields</a></li>
+</ul>
+</li>
+<li><a href="#pax-exam">Pax Exam</a></li>
+<li><a href="#sling-testing-tools-server-side-junit-tests">Sling testing tools: server-side JUnit tests</a></li>
+<li><a href="#http-based-integration-tests">HTTP-based integration tests</a></li>
+<li><a href="#summary">Summary</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<h2 id="unit-tests">Unit tests</h2>
+<p>When possible, unit tests are obviously the fastest executing ones, and it's easy to keep them close to the code that they're testing. </p>
+<p>We have quite a lot of those in Sling, the older use the JUnit3 TestCase base class, and later ones use JUnit4 annotations. Mixing both approaches is possible, there's no need to rewrite existing tests.</p>
+<h2 id="tests-that-use-a-jcr-repository">Tests that use a JCR repository</h2>
+<p>Utility classes from our <a href="">commons/testing</a> module make it easy to get a real JCR repository for testing. That's a bit slower than pure unit tests, of course, but this only adds 1-2 seconds to the execution of a test suite.</p>
+<p>The <code>RepositoryProviderTest</code> in that module uses this technique to get a JCR repository.</p>
+<p>Note that our utilities do not cleanup the repository between tests, so you must be careful about test isolation, for example by using unique paths for each test.</p>
+<h2 id="mock-classes-and-services">Mock classes and services</h2>
+<p>The next step is to use mock classes and services to simulate components that are needed for testing. This makes it possible to test OSGi service classes without an OSGi framework.</p>
+<p>We have a number of custom-written mock services in Sling, like <a href="">MockNodeType</a> for example. These handwritten mocks implement just what's needed for their tests, so they might not be reusable as is.</p>
+<p>In other cases we use <a href="">jmock</a> to help create mock objects without having to write much code - such mocking libraries take care of the plumbing and allow you to write just the bits of code that matter (often with funny syntaxes). The tests of the [org.apache.sling.event|https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/event/] bundle, for example, make extensive use of such mock services.</p>
+<p>The problem with mocks is that it can become hard to make sure you're actually testing something, and not just "mocking mocks". At a certain level of complexity, it becomes quicker and clearer to actually start an OSGi framework for automated tests.</p>
+<h3 id="side-note-injecting-services-in-private-fields">Side note: injecting services in private fields</h3>
+<p>To inject (real or fake) services in others for testing, without having to create getters and setters just for this, we use a reflection-based trick, as in this example:</p>
+<p><DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>setting a private field via reflection</B></DIV><DIV class="codeContent panelContent">
+ // set resource resolver factory
+ // in a ServletResolver object which has a private resourceResolverFactory field</p>
+<div class="codehilite"><pre><span class="x">ServletResolver servletResolver = ....</span>
+<span class="x">Class</span><span class="cp"><?</span><span class="o">></span> <span class="nx">resolverClass</span> <span class="o">=</span> <span class="nx">servletResolver</span><span class="o">.</span><span class="nx">getClass</span><span class="p">()</span><span class="o">.</span><span class="nx">getSuperclass</span><span class="p">();</span>
+<span class="k">final</span> <span class="nx">java</span><span class="o">.</span><span class="nx">lang</span><span class="o">.</span><span class="nx">reflect</span><span class="o">.</span><span class="nx">Field</span> <span class="nx">resolverField</span> <span class="o">=</span> <span class="nx">resolverClass</span><span class="o">.</span><span class="nx">getDeclaredField</span><span class="p">(</span><span class="s2">"resourceResolverFactory"</span><span class="p">);</span>
+<span class="nx">resolverField</span><span class="o">.</span><span class="nx">setAccessible</span><span class="p">(</span><span class="k">true</span><span class="p">);</span>
+<span class="nx">resolverField</span><span class="o">.</span><span class="nx">set</span><span class="p">(</span><span class="nx">servletResolver</span><span class="p">,</span> <span class="nx">factory</span><span class="p">);</span>
+</pre></div>
+
+
+<h2 id="pax-exam">Pax Exam</h2>
+<p><a href="">Pax Exam</a> allows you to easily start an OSGi framework during execution of a JUnit test suite.</p>
+<p>We currently use it for our <a href="">Sling installer integration tests</a> for example. As parts of the installer interact directly with the OSGi framework, it felt safer to test it in a realistic situation rather than mock everything.</p>
+<p>Such tests are obviously slower than plain unit tests and tests that use mocks. Our installer integration tests, using Pax Exam, take about a minute to execute on a 2010 macbook pro.</p>
+<h2 id="sling-testing-tools-server-side-junit-tests">Sling testing tools: server-side JUnit tests</h2>
+<p>The <a href="">Sling testing tools</a> include a module that executes JUnit tests server-side, in a Sling instance. This allows integration tests to run in a realistic environment, and could also be used for self-testing production systems.</p>
+<p>As I write this, we are not using those tools to test Sling itself, but we have a <a href="">complete example</a> of integration tests that use them to run server-side JUnit tests, including automatic setup of the test Sling instance.</p>
+<h2 id="http-based-integration-tests">HTTP-based integration tests</h2>
+<p>The highest level of integration is testing a complete Sling instance via its HTTP interface.</p>
+<p>We use this technique to test Sling itself: the <a href="">launchpad/integration-tests</a> module defines the tests (462 of them as I write this), and the [launchpad/testing|https://svn.apache.org/repos/asf/sling/trunk/launchpad/testing] module executes them, after setting up a Sling instance from scratch (which is quite easy as Sling is just a runnable jar). </p>
+<p>A simple mechanism (described in README files in these modules) allows individual tests to be executed quickly against a previously started Sling instance, to be able to write and debug tests efficiently.</p>
+<p>The test code could be made simpler using the fluent HTTP interfaces defined in the Sling testing tools described above, but the launchpad tests were written before that module was created, and as they're stable there's no reason to rewrite them. If you're planning on using this technique for your own applications, we recommend looking at the Sling testing tools instead of these "legacy" tests - but the basic technique is the same.</p>
+<p>One problem with these launchpad tests is that the tests of all Sling modules are defined in a single testing module, they are not co-located with the code that they test. This could be improved by providing the tests in bundles that can be created from the same Maven modules that the code that they test.</p>
+<h2 id="summary">Summary</h2>
+<p>Combining the above testing techniques has worked well for us in creating and testing Sling. Being able to test things at different levels of integration has proved an efficient way to get good test coverage without having to write too much boring test code.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
+ </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>
Modified: websites/staging/sling/trunk/content/downloads.html
==============================================================================
--- websites/staging/sling/trunk/content/downloads.html (original)
+++ websites/staging/sling/trunk/content/downloads.html Tue May 22 09:41:22 2012
@@ -83,7 +83,7 @@
</div>
<h1>Downloads</h1>
<p>To get the latest development release of Apache Sling, you can check out the <a href="">Source Code</a> and [Getting and Building Sling] yourself. Otherwise, the releases below are available for download. To install, just download and extract. These [KEYS|http://www.apache.org/dist/sling/KEYS] can be used to verify the release archive.</p>
-<p>All Apache Sling products are distributed under the terms of The Apache Software License (version 2.0). See our <a href="/project-license.html">license</a>, or the LICENSE file included in each distribution.</p>
+<p>All Apache Sling products are distributed under the terms of The Apache Software License (version 2.0). See our <a href="/project-information/project-license.html">license</a>, or the LICENSE file included in each distribution.</p>
<h2 id="mirrors">Mirrors</h2>
<p>Use the links below to download binary or source distributions of Apache Sling from one of our mirrors.</p>
<p>You are currently using <em>[preferred]()</em>. If you encounter a problem with this mirror, please select another mirror. If all mirrors are failing, there are backup mirrors (at the end of the mirrors list) that should be available.
@@ -130,7 +130,7 @@ Other mirrors: </P><select name="Preferr
</tbody>
</table>
<p>{downloadmirror:sling}sling-6-source-release.zip{downloadmirror} |</p>
-<p>If you want to experiment with bleeding edge code, <a href="/getting-and-building-sling.html">building Sling yourself</a> is not that hard.</p>
+<p>If you want to experiment with bleeding edge code, <a href="/documentation/development/getting-and-building-sling.html">building Sling yourself</a> is not that hard.</p>
<p>If you are looking for previous releases of Apache Sling, have a look in the <a href="">archives</a>. For previous incubator releases of Apache Sling, have a look in the [Incubator archives|http://archive.apache.org/dist/incubator/sling/].</p>
<h2 id="sling-components">Sling Components</h2>
<table>
Modified: websites/staging/sling/trunk/content/guides.html
==============================================================================
--- websites/staging/sling/trunk/content/guides.html (original)
+++ websites/staging/sling/trunk/content/guides.html Tue May 22 09:41:22 2012
@@ -83,21 +83,21 @@
</div>
<h1>Guides</h1>
<p>These pages contain further information in a more informal way.</p>
-<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Discover</span> <span class="n">Sling</span> <span class="n">in</span> <span class="mi">15</span> <span class="n">minutes</span> <span class="p">](</span><span class="sr">/discover-sling-in-15-minutes.html) - title says it all</span>
+<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Discover</span> <span class="n">Sling</span> <span class="n">in</span> <span class="mi">15</span> <span class="n">minutes</span> <span class="p">](</span><span class="sr">/documentation/g</span><span class="n">etting</span><span class="o">-</span><span class="n">started</span><span class="o">/</span><span class="n">discover</span><span class="o">-</span><span class="n">sling</span><span class="o">-</span><span class="n">in</span><span class="o">-</span><span class="mi">15</span><span class="o">-</span><span class="n">minutes</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">-</span> <span class="n">title</span> <span class="n">says</span> <span class="n">it</span> <span class="n">all</span>
-<span class="sr">* [Resources](/</span><span class="n">resources</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">--</span> <span class="n">Presents</span> <span class="n">the</span> <span class="n">Resource</span> <span class="n">as</span> <span class="n">the</span> <span class="n">object</span> <span class="n">around</span> <span class="n">which</span> <span class="n">Sling</span> <span class="n">is</span> <span class="n">built</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">Servlet</span> <span class="n">Resolution</span><span class="p">](</span><span class="sr">/servlet-resolution.html) -- How Sling resolves the servlet or script responsible for rendering a Resource.</span>
-<span class="sr">* [Request Parameters](/</span><span class="n">request</span><span class="o">-</span><span class="n">parameters</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">--</span> <span class="n">Explains</span> <span class="n">how</span> <span class="n">Sling</span> <span class="n">provides</span> <span class="n">request</span> <span class="n">parameters</span> <span class="n">to</span> <span class="n">servlets</span><span class="p">,</span> <span class="n">scripts</span> <span class="ow">and</span> <span class="n">filters</span><span class="o">.</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">Repository</span> <span class="n">Based</span> <span class="n">Development</span><span class="p">](</span><span class="sr">/repository-based-development.html) -- Shows how WebDAV is supported by Sling.</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Resources</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">the</span><span class="o">-</span><span class="n">sling</span><span class="o">-</span><span class="n">engine</span><span class="o">/</span><span class="n">resources</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">--</span> <span class="n">Presents</span> <span class="n">the</span> <span class="n">Resource</span> <span class="n">as</span> <span class="n">the</span> <span class="n">object</span> <span class="n">around</span> <span class="n">which</span> <span class="n">Sling</span> <span class="n">is</span> <span class="n">built</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Servlet</span> <span class="n">Resolution</span><span class="p">](</span><span class="sr">/old-stuff/s</span><span class="n">ervlet</span><span class="o">-</span><span class="n">resolution</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">--</span> <span class="n">How</span> <span class="n">Sling</span> <span class="n">resolves</span> <span class="n">the</span> <span class="n">servlet</span> <span class="ow">or</span> <span class="n">script</span> <span class="n">responsible</span> <span class="k">for</span> <span class="n">rendering</span> <span class="n">a</span> <span class="n">Resource</span><span class="o">.</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Request</span> <span class="n">Parameters</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">the</span><span class="o">-</span><span class="n">sling</span><span class="o">-</span><span class="n">engine</span><span class="o">/</span><span class="n">request</span><span class="o">-</span><span class="n">parameters</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">--</span> <span class="n">Explains</span> <span class="n">how</span> <span class="n">Sling</span> <span class="n">provides</span> <span class="n">request</span> <span class="n">parameters</span> <span class="n">to</span> <span class="n">servlets</span><span class="p">,</span> <span class="n">scripts</span> <span class="ow">and</span> <span class="n">filters</span><span class="o">.</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Repository</span> <span class="n">Based</span> <span class="n">Development</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">repository</span><span class="o">-</span><span class="n">based</span><span class="o">-</span><span class="n">development</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">--</span> <span class="n">Shows</span> <span class="n">how</span> <span class="n">WebDAV</span> <span class="n">is</span> <span class="n">supported</span> <span class="n">by</span> <span class="n">Sling</span><span class="o">.</span>
-<span class="sr">* [Bundle Management](/</span><span class="n">tutorials</span><span class="o">-</span><span class="n">how</span><span class="o">-</span><span class="n">tos</span><span class="o">/</span><span class="n">installing</span><span class="o">-</span><span class="ow">and</span><span class="o">-</span><span class="n">upgrading</span><span class="o">-</span><span class="n">bundles</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">--</span> <span class="n">Explains</span> <span class="n">how</span> <span class="n">to</span> <span class="n">install</span><span class="p">,</span> <span class="n">upgrade</span> <span class="ow">and</span> <span class="n">uninstall</span> <span class="n">Bundles</span> <span class="n">using</span> <span class="n">the</span> <span class="n">Sling</span> <span class="n">Management</span> <span class="n">console</span><span class="o">.</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Bundle</span> <span class="n">Management</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">tutorials</span><span class="o">-</span><span class="n">how</span><span class="o">-</span><span class="n">tos</span><span class="o">/</span><span class="n">installing</span><span class="o">-</span><span class="ow">and</span><span class="o">-</span><span class="n">upgrading</span><span class="o">-</span><span class="n">bundles</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">--</span> <span class="n">Explains</span> <span class="n">how</span> <span class="n">to</span> <span class="n">install</span><span class="p">,</span> <span class="n">upgrade</span> <span class="ow">and</span> <span class="n">uninstall</span> <span class="n">Bundles</span> <span class="n">using</span> <span class="n">the</span> <span class="n">Sling</span> <span class="
n">Management</span> <span class="n">console</span><span class="o">.</span>
</pre></div>
<p>These pages refer to the old Component API and launcher, and remain referred to here until more up to date documentation has been prepared:</p>
-<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Getting</span> <span class="ow">and</span> <span class="n">Building</span> <span class="n">Sling</span><span class="p">](</span><span class="sr">/getting-and-building-sling.html) -- A short recount on the first step for getting a running Sling instance after checking out the source from the SVN repository</span>
-<span class="sr">* [Default Mapping and Rendering](/</span><span class="n">default</span><span class="o">-</span><span class="n">mapping</span><span class="o">-</span><span class="ow">and</span><span class="o">-</span><span class="n">rendering</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">--</span> <span class="n">Explains</span> <span class="n">default</span> <span class="n">mapping</span> <span class="n">of</span> <span class="n">repository</span> <span class="n">nodes</span> <span class="n">to</span> <span class="n">Content</span> <span class="n">instances</span> <span class="ow">and</span> <span class="n">selection</span> <span class="n">of</span> <span class="n">a</span> <span class="n">default</span> <span class="n">Component</span><span class="o">.</span>
-<span class="o">*</span> <span class="p">[</span><span class="n">Dispatching</span> <span class="n">Requests</span><span class="p">](</span><span class="o">/</span><span class="n">dispatching</span><span class="o">-</span><span class="n">requests</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">--</span> <span class="n">Explains</span> <span class="n">how</span> <span class="n">a</span> <span class="n">Component</span> <span class="n">may</span> <span class="n">dispatch</span> <span class="n">requests</span> <span class="n">to</span> <span class="n">include</span> <span class="n">further</span> <span class="n">content</span> <span class="n">renderings</span> <span class="n">in</span> <span class="n">the</span> <span class="n">response</span> <span class="n">to</span> <span class="n">the</span> <span class="n">client</span><span class="err">'</span><span class="n">s</span> <span class="n">request</span>
+<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Getting</span> <span class="ow">and</span> <span class="n">Building</span> <span class="n">Sling</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">getting</span><span class="o">-</span><span class="ow">and</span><span class="o">-</span><span class="n">building</span><span class="o">-</span><span class="n">sling</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">--</span> <span class="n">A</span> <span class="n">short</span> <span class="n">recount</span> <span class="n">on</span> <span class="n">the</span> <span class="n">first</span> <span class="n">step</span> <span class="k">for</span> <span class="n">getting</span> <span class="n">a</span> <span class="n">running</span> <span class="n">Sling</span> <span class="n">instance</span> <span clas
s="n">after</span> <span class="n">checking</span> <span class="n">out</span> <span class="n">the</span> <span class="n">source</span> <span class="n">from</span> <span class="n">the</span> <span class="n">SVN</span> <span class="n">repository</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Default</span> <span class="n">Mapping</span> <span class="ow">and</span> <span class="n">Rendering</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">the</span><span class="o">-</span><span class="n">sling</span><span class="o">-</span><span class="n">engine</span><span class="o">/</span><span class="n">default</span><span class="o">-</span><span class="n">mapping</span><span class="o">-</span><span class="ow">and</span><span class="o">-</span><span class="n">rendering</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">--</span> <span class="n">Explains</span> <span class="n">default</span> <span class="n">mapping</span> <span class="n">of</span> <span class="n">repository</span> <span class="n">nodes</span> <span class="n">to</span> <span class="n">Content</span> <span class="n">instances</span> <span class="ow">and</span> <span
class="n">selection</span> <span class="n">of</span> <span class="n">a</span> <span class="n">default</span> <span class="n">Component</span><span class="o">.</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Dispatching</span> <span class="n">Requests</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">the</span><span class="o">-</span><span class="n">sling</span><span class="o">-</span><span class="n">engine</span><span class="o">/</span><span class="n">dispatching</span><span class="o">-</span><span class="n">requests</span><span class="o">.</span><span class="n">html</span><span class="p">)</span> <span class="o">--</span> <span class="n">Explains</span> <span class="n">how</span> <span class="n">a</span> <span class="n">Component</span> <span class="n">may</span> <span class="n">dispatch</span> <span class="n">requests</span> <span class="n">to</span> <span class="n">include</span> <span class="n">further</span> <span class="n">content</span> <span class="n">renderings</span> <span class="n">in</span> <span class="n">the</span> <span class="n">response</span> <span class="n">to
</span> <span class="n">the</span> <span class="n">client</span><span class="err">'</span><span class="n">s</span> <span class="n">request</span>
</pre></div>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
Rev. 1341347 by fmeschbe on Tue, 22 May 2012 08:25:18 +0000
Modified: websites/staging/sling/trunk/content/old-stuff.html
==============================================================================
--- websites/staging/sling/trunk/content/old-stuff.html (original)
+++ websites/staging/sling/trunk/content/old-stuff.html Tue May 22 09:41:22 2012
@@ -83,6 +83,15 @@
</div>
<h1>Old Stuff</h1>
<p>Should either be deleted or reviewed and updated to match the current code:</p>
+<ul>
+<li><a href="/old-stuff/assembly.html">Assembly</a></li>
+<li><a href="/old-stuff/launch-sling.html">Launch Sling</a></li>
+<li><a href="/old-stuff/request-processing.html">Request Processing</a></li>
+<li><a href="/old-stuff/run-modes-org-apache-sling-runmode.html">Run Modes (org.apache.sling.runmode)</a></li>
+<li><a href="/old-stuff/scriptengineintegration.html">Integrating Scripting Languages</a></li>
+<li><a href="/old-stuff/servlet-resolution.html">Servlet Resolution</a></li>
+<li><a href="/old-stuff/sling-api.html">Sling API</a></li>
+</ul>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
Rev. 1341361 by fmeschbe on Tue, 22 May 2012 08:54:04 +0000
</div>
Added: websites/staging/sling/trunk/content/old-stuff/assembly.html
==============================================================================
--- websites/staging/sling/trunk/content/old-stuff/assembly.html (added)
+++ websites/staging/sling/trunk/content/old-stuff/assembly.html Tue May 22 09:41:22 2012
@@ -0,0 +1,176 @@
+<!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="/css/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><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</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>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/old-stuff.html">Old Stuff</a>
+ </div>
+ <h1>Assembly</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>
+<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>
+<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 <code>META-INF/MANIFEST.MF</code> file - contains specific headers identifying the bundle. Most manifest headers are optional with defined default values - only the <code>Bundle-SymbolicName</code> header is actually required and the <code>Bundle-ManifestVersion</code> header should be set to <code>2</code> 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 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>
+<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 <code>Assembly-Bundles</code> header. This header is optional with not default value.</li>
+</ul>
+<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 <code>Assembly-Bundles</code> header. The start levels of the bundles will be set according to the <code>startlevel</code> 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 <code>Bundle.start()</code> 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 <code>Bundle.stop()</code> 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 <code>Bundle.uninstall()</code> method. The <em>Assembly Manager</em> will (try to) uninstall all bundles listed in the <code>Assembly-Bundles</code> header.</li>
+<li><em>Updated</em> - The Assembly bundle will update all bundles installed previously according to the <code>Assembly-Bundles</code> 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 id="bundles-referenced-by-multiple-assembly-bundles">Bundles referenced by multiple Assembly Bundles</h3>
+<p>It is conceivable, that bundles are listed in the <code>Assembly-Bundles</code> 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 <code>Assembly-Bundles</code> 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 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 <code>Assembly-Bundles</code> 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">","</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">";"</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">"="</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, ∞~)</em>. The default value is <em>~[0.0.0,∞~)</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 <code>true</code>.</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 id="bundle-location">Bundle Location</h3>
+<p>Generally bundles to be installed with an Assembly Bundle are retrieved from an OSGi Bundle Repository. The <code>Assembly-BundleRepository</code> 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 <code>Assembly-Bundles</code> header with an <code>entry</code> 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 <code>entry</code> 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><code>version</code> Parameter</em> - The <code>version</code> 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 <code>Assembly-BundleRepository</code> 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 <code>Assembly-Bundles</code> header are resolved through the OSGi Bundle Repository Service using the URL from the <code>Assembly-BundleRepository</code> 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 <code>Assembly-Bundles</code> header is set to <code>org.apache.sling.sample1;entry=path.jar,org.apache.sling.sample2</code>. The bundle <code>org.apache.sling.sample1</code> is then installed from the Assembly Bundle entry <code>path.jar</code>, while the bundle <code>org.apache.sling.sample2</code> is resolved in the OSGi Bundle Repository.</li>
+</ul>
+<h2 id="best-practices">Best Practices</h2>
+<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>
+<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 <code>org.apache.sling.sample</code>, <code>org.apache.sling.sample.impl</code>, <code>org.apache.sling.more</code>. The bundle would the be named <code>org.apache.sling.sample</code>.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +0000
+ </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/old-stuff/launch-sling.html
==============================================================================
--- websites/staging/sling/trunk/content/old-stuff/launch-sling.html (added)
+++ websites/staging/sling/trunk/content/old-stuff/launch-sling.html Tue May 22 09:41:22 2012
@@ -0,0 +1,96 @@
+<!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 - Launch Sling</title>
+ <link rel="stylesheet" href="/css/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><strong>Documentation</strong> <br />
+<a href="/getting-started.html">Getting Started</a> <br />
+<a href="/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/development.html">Development</a> <br />
+<a href="/bundles.html">Bundles</a> <br />
+<a href="/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="http://sling.apache.org/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="http://sling.apache.org/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="http://sling.apache.org/site/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a> <br />
+<a href="/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> <br />
+</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>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/old-stuff.html">Old Stuff</a>
+ </div>
+ <h1>Launch Sling</h1>
+ <p>Please refer to <a href="/documentation/the-sling-engine/the-sling-launchpad.html">The Sling Launchpad</a> for up-to-date information on launching Sling.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1341376 by fmeschbe on Tue, 22 May 2012 09:41:06 +0000
+ </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>