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/04/22 18:52:31 UTC
svn commit: r813967 [15/16] - /websites/staging/sling/trunk/content/
Added: websites/staging/sling/trunk/content/sling.html
==============================================================================
--- websites/staging/sling/trunk/content/sling.html (added)
+++ websites/staging/sling/trunk/content/sling.html Sun Apr 22 16:52:28 2012
@@ -0,0 +1,472 @@
+<!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 - Sling</title>
+ <link rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="getting-started.html">Getting Started</a></li>
+<li><a href="the-sling-engine.html">The Sling Engine</a></li>
+<li><a href="development.html">Development</a></li>
+<li><a href="bundles.html">Bundles</a></li>
+<li><a href="tutorials-&-how-tos.html">Tutorials & How-Tos</a></li>
+<li><a href="configuration.html">Configuration</a></li>
+<li><a href="http://sling.apache.org/apidocs/sling5/index.html">API docs</a></li>
+<li><a href="http://s.apache.org/sling.wiki">Wiki</a></li>
+<li><a href="http://s.apache.org/sling.faq">FAQ</a></li>
+</ul>
+<h1 id="project-info">Project info</h1>
+<ul>
+<li><a href="http://sling.apache.org/site/downloads.cgi">Downloads</a></li>
+<li><a href="http://www.apache.org/licenses/">License</a></li>
+<li><a href="contributing.html">Contributing</a></li>
+<li><a href="news.html">News</a></li>
+<li><a href="links.html">Links</a></li>
+<li><a href="project-information.html">Project Information</a></li>
+<li><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a></li>
+<li><a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+<h1 id="sponsorship">Sponsorship</h1>
+<ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a></li>
+</ul>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ (TODO: breadcrumb here)
+ </div>
+ <h1 class="title">Sling</h1>
+ <div>
+ <p><a name="Sling-MavenSlingPlugin"></a></p>
+<h1 id="maven-sling-plugin">Maven Sling Plugin</h1>
+<p>The Maven Sling Plugin provides a number of goals which may be of help
+while developping bundles for Sling. To run the plugin you need at least
+Maven 2.x and JDK 1.5 or higher. Maven Sling Plugin provides the following
+goals:</p>
+<table>
+<tr><td> [sling:deploy](#deploy.html)
+ </td><td> Deploy a OSGi-bundle into a running Sling instance. </td></tr>
+<tr><td> [sling:deploy-file](#deploy-file.html)
+ </td><td> Deploy a OSGi-bundle into a running Sling instance without requiring a
+project descriptor file. </td></tr>
+
+<tr><td> [sling:install-file](#install-file.html)
+ </td><td> Install a OSGi-bundle into a running Sling instance without requiring a
+project descriptor file. </td></tr>
+
+</table>
+
+<p><a name="Sling-Usage"></a></p>
+<h2 id="usage">Usage</h2>
+<p>You should specify the version in your project's plugin configuration:</p>
+<div class="codehilite"><pre><span class="nt"><project></span>
+ ...
+ <span class="nt"><build></span>
+ <span class="c"><!-- To define the plugin version in your parent POM --></span>
+ <span class="nt"><pluginManagement></span>
+ <span class="nt"><plugins></span>
+ <span class="nt"><plugin></span>
+ <span class="nt"><groupId></span>org.apache.sling<span class="nt"></groupId></span>
+ <span class="nt"><artifactId></span>maven-sling-plugin<span class="nt"></artifactId></span>
+ <span class="nt"><version></span>2.0.5-SNAPSHOT<span class="nt"></version></span>
+ <span class="nt"></plugin></span>
+ ...
+ <span class="nt"></plugins></span>
+ <span class="nt"></pluginManagement></span>
+ <span class="c"><!-- To use the plugin goals in your POM or parent POM --></span>
+ <span class="nt"><plugins></span>
+ <span class="nt"><plugin></span>
+ <span class="nt"><groupId></span>org.apache.sling<span class="nt"></groupId></span>
+ <span class="nt"><artifactId></span>maven-sling-plugin<span class="nt"></artifactId></span>
+ <span class="nt"><version></span>2.0.5-SNAPSHOT<span class="nt"></version></span>
+ <span class="nt"></plugin></span>
+ ...
+ <span class="nt"></plugins></span>
+ <span class="nt"></build></span>
+ ...
+<span class="nt"></project></span>
+</pre></div>
+
+
+<p>For more information, see <a href="http://maven.apache.org/guides/mini/guide-configuring-plugins.html">"Guide to Configuring Plug-ins"</a></p>
+<p>{anchor:deploy}</p>
+<p><a name="Sling-The*deploy*goal"></a></p>
+<h2 id="the-deploy-goal">The <em>deploy</em> goal</h2>
+<p>The <em>deploy</em> goal uploads a bundle to a Sling OSGi Bundle Repository
+server implemented by the <em>sling-obr</em> bundle, which may be located on a
+remote system. The plugin places an HTTP <em>POST</em> request to the server
+sending the bundle file. </p>
+<p><a name="Sling-Use"></a></p>
+<h3 id="use">Use</h3>
+<p>To use the <em>deploy</em> goal of the Maven Sling Plugin define the following
+elements in the <em><plugins></em> section of the POM:</p>
+<div class="codehilite"><pre><span class="cp"><?xml version="1.0" encoding="ISO-8859-1"?></span>
+<span class="nt"><project></span>
+ ....
+ <span class="nt"><build></span>
+ ....
+ <span class="nt"><plugins></span>
+ ....
+ <span class="nt"><plugin></span>
+ <span class="nt"><groupId></span>org.apache.sling<span class="nt"></groupId></span>
+ <span class="nt"><artifactId></span>maven-sling-plugin<span class="nt"></artifactId></span>
+ <span class="nt"><executions></span>
+ <span class="nt"><execution></span>
+ <span class="nt"><id></span>deploy-bundle<span class="nt"></id></span>
+ <span class="nt"><goals></span>
+ <span class="nt"><goal></span>deploy<span class="nt"></goal></span>
+ <span class="nt"></goals></span>
+ <span class="nt"></execution></span>
+ <span class="nt"></executions></span>
+ <span class="nt"></plugin></span>
+ ....
+ <span class="nt"><plugins></span>
+ ....
+ <span class="nt"><build></span>
+ ....
+<span class="nt"><project></span>
+</pre></div>
+
+
+<p><a name="Sling-Configuration"></a></p>
+<h3 id="configuration">Configuration</h3>
+<p>The <em>deploy</em> goal may be configured in the <em><configuration></em> element
+using the following properties:
+<table>
+<tr><th> Parameter </th><th> Default Value </th><th> System Property Overwrite </th><th> Description
+</th></tr>
+<tr><td> <em>skip</em> </td><td> <em>false</em> </td><td> <em>sling.deploy.skip</em> </td><td> Whether to skip this step
+even though it has been configured in the project to be executed. The main
+use of this setting is preventing deployment of the bundle to a Sling OSGi
+Bundle Repository server if it is known that there is none or if such an
+upload is not required. </td></tr>
+<tr><td> <em>buildDirectory</em> </td><td> <em>${project.build.directory</em>} </td><td> - </td><td> The path of
+the file to be installed </td></tr>
+<tr><td> <em>jarName</em> </td><td> <em>${project.build.finalName}.jar</em> </td><td> - </td><td> The name of the
+file to be installed </td></tr>
+<tr><td> <em>obr</em> </td><td> - </td><td> <em>obr</em> </td><td> The URL of the running Sling instance to which
+the bundle is installed. Note that this parameter is required and has no
+defualt value. It must always be specified in the configuration section or
+on the command line. </td></tr>
+{anchor:deploy-file}
+</table></p>
+<p><a name="Sling-The*deploy-file*goal"></a></p>
+<h2 id="the-deploy-file-goal">The <em>deploy-file</em> goal</h2>
+<p>The <em>deploy-file</em> goal is equivalent to the <em>deploy</em> goal except, that
+the <em>deploy-file</em> does not require a project descriptor file while the
+<em>deploy</em> goal does. In other words the <em>deploy-file</em> goal may used to
+upload any bundle file available to a Sling OBR server instance.</p>
+<p><a name="Sling-Use"></a></p>
+<h3 id="use_1">Use</h3>
+<p>The <em>deploy-file</em> goal may only be used from the command line by
+explicitly calling it as in:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">mvn</span> <span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling:maven</span><span class="o">-</span><span class="n">sling</span><span class="o">-</span><span class="n">plugin:deploy</span><span class="o">-</span><span class="n">file</span> <span class="o">-</span><span class="n">Dsling</span><span class="o">.</span><span class="n">file</span><span class="o">=</span><span class="sr"><file></span>
+</pre></div>
+
+
+<p>-Dobr=<url></p>
+<p>Specifying the bundle file to upload with the <em>sling.file</em> property is
+required.</p>
+<p><a name="Sling-Configuration"></a></p>
+<h3 id="configuration_1">Configuration</h3>
+<p>The <em>deploy-file</em> supports similar configuration parameters as the
+<em>deploy</em> goal with the exception of the <em>skip</em> parameter which makes no
+sense. In addition, all parameters must be specified on the command line by
+setting system properties. The <em>bundleFileName</em> parameter specified as
+the <em>sling.file</em> system property as well as the <em>obr</em> URL are required
+by the <em>deploy-file</em> goal.
+<table>
+<tr><th> Parameter </th><th> Default Value </th><th> System Property Overwrite </th><th> Description
+</th></tr>
+<tr><td> <em>bundleFileName</em> </td><td>
+<em>${project.build.directory}/${project.build.finalName}.jar</em> </td><td>
+<em>sling.file</em> </td><td> The path and name of the file to be installed </td></tr>
+<tr><td> <em>obr</em> </td><td> - </td><td> <em>obr</em> </td><td> The URL of the running Sling instance to which
+the bundle is installed. Note that this parameter is required and has no
+defualt value. It must always be specified in the configuration section or
+on the command line. </td></tr>
+Example: To deploy the bundle file <em>someBundle.jar</em> to the OBR running at {{<a href="http://obr.sample.org">http://obr.sample.org</a>
+}} you might use the goal as follows:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">mvn</span> <span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling:maven</span><span class="o">-</span><span class="n">sling</span><span class="o">-</span><span class="n">plugin:deploy</span><span class="o">-</span><span class="n">file</span>
+</pre></div>
+
+
+<p>-Dsling.file=someBundle.jar -Dobr=http://obr.sample.org</p>
+<p>{anchor:install}</p>
+<p><a name="Sling-The*install*goal"></a></p>
+<h2 id="the-install-goal">The <em>install</em> goal</h2>
+<p>The <em>install</em> goal uploads a bundle to a running sling instance, which
+may be located on a remote system. The plugin places an HTTP <em>POST</em>
+request to the sling instance sending the bundle file together with flags
+indicating whether to start the bundle and what start level to assign the
+bundle. It's also possible to HTTP <em>PUT</em> instead of <em>POST</em> for WebDAV.</p>
+<p><a name="Sling-Use"></a></p>
+<h3 id="use_2">Use</h3>
+<p>To use the <em>install</em> goal of the Maven Sling Plugin define the following
+elements in the <em><plugins></em> section of the POM:</p>
+<div class="codehilite"><pre><span class="cp"><?xml version="1.0" encoding="ISO-8859-1"?></span>
+<span class="nt"><project></span>
+ ....
+ <span class="nt"><build></span>
+ ....
+ <span class="nt"><plugins></span>
+ ....
+ <span class="nt"><plugin></span>
+ <span class="nt"><groupId></span>org.apache.sling<span class="nt"></groupId></span>
+ <span class="nt"><artifactId></span>maven-sling-plugin<span class="nt"></artifactId></span>
+ <span class="nt"><executions></span>
+ <span class="nt"><execution></span>
+ <span class="nt"><id></span>install-bundle<span class="nt"></id></span>
+ <span class="nt"><goals></span>
+ <span class="nt"><goal></span>install<span class="nt"></goal></span>
+ <span class="nt"></goals></span>
+ <span class="nt"></execution></span>
+ <span class="nt"></executions></span>
+ <span class="nt"></plugin></span>
+ ....
+ <span class="nt"><plugins></span>
+ ....
+ <span class="nt"><build></span>
+ ....
+<span class="nt"><project></span>
+</pre></div>
+
+
+<p><a name="Sling-Configuration"></a></p>
+<h3 id="configuration_2">Configuration</h3>
+<p>The <em>install</em> goal may be configured in the <em><configuration></em> element
+using the following properties:
+<table>
+<tr><th> Parameter </th><th> Default Value </th><th> System Property Overwrite </th><th> Description
+</th></tr>
+<tr><td> <em>skip</em> </td><td> <em>false</em> </td><td> <em>sling.install.skip</em> </td><td> Whether to skip this step
+even though it has been configured in the project to be executed. The main
+use of this setting is preventing installation of the bundle to a running
+Sling installation if it is known that there is none or if such an upload
+is not required, for example when building the bundle in an automated build
+system such as Confluence. </td></tr>
+<tr><td> <em>bundleFileName</em> </td><td>
+<em>${project.build.directory}/${project.build.finalName}.jar</em> </td><td>
+<em>sling.file</em> </td><td> The path and name of the file to be installed </td></tr>
+<tr><td> <em>bundleStart</em> </td><td> <em>true</em> </td><td> <em>sling.bundle.start</em> </td><td> Whether to start
+the bundle after installing it. If the bundle is just updated, this
+parameter is ignored even if the bundle is currently stopped </td></tr>
+<tr><td> <em>bundleStartLevel</em> </td><td> <em>20</em> </td><td> <em>sling.bundle.startlevel</em> </td><td> The start
+level to set on the installed bundle. If the bundle is already installed
+and therefore is only updated this parameter is ignored. The parameter is
+also ignored if the running Sling instance has no StartLevel service (which
+is unusual actually) </td></tr>
+<tr><td> <em>slingUrl</em> </td><td> <em>http{</em>}<em>://localhost:8080/sling</em> </td><td> <em>sling.url</em> </td><td>
+The URL of the running Sling instance to which the bundle is installed </td></tr>
+<tr><td> <em>user</em> </td><td> <em>admin</em> </td><td> <em>sling.user</em> </td><td> The name of the user to
+authenticate as with the running Sling instance given by the <em>slingUrl</em>
+parameter </td></tr>
+<tr><td> <em>password</em> </td><td> <em>admin</em> </td><td> <em>sling.password</em> </td><td> The password of the user
+to authenticate as with the running Sling instance given by the
+<em>slingUrl</em> parameter </td></tr></p>
+<tr><td> *usePut* </td><td> *false* </td><td> *sling.usePut* </td><td> If a simple HTTP PUT should
+be used instead of the standard POST to the felix console. In the
+uninstall goal, a HTTP DELETE will be used. </td></tr>
+
+<tr><td> *refreshPackages* </td><td> *true* </td><td> *sling.refreshPackages* </td><td> Whether to refresh the packages after installing the uploaded bundle. If this property is set to *true*, the {{PackageAdmin.refreshPackages(Bundle\[\](\.html)
+)}} method is called after installing or updating the bundle. </td></tr>
+
+<p>{anchor:install-file}
+</table></p>
+<p><a name="Sling-The*install-file*goal"></a></p>
+<h2 id="the-install-file-goal">The <em>install-file</em> goal</h2>
+<p>The <em>install-file</em> goal is equivalent to the <em>install</em> goal except,
+that the <em>install-file</em> does not require a project descriptor file while
+the <em>install</em> goal does. In other words the <em>install-file</em> goal may
+used to upload any bundle file available to a running Sling instance.</p>
+<p><a name="Sling-Use"></a></p>
+<h3 id="use_3">Use</h3>
+<p>The <em>install-file</em> goal may only be used from the command line by
+explicitly calling it as in:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">mvn</span> <span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling:maven</span><span class="o">-</span><span class="n">sling</span><span class="o">-</span><span class="n">plugin:install</span><span class="o">-</span><span class="n">file</span> <span class="o">-</span><span class="n">Dsling</span><span class="o">.</span><span class="n">file</span><span class="o">=</span><span class="sr"><file></span>
+</pre></div>
+
+
+<p>Specifying the bundle file to upload with the <em>sling.file</em> property is
+required.</p>
+<p><a name="Sling-Configuration"></a></p>
+<h3 id="configuration_3">Configuration</h3>
+<p>The <em>install-file</em> supports the same configuration parameters as the
+<em>install</em> goal with the exception of the <em>skip</em> parameter which makes
+no sense. In addition, all parameters must be specified on the command line
+by setting system properties. The <em>bundleFileName</em> parameter specified as
+the <em>sling.file</em> system property is required by the <em>install-file</em>
+goal.</p>
+<p>For a description of the parameters see the configuration section of the <a href="#install.html"><em>install</em> goal</a>
+ above.</p>
+<p>Example: To upload the bundle file <em>someBundle.jar</em> you might use the
+goal as follows:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">mvn</span> <span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling:maven</span><span class="o">-</span><span class="n">sling</span><span class="o">-</span><span class="n">plugin:install</span><span class="o">-</span><span class="n">file</span>
+</pre></div>
+
+
+<p>-Dsling.file=someBundle.jar</p>
+<p>{anchor:uninstall}</p>
+<p><a name="Sling-The*uninstall*goal"></a></p>
+<h2 id="the-uninstall-goal">The <em>uninstall</em> goal</h2>
+<p>The <em>uninstall</em> goal uninstalls a bundle from a running sling instance,
+which may be located on a remote system. The plugin uninstalles a bundle
+via a HTTP <em>POST{</em>}request. It's also possible to use HTTP <em>DELETE</em>
+instead of <em>POST</em> for WebDAV.</p>
+<p><a name="Sling-Use"></a></p>
+<h3 id="use_4">Use</h3>
+<p>To use the <em>uninstall</em> goal of the Maven Sling Plugin define the
+following elements in the <em><plugins></em> section of the POM:</p>
+<div class="codehilite"><pre><span class="cp"><?xml version="1.0" encoding="ISO-8859-1"?></span>
+<span class="nt"><project></span>
+ ....
+ <span class="nt"><build></span>
+ ....
+ <span class="nt"><plugins></span>
+ ....
+ <span class="nt"><plugin></span>
+ <span class="nt"><groupId></span>org.apache.sling<span class="nt"></groupId></span>
+ <span class="nt"><artifactId></span>maven-sling-plugin<span class="nt"></artifactId></span>
+ <span class="nt"><executions></span>
+ <span class="nt"><execution></span>
+ <span class="nt"><id></span>uninstall-bundle<span class="nt"></id></span>
+ <span class="nt"><goals></span>
+ <span class="nt"><goal></span>uninstall<span class="nt"></goal></span>
+ <span class="nt"></goals></span>
+ <span class="nt"></execution></span>
+ <span class="nt"></executions></span>
+ <span class="nt"></plugin></span>
+ ....
+ <span class="nt"><plugins></span>
+ ....
+ <span class="nt"><build></span>
+ ....
+<span class="nt"><project></span>
+</pre></div>
+
+
+<p><a name="Sling-Configuration"></a></p>
+<h3 id="configuration_4">Configuration</h3>
+<p>The <em>uninstall</em> goal may be configured in the <em><configuration></em> element
+using the following properties:
+<table>
+<tr><th> Parameter </th><th> Default Value </th><th> System Property Overwrite </th><th> Description
+</th></tr>
+<tr><td> <em>bundleFileName</em> </td><td>
+<em>${project.build.directory}/${project.build.finalName}.jar</em> </td><td>
+<em>sling.file</em> </td><td> The path and name of the file to be uninstalled </td></tr>
+<tr><td> <em>slingUrl</em> </td><td> <em>http{</em>}<em>://localhost:8080/sling</em> </td><td> <em>sling.url</em> </td><td>
+The URL of the running Sling instance to which the bundle should be
+uninstalled </td></tr>
+<tr><td> <em>user</em> </td><td> <em>admin</em> </td><td> <em>sling.user</em> </td><td> The name of the user to
+authenticate as with the running Sling instance given by the <em>slingUrl</em>
+parameter </td></tr>
+<tr><td> <em>password</em> </td><td> <em>admin</em> </td><td> <em>sling.password</em> </td><td> The password of the user
+to authenticate as with the running Sling instance given by the
+<em>slingUrl</em> parameter </td></tr>
+<tr><td> <em>usePut</em> </td><td> <em>false</em> </td><td> <em>sling.usePut</em> </td><td> In the uninstall goal, a HTTP
+DELETE will be used. </td></tr>
+{anchor:validate}
+</table></p>
+<p><a name="Sling-The*validate*goal"></a></p>
+<h2 id="the-validate-goal">The <em>validate</em> goal</h2>
+<p>The <em>validate</em> goal checks the JSON code of a bundle.</p>
+<p><a name="Sling-Use"></a></p>
+<h3 id="use_5">Use</h3>
+<p>To use the <em>validate</em> goal of the Maven Sling Plugin define the following
+elements in the <em><plugins></em> section of the POM:</p>
+<div class="codehilite"><pre><span class="cp"><?xml version="1.0" encoding="ISO-8859-1"?></span>
+<span class="nt"><project></span>
+ ....
+ <span class="nt"><build></span>
+ ....
+ <span class="nt"><plugins></span>
+ ....
+ <span class="nt"><plugin></span>
+ <span class="nt"><groupId></span>org.apache.sling<span class="nt"></groupId></span>
+ <span class="nt"><artifactId></span>maven-sling-plugin<span class="nt"></artifactId></span>
+ <span class="nt"><executions></span>
+ <span class="nt"><execution></span>
+ <span class="nt"><id></span>validate-bundle<span class="nt"></id></span>
+ <span class="nt"><goals></span>
+ <span class="nt"><goal></span>validate<span class="nt"></goal></span>
+ <span class="nt"></goals></span>
+ <span class="nt"></execution></span>
+ <span class="nt"></executions></span>
+ <span class="nt"></plugin></span>
+ ....
+ <span class="nt"><plugins></span>
+ ....
+ <span class="nt"><build></span>
+ ....
+<span class="nt"><project></span>
+</pre></div>
+
+
+<p><a name="Sling-Configuration"></a></p>
+<h3 id="configuration_5">Configuration</h3>
+<p>The <em>validate</em> goal may be configured in the <em><configuration></em> element
+using the following properties:
+<table>
+<tr><th> Parameter </th><th> Default Value </th><th> System Property Overwrite </th><th> Description
+</th></tr>
+<tr><td> <em>skip</em> </td><td> <em>false</em> </td><td> <em>sling.validation.skip</em> </td><td> Whether to skip the
+validation </td></tr>
+<tr><td> <em>skipJson</em> </td><td> <em>false</em> </td><td> <em>sling.validation.skipJson</em> </td><td> Whether to
+skip the JSON validation. At the time, there's no difference between
+<em>skip</em> and <em>skipJson</em> because only JSON files will be validated by now.
+</td></tr></p>
+ </div>
+ </div>
+
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/the-sling-engine.html
==============================================================================
--- websites/staging/sling/trunk/content/the-sling-engine.html (added)
+++ websites/staging/sling/trunk/content/the-sling-engine.html Sun Apr 22 16:52:28 2012
@@ -0,0 +1,125 @@
+<!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 - The Sling Engine</title>
+ <link rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="getting-started.html">Getting Started</a></li>
+<li><a href="the-sling-engine.html">The Sling Engine</a></li>
+<li><a href="development.html">Development</a></li>
+<li><a href="bundles.html">Bundles</a></li>
+<li><a href="tutorials-&-how-tos.html">Tutorials & How-Tos</a></li>
+<li><a href="configuration.html">Configuration</a></li>
+<li><a href="http://sling.apache.org/apidocs/sling5/index.html">API docs</a></li>
+<li><a href="http://s.apache.org/sling.wiki">Wiki</a></li>
+<li><a href="http://s.apache.org/sling.faq">FAQ</a></li>
+</ul>
+<h1 id="project-info">Project info</h1>
+<ul>
+<li><a href="http://sling.apache.org/site/downloads.cgi">Downloads</a></li>
+<li><a href="http://www.apache.org/licenses/">License</a></li>
+<li><a href="contributing.html">Contributing</a></li>
+<li><a href="news.html">News</a></li>
+<li><a href="links.html">Links</a></li>
+<li><a href="project-information.html">Project Information</a></li>
+<li><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a></li>
+<li><a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+<h1 id="sponsorship">Sponsorship</h1>
+<ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a></li>
+</ul>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ (TODO: breadcrumb here)
+ </div>
+ <h1 class="title">The Sling Engine</h1>
+ <div>
+ <p><a name="TheSlingEngine-TheSlingEngine"></a></p>
+<h1 id="the-sling-engine">The Sling Engine</h1>
+<p><a name="TheSlingEngine-General"></a></p>
+<h2 id="general">General</h2>
+<ul>
+<li><a href="architecture.html">Architecture</a></li>
+<li><a href="authentication.html">Authentication</a></li>
+</ul>
+<p><a name="TheSlingEngine-RequestHandling"></a></p>
+<h2 id="request-handling">Request Handling</h2>
+<ul>
+<li><a href="dispatching-requests.html">Dispatching Requests</a></li>
+<li><a href="url-decomposition.html">URL decomposition</a></li>
+<li><a href="request-listeners.html">Request Listeners</a></li>
+<li><a href="filters.html">Filters</a></li>
+<li><a href="servlets.html">Servlets and Scripts</a></li>
+<li><a href="errorhandling.html">Errorhandling</a></li>
+<li><a href="request-parameters.html">Request Parameters</a></li>
+</ul>
+<p><a name="TheSlingEngine-Resources"></a></p>
+<h2 id="resources">Resources</h2>
+<ul>
+<li><a href="resources.html">Resources</a></li>
+<li><a href="wrap-or-decorate-resources.html">Wrap or Decorate Resources</a></li>
+<li><a href="mappings-for-resource-resolution.html">Mappings for Resource Resolution</a></li>
+</ul>
+<p><a name="TheSlingEngine-Misc"></a></p>
+<h2 id="misc">Misc</h2>
+<ul>
+<li><a href="adapters.html">Adapters</a></li>
+<li><a href="eventing-and-jobs.html">Eventing and Jobs</a></li>
+</ul>
+ </div>
+ </div>
+
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/the-sling-launchpad.html
==============================================================================
--- websites/staging/sling/trunk/content/the-sling-launchpad.html (added)
+++ websites/staging/sling/trunk/content/the-sling-launchpad.html Sun Apr 22 16:52:28 2012
@@ -0,0 +1,353 @@
+<!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 - The Sling Launchpad</title>
+ <link rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="getting-started.html">Getting Started</a></li>
+<li><a href="the-sling-engine.html">The Sling Engine</a></li>
+<li><a href="development.html">Development</a></li>
+<li><a href="bundles.html">Bundles</a></li>
+<li><a href="tutorials-&-how-tos.html">Tutorials & How-Tos</a></li>
+<li><a href="configuration.html">Configuration</a></li>
+<li><a href="http://sling.apache.org/apidocs/sling5/index.html">API docs</a></li>
+<li><a href="http://s.apache.org/sling.wiki">Wiki</a></li>
+<li><a href="http://s.apache.org/sling.faq">FAQ</a></li>
+</ul>
+<h1 id="project-info">Project info</h1>
+<ul>
+<li><a href="http://sling.apache.org/site/downloads.cgi">Downloads</a></li>
+<li><a href="http://www.apache.org/licenses/">License</a></li>
+<li><a href="contributing.html">Contributing</a></li>
+<li><a href="news.html">News</a></li>
+<li><a href="links.html">Links</a></li>
+<li><a href="project-information.html">Project Information</a></li>
+<li><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a></li>
+<li><a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+<h1 id="sponsorship">Sponsorship</h1>
+<ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a></li>
+</ul>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ (TODO: breadcrumb here)
+ </div>
+ <h1 class="title">The Sling Launchpad</h1>
+ <div>
+ <p><a name="TheSlingLaunchpad-TheSlingLaunchpad"></a></p>
+<h1 id="the-sling-launchpad">The Sling Launchpad</h1>
+<p>{toc:minLevel=2|maxLevel=3}</p>
+<p>This tries to explain how exactly the Sling Launchpad works, what
+constitutes the Sling Launchpad and how you can use the Sling Launchpad to
+custom create you Sling launchers. For a view behind the scenes of the
+Sling Launchpad Base module (the actual launcher) you might want to refer
+to the <a href="embedding-sling.html">Embedding Sling</a>
+ page.</p>
+<p><a name="TheSlingLaunchpad-SlingHome"></a></p>
+<h2 id="sling-home">Sling Home</h2>
+<p>Since Sling requires some space on the filesystem to store various files
+Sling has to know where this filesystem space is located.</p>
+<p>The following is a list of uses for the Sling Home directory:</p>
+<ul>
+<li><em>sling.properties</em> -- The main configuration file used by Sling to
+launch the framework. It mainly contains OSGi framework configuration and
+initial configuration for some bundles. This file is read on each startup
+of <em>Launcher JAR</em>. That is, changes to this file require a restart of the
+<em>Launcher JAR</em>.</li>
+<li><em>org.apache.sling.launchpad.base.jar</em> -- This is the <em>Launcher JAR</em>
+file used by the Standalone Application or the Web Application to start the
+OSGi Framework. This file is initially placed when first starting Sling and
+may later be updated by updating the system bundle with a new <em>Launcher
+JAR</em>.</li>
+<li><em>felix</em> -- The directory into which the Apache Felix Framework places
+the bundles, which have been installed into the system. This does generally
+not need to be touched.</li>
+<li><em>config</em> -- The directory into which the Apache Felix Configuration
+Admin Service stores the configurationes. Do not change any files in this
+directory, since changes will not generally be picked up.</li>
+<li><em>jackrabbit</em> -- The directory in which the Apache Jackrabbit JCR
+repository is started. Amongst other things this also contains the
+Jackrabbit configuration file <em>repository.xml</em>. You may modify this file,
+but don't forget to restart the Embedded Jackrabbit Repository bundle after
+doing this.</li>
+<li><em>logs</em> -- Contains the log files generated by Sling. By default this
+contains the error.log and its rotated generations.</li>
+</ul>
+<p><a name="TheSlingLaunchpad-CommandLineOptions"></a></p>
+<h2 id="command-line-options">Command Line Options</h2>
+<p>The Java Standalone Application supports a number of command line options,
+which influence the operation of the launch process.</p>
+<table>
+<tr><th> Option </th><th> Argument </th><th> Description </th></tr>
+<tr><td> *start* </td><td> -- </td><td> Open a TCP/IP server socket when starting Sling. Uses
+option *-j* to define the local socket address. </td></tr>
+<tr><td> *status* </td><td> -- </td><td> Check whether a (remote) Sling application is running.
+Uses option *-j* to define the address of the Sling instance to check.
+Note, that the Sling application terminates after checking for the (remote)
+Sling status. </td></tr>
+<tr><td> *stop* </td><td> -- </td><td> Stop a (remote) Sling application is running. Uses option
+*-j* to define the address of the Sling instance to stop. Note, that the
+Sling application terminates after stopping the (remote) Sling instance. </td></tr>
+<tr><td> *-c* </td><td> slinghome </td><td> The directory in which Sling locates its initial
+configuration file *sling.properties* and where files of Sling itself
+such as the Apache Felix bundle archive or the JCR repository files are
+stored. This defaults to the *sling* folder in the current working
+directory. This is the value which is commonly refered to as
+*$\{sling.home}.*
+</tr>
+<tr><td> *-l* </td><td> loglevel </td><td> Sets the initial loglevel as an integer in the range
+0 to 4 or as one of the well known level strings *ERROR*, *WARN*,
+*INFO*, or *DEBUG*. This option overwrites the
+*org.apache.sling.osg.log.level* setting the *sling.properties* file.
+The default is *INFO*. </td></tr>
+<tr><td> *-f* </td><td> logfile </td><td> The log file to use or *-* to log to standard out.
+This option overwrites the *org.apache.sling.osg.log.file* setting the
+*sling.properties* file. The default is
+*$\{sling.home}/logs/error.log*. </td></tr>
+<tr><td> *-a* </td><td> address </td><td> The interfact to bind to (use 0.0.0.0 for any). This
+option is not implemented yet. </td></tr>
+<tr><td> *-p* </td><td> port </td><td> The port to listen (default 8080) to handle HTTP
+requests. This option overwrites the *org.osgi.service.http.port* setting
+the *sling.properties* file. </td></tr>
+<tr><td> *-j* </td><td> [ host ":" ](-host-":"-.html)
+ port </td><td> The socket address to listen on for control connections (*start*
+or to use as the remote endpoint for the control connection (*status* and
+*stop*. If this parameter has no arguments or is not specified, the
+address defaults to port 63000 on localhost/127.0.0.1. If only the port is
+specified localhost/127.0.0.1 is used as the host part of the address. </td></tr>
+<tr><td> *-h* </td><td> -- </td><td> Prints a simple usage message listing all available command
+line options. </td></tr>
+</table>
+
+<p>The Sling Standalone application looks for a definition of the
+<em>sling.home</em> setting in the following locations in order of precendence:</p>
+<ol>
+<li>The <em>-c</em> command line option</li>
+<li>The <em>sling.home</em> system property</li>
+<li>The <em>SLING_HOME</em> environment variable</li>
+<li>If none of the above resolves to a non-null value, the default value of
+<em>sling</em> is assumed</li>
+</ol>
+<p><a name="TheSlingLaunchpad-SecurityImplication"></a></p>
+<h3 id="security-implication">Security Implication</h3>
+<p>Note that using a control connection for the Sling Standalone Application
+presents a potential security issue. For this reason the following defaults
+apply:</p>
+<ul>
+<li>The server side socket for a running Sling Standalone Application is only
+created if the application is started with the <em>start</em> command line
+option. If this option is omitted -- the default -- the server side socket
+is not created and the Sling Standalone Application instance cannot be
+remotely controlled.</li>
+<li>The default host name for the socket is localhost/127.0.0.1 meaning that
+the socket is only accessible from the same system as the Sling Standalone
+Application is running on. If the socket is accessible from remote systems
+additional must be taken to prevent malicious attackers to stop the system.
+The server side control connection implementation implements no security
+precaution (except from supporting to not create such a connection at all).</li>
+</ul>
+<p><a name="TheSlingLaunchpad-ServletParameters"></a></p>
+<h2 id="servlet-parameters">Servlet Parameters</h2>
+<p>The Web Application does not require specific servlet parameters. Those
+which are specified are used to overwrite any properties with the same name
+from the <em>sling.properties</em> file. One exception to this rule is the
+<em>sling.home</em> parameter, which is used to set the value of the
+<em>sling.home</em> property. If no parameter with this name is defined the
+Sling home directory is derived from the context path at which the Sling
+Web Application is registered.</p>
+<p>The <em>sling.home</em> folders for Sling Web Applications without the
+<em>sling.home</em> servlet parameter are all located in the <em>sling</em> folder in
+the current working directory as reported by the <em>user.dir</em> system
+property. The name of the actual directory is derived from the Web
+Application Context Path by replacing all slash characters <em>/</em> by
+underscore characters <em>_</em>. For the root context a single underscore
+character <em>_</em> is used.</p>
+<p>Examples:</p>
+<table>
+<tr><th> Servlet Context </th><th> Default *sling.home* </th></tr>
+<tr><td> _root_ </td><td> *sling/\_* </td></tr>
+<tr><td> */sling* </td><td> *sling/\_sling* </td></tr>
+<tr><td> */sling/instance1* </td><td> *sling/\_sling\_instance1* </td></tr>
+</table>
+
+<p>Starting with Launchpad Base 2.2.2 the fixed prefix <em>sling</em> is
+configurable with the <em>sling.home.prefix</em> system property. If this
+property is set the value used as the prefix.</p>
+<p>Examples: Assume the <em>sling.home.prefix</em> system property is set to
+<em>/var/sling</em></p>
+<table>
+<tr><th> Servlet Context </th><th> Default *sling.home* </th></tr>
+<tr><td> _root_ </td><td> */var/sling/\_* </td></tr>
+<tr><td> */sling* </td><td> */var/sling/\_sling* </td></tr>
+<tr><td> */sling/instance1* </td><td> */var/sling/\_sling\_instance1* </td></tr>
+</table>
+
+<p><a name="TheSlingLaunchpad-sling.properties"></a></p>
+<h2 id="slingproperties">sling.properties</h2>
+<p>The <em>sling.properties</em> file contains the initial setup of the Sling
+Application and the OSGi framework. Some of the parameters are required and
+should not be modified without a very good reason. Some parameters may be
+freely modified to your needs. Please see the inlined comment in the
+<em>sling.properties</em> file installed when Sling is first started.</p>
+<p>One thing to note is, that the <em>sling.properties</em> file is a simple Java
+Properties file with support for property references. That is, the value of
+properties may refer other property values by means of the well known
+<em>${name</em>} notation. Such property references may even be cascaded as in</p>
+<div class="codehilite"><pre>java.packages=<span class="cp">${</span><span class="n">jre</span><span class="o">-</span><span class="err">$</span><span class="p">{</span><span class="n">java</span><span class="o">.</span><span class="n">specification</span><span class="o">.</span><span class="n">version</span><span class="cp">}</span>}
+</pre></div>
+
+
+<p><a name="TheSlingLaunchpad-Components"></a></p>
+<h2 id="components">Components</h2>
+<p>The Sling Launchapd consists of <em>Launchbad Base</em> project and three
+additional projects which ultimately create a Standalone Java Application
+and a Web Appliction with standard parts of Sling.</p>
+<p><a name="TheSlingLaunchpad-LaunchpadBase"></a></p>
+<h3 id="launchpad-base">Launchpad Base</h3>
+<p>The <em>Launchpad Base</em> projects creates the following artifacts, which are
+required in actual setups to get a Sling application:</p>
+<ul>
+<li>
+<p><em>Launcher JAR</em> -- The primary artifact of the Base project contains the
+actual support to launch the Apache Felix OSGi Framework and install
+bundles, which are packaged with the application. It also contains the
+Apache Felix Framework together with the OSGi R4.1 Core and Compendium
+libraries as well as the Equinox HttpService bridge and the Servlet API.</p>
+</li>
+<li>
+<p><em>App JAR</em> -- The secondary artifact with classifier <em>app</em> is a minimal
+Standalone Java Application which may be started by simply typing</p>
+<p>$ java -jar org.apache.sling.launchpad.base-app.jar</p>
+</li>
+<li>
+<p><em>Web App Archive</em> -- The secondary artifact with classifier <em>webapp</em> is a
+minimal Web Application, which may simply be deployed into your favirourite
+servlet container, provided it supports at least Servlet API 2.4.</p>
+</li>
+<li>
+<p><em>Source JAR</em> -- The secondary artifact with the classifier <em>sources</em> is
+simple the source of the <em>Launchpad Base</em> project.</p>
+</li>
+</ul>
+<p>To build a very basic Sling launcher, the <em>Launchpad Base</em> is actually all
+you need. But to really glue this together and get a usable system, some
+more work is required. Lets see how the additionaly projects <em>Launchpad
+Bundles</em>, <em>Launchpad App</em>, and <em>Launchpad WebApp</em> get to that.</p>
+<p><a name="TheSlingLaunchpad-LaunchpadBundles"></a></p>
+<h3 id="launchpad-bundles">Launchpad Bundles</h3>
+<p>The second project we want to look at is the <em>Launchpad Bundles</em> project.
+This is a very simple project in that it only collects together a number of
+OSGi bundles, which will make up the final application. The bundles are
+stored in a (big) Java Archive in folders whose path is formed with
+<em>resources/9</em> where <em>9</em> is a start level which is assigned to the
+bundles as they are installed. The special start level <em>0</em> instructs the
+installer to not actually assign a specific start level to the bundles
+contained in that folder.</p>
+<p>Currently the following start level assignement is used by the <em>Launchpad
+Bundles</em> project:</p>
+<table>
+<tr><th> Start Level </th><th> Bundle Group </th><th> Bundle(s) </th></tr>
+<tr><td> 1 </td><td> Basic bundles required for the correct operation of Sling </td><td>
+org.apache.sling.commons.log
+</tr>
+<tr><td> 5 </td><td> Apache Felix Web Console </td><td> org.apache.felix.bundlerepository,
+org.apache.felix.webconsole, org.apache.sling.extensions.threaddump </td></tr>
+<tr><td> 10 </td><td> OSGi Compendium Service Implementations </td><td>
+org.apache.felix.configadmin, org.apache.felix.eventadmin,
+org.apache.felix.metatype, org.apache.felix.scr </td></tr>
+<tr><td> 15 </td><td> JCR Repository (Jackrabbit) </td><td> commons-collections,
+commons-io-1.4.jar
+</tr>
+commons-lang, jackrabbit-api, jackrabbit-jcr-commons,
+org.apache.sling.commons.mime, org.apache.sling.commons.osgi,
+org.apache.sling.jcr.api, org.apache.sling.jcr.base,
+org.apache.sling.jcr.jackrabbit.server, org.apache.sling.jcr.webdav |
+<tr><td> 0 </td><td> Actual Sling Application bundles </td><td> org.apache.sling.adapter,
+org.apache.sling.api, org.apache.sling.bundleresource.impl,
+org.apache.sling.commons.json, org.apache.sling.engine,
+org.apache.sling.extensions.apt.parser,
+org.apache.sling.extensions.apt.servlet, org.apache.sling.httpauth,
+org.apache.sling.jcr.classloader, org.apache.sling.jcr.contentloader,
+org.apache.sling.jcr.ocm, org.apache.sling.jcr.resource,
+org.apache.sling.launchpad.content,
+org.apache.sling.samples.path-based.rtp, org.apache.sling.scripting.api,
+org.apache.sling.scripting.core, org.apache.sling.scripting.javascript,
+org.apache.sling.scripting.jsp, org.apache.sling.scripting.jsp.taglib,
+org.apache.sling.servlets.get, org.apache.sling.servlets.post,
+org.apache.sling.servlets.resolver </td></tr>
+</table>
+
+<p><a name="TheSlingLaunchpad-LaunchpadAppandLaunchpadWebApp"></a></p>
+<h3 id="launchpad-app-and-launchpad-webapp">Launchpad App and Launchpad WebApp</h3>
+<p>The <em>Launchpad App</em> and <em>Launchpad WebApp</em> bundles are actually projects
+which just glue together artifacts from the Launchpad projects. There is
+nothing special about them. Here's what is done:</p>
+<ul>
+<li>Take the appropriate secondary artifact from the <em>Launchpad Base</em>
+project: <em>app</em> for the Standalone Java Application or <em>webapp</em> for the Web
+Application and unpack</li>
+<li>Take the <em>Launchpad Base</em> primary artifact and place it under the name
+<em>org.apache.sling.launchpad.base.jar</em> into the <em>resources</em> folder</li>
+<li>Take the <em>Launchpad Bundles</em> artifact and unpack it</li>
+<li>Finally pack all together into a single big JAR or WAR file</li>
+</ul>
+<p>That's it. The resulting artifact may be directly used to launch the
+Standalone Java Application or may directly be deployed into any Servlet
+API 2.4 (or later) compliant servlet container.</p>
+ </div>
+ </div>
+
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/url-decomposition.html
==============================================================================
--- websites/staging/sling/trunk/content/url-decomposition.html (added)
+++ websites/staging/sling/trunk/content/url-decomposition.html Sun Apr 22 16:52:28 2012
@@ -0,0 +1,142 @@
+<!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 - URL decomposition</title>
+ <link rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="getting-started.html">Getting Started</a></li>
+<li><a href="the-sling-engine.html">The Sling Engine</a></li>
+<li><a href="development.html">Development</a></li>
+<li><a href="bundles.html">Bundles</a></li>
+<li><a href="tutorials-&-how-tos.html">Tutorials & How-Tos</a></li>
+<li><a href="configuration.html">Configuration</a></li>
+<li><a href="http://sling.apache.org/apidocs/sling5/index.html">API docs</a></li>
+<li><a href="http://s.apache.org/sling.wiki">Wiki</a></li>
+<li><a href="http://s.apache.org/sling.faq">FAQ</a></li>
+</ul>
+<h1 id="project-info">Project info</h1>
+<ul>
+<li><a href="http://sling.apache.org/site/downloads.cgi">Downloads</a></li>
+<li><a href="http://www.apache.org/licenses/">License</a></li>
+<li><a href="contributing.html">Contributing</a></li>
+<li><a href="news.html">News</a></li>
+<li><a href="links.html">Links</a></li>
+<li><a href="project-information.html">Project Information</a></li>
+<li><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a></li>
+<li><a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+<h1 id="sponsorship">Sponsorship</h1>
+<ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a></li>
+</ul>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ (TODO: breadcrumb here)
+ </div>
+ <h1 class="title">URL decomposition</h1>
+ <div>
+ <p><a name="URLdecomposition-URLdecomposition"></a></p>
+<h1 id="url-decomposition">URL decomposition</h1>
+<p>During the <em>Resource Resolution</em> step, the client request URL is decomposed
+into the following parts:</p>
+<ol>
+<li><em>Resource Path</em> - The longest substring of the request URL such that the
+resource path is either the complete request URL or the next character in
+the request URL after the resource path is a dot (<em>.</em>).</li>
+<li><em>Selectors</em> - If the first character in the request URL after the
+resource path is a dot, the string after the dot up to but not including
+the last dot before the next slash character or the end of the request URL.
+If the resource path spans the complete request URL no seletors exist. If
+only one dot follows the resource path before the end of the request URL or
+the next slash, also no selectors exist.</li>
+<li><em>Extension</em> - The string after the last dot after the resource path in
+the request URL but before the end of the request URL or the next slash
+after the resource path in the request URL. </li>
+<li><em>Suffix Path</em> - If the request URL contains a slash character after the
+resource path and optional selectors and extension, the path starting with
+the slash up to the end of the request URL is the suffix path. Otherwise,
+the suffix path is empty. Note, that after the resource path at least a dot
+must be in the URL to let Sling detect the resource path.</li>
+</ol>
+<p>There's a cheat sheet on Day's dev page under <a href="http://dev.day.com/content/docs/en/cq/current/developing/sling_cheatsheet.html">http://dev.day.com/content/docs/en/cq/current/developing/sling_cheatsheet.html</a>
+ available to get you familiar with the URL decomposition of Sling.</p>
+<p><em>Examples</em>: Assume there is a Resource at <em>/a/b</em>, which has no children.</p>
+<table>
+<tr><th> URI </th><th> Resource Path </th><th> Selectors </th><th> Extension </th><th> Suffix </th><th> Resource
+Found </th></tr>
+<tr><td> /a/b </td><td> /a/b </td><td> null </td><td> null </td><td> null </td><td> yes </td></tr>
+<tr><td> /a/b.html </td><td> /a/b </td><td> null </td><td> html </td><td> null </td><td> yes </td></tr>
+<tr><td> /a/b.s1.html </td><td> /a/b </td><td> s1 </td><td> html </td><td> null </td><td> yes </td></tr>
+<tr><td> /a/b.s1.s2.html </td><td> /a/b </td><td> s1.s2 </td><td> html </td><td> null </td><td> yes </td></tr>
+<tr><td> /a/b/c/d </td><td> /a/b/c/d </td><td> null </td><td> null </td><td> null </td><td> no! </td></tr>
+<tr><td> /a/b./c/d </td><td> /a/b </td><td> null </td><td> null </td><td> /c/d </td><td> yes </td></tr>
+<tr><td> /a/b.html/c/d </td><td> /a/b </td><td> null </td><td> html </td><td> /c/d </td><td> yes </td></tr>
+<tr><td> /a/b.s1.html/c/d </td><td> /a/b </td><td> s1 </td><td> html </td><td> /c/d </td><td> yes </td></tr>
+<tr><td> /a/b.s1.s2.html/c/d </td><td> /a/b </td><td> s1.s2 </td><td> html </td><td> /c/d </td><td> yes </td></tr>
+<tr><td> /a/b/c/d.s.txt </td><td> /a/b/c/d </td><td> s </td><td> txt </td><td> null </td><td> no! </td></tr>
+<tr><td> /a/b.html/c/d.s.txt </td><td> /a/b </td><td> null </td><td> html </td><td> /c/d.s.txt </td><td> yes </td></tr>
+<tr><td> /a/b.s1.html/c/d.s.txt </td><td> /a/b </td><td> s1 </td><td> html </td><td> /c/d.s.txt </td><td> yes </td></tr>
+<tr><td> /a/b.s1.s2.html/c/d.s.txt </td><td> /a/b </td><td> s1.s2 </td><td> html </td><td> /c/d.s.txt </td><td> yes </td></tr>
+</table>
+
+<p>{info:title=Automated tests and examples}
+The <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/engine/src/test/java/org/apache/sling/engine/impl/request/SlingRequestPathInfoTest.java">SlingRequestPathInfoTest</a>
+ demonstrates and tests this decomposition. Feel free to suggest additional
+tests that help clarify how this works!
+{info}</p>
+ </div>
+ </div>
+
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </body>
+</html>
Added: websites/staging/sling/trunk/content/version-policy.html
==============================================================================
--- websites/staging/sling/trunk/content/version-policy.html (added)
+++ websites/staging/sling/trunk/content/version-policy.html Sun Apr 22 16:52:28 2012
@@ -0,0 +1,376 @@
+<!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 - Version Policy</title>
+ <link rel="stylesheet" href="http://sling.apache.org/site/media.data/site.css" type="text/css" media="all">
+ <link rel="icon" href="http://sling.apache.org/site/media.data/favicon.ico">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/site/index.html">
+ <img border="0" alt="Apache Sling" src="http://sling.apache.org/site/media.data/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="http://sling.apache.org/site/media.data/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="getting-started.html">Getting Started</a></li>
+<li><a href="the-sling-engine.html">The Sling Engine</a></li>
+<li><a href="development.html">Development</a></li>
+<li><a href="bundles.html">Bundles</a></li>
+<li><a href="tutorials-&-how-tos.html">Tutorials & How-Tos</a></li>
+<li><a href="configuration.html">Configuration</a></li>
+<li><a href="http://sling.apache.org/apidocs/sling5/index.html">API docs</a></li>
+<li><a href="http://s.apache.org/sling.wiki">Wiki</a></li>
+<li><a href="http://s.apache.org/sling.faq">FAQ</a></li>
+</ul>
+<h1 id="project-info">Project info</h1>
+<ul>
+<li><a href="http://sling.apache.org/site/downloads.cgi">Downloads</a></li>
+<li><a href="http://www.apache.org/licenses/">License</a></li>
+<li><a href="contributing.html">Contributing</a></li>
+<li><a href="news.html">News</a></li>
+<li><a href="links.html">Links</a></li>
+<li><a href="project-information.html">Project Information</a></li>
+<li><a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a></li>
+<li><a href="http://svn.apache.org/viewvc/sling/trunk">Browse Source Repository</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+<h1 id="sponsorship">Sponsorship</h1>
+<ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a></li>
+</ul>
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ (TODO: breadcrumb here)
+ </div>
+ <h1 class="title">Version Policy</h1>
+ <div>
+ <p><a name="VersionPolicy-DRAFTVersionPolicy"></a></p>
+<h1 id="draft-version-policy">DRAFT Version Policy</h1>
+<p>{excerpt}This page is about how we assign versions to exported packages and
+bundles and defines when to increase which part of the version
+number.{excerpt}</p>
+<p>{info}
+Please note that this page is currently in draft stage and still being
+discussed.
+{info}</p>
+<p>{toc:minLevel=2|maxLevel=2}</p>
+<p><a name="VersionPolicy-Introduction"></a></p>
+<h2 id="introduction">Introduction</h2>
+<p>In comments to SLING-1176 Ian Boston wrote:</p>
+<p>{quote}
+The exports in bundle/api/pom.xml look like they might become problematic from a support point of view, although we probably can't avoid this. [...](....html)
+ [The problem is the] manual maintenance of the version numbers. (not a
+big problem but needs to be done)
+{quote}</p>
+<p>I agree, that this is a problem. So let me reasonate on this a bit ;-)</p>
+<p>As a reference you might want to read <a href="http://blog.meschberger.ch/2009/10/on-version-numbers.html">my blog post on version numbers</a>
+ and also what the [Eclipse guys have to say|http://wiki.eclipse.org/index.php/Version_Numbering]
+ (great read, btw). The OSGi Alliance has come up with a good definition
+for [Semantic Versioning|http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf]
+ to which the definitions described below perfectly match.</p>
+<p>For Sling we have three kinds of version numbers:</p>
+<ol>
+<li>Big Sling Releases</li>
+<li>Sling Bundles</li>
+<li>Package Exports</li>
+</ol>
+<p><em>Big Sling Releases</em></p>
+<p>For <em>Big Sling releases</em> we already have an ample solution in that we just
+use a single number increased from release to release. Just remember that a
+<em>Big Sling release</em> is a convenience release of existing released Sling
+bundles.</p>
+<p><em>Sling Bundles</em></p>
+<p>For <em>Sling Bundles</em> version numbers are just defined as the <em><version></em>
+element of the bundle's POM. The only restriction here is, that we decided
+to use even numbers for releases and odd numbers for SNAPSHOTs. Whether and
+when which version part is increased is not explicitly defined yet.</p>
+<p><em>Package Exports</em></p>
+<p>For <em>Package Exports</em> the situation is more problematic since there are a
+number of places to set exported package version number:</p>
+<ul>
+<li>In a <em>packageinfo</em> file inside the package (picked up by the Maven
+Bundle Plugin to set the export version)</li>
+<li>Explicitly in the <em><Export-Package></em> element of the Maven Bundle
+Plugin configuration</li>
+<li>By reference to the bundle version number using the <em>${pom.version</em>}
+variable.</li>
+</ul>
+<p>Upto now, we mostly used the <em>${pom.version</em> notation linking the
+exported package version to the bundle version. Over time this mechanism
+leads to a number of problems:</p>
+<ul>
+<li>For bundles with more than one package exported, the exported packages
+will evolve independently. As a consequence their versionin should also
+evolve independently. An example of such a bundle is the Sling API bundle
+of course.</li>
+<li>Linking the package export version number to the bundle version number
+confuses the actual semantics of both version numbers. The package export
+version number only indicates the version of the actual package while the
+bundle version number indicates a development state of the overall bundle.
+This will generally not be the same.</li>
+<li>The version of the exported package is increased on each bundle
+release, even though nothing may have changed on the export. In such a
+situation the version of the export should stay the same.</li>
+</ul>
+<p>That said, the reuse of the bundle version as the package export version
+still is probably the correct thing to do for legacy library wrappers.</p>
+<p>Consider for example the Sling API bundle, which exports 9 packages. Each
+of which may evolve independently. Now the <em>resource</em> package is extended
+causing a minor version increase. Should the version numbers of the other
+exports also be increased ? Thus acting as if there was some API change ?</p>
+<p>I would say, no. Particularly if some API implementation bundle is
+restricting the import version of the API implemented. Such an
+implementation would immediately stop working because the version has been
+increased. But since there has been no change, the implementation would
+still be correct.</p>
+<p>So, I think, we should evolve the exported package versions independently
+from each other and even independently from the bundle version.</p>
+<p>This places more burden on the developer when deciding on the exported
+package version - in fact this requires such a decision as compared to have
+Maven take the decision by just setting the bundle version.</p>
+<p>The only problem is: Where shall this be noted ? In the POM or in the
+<em>packageinfo</em> file ? If we would place the <em>packageinfo</em> file just
+beneath the class source files, I would say, in the <em>packageinfo</em> file.</p>
+<p>But this would require defining the class source locations as resource
+location in the POM (at least for <em>packageinfo</em>) files.</p>
+<p>I am not sure ....</p>
+<p>This has not been discussed at large, but I would assume, that the POM is
+still the correct place to take note of the version of the exported
+packages.</p>
+<p><em>Future</em></p>
+<p>The newest versions of the BND library also support an <em>@Export</em>
+annotation in the <em>package-info.java</em> pseudo class file. This pseudo
+class is supported starting with Java 5 to take package level annotations
+(like the <em>@Export</em> annotation) and as a replacement of the
+<em>package-info.html</em> file.</p>
+<p>Using this syntax something like the following would be easily possible:</p>
+<div class="codehilite"><pre><span class="o">/**</span>
+ <span class="o">*</span> <span class="n">This</span> <span class="n">is</span> <span class="n">the</span> <span class="n">Package</span> <span class="n">Level</span> <span class="n">JavaDoc</span>
+ <span class="o">*/</span>
+<span class="nv">@Export</span><span class="p">(</span><span class="n">version</span> <span class="o">=</span> <span class="s">"1.0"</span><span class="p">)</span>
+<span class="nb">package</span> <span class="n">org</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">sling</span><span class="o">.</span><span class="n">api</span><span class="o">.</span><span class="n">auth</span><span class="p">;</span>
+<span class="nb">import</span> <span class="n">aQute</span><span class="o">.</span><span class="n">bnd</span><span class="o">.</span><span class="n">annotation</span><span class="o">.</span><span class="n">Export</span><span class="p">;</span>
+</pre></div>
+
+
+<p>See <a href="http://www.aqute.biz/Code/XBnd">Bnd Experimental</a>
+ for details. Unfortunately the current Maven Bundle Plugin version does
+not support updating to the most recent BND library versions due to
+incompatibilities.</p>
+<p><a name="VersionPolicy-VersionNumberSyntax"></a></p>
+<h2 id="version-number-syntax">Version Number Syntax</h2>
+<p>As a small reminder, this is how a version number is constructed: In OSGi
+version numbers are composed of four (4) segments: 3 integers and a string
+named major.minor.micro.qualifier.</p>
+<p>Each segment captures a different intent:</p>
+<div class="codehilite"><pre><span class="o">*</span> <span class="n">the</span> <span class="n">major</span> <span class="n">segment</span> <span class="n">indicates</span> <span class="n">breakage</span> <span class="n">in</span> <span class="n">the</span> <span class="n">API</span>
+<span class="o">*</span> <span class="n">the</span> <span class="n">minor</span> <span class="n">segment</span> <span class="n">indicates</span> <span class="n">_externally</span> <span class="n">visible_</span> <span class="n">changes</span>
+<span class="o">*</span> <span class="n">the</span> <span class="n">micro</span> <span class="n">segment</span> <span class="n">indicates</span> <span class="n">bug</span> <span class="n">fixes</span>
+<span class="o">*</span> <span class="n">the</span> <span class="n">qualifier</span> <span class="n">segment</span> <span class="n">is</span> <span class="ow">not</span> <span class="n">generally</span> <span class="n">used</span> <span class="n">but</span> <span class="n">may</span> <span class="n">be</span> <span class="n">used</span> <span class="n">to</span> <span class="n">convey</span>
+</pre></div>
+
+
+<p>more information about a particular build, such as a build time or an SVN
+revision number.</p>
+<p><a name="VersionPolicy-EvolutionofExportedPackageVersions"></a></p>
+<h2 id="evolution-of-exported-package-versions">Evolution of Exported Package Versions</h2>
+<p>Version numbers of exported packages evolve independently from each other.
+Depending on the changes applied, the micro, minor, or major segement is
+increased. Whenever the major segment is increased, the minor and micro
+segments are reset to zero. Whenever the minor segment is increased, the
+micro segment is reset to zero.</p>
+<p>Segments are increased according to the above listing.</p>
+<p>This requires committers to think well about changes they apply to exported
+packages:</p>
+<ul>
+<li>Removing interfaces, methods or constants is likely an API breakage and
+thus requires a major version increase. In Sling we try to prevent this
+from happening.</li>
+<li>Adding new methods to interfaces is likely just an <em>externally visible</em>
+change and thus requires a minor version increase</li>
+<li>Fixing a bug in an exported class just requires a minor version
+increase.</li>
+</ul>
+<p>JavaDoc updates generally do not constitute a reason to evolve the version
+number. The exception is that if the JavaDoc update is caused by a API
+limitation, it might be conceivable to increase the version number of the
+exported package. A decision on this will have to be taken on a
+case-by-case basis.</p>
+<p><a name="VersionPolicy-EvolutionofBundleVersions"></a></p>
+<h2 id="evolution-of-bundle-versions">Evolution of Bundle Versions</h2>
+<p>Version numbers of bundles evolve depending on the evolution of the
+exported packages but also depending on the evolution of the private code,
+which is not exported.</p>
+<p>As a rule of thumb, the following reasons apply for increasing the segments
+of bundle version numbers:</p>
+<ul>
+<li>Increasing the major version number of any of the exported packages or
+restructuring the bundle such that major parts are removed from the bundle
+(and either completely removed or moved to other bundle(s)).</li>
+<li>Increasing the minor version number of any of the exported packages or
+refactoring the internal code or implementing a package exported by another
+bundle whose minor (or even major) version number has increased. Also
+functional extensions of the internal bundle classes consitutes a reason to
+increase the minor version number.</li>
+<li>Increasing the micro version number of any of the exported packages or
+bug fixes.</li>
+</ul>
+<p>Note, that this definition does not require the bundle and epxorted package
+version numbers to be synchronized in any way. While doing so might help in
+a first or second step, over time it will become close to impossible to
+keep the versions in sync. So rather than trying to keep the versions in
+sync, we should make sure, we increase the versions correctly.</p>
+<p><a name="VersionPolicy-Examples"></a></p>
+<h2 id="examples">Examples</h2>
+<p><a name="VersionPolicy-PureAPIBundle"></a></p>
+<h3 id="pure-api-bundle">Pure API Bundle</h3>
+<p>An example of an almost <em>Pure API Bundle</em> is the Sling API bundle. This
+bundle exports 9 packages. Some are really stable -- e.g. the
+<em>org.apache.sling.api</em> package or the <em>org.apache.sling.wrappers</em>
+package -- and some are being worked on at the moment -- e.g. the
+<em>org.apache.sling.resource</em> package.</p>
+<p>To not break existing users of the unmodified packages, the exported
+versions of these packages must not be increased.</p>
+<p>To signal to users of evolving packages, that there might be new and
+interesting functionality, the version number must be increased according
+to above definition. This also conveys to the implementor(s) of the API,
+that they have to take some action.</p>
+<p>A hypothetical evolution of version numbers shown on two packages and the
+bundle version might be as follows</p>
+<table>
+<tr><td> Description </td><td> *api* package </td><td> *resource* package </td><td> bundle </td></tr>
+<tr><td> Initial Release </td><td> 1.0.0 </td><td> 1.0.0 </td><td> 1.0.0 </td></tr>
+<tr><td> Bug fix in a *resource* class </td><td> 1.0.0 </td><td> 1.0.2 </td><td> 1.0.2 </td></tr>
+<tr><td> New API in the *resource* package </td><td> 1.0.0 </td><td> 1.1.0 </td><td> 1.1.0 </td></tr>
+<tr><td> New API in the *api* package </td><td> 1.1.0 </td><td> 1.1.0 </td><td> 1.2.0 </td></tr>
+<tr><td> API breakage in the *api* package </td><td> 2.0.0 </td><td> 1.1.0 </td><td> 2.0.0 </td></tr>
+</table>
+
+<p><a name="VersionPolicy-ImplementationBundleprovidingAPI"></a></p>
+<h3 id="implementation-bundle-providing-api">Implementation Bundle providing API</h3>
+<p>An example of such a hybrid bundle is the Sling Engine bundle. This bundle
+exports two packages themselves defining API and contains a number of
+internal packages which actually implement parts of the Sling API.</p>
+<p>A hypothetical evolution of version numbers shown on one exported package
+and the bundle version might be as follows</p>
+<table>
+<tr><td> Description </td><td> *engine* package </td><td> bundle </td></tr>
+<tr><td> Initial Release </td><td> 1.0.0 </td><td> 1.0.0 </td></tr>
+<tr><td> Bug fix in a *engine* class </td><td> 1.0.2 </td><td> 1.0.2 </td></tr>
+<tr><td> Bug fix in an internal calss </td><td> 1.0.2 </td><td> 1.0.4 </td></tr>
+<tr><td> New API in the *engine* package </td><td> 1.1.0 </td><td> 1.1.0 </td></tr>
+<tr><td> Implement new API from *api* 1.1.0 </td><td> 1.1.0 </td><td> 1.2.0 </td></tr>
+<tr><td> Refactor internal classes </td><td> 1.1.0 </td><td> 1.3.0 </td></tr>
+<tr><td> Implement API from *api* 2.0.0 </td><td> 1.1.0 </td><td> 2.0.0 </td></tr>
+</table>
+
+<p><a name="VersionPolicy-PureImplementationBundle"></a></p>
+<h3 id="pure-implementation-bundle">Pure Implementation Bundle</h3>
+<p>For Pure Implementation Bundles only the bundle version numbers are
+maintained because there is no exported package whose version number needs
+to be managed. This makes the decision process of version number evolution
+very simple.</p>
+<p><a name="VersionPolicy-ImportingPackages"></a></p>
+<h2 id="importing-packages">Importing Packages</h2>
+<p>When importing packages a version number will automatically be generated by
+the Maven Bundle Plugin as follows:</p>
+<ul>
+<li>If the providing package exports a package with an explicit version
+number, that exact version number will be used as the lower bound</li>
+<li>If such a lower bound exists, the upper bound is exclusive the next
+major version number.</li>
+</ul>
+<p>For example if importing the <em>api</em> package exported at version 1.2.3, the
+<em>Import-Package</em> statement is generated as</p>
+<div class="codehilite"><pre><span class="n">Import</span><span class="o">-</span><span class="n">Package:</span> <span class="n">api</span><span class="p">;</span><span class="n">version</span><span class="o">=</span><span class="p">[</span><span class="mf">1.2.3</span><span class="p">,</span><span class="mf">2.0.0</span><span class="p">)</span>
+</pre></div>
+
+
+<p>This default works well for consumers of the API, since according to above
+definitions an API is guaranteed to not contain breakages if the major
+version number is not increased.</p>
+<p>For bundles implementing the API, this default does not work well, since
+from their point of view an <em>externally visible</em> change in fact constitutes
+a breakage, because the implementation is not complete. So if a bundle
+implements a package a manually crafted import version should be defined
+which includes the export version of the defining bundle but excludes the
+next minor version.</p>
+<p>For example implementing the <em>api</em> package exported at version 1.2.3,
+would require the following manually created <em>Import-Package</em> statement:</p>
+<div class="codehilite"><pre><span class="n">Import</span><span class="o">-</span><span class="n">Package:</span> <span class="n">api</span><span class="p">;</span><span class="n">version</span><span class="o">=</span><span class="p">[</span><span class="mf">1.2.3</span><span class="p">,</span><span class="mf">1.3.0</span><span class="p">)</span>
+</pre></div>
+
+
+<p>This allows for the implementation to work correctly with bug fixed package
+exports but as soon as there are any <em>externally visible</em> changes, the
+implementation bundle has to be adapted -- even if this just means
+increasing the upper version bound in the <em>Import-Package</em> statement thus
+guaranteeing compliance (again).</p>
+<p><em>Future</em></p>
+<p>Recent versions of the BND library support automatic differntiation between
+use and implementation of API and to set the import version ranges
+accordingly. See <a href="http://www.aqute.biz/Code/XBnd">Bnd Experimental</a>
+ for details. Unfortunately the current Maven Bundle Plugin version does
+not support updating to the most recent BND library versions due to
+incompatibilities.</p>
+<p><a name="VersionPolicy-References"></a></p>
+<h2 id="references">References</h2>
+<p><a href="http://markmail.org/thread/zshobgjwtqrncajt">Version Numbers</a>
+ -- The mail thread discussing version numbering
+<a href="http://blog.meschberger.ch/2009/10/on-version-numbers.html">On Version Numbers</a>
+ -- Blog about version numbers
+<a href="http://wiki.eclipse.org/index.php/Version_Numbering">Version Numbering</a>
+ -- An Eclipse paper on assigning version numbers. Very good read.
+<a href="http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf">Semantic Versioning</a>
+ -- An OSGi Alliance paper on semantic versioning.
+<a href="http://www.aqute.biz/Code/XBnd">Bnd Experimental</a>
+ -- Experimental extensions to the BND library; unfortunately these
+extensions are not yet usable with Maven Bundle Plugin 2.1.0 due to API
+changes in the BND library not supported by the plugin.</p>
+ </div>
+ </div>
+
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </body>
+</html>