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 [6/18] - in /websites/staging/sling/trunk/content: ./
authentication/ documentation/ documentation/bundles/
documentation/development/ documentation/getting-started/
documentation/the-sling-engine/ documentation/the-sling-engine/aut...
Added: websites/staging/sling/trunk/content/documentation/configuration.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/configuration.html (added)
+++ websites/staging/sling/trunk/content/documentation/configuration.html Tue May 22 09:41:22 2012
@@ -0,0 +1,280 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - Configuration</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>
+ </div>
+ <h1>Configuration</h1>
+ <h2 id="introduction">Introduction</h2>
+<p>Configuration in Sling is aligned with respective support by the OSGi specification:</p>
+<ul>
+<li>Framework and Java system properties are available through the <code>BundleContext.getProperty(String)</code> method. These properties are provided in Sling through the Sling launcher.</li>
+<li>Bundle Header values are available through the <code>Bundle.getHeaders()</code> and <code>Bundle.getHeaders(String)</code> methods. These header values are set by the bundle developer in the <code>META-INF/MANIFEST.MF</code> file. In fact, all main manifest attributes are available through these methods.</li>
+<li>Components managed by the Service Component Runtime and declared in component descriptor files listed in the <code>Service-Component</code> manifest header access configuration properties through the <code>ComponentContext.getProperties()</code> method. These properties have three sources:
+ <em># Configuration specified specifically for factory components
+ </em># Properties retrieved from the Configuration Admin Service
+ *# Properties set in the component descriptor</li>
+<li>Configuration properties provided to <code>ManagedService</code> and <code>ManagedServiceFactory</code> instances by the Configuration Admin Service.</li>
+</ul>
+<p>For the discussion to follow we differentiate between intial configuration provided by Framework and system properties and managed configuration provided by the Configuration Admin Service.</p>
+<p>Components managed by the Service Component Runtime are generally configured (as listed above) through the descriptor properties and configuration set by Configuration Admin Service configuration. The descriptor property values may be seen as configuration default values set by the component developer, which may be overwritten by user configuration through the Configuration Admin Service. Components may but are not required to make use of Framework properties by accessing the <code>BundleContext</code> through the <code>ComponentContext</code> given to the <code>activate(ComponentContext)</code> method of the component.</p>
+<h2 id="initial-configuration">Initial Configuration</h2>
+<p>The lifecycle of the OSGi framework implemented by an instance of the <code>org.apache.felix.framework.Felix</code> class is managed by the Sling launcher class <code>org.apache.sling.launcher.Sling</code>. This class is used by the standalone main class (<code>org.apache.sling.launcher.main.Main</code>) and the Sling Servlet (<code>org.apache.sling.launcher.servlet.SlingServlet</code>) to control the lifecycle.</p>
+<p>The Sling launcher is responsible to provide the Framework properties to the OSGi framework. The properties are prepared as a <code>java.util.Map<String, String></code> instance as follows (later steps may overwrite properties defined in earlier steps) :</p>
+<ol>
+<li>Load core properties from the embedded <code>sling.properties</code> file.</li>
+<li>Resolve any property file inclusions. This is mainly used to resolve the correct JRE package definitions for the JRE version used.</li>
+<li>Overwrite with any properties provided by the main class or the Sling Servlet.</li>
+<li>Make sure the <code>sling.home</code> property is set defining a sensible default value if missing</li>
+<li>Load the contents of the <code>$\{sling.home}/sling.properties</code> file</li>
+<li>Overwrite properties with Java system properties. This step only considers system properties of the same names as properties already existing. That is, the system properties are not just copied into the properties here. Additionally this step my be omitted if the <code>sling.ignoreSystemProperties</code> property is set to <code>true</code>.</li>
+<li>Resolve any property file inclusions. This may be used to provide more configurability depending on the integration.</li>
+<li>Handle OSGi boot delegation support (see below).</li>
+<li>Resolve property references of the form <code>$\{propName</code>}</li>
+<li>For each property value starting with <code>ontext:/</code> do the following, assuming the value to be an URL with scheme <code>context:</code>:</li>
+<li>
+<ul>
+<li>Copy the application resource to <code>$\{sling.home</code>} preserving the URL path unless such a file already exists.</li>
+</ul>
+</li>
+<li>
+<ul>
+<li>Replace the property value with the path to the newly created file. The path has the form <code>$\{sling.home}/relpath</code>.</li>
+</ul>
+</li>
+<li>Store the properties as <code>$\{sling.home}/sling.properties</code> to be re-used on next startup</li>
+<li>Setup Bundle auto installation for the Felix Framework</li>
+</ol>
+<p>Using file system copies of the initial configuration and referred files, it is easy to modify this configuration without the need to unpack and repackage the web application archive.</p>
+<p>The only property really required is actually the <code>sling.home</code> property, which defines the file system location where runtime files will be placed. The default if this property is missing will be <em>sling</em> in the current working directory as defined the <code>user.dir</code> system property.</p>
+<h3 id="standalone-application">Standalone Application</h3>
+<p>When launching Sling as a standalone application the <code>sling-app.jar</code> file is used. This is an executable JAR File. The <code>sling.properties</code> file as well as the <code>sling_install.properties</code> and JRE specific properties files are located at the root of the JAR file hierarchy.</p>
+<p>The standalone application currently sets properties for the third step of the configuration setup to ensure the HTTP Servlet integration is using the Apache Felix <em>http.jetty</em> bundle. Additionally system properties may be set using the <code>-D</code> command line switch of the Java binary.</p>
+<p>In addition the following command line arguments are accepted:</p>
+<table>
+<thead>
+<tr>
+<th>Argument</th>
+<th>Sling property</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>-l loglevel</code></td>
+<td><code>org.apache.sling.osgi.log.level</code></td>
+<td>The initial loglevel (0..4, FATAL, ERROR, WARN, INFO, DEBUG)</td>
+</tr>
+<tr>
+<td><code>-f logfile</code></td>
+<td><code>org.apache.sling.osgi.log.file</code></td>
+<td>The log file, "-" for stdout</td>
+</tr>
+<tr>
+<td><code>-c slinghome</code></td>
+<td><code>sling.home</code></td>
+<td>the sling context directory</td>
+</tr>
+<tr>
+<td><code>-a address</code></td>
+<td>--</td>
+<td>the interfact to bind to (use 0.0.0.0 for any) (not supported yet)</td>
+</tr>
+<tr>
+<td><code>-p port</code></td>
+<td><code>org.osgi.service.http.port</code></td>
+<td>the port to listen to (default 8080)</td>
+</tr>
+<tr>
+<td><code>-h</code></td>
+<td>--</td>
+<td>Prints a simple usage message and exits.</td>
+</tr>
+</tbody>
+</table>
+<p>The standalone application exits with status code 0 (zero) if Sling terminates normally, that is if the OSGi framework is stopped or if just the usage note has been displayed. If any error occurrs during command line parsing, the cause is printed to the error output and the application exists with status code 1 (one). If the OSGi framework fails to start, the cause is printed to the error output and the application exists with status code 2.</p>
+<h3 id="web-application">Web Application</h3>
+<p>When launching Sling as a web application using the <code>sling-servlet.war</code> or any derived Web Application archive file, the <code>sling.properties</code> file is located in the <code>WEB-INF</code> folder along with the <code>sling_install.properties</code> and JRE specific properties files.</p>
+<p>The Sling Servlet uses the Servlet Context and Servlet <code>init-param</code> configurations to prepare the properties for the third step of the configuration setup.</p>
+<p>If the OSGi framework fails to startup for any reason a <code>javax.servlet.UnavailableException</code>.</p>
+<h3 id="property-file-inclusions">Property File Inclusions</h3>
+<p>Twice in the configuration setup (second and seventh step) any property file inclusions will be handled. Property files may be included by defining one or more properties containing a comma-separated list of properties files to include. Property file inclusion looks at the <code>sling.include</code> property and any other property whose prefix is <code>sling.include.</code>. When such properties exist, the files listed in those properties are included.</p>
+<p>The order of handling the property file inclusion properties is defined as natural sort order of the actual property names. So the properties of the files listed in the <code>sling.include.first</code> property will be loaded before the files listed in the <code>sling.include.second</code> but after the files listed in the <code>sling.include.a</code> property.</p>
+<p>Any file which does not exist is silently ignored.</p>
+<p>The names of the files are resolved as follows:</p>
+<ol>
+<li>If a resource exists at the same location as the initial <code>sling.properties</code> file packaged with the application, that resource is used</li>
+<li>If the name is a relative file name, it is looked for in the <code>sling.home</code> directory</li>
+<li>If the name is an absolute file name, it is used as is</li>
+</ol>
+<p><em>Example</em></p>
+<p>The packaged <code>sling.properties</code> file contains the following properties file inclusion setting:</p>
+<div class="codehilite"><pre>sling.include.jre = jre-<span class="cp">${</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>.properties
+</pre></div>
+
+
+<p>This is used to include the JRE package list to be made visible inside the OSGi framework.</p>
+<h3 id="osgi-boot-delegation-support">OSGi Boot Delegation Support</h3>
+<p>Some packages may have to be shared between bundles in an OSGi framework and the rest of Java VM in which the framework has been launched. This is especially true for OSGi framework instances launched in embedding such as Servlet Containers. In the case of a Sling Application accessing a JCR Repository launched in a different Web Application, this mainly concerns an API packages as well as the JNDI Initial Factory package(s).</p>
+<p>To cope with this sharing issue, the OSGi core specification defines two properties, which may list packages to be used from the environment:</p>
+<ul>
+<li><em><code>org.osgi.framework.system.packages</code></em> - This property lists package names which are added to the list of exported packages of the system bundle of the OSGi framework. These packages are used in the resolution process just as any package listed in an <code>Export-Package</code> bundle manifest header.</li>
+<li><em><code>org.osgi.framework.bootdelegation</code></em> - This property lists packages, which are always used from the environment. As such, these packages will never be looked up in package wirings as are packages imported by listing them in the <code>Import-Package</code> bundle manifest header.</li>
+</ul>
+<p>Sometimes, especially in the Servlet Container case, it is important to use the shared classes from the container and not resolve using standard OSGi resolution. In such cases, the packages of these shared classes must be listed in the <code>org.osgi.framework.bootdelegation</code> property. Sling provides a mechanism to extend the default setting of the <code>org.osgi.framework.bootdelegation</code> property by adding properties prefixed with <code>sling.bootdelegation.</code>. The value of each of these prefixed properties is conditionally appended to the <code>org.osgi.framework.bootdelegation</code> property. <em>Conditionally</em> means, that the property name may contain the fully qualified name of a class, which is checked to see whether to add the property value or not.</p>
+<p><em>Examples</em></p>
+<p>| <code>sling.bootdelegation.simple = com.some.package</code> | This setting unconditionally adds the <code>com.some.package</code> package to the <code>org.osgi.framework.bootdelegation</code> property |
+|
+| <code>sling.bootdelegation.class.com.some.other.Main = com.some.other</code> | This setting checks whether the <code>com.some.other.Main</code> class is known. If so, the <code>com.some.other</code> package is added to the <code>org.osgi.framework.bootdelegation</code> property. Otherwise the <code>com.some.other</code> package is not added - and therefore must be exported by a bundle if required for use inside the framework. |</p>
+<p><em>Note</em> Even though packages listed in the <code>org.osgi.framework.bootdelegation</code> property will always be loaded from the environment, any bundles using these packages must still import them (through <code>Import-Package</code> or <code>DynamicImport-Package</code>) and the bundles must resolve for being usable.</p>
+<h3 id="osgi-system-packages-support">OSGi System Packages Support</h3>
+<p>As listed in the above section on OSGi Boot Delegation Support, the <code>org.osgi.framework.system.packages</code> property may be used to extend the export list of the system bundle. Similar to the support for extending the boot delegation packages list, Sling supports extending the system packages list. The mechanism to extend the default setting of the <code>org.osgi.framework.system.packages</code> property by adding properties prefixed with <code>sling.system.packages.</code>. The value of each of these prefixed properties is conditionally appended to the <code>org.osgi.framework.system.packages</code> property. <em>Conditionally</em> means, that the property name may contain the fully qualified name of a class, which is checked to see whether to add the property value or not.</p>
+<p><em>Examples</em></p>
+<p>| <code>sling.system.packages.simple = com.some.package</code> | This setting unconditionally adds the <code>com.some.package</code> package to the <code>org.osgi.framework.system.packages</code> property |
+|
+| <code>sling.system.packages.class.com.some.other.Main = com.some.other</code> | This setting checks whether the <code>com.some.other.Main</code> class is known. If so, the <code>com.some.other</code> package is added to the <code>org.osgi.framework.system.packages</code> property. Otherwise the <code>com.some.other</code> package is not added - and therefore must be exported by a bundle if required for use inside the framework. |</p>
+<p><em>Note</em> Packages listed in the <code>org.osgi.framework.system.packages</code> required by any bundles must be imported by those bundles by listing them in the <code>Import-Package</code> or <code>DynamicImport-Package</code> manifest header.</p>
+<h2 id="recommendations-for-property-names">Recommendations for property names</h2>
+<p>The following system property names are reserved:</p>
+<ul>
+<li>Names starting with <code>org.osgi.</code> are reserved for OSGi defined Framework properties</li>
+<li>Names starting with <code>org.apache.felix.</code> are reserved for the Felix Framework</li>
+<li>Names starting with <code>sling.</code> and <code>org.apache.sling.</code> are reserved for Sling</li>
+</ul>
+<p>To prevent property name collisions, I suggest the following convention:</p>
+<ul>
+<li>Use fully qualified property names for initial configuration through Framework properties</li>
+<li>Use unqualified property names for configuration through the Configuration Admin Service</li>
+</ul>
+<h2 id="well-known-properties">Well Known Properties</h2>
+<p>The following table is a collection of well known property names from different parts of Project Sling.</p>
+<table>
+<thead>
+<tr>
+<th>Property</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>sling.home</code></td>
+<td>Defines the file system location where Project Sling will write copies of the initial configuration. This property should also be used to define other local file system locations such as the directory to use for the Apache Felix Bundle Cache (<code>$\{sling.home}/felix</code> by default). If this property is not set it defaults to <code>$\{user.dir}/sling</code>.</td>
+</tr>
+<tr>
+<td><code>sling.home.url</code></td>
+<td>Contains the Sling directory set in the <code>sling.home</code> property as a valid URL. This property may be used in situations where the Sling directory is required as an URL. This property is automatically set by the Sling application and may not be modified by configuration files.</td>
+</tr>
+<tr>
+<td><code>sling.ignoreSystemProperties</code></td>
+<td>Whether to overwrite any configuration properties with Java system properties or not. By default this property is set to <code>true</code> by the Sling Servlet but not set by the Sling main class. The reason to set this by default in the Sling Servlet is to not induce values from the environment, which may not be appropriate in the Web Application case.</td>
+</tr>
+<tr>
+<td><code>obr.repository.url</code></td>
+<td>A comma-separated list of OSGi Bundle Repository URLs. See <em>Important Properties</em> on the page <a href="/old-stuff/launch-sling.html">Initial Provisioning and Startup</a>.</td>
+</tr>
+<tr>
+<td><code>sling.install.bundles</code></td>
+<td>A comma-separated list of start level numbers. See <em>Important Properties</em> on the page <a href="/old-stuff/launch-sling.html">Initial Provisioning and Startup</a>.</td>
+</tr>
+<tr>
+<td><code>sling.install.<n></code></td>
+<td>A comma-separated list of bundle specifications. See <em>Important Properties</em> on the page <a href="/old-stuff/launch-sling.html">Initial Provisioning and Startup</a>.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.osgi.log.*</code></td>
+<td>Properties providing initial configuration to the Sling Log Service. See 'Important Properties' on the page <a href="/old-stuff/launch-sling.html">Initial Provisioning and Startup</a>.</td>
+</tr>
+</tbody>
+</table>
+<h2 id="configuration-admin-service">Configuration Admin Service</h2>
+<p>Configuration of the system entities, such as services and components, by the system administrator is supported the Configuration Admin Service. The Configuration Admin Service acts as the center for the management of the configuration data, to which GUI-based tools will connect to retrieve and update configuration data. The Configuration Admin Service is responsible for persisting the configuration data and for providing configuration consumers with the configuration data. Specifically services registered with the <code>ManagedService</code> or <code>ManagedServiceFactory</code> interfaces are updated with the configuration upon updated. The Service Component Runtime on the other hand recognizes updated configuration and provides it to the managed components as defined in the OSGi Declarative Services Specification.</p>
+<p>By default the Configuration Admin Service is installed when Sling is started for the first time. This service is used by the Service Component Runtime launching the OSGi components declared in the bundles with configuration values. The Sling Management Console provides a simple GUI to manage these configuration elements on the 'Configuration' page.</p>
+<p>For more information on the Configuration Admin Service refer to the OSGi Configuration Admin Service Specification in the OSGi Service Platform Service Compendium book.</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/documentation/development.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/development.html (added)
+++ websites/staging/sling/trunk/content/documentation/development.html Tue May 22 09:41:22 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 - Development</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>
+ </div>
+ <h1>Development</h1>
+ <p>Welcome to the wonderful world of extending Sling. Refer to these pages to find out how we envision the extension of Sling and how to do it.</p>
+<h2 id="using-sling-as-your-development-framework">Using Sling as your Development Framework</h2>
+<p>Look here for more information on developper support when your are using Sling to build your own applications.</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">/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="p">[</span><span class="n">Embedding</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">embedding</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="p">[</span><span class="n">Logging</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">logging</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Client</span> <span class="n">Request</span> <span class="n">Logging</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">client</span><span class="o">-</span><span class="n">request</span><span class="o">-</span><span class="n">logging</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Monitoring</span> <span class="n">Requests</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">monitoring</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="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="p">[</span><span class="n">Sling</span> <span class="n">Testing</span> <span class="n">Tools</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">sling</span><span class="o">-</span><span class="n">testing</span><span class="o">-</span><span class="n">tools</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+</pre></div>
+
+
+<h2 id="maven-2-stuff">Maven 2 stuff</h2>
+<p>Sling is using Apache Maven as it build system. Over time we have created a number of Maven 2 Plugins and gathered a whole range of knowledge about using Maven.</p>
+<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Maven</span> <span class="n">Tips</span> <span class="o">&</span> <span class="n">Tricks</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">maventipsandtricks</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Maven</span> <span class="n">Sling</span> <span class="n">Plugin</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</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="p">[</span><span class="n">Maven</span> <span class="n">JspC</span> <span class="n">Plugin</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">jspc</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Maven</span> <span class="n">Launchpad</span> <span class="n">Plugin</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">maven</span><span class="o">-</span><span class="n">launchpad</span><span class="o">-</span><span class="n">plugin</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Maven</span> <span class="n">Archetypes</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">maven</span><span class="o">-</span><span class="n">archetypes</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+</pre></div>
+
+
+<h3 id="sling-development">Sling Development</h3>
+<p>Last but not least, here is some more information on how we ourselves are working on Sling</p>
+<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Dependency</span> <span class="n">Management</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">dependency</span><span class="o">-</span><span class="n">management</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Version</span> <span class="n">Policy</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">version</span><span class="o">-</span><span class="n">policy</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Issue</span> <span class="n">Tracker</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">issue</span><span class="o">-</span><span class="n">tracker</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+<span class="o">*</span> <span class="p">[</span><span class="n">Release</span> <span class="n">Management</span><span class="p">](</span><span class="sr">/documentation/</span><span class="n">development</span><span class="o">/</span><span class="n">release</span><span class="o">-</span><span class="n">management</span><span class="o">.</span><span class="n">html</span><span class="p">)</span>
+</pre></div>
+ <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/documentation/development/client-request-logging.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/development/client-request-logging.html (added)
+++ websites/staging/sling/trunk/content/documentation/development/client-request-logging.html Tue May 22 09:41:22 2012
@@ -0,0 +1,385 @@
+<!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 - Client Request Logging</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/development.html">Development</a>
+ </div>
+ <h1>Client Request Logging</h1>
+ <p>Sling provides extensive support to log various information at the before and after processing client requests. Out of the box, there are two loggers configured to write traditional <code>access.log</code> and <code>request.log</code> files. In addition more logging can be configured by providing OSGi Configuration Admin configuration.</p>
+<h2 id="traditional-accesslog-and-requestlog-files">Traditional access.log and request.log Files</h2>
+<p>In the Web Console configure the <em>Apache Sling Request Logger</em> (PID=<code>org.apache.sling.engine.impl.log.RequestLogger</code>) configuration.</p>
+<p>In the Sling Web Console locate the Configuration page (<code>/system/console/configMgr</code>) and click on the <code>+</code> (plus) symbol on the <em>Apache Sling Customizable Request Data Logger</em> line. This opens a dialog to enter the configuration whose properties can be configured as follows:</p>
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Name</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Request Log Name</td>
+<td><code>request.log.output</code></td>
+<td>Name of the destination for the request log. The request log logs the entry and exit of each request into and out of the system together with the entry time, exit time, time to process the request, a request counter as well as the final status code and response content type. In terms of Request Logger Service formats, request entry is logged with the format <code>%t \[%R]() \-> %m %U%q %H</code> and request exit is logged with the format <code>%\{end}t \[%R] <\- %s %\{Content-Type}o %Dms</code> (See [#Log Format Specification] below for the specification of the format).</td>
+<td></td>
+</tr>
+<tr>
+<td>Request Log Type</td>
+<td><code>request.log.outputtype</code></td>
+<td>Type of Logger named with the Logger Name parameter. See <a href="">#Log Output</a> below</td>
+<td></td>
+</tr>
+<tr>
+<td>Enable Request Log</td>
+<td><code>request.log.enabled</code></td>
+<td>Whether to enable Request logging or not.</td>
+<td></td>
+</tr>
+<tr>
+<td>Access Log Name</td>
+<td><code>access.log.output</code></td>
+<td>Name of the destination for the access log. The access log writes an entry for each request as the request terminates using the NCSA extended/combined log format. In terms of Request Logger Service formats the access log is written with the format <code>%h %l %u %t "%r" %>s %b "%\{Referer}i" "%\{User-Agent}i"</code> (See <a href="">#Log Format Specification</a> below for the specification of the format).</td>
+<td></td>
+</tr>
+<tr>
+<td>Access Log Type</td>
+<td><code>access.log.outputtype</code></td>
+<td>Type of Logger named with the Logger Name parameter. See <a href="">#Log Output</a> below</td>
+<td></td>
+</tr>
+<tr>
+<td>Enable Access Log</td>
+<td><code>access.log.enabled</code></td>
+<td>Whether to enable Access logging or not.</td>
+<td></td>
+</tr>
+</tbody>
+</table>
+<h4 id="log-output">Log Output</h4>
+<p>Output of client request logging is defined by the Logger Type and and Logger Name where the use of the Logger Name property value depends on the Logger Type:</p>
+<table>
+<thead>
+<tr>
+<th>Type Code</th>
+<th>Type Name</th>
+<th>Description and Logger Name interpretation</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>0</td>
+<td>Logger Name</td>
+<td>Writes the logging information to a named SLF4J Logger. The name of the Logger is defined in the Logger Name property. The actual destination of the log messages is defined the SLF4J configuration for the named logger</td>
+</tr>
+<tr>
+<td>1</td>
+<td>File Name</td>
+<td>Writes the logging information to a file, on message per line. The file name is an absolute or relative path name. If the name is relative, it is resolved against the <code>sling.home</code> framework property.</td>
+</tr>
+<tr>
+<td>2</td>
+<td>RequestLog Service</td>
+<td>Sends the logging information to a <code>org.apache.sling.engine.RequestLog</code> service whose <code>requestlog.name</code> service registration property must the same as the value of the Logger Name property. If more than one such service is registered, all services are called. If no such service is registered, the logging information is discarded. Using RequestLog Services is deprecated.</td>
+</tr>
+</tbody>
+</table>
+<p><em>Note:</em> If logging to a file, this file is not rotated and/or limited by size. To get log file rotation use the <em>Logger Name</em> logging type. See <a href="">#Rotating Logger Files</a> below for information on how logging information can be written to rotated and/or size limited files.</p>
+<h3 id="additional-per-request-loggers">Additional per-request Loggers</h3>
+<p>In the Web Console create <em>Apache Sling Customizable Request Data Logger</em> (Factory PID=<code>org.apache.sling.engine.impl.log.RequestLoggerService</code>) configuration.</p>
+<p>In the Sling Web Console locate the Configuration page (<code>/system/console/configMgr</code>) and click on the <code>+</code> (plus) symbol on the <em>Apache Sling Customizable Request Data Logger</em> line. This opens a dialog to enter the configuration whose properties can be configured as follows:</p>
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Name</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Log Format</td>
+<td><code>request.log.service.format</code></td>
+<td>Specify a <a href="">#Log Format Specification</a> as described below</td>
+<td></td>
+</tr>
+<tr>
+<td>Logger Type</td>
+<td><code>request.log.service.outputtype</code></td>
+<td>Logger Name/<code>0</code></td>
+<td>Type of Logger named with the Logger Name parameter. See <a href="">#Log Output</a> above</td>
+</tr>
+<tr>
+<td>Logger Name</td>
+<td><code>request.log.service.output</code></td>
+<td><code>request.log</code></td>
+<td>Name of the Logger to be used. See <a href="">#Log Output</a> above</td>
+</tr>
+<tr>
+<td>Request Entry</td>
+<td><code>request.log.service.onentry</code></td>
+<td>unchecked/<code>false</code></td>
+<td>Whether logger is called at the start of request processing or after processing the request</td>
+</tr>
+</tbody>
+</table>
+<h4 id="log-format-specification">Log Format Specification</h4>
+<p>The log format specification follows the <a href="">definition of the <code>format</code> argument for the <code>LogFormat</code> and <code>CustomLog</code> directives of Apache httpd</a>:</p>
+<p>The characteristics of the request itself are logged by placing "%" directives in the format string, which are replaced in the log file by the values as follows:</p>
+<table>
+<thead>
+<tr>
+<th>Format String</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>%%</code></td>
+<td>The percent sign</td>
+</tr>
+<tr>
+<td><code>%a</code></td>
+<td>Remote IP-address</td>
+</tr>
+<tr>
+<td><code>%A</code></td>
+<td>Local IP-address</td>
+</tr>
+<tr>
+<td><code>%B</code></td>
+<td>Size of response in bytes, excluding HTTP headers.</td>
+</tr>
+<tr>
+<td><code>%b</code></td>
+<td>Size of response in bytes, excluding HTTP headers. In CLF format, i.e. a '-' rather than a 0 when no bytes are sent.</td>
+</tr>
+<tr>
+<td><code>%\{Foobar}C</code></td>
+<td>The contents of cookie Foobar in the request sent to the server.</td>
+</tr>
+<tr>
+<td><code>%D</code></td>
+<td>The time taken to serve the request, in microseconds.</td>
+</tr>
+<tr>
+<td><code>%\{FOOBAR}e</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+<tr>
+<td><code>%f</code></td>
+<td>The absolute path of the resolved resource</td>
+</tr>
+<tr>
+<td><code>%h</code></td>
+<td>Remote host</td>
+</tr>
+<tr>
+<td><code>%H</code></td>
+<td>The request protocol</td>
+</tr>
+<tr>
+<td><code>%\{Foobar}i</code></td>
+<td>The contents of Foobar: header line(s) in the request sent to the server.</td>
+</tr>
+<tr>
+<td><code>%k</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+<tr>
+<td><code>%l</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+<tr>
+<td><code>%m</code></td>
+<td>The request method</td>
+</tr>
+<tr>
+<td><code>%\{Foobar}n</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+<tr>
+<td><code>%\{Foobar}o</code></td>
+<td>The contents of Foobar: header line(s) in the reply.</td>
+</tr>
+<tr>
+<td><code>%p</code></td>
+<td>The canonical port of the server serving the request</td>
+</tr>
+<tr>
+<td><code>%\{format}p</code></td>
+<td>The canonical port of the server serving the request or the server's actual port or the client's actual port. Valid formats are canonical, local, or remote.</td>
+</tr>
+<tr>
+<td><code>%P</code></td>
+<td>The <em>name of the thread</em> -process ID of the child- that serviced the request.</td>
+</tr>
+<tr>
+<td><code>%\{format}P</code></td>
+<td>Same as <code>%P</code>; the <code>format</code> parameter is ignored.</td>
+</tr>
+<tr>
+<td><code>%q</code></td>
+<td>The query string (prepended with a ? if a query string exists, otherwise an empty string)</td>
+</tr>
+<tr>
+<td><code>%r</code></td>
+<td>First line of request</td>
+</tr>
+<tr>
+<td><code>%R</code></td>
+<td>The number of requests processed by Sling since the last start.</td>
+</tr>
+<tr>
+<td><code>%s</code></td>
+<td>Status.</td>
+</tr>
+<tr>
+<td><code>%t</code></td>
+<td>Time the request was received (standard english format)</td>
+</tr>
+<tr>
+<td><code>%\{format}t</code></td>
+<td>Same as <code>%t</code>; the <code>format</code> parameter is ignored unless it is the literal value <em>end</em> indicating to use the time of request terminating (instead of the time of request receipt).</td>
+</tr>
+<tr>
+<td><code>%T</code></td>
+<td>The time taken to serve the request, in seconds.</td>
+</tr>
+<tr>
+<td><code>%u</code></td>
+<td>Remote user (from auth; may be bogus if return status (%s) is 401)</td>
+</tr>
+<tr>
+<td><code>%U</code></td>
+<td>The URL path requested, not including any query string.</td>
+</tr>
+<tr>
+<td><code>%v</code></td>
+<td>The canonical ServerName of the server serving the request.</td>
+</tr>
+<tr>
+<td><code>%V</code></td>
+<td>Same as <code>%v</code>.</td>
+</tr>
+<tr>
+<td><code>%X</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+<tr>
+<td><code>%I</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+<tr>
+<td><code>%O</code></td>
+<td>Not supported in Sling; prints nothing.</td>
+</tr>
+</tbody>
+</table>
+<p><em>Modifiers</em></p>
+<p>Particular items can be restricted to print only for responses with specific HTTP status codes by placing a comma-separated list of status codes immediately following the "%". For example, "%400,501{User-agent}i" logs User-agent on 400 errors and 501 errors only. For other status codes, the literal string "-" will be logged. The status code list may be preceded by a "!" to indicate negation: "%!200,304,302{Referer}i" logs Referer on all requests that do not return one of the three specified codes.</p>
+<p>The Apache httpd modifiers "<" and ">" are not supported by Sling and currently ignored.</p>
+<p><em>Some Notes</em></p>
+<p>For security reasons non-printable and other special characters in %C, %i and %o are escaped using \uhhhh sequences, where hhhh stands for the hexadecimal representation of the character's unicode value. Exceptions from this rule are " and \, which are escaped by prepending a backslash, and all whitespace characters, which are written in their Java-style notation (\n, \t, etc).</p>
+<h4 id="rotating-logger-files">Rotating Logger Files</h4>
+<p>If you want to write the request (and access) logging information into a rotated file, you should configure as follows:</p>
+<ol>
+<li>Configure the Log Type to be a <em>Logger Name</em> and some usefull Logger name. For example <code>clientlog.request</code>.</li>
+<li>Create an <em>Apache Sling Logging Logger Configuration</em> for this Logger name according to <a href="">Logging Configuration</a> with the following setup:
+ <strong> Allow message at INFO (Information) level to be logged which is the level used by the request loggers
+ </strong> Define the appropriate log file name, for example <code>logs/client.request.log</code>
+ <strong> Use only <code>\{5</code>} as the message format because request logger messages are generally already fully formated with required timestamp etc.
+<br />
+</strong> Add any Logger names used for the client request log configuration, <code>clientlog.request</code> in the example above, to the Logger field. By clicking on the <code>+</code> (plus) button you may add more than a single logger name whose messages are written to this file.</li>
+<li>Optionally, you may create an <em>Apache Sling Logging Writer Configuration</em> for the log file defined in the previous step to better control rotation setup. See <a href="">Log Writer Configuration</a> for full details.</li>
+</ol>
+ <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/documentation/development/dependency-management.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/development/dependency-management.html (added)
+++ websites/staging/sling/trunk/content/documentation/development/dependency-management.html Tue May 22 09:41:22 2012
@@ -0,0 +1,188 @@
+<!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 - Dependency Management</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/development.html">Development</a>
+ </div>
+ <h1>Dependency Management</h1>
+ <p>This page is about how we do and don't do dependency management in the Sling project.</p>
+<div class="toc">
+<ul>
+<li><a href="#introduction">Introduction</a></li>
+<li><a href="#dependency-management">Dependency Management</a></li>
+<li><a href="#references">References</a></li>
+</ul>
+</div>
+<h2 id="introduction">Introduction</h2>
+<p>Maven provides projects with a nice feature called dependency management. In Sling we currently use this feature to declare the non-Sling dependencies of modules in the parent POM.</p>
+<p>After working with this some time and trying to upgrade various dependencies we came to the conclusion, that using Maven dependency management is not going to work out in the Sling scenario.</p>
+<p>Why ? Maven's dependency management is aimed at traditional applicaitons, which are glued together statically during the build process. For this environment, dependency management is a great thing, since it guarantees a consistent application setup.</p>
+<p>In a dynamic application setup as provided by an OSGi framework the static dependency management of Maven does not help. Actually it even causes problematic results with respect to backwards compatibility when using the Maven Bundle plugin.</p>
+<p>Why's that ? The Maven Bundle plugin is constructs the bundle manifest and will generally automatically create the Import-Package header. If the providing library (from maven's dependency list) has <code>Export-Package</code> headers with version numbers, the Maven Bundle plugin will insert the respective version numbers for the <code>Import-Package</code> header. This makes perfect sense, because it is expected, that the artifact required at least the given package version.</p>
+<p>When using Maven dependency management, upgrading any dependencies in the parent POM may automatically increse the version numbers in the <code>Import-Package</code> headers and hence may cause any such bundle to fail resolution if deployed - even though the bundle did not change and does not really require a new version of the dependency.</p>
+<p>So, in the case of OSGi deployment, Maven's dependency management actually interferes with the OSGi framework dependency management.</p>
+<p>As a consequence, I suggest we drop dependency management in the parent pom (almost) completely and state the followin.</p>
+<h2 id="dependency-management">Dependency Management</h2>
+<p>The parent pom only does dependency management for build time dependencies and a very limited number of API dependencies used Sling wide. These dependencies are:</p>
+<ul>
+<li>All plugin dependencies. That is <code>PluginManagement</code> is still used. Maven plugins are actualy build time dependencies and therefore have no influence on the actual deployment.</li>
+<li>Dependencies on commonly used testing environment helpers. Test helper classes are also build time dependencies used to run the unit and integration tests. As such, they may well be managed.</li>
+<li>Sling makes a small number of assumptions about the environment, which we codify in the dependency management: The minimum version number of the OSGi specificaiton used, the servlet API version and the JCR API version.</li>
+</ul>
+<p>The <code><DependencyManagement></code> element currently contains the following managed dependencies:</p>
+<table>
+<thead>
+<tr>
+<th>Group ID</th>
+<th>Artifact ID</th>
+<th>Version</th>
+<th>Scope</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>org.apache.felix</td>
+<td>org.osgi.core</td>
+<td>1.2.0</td>
+<td>provided</td>
+</tr>
+<tr>
+<td>org.apache.felix</td>
+<td>org.osgi.compendium</td>
+<td>1.2.0</td>
+<td>provided</td>
+</tr>
+<tr>
+<td>javax.servlet</td>
+<td>servlet-api</td>
+<td>2.4</td>
+<td>provided</td>
+</tr>
+<tr>
+<td>javax.jcr</td>
+<td>jcr</td>
+<td>1.0</td>
+<td>provided</td>
+</tr>
+<tr>
+<td>org.slf4j</td>
+<td>slf4j-api</td>
+<td>1.5.2</td>
+<td>provided</td>
+</tr>
+<tr>
+<td>junit</td>
+<td>junit</td>
+<td>4.3</td>
+<td>test</td>
+</tr>
+<tr>
+<td>org.jmock</td>
+<td>jmock-junit4</td>
+<td>2.2.0</td>
+<td>test</td>
+</tr>
+<tr>
+<td>org.slf4j</td>
+<td>slf4j-simple</td>
+<td>1.5.2</td>
+<td>test</td>
+</tr>
+</tbody>
+</table>
+<p>All dependencies per module are fully described in terms of version, scope, and classifier by the respective project.</p>
+<p>The version of the module dependency should be selected according to the following rule: The lowest version providing the functionality required by the module (or bundle). By required functionality we bascially mean provided API.</p>
+<p>Generally there is a constant flow of releases of dependent libraries. In general this should not cause the dependency version number of a using module to be increased. There is one exception though: If the fixed library version contains a bug fix, which has an influence on the operation of the module, an increase in the version number is indicated and should also be applied.</p>
+<h2 id="references">References</h2>
+<ul>
+<li><a href="">Dependency ManagementLink to this message</a> -- Discussion thread about reducing Maven 2 <code>DependencyManagement</code></li>
+<li><a href="">SLING-811</a> -- The actual issue governing the changes to the project descriptors</li>
+</ul>
+ <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/documentation/development/embedding-sling.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/development/embedding-sling.html (added)
+++ websites/staging/sling/trunk/content/documentation/development/embedding-sling.html Tue May 22 09:41:22 2012
@@ -0,0 +1,240 @@
+<!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 - Embedding 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="/documentation.html">Documentation</a> » <a href="/documentation/development.html">Development</a>
+ </div>
+ <h1>Embedding Sling</h1>
+ <p>The Sling Launchpad Launcher can be used to embed the OSGi Framework startup in your own Java application. This functionality is implemented in the <a href="">Sling Launchpad Base project</a>. This project has the following features:</p>
+<ul>
+<li>Builds three artifacts:
+<strong> A standalone Java Application with the artifact qualifier <em>app</em>; e.g. <code>org.apache.sling.launchpad.base-2.3.1-SNAPSHOT-app.jar</code></strong> A Web Application with the artifact qualifier <em>webapp</em>; e.g <code>org.apache.sling.launchpad.base-2.3.1-SNAPSHOT-wepabb.war</code>
+** The primary artifact without an artifact qualifier; e.g. <code>org.apache.sling.launchpad.base-2.3.1-SNAPSHOT.jar</code></li>
+<li>Embeds the OSGi Framework (Apache Felix) in the primary artifact</li>
+<li>Encapsulates the OSGi Framework in its own <code>URLClassLoader</code></li>
+<li>Supports Framework restart</li>
+<li>Allows propagation of core setup functionality depending on the environment</li>
+</ul>
+<p>This page is about the internal details of the Sling Launchpad Base module. To get an outside overview of the Sling Launchpad you might want to refer to <a href="/documentation/the-sling-engine/the-sling-launchpad.html">The Sling Launchpad</a> page.</p>
+<h1 id="structure">Structure</h1>
+<p>The Launcher is based on three parts:
+1. The external part which is for example the standalone Java application's main class or the servlet deployed into the servlet container
+1. The internal part which is the OSGi framework plus helper classes to control the framework and run initial installations
+1. The bridging part, which contains API common to the external and internal part.</p>
+<p>The external part uses the bridging part to create the class loader into which the internal part is loaded. The bidirectional communication between the external and internal part is implement based on two interfaces:</p>
+<ul>
+<li>The <code>Launcher</code> interface is implemented by a class in the internal part which is loaded through the bridge class loader. This interface allows setting, starting and stopping of the framework.</li>
+<li>The <code>Notifiable</code> interface is implemented by a class in the external part which instance is handed to the <code>Launcher</code> instance. This interface allows the internal part to communicate back to the external part, most notably to indicate that the framework has been stopped from within or that the framework has been updated and must be restarted.</li>
+</ul>
+<h1 id="the-bridging-part">The Bridging Part</h1>
+<p>The bridging part is provided in the <code>org.apache.sling.launchpad.base.shared</code> package:</p>
+<p>| Class | Description |
+| Launcher | The interface implemented by the internal class matching the external class being called to start/stop the framework. |
+| LauncherClassLoader | <code>URLClassLoader</code> implementing the class loader to load the internal part (along with the OSGi framework). This class loader only delegates to the parent class loader any packages not contained in the launchpad library (primary artifact of the Launchpad Base project). |
+| Loader | Helper class to find the launchpad library and to create the <code>LauncherClassLoader</code> with that library. This class is also used to actually load the <code>Launcher</code> implementation to be called from the external launcher class. |
+| Notifiable | The interface implemented in the external part and handed over to the internal part. |
+| SharedConstants | Constants naming various properties and classes. |</p>
+<h1 id="the-internal-part">The Internal Part</h1>
+<p>The main class from the internal class directly used is <a href=""><code>Sling</code></a> which instantiated to start the OSGi Framework. This class is responsible for setting up the environment to finally start the OSGi Framework:</p>
+<ul>
+<li>Read the <code>sling.properties</code> file</li>
+<li>Ensure the presence of the JMX MBeanServer service</li>
+<li>Execute the bootstrap installations, updates and uninstallations</li>
+</ul>
+<p>The <a href=""><code>SlingFelix</code></a> class extends the Apache Felix <code>Felix</code> class which is the actual OSGi framework implementation. We extend the class to be able to notify the <code>Notifiable</code> implementation and update the OSGi framework from within the OSGi framework by updating the system bundle.</p>
+<h2 id="the-external-part">The External Part</h2>
+<p>The external part is comprised of a main class started from the environment -- main class of the Java applicaction or the servlet deployed in the servlet container -- and a corresponding delegate class located inside of the launchpad base library. This delegate class is instantiated by the <code>Loader</code> loading from the <code>LauncherClassLoader</code>.</p>
+<h3 id="standalone-java-application">Standalone Java Application</h3>
+<p>The standalone Java Application makes use of three classes:</p>
+<p>| Class | Description |
+| Main | This is the main class whose <code>main</code> method is called by the Java VM. This class is itself the <code>Notifiable</code> and finds the <code>sling.home</code> location from the environment (command line parameter, system property, or environment variable). |
+| MainDelegate | This class is loaded by the <code>Loader</code> from the <code>LauncherClassLoader</code> to actually complete the initial setup before creating the <code>Sling</code> class to start the framework. |
+| ControlListener | This class is used by the <code>Main</code> class to open a server socket to be able to start and stop Sling as a server. This class allows for starting (opening the server socket), status check (connecting to the socket asking for status), and shutdown (connecting to the socket asking for shutdown). |</p>
+<p>At the moment these classes are not directly suitable to be embedded in an existing application (or custom application launcher framework) unless that embedding prepares command line arguments in a <code>String[]()</code> and calls the <code>Main.main</code> method. To allow for custom embeddings or extensions, the work distriubtions between the three classes should be refactored.</p>
+<h3 id="embedding-the-standalone-java-application">Embedding the Standalone Java Application</h3>
+<p>{info}
+This work is being done as part of <a href="">SLING-2225</a> and will be officially available with the Sling Launchpad Base release 2.4.0. If you want to use the embedding before the release, you have to checkout the source from [SVN|http://svn.apache.org/repos/asf/sling/trunk/launchpad/base] and build yourself.
+{info}</p>
+<p>To embedd the Sling Launcher in an application, the <code>Main</code> class is extended from. To manage the launcher, the following API is available:</p>
+<table>
+<thead>
+<tr>
+<th>Method</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>Main(Map<String, String> properties)</code></td>
+<td>Instantiates the Main class with the given configuration properties. These are properties which are used directly as overwrites to the configurations in the <code>sling.properties</code> file. There is no more conversion applied.</td>
+</tr>
+<tr>
+<td><code>doControlCommand()</code></td>
+<td>Before starting the application for the first time, this method can be called to handle any control command action.</td>
+</tr>
+<tr>
+<td><code>doStart()</code></td>
+<td>Starts the Sling Application using the provided configuration properties as overwrites. Also these properties (or the <code>sling.home</code> system property or the <code>SLING_HOME</code> environment variable are analyzed to get the value for the <code>sling.home</code> setting.</td>
+</tr>
+<tr>
+<td><code>doStop()</code></td>
+<td>Stops the application started by the <code>doStart()</code> method.</td>
+</tr>
+</tbody>
+</table>
+<h4 id="external-control-of-the-sling-application">External Control of the Sling Application</h4>
+<p>By using control actions, the Sling Launcher may open or connect to a control port to communicate. The <code>doControlAction()</code> method together with the <code>sling.control.action</code> and <code>sling.control.socket</code> properties is able to setup this communication.</p>
+<p>The <code>sling.control.socket</code> is either a normal port number, in which case the connection is opened on the <code>localhost</code> interface (usually 127.0.0.1). Otheriwse, it may also be a value of the form <em>host:port</em> where <em>host</em> is the name or IP address of the interface to connect to and port is the port number. For security reasons it is suggested to not use an interface which is available remotely. So the default of <code>localhost</code> is usually the best choice.</p>
+<p>The <code>sling.control.action</code> takes either of three values:</p>
+<p>| <code>start</code> | Starts a server socket as specified by the <code>sling.control.socket</code> property. If the socket cannot be bound to (because the port is in use) an error message is printed. Using the <code>start</code> action only makes sense when starting the application. |
+| <code>stop</code> | The <code>stop</code> action is used to stop a running application. For that a connection is opened to the server running on the socket specified by the <code>sling.control.socket</code> property. On this connection the server is instructed to shut down. After executing the <code>stop</code> action, the Java application should be terminated. |
+| <code>status</code> | The <code>status</code> action is used to check the status of a running application. For that a connection is opened to the server running on the socket specified by the <code>sling.control.socket</code> property. On this connection the server is queried on its status. After executing the <code>stop</code> action, the Java application should be terminated. |</p>
+<h4 id="conversion-of-commandline-arguments-to-properties">Conversion of Commandline Arguments to Properties</h4>
+<p>When calling the Main class through the JVM startup the <code>Main.main(String[]() args)</code> methods is called which reads the command line arguments and converts them into a <code>Map<String, String></code> suitable for the constructore as follows:</p>
+<table>
+<thead>
+<tr>
+<th>Command Line Argument</th>
+<th>Properties Entry</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>start</td>
+<td>sling.control.action = "start"</td>
+</tr>
+<tr>
+<td>status</td>
+<td>sling.control.action = "status"</td>
+</tr>
+<tr>
+<td>stop</td>
+<td>sling.control.action = "stop"</td>
+</tr>
+<tr>
+<td>-c slinghome</td>
+<td>sling.home = slinghome</td>
+</tr>
+<tr>
+<td>-l loglevel</td>
+<td>org.apache.sling.commons.log.level = loglevel</td>
+</tr>
+<tr>
+<td>-f logfile</td>
+<td>org.apache.sling.commons.log.file = logfile</td>
+</tr>
+<tr>
+<td>-a address</td>
+<td>This command line argument is not supported yet and thus ignored</td>
+</tr>
+<tr>
+<td>-p port</td>
+<td>org.osgi.service.http.port = port</td>
+</tr>
+<tr>
+<td>-j <a href=""> host ":" </a> port</td>
+<td>sling.control.socket = [ host ":" ] port</td>
+</tr>
+<tr>
+<td>-h</td>
+<td>This command line option is handled directly and not converted into the map</td>
+</tr>
+</tbody>
+</table>
+<h3 id="web-application">Web Application</h3>
+<p>The web application makes use of 5 classes:</p>
+<p>| Class | Description |
+| SlingServlet | This is the servlet registered in the <code>web.xml</code> descriptor and loaded by the servlet container into which Sling is deplyoed. This class locates the <code>sling.home</code> folder and loads the <code>SlingServletDelagate</code> to actually launch the framework. |
+| SlingSessionListener | This -- somewhat inappropriately named -- class is registered as a listener by the Sling <code>web.xml</code> descriptor. It is called by the servlet container and forwards events to the <code>SlingHttpSessionListenerDelegate</code> which in turn forwards the events to the respective Servlet API listener services registered in the OSGi Framework. |
+| SlingBridge | Simple extension of the <code>Sling</code> class which registers the system bundle's <code>BundleContext</code> as a servlet context attribute of the Sling web application. This allows Servlet Container bridging to properly work. |
+| SlingHttpSessionListenerDelegate | This class is loaded by the <code>LauncherClassLoader</code> called from the <code>SlingSessionListener</code>. It is called by the <code>SlingSessionListener</code> to forward servlet container events to registered Servlet API listener services. |
+| SlingServletDelegate | This class is loaded by the <code>Loader</code> from the <code>LauncherClassLoader</code> to actually complete the initial setup before creating the <code>SlingBridge</code> class to start the framework. |</p>
+<p>At the moment these classes, particularly the <code>SlingServlet</code> class, are not particularly well suited to be extended by a servlet slightly modifying the launcher.</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>