svn commit: r813971 [3/11] - /websites/staging/sling/trunk/content/

[bu...@apache.org]

Modified: websites/staging/sling/trunk/content/configuration.html
==============================================================================
--- websites/staging/sling/trunk/content/configuration.html (original)
+++ websites/staging/sling/trunk/content/configuration.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,330 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Configuration</h1> -->
+<!-- -->
+<p><a name="Configuration-ConfigurationSupport"></a></p>
+<h1 id="configuration-support">Configuration Support</h1>
+<p><a name="Configuration-Introduction"></a></p>
+<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
+<em>BundleContext.getProperty(String)</em> method. These properties are provided
+in Sling through the Sling launcher.</li>
+<li>Bundle Header values are available through the <em>Bundle.getHeaders()</em>
+and <em>Bundle.getHeaders(String)</em> methods. These header values are set by
+the bundle developer in the <em>META-INF/MANIFEST.MF</em> 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 <em>Service-Component</em> manifest
+header access configuration properties through the
+<em>ComponentContext.getProperties()</em> 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 <em>ManagedService</em> and
+<em>ManagedServiceFactory</em> 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
+<em>BundleContext</em> through the <em>ComponentContext</em> given to the
+<em>activate(ComponentContext)</em> method of the component.</p>
+<p><a name="Configuration-InitialConfiguration"></a></p>
+<h2 id="initial-configuration">Initial Configuration</h2>
+<p>The lifecycle of the OSGi framework implemented by an instance of the
+<em>org.apache.felix.framework.Felix</em> class is managed by the Sling launcher
+class <em>org.apache.sling.launcher.Sling</em>. This class is used by the
+standalone main class (<em>org.apache.sling.launcher.main.Main</em>) and the
+Sling Servlet (<em>org.apache.sling.launcher.servlet.SlingServlet</em>) 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
+<em>java.util.Map<String, String></em> instance as follows (later steps may
+overwrite properties defined in earlier steps) :</p>
+<ol>
+<li>Load core properties from the embedded <em>sling.properties</em> 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 <em>sling.home</em> property is set defining a sensible
+default value if missing</li>
+<li>Load the contents of the <em>${sling.home}/sling.properties</em> 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
+<em>sling.ignoreSystemProperties</em> property is set to <em>true</em>.</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 <em>${propName</em>}</li>
+<li>For each property value starting with <em>ontext:/</em> do the following,
+assuming the value to be an URL with scheme <em>context:</em>:</li>
+<li>
+<ul>
+<li>Copy the application resource to <em>${sling.home</em>} 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 <em>${sling.home}/relpath</em>.</li>
+</ul>
+</li>
+<li>Store the properties as <em>${sling.home}/sling.properties</em> 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 <em>sling.home</em> 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 <em>user.dir</em> system property.</p>
+<p><a name="Configuration-StandaloneApplication"></a></p>
+<h3 id="standalone-application">Standalone Application</h3>
+<p>When launching Sling as a standalone application the <em>sling-app.jar</em> file
+is used. This is an executable JAR File. The <em>sling.properties</em> file as
+well as the <em>sling_install.properties</em> 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 <em>-D</em> command line switch of the Java binary.</p>
+<p>In addition the following command line arguments are accepted:</p>
+<table>
+<tr><th> Argument </th><th> Sling property </th><th> Description </th></tr>
+<tr><td> *-l loglevel* </td><td> *org.apache.sling.osgi.log.level* </td><td> The initial
+loglevel (0..4, FATAL, ERROR, WARN, INFO, DEBUG) </td></tr>
+<tr><td> *-f logfile* </td><td> *org.apache.sling.osgi.log.file* </td><td> The log file, "-"
+for stdout </td></tr>
+<tr><td> *-c slinghome* </td><td> *sling.home* </td><td> the sling context directory </td></tr>
+<tr><td> *-a address* </td><td> -- </td><td> the interfact to bind to (use 0.0.0.0 for any) (not
+supported yet) </td></tr>
+<tr><td> *-p port* </td><td> *org.osgi.service.http.port* </td><td> the port to listen to
+(default 8080) </td></tr>
+<tr><td> *-h* </td><td> -- </td><td> Prints a simple usage message and exits. </td></tr>
+</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>
+<p><a name="Configuration-WebApplication"></a></p>
+<h3 id="web-application">Web Application</h3>
+<p>When launching Sling as a web application using the <em>sling-servlet.war</em>
+or any derived Web Application archive file, the <em>sling.properties</em> file
+is located in the <em>WEB-INF</em> folder along with the
+<em>sling_install.properties</em> and JRE specific properties files.</p>
+<p>The Sling Servlet uses the Servlet Context and Servlet <em>init-param</em>
+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
+<em>javax.servlet.UnavailableException</em>.</p>
+<p><a name="Configuration-PropertyFileInclusions"></a></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 <em>sling.include</em>
+property and any other property whose prefix is <em>sling.include.</em>. 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 <em>sling.include.first</em> property will be loaded before
+the files listed in the <em>sling.include.second</em> but after the files listed
+in the <em>sling.include.a</em> 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
+<em>sling.properties</em> 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
+<em>sling.home</em> 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 <em>sling.properties</em> 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>
+<p><a name="Configuration-OSGiBootDelegationSupport"></a></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><strong>org.osgi.framework.system.packages</strong> - 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 <em>Export-Package</em> bundle manifest header.</li>
+<li><strong>org.osgi.framework.bootdelegation</strong> -  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 <em>Import-Package</em> 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 <em>org.osgi.framework.bootdelegation</em> property. Sling
+provides a mechanism to extend the default setting of the
+<em>org.osgi.framework.bootdelegation</em> property by adding properties
+prefixed with <em>sling.bootdelegation.</em>. The value of each of these
+prefixed properties is conditionally appended to the
+<em>org.osgi.framework.bootdelegation</em> 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>
+<table>
+<tr><td> *sling.bootdelegation.simple = com.some.package* </td><td> This setting
+unconditionally adds the *com.some.package* package to the
+*org.osgi.framework.bootdelegation* property </th></tr>
+<tr><td> *sling.bootdelegation.class.com.some.other.Main = com.some.other* </td><td>
+This setting checks whether the *com.some.other.Main* class is known. If
+so, the *com.some.other* package is added to the
+*org.osgi.framework.bootdelegation* property. Otherwise the
+*com.some.other* package is not added - and therefore must be exported by
+a bundle if required for use inside the framework. </td></tr>
+</table>
+
+<p><em>Note</em> Even though packages listed in the
+<em>org.osgi.framework.bootdelegation</em> property will always be loaded from
+the environment, any bundles using these packages must still import them
+(through <em>Import-Package</em> or <em>DynamicImport-Package</em>) and the bundles
+must resolve for being usable.</p>
+<p><a name="Configuration-OSGiSystemPackagesSupport"></a></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
+<em>org.osgi.framework.system.packages</em> 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
+<em>org.osgi.framework.system.packages</em> property by adding properties
+prefixed with <em>sling.system.packages.</em>. The value of each of these
+prefixed properties is conditionally appended to the
+<em>org.osgi.framework.system.packages</em> 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>
+<table>
+<tr><td> *sling.system.packages.simple = com.some.package* </td><td> This setting
+unconditionally adds the *com.some.package* package to the
+*org.osgi.framework.system.packages* property </th></tr>
+<tr><td> *sling.system.packages.class.com.some.other.Main = com.some.other* </td><td>
+This setting checks whether the *com.some.other.Main* class is known. If
+so, the *com.some.other* package is added to the
+*org.osgi.framework.system.packages* property. Otherwise the
+*com.some.other* package is not added - and therefore must be exported by
+a bundle if required for use inside the framework. </td></tr>
+</table>
+
+<p><em>Note</em> Packages listed in the <em>org.osgi.framework.system.packages</em>
+required by any bundles must be imported by those bundles by listing them
+in the <em>Import-Package</em> or <em>DynamicImport-Package</em> manifest header.</p>
+<p><a name="Configuration-Recommendationsforpropertynames"></a></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 <em>org.osgi.</em> are reserved for OSGi defined
+Framework properties</li>
+<li>Names starting with <em>org.apache.felix.</em> are reserved for the Felix
+Framework</li>
+<li>Names starting with <em>sling.</em> and <em>org.apache.sling.</em> 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>
+<p><a name="Configuration-WellKnownProperties"></a></p>
+<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>
+<tr><th> Property </th><th> Description </th></tr>
+<tr><td> *sling.home* </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 (*$\{sling.home}/felix* by
+default). If this property is not set it defaults to
+*$\{user.dir}/sling*. </td></tr>
+<tr><td> *sling.home.url* </td><td> Contains the Sling directory set in the
+*sling.home* 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> *sling.ignoreSystemProperties* </td><td> Whether to overwrite any configuration
+properties with Java system properties or not. By default this property is
+set to *true* 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> *obr.repository.url* </td><td> A comma-separated list of OSGi Bundle Repository
+URLs. See _Important Properties_ on the page [Initial Provisioning and Startup](launch-sling.html)
+. </td></tr>
+<tr><td> *sling.install.bundles* </td><td> A comma-separated list of start level
+numbers. See _Important Properties_ on the page [Initial Provisioning and Startup](launch-sling.html)
+. </td></tr>
+<tr><td> *sling.install.<n>* </td><td> A comma-separated list of bundle specifications.
+See _Important Properties_ on the page [Initial Provisioning and Startup](launch-sling.html)
+. </td></tr>
+<tr><td> *org.apache.sling.osgi.log.** </td><td> Properties providing initial
+configuration to the Sling Log Service. See 'Important Properties' on the
+page [Initial Provisioning and Startup](launch-sling.html)
+. </td></tr>
+</table>
+
+<p><a name="Configuration-ConfigurationAdminService"></a></p>
+<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 <em>ManagedService</em> or <em>ManagedServiceFactory</em> 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="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.

Modified: websites/staging/sling/trunk/content/contributing.html
==============================================================================
--- websites/staging/sling/trunk/content/contributing.html (original)
+++ websites/staging/sling/trunk/content/contributing.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,39 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Contributing</h1> -->
+<!-- -->
+<p><a name="Contributing-Contributing"></a></p>
+<h1 id="contributing">Contributing</h1>
+<p>See <a href="slingxsite:project-information.html">SLINGxSITE:Project Information</a>
+ for details about the tools mentioned below.</p>
+<p>Apache Sling is a volunteer effort, so there is always plenty of work that
+needs to be accomplished. If you want to help support Sling, this page is
+intended as a starting point for specific contribution ideas. To further
+understand how the Sling community operates, refer to the Community Roles
+and Processes document and/or join the mailing lists.</p>
+<p>The Sling project organizes its "to do" list using the JIRA issue tracking
+system. Specific items from Sling's JIRA issue tracking system are
+highlighted on this page, but are not limited to it. The purpose of the
+list here is to highlight issues that are either more important or serve as
+good entry points for new contributors.</p>
+<p>It is important to point out that you do not need to be a programmer to
+contribute to Sling. As such, we will break out the list of issues below
+for non-programmers and programmers.</p>
+<p><a name="Contributing-Non-Programmers"></a></p>
+<h2 id="non-programmers">Non-Programmers</h2>
+<div class="codehilite"><pre><span class="o">*</span> <span class="n">Improve</span> <span class="n">web</span> <span class="n">site</span> <span class="ow">or</span> <span class="n">documentation</span> <span class="p">(</span><span class="n">e</span><span class="o">.</span><span class="n">g</span><span class="o">.</span><span class="p">,</span> <span class="n">create</span><span class="o">/</span><span class="n">propose</span> <span class="n">FAQ</span> <span class="n">entries</span><span class="p">)</span><span class="o">.</span>
+</pre></div>
 
+
+<p>There is no specific JIRA issue for this task, but any contributions could
+be posted as new JIRA issues for the Documentation component.</p>
+<p><a name="Contributing-Programmers"></a></p>
+<h2 id="programmers">Programmers</h2>
+<div class="codehilite"><pre><span class="o">*</span> <span class="n">Implement</span> <span class="n">support</span> <span class="k">for</span> <span class="n">various</span> <span class="n">rendering</span> <span class="n">technologies</span> <span class="n">in</span> <span class="n">Sling</span><span class="o">.</span>
+</pre></div>
+
+
+<p>Examples coming to mind are JSF and Wicket.</p>
     
         <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.

Modified: websites/staging/sling/trunk/content/default-mapping-and-rendering.html
==============================================================================
--- websites/staging/sling/trunk/content/default-mapping-and-rendering.html (original)
+++ websites/staging/sling/trunk/content/default-mapping-and-rendering.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,10 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Default Mapping and Rendering</h1> -->
-
+<!-- -->
+<p>This page contained obsolete content, moved it to
+http://cwiki.apache.org/confluence/display/SLING/Default+Mapping+and+Rendering+%28OBSOLETE%29
+in case it is useful to someone.</p>
     
         <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.

Modified: websites/staging/sling/trunk/content/dependency-management.html
==============================================================================
--- websites/staging/sling/trunk/content/dependency-management.html (original)
+++ websites/staging/sling/trunk/content/dependency-management.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,94 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Dependency Management</h1> -->
+<!-- -->
+<p><a name="DependencyManagement-DependencyManagement"></a></p>
+<h1 id="dependency-management">Dependency Management</h1>
+<p>{excerpt}This page is about how we do and don't do dependency management in
+the Sling project.{excerpt}</p>
+<p>{toc:minLevel=2}</p>
+<p><a name="DependencyManagement-Introduction"></a></p>
+<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 <em>Export-Package</em>
+headers with version numbers, the Maven Bundle plugin will insert the
+respective version numbers for the <em>Import-Package</em> 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
+<em>Import-Package</em> 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>
+<p><a name="DependencyManagement-DependencyManagement"></a></p>
+<h2 id="dependency-management_1">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 <em>PluginManagement</em> 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 <em><DependencyManagement></em> element currently contains the following
+managed dependencies:</p>
+<table>
+<tr><th> Group ID </th><th> Artifact ID </th><th> Version </th><th> Scope </th></tr>
+<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>
+</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>
+<p><a name="DependencyManagement-References"></a></p>
+<h2 id="references">References</h2>
+<ul>
+<li><a href="http://markmail.org/message/5qpmsukdk4mdacdy">Dependency ManagementLink to this message</a>
+ -- Discussion thread about reducing Maven 2 <em>DependencyManagement</em></li>
+<li><a href="https://issues.apache.org/jira/browse/SLING-811">SLING-811</a>
+ -- The actual issue governing the changes to the project descriptors</li>
+</ul>
     
         <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.

Modified: websites/staging/sling/trunk/content/development.html
==============================================================================
--- websites/staging/sling/trunk/content/development.html (original)
+++ websites/staging/sling/trunk/content/development.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,47 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Development</h1> -->
+<!-- -->
+<p><a name="Development-Development"></a></p>
+<h1 id="development">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>
+<p><a name="Development-UsingSlingasyourDevelopmentFramework"></a></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="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="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="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="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="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="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="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>
 
+
+<p><a name="Development-Maven2stuff"></a></p>
+<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">&amp;</span> <span class="n">Tricks</span><span class="p">](</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="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="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="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="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>
+
+
+<p><a name="Development-SlingDevelopment"></a></p>
+<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="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="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="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="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="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.

Modified: websites/staging/sling/trunk/content/discover-sling-in-15-minutes.html
==============================================================================
--- websites/staging/sling/trunk/content/discover-sling-in-15-minutes.html (original)
+++ websites/staging/sling/trunk/content/discover-sling-in-15-minutes.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,244 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Discover Sling in 15 minutes</h1> -->
+<!-- -->
+<p><a name="DiscoverSlingin15minutes-DiscoverSlingin15minutes-theSlingLaunchpad"></a></p>
+<h1 id="discover-sling-in-15-minutes-the-sling-launchpad">Discover Sling in 15 minutes - the Sling Launchpad</h1>
+<p>The Sling Launchpad is a ready-to-run Sling configuration, providing an
+embedded JCR content repository and web server, a selection of Sling
+components, documentation and examples. The Launchpad makes it easy to get
+started with Sling and to develop script-based applications.</p>
+<p>This page will help you get started with the Launchpad. Fifteen minutes
+should be enough to get an overview of what Sling does.</p>
+<p>While simple to run and understand, the Launchpad is a full-featured
+instance of Sling, an example configuration that we have created with the
+most common modules and configurations. The full functionality of Sling is
+available by loading additional Sling (or custom) OSGi bundles as needed,
+using the Launchpad's web-based OSGi management console.</p>
+<p><a name="DiscoverSlingin15minutes-SeeAlso"></a></p>
+<h2 id="see-also">See Also</h2>
+<p>Example applications and mini-applications for Sling can be found under
+http://svn.apache.org/repos/asf/sling/trunk/samples/ (each application has
+a <em>README.txt</em> file, see these for more details).</p>
+<p>Once you grok the basic examples of this page, we recommend studying the
+<em>espblog</em> and <em>webloader</em> samples for more complete examples. The
+<em>javashell</em> sample is useful to play with JCR java code (or any java code,
+for that matter) interactively.</p>
+<p><a name="DiscoverSlingin15minutes-Prerequisites"></a></p>
+<h2 id="prerequisites">Prerequisites</h2>
+<p>We'll start with the self-runnable jar from the Sling distribution, you
+only need a Java 5 JDK. Download the latest release from the Sling <a href="downloads.html">Downloads</a>
+ page or by clicking this link: [org.apache.sling.launchpad-6-standalone.jar|http://www.apache.org/dyn/closer.cgi/sling/org.apache.sling.launchpad-6-standalone.jar]
+. Alternatively you can deploy the [Sling Web application|http://www.apache.org/dyn/closer.cgi/sling/org.apache.sling.launchpad-6.war]
+ into any decent Servlet Container such as Jetty or Tomcat or you can [build the current source yourself|Getting and Building Sling]
+.</p>
+<p>To show the simplicity of the REST-style approach taken by Sling the
+examples below will be using <a href="http://curl.haxx.se/">cURL</a>
+. Any HTTP client would do, but cURL is the easiest to document in a
+reproducible way.</p>
+<p>A WebDAV client makes editing server-side scripts much more convenient, but
+to make our examples easy to reproduce, we're using cURL below to create
+and update files in the JCR repository, via the Sling WebDAV server.</p>
+<p><a name="DiscoverSlingin15minutes-StarttheLaunchpad"></a></p>
+<h2 id="start-the-launchpad">Start the Launchpad</h2>
+<p>After downloading the Sling Launchpad self-runnable jar just start it as
+follows:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">java</span> <span class="o">-</span><span class="n">jar</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">launchpad</span><span class="o">-</span><span class="mi">6</span><span class="o">-</span><span class="n">standalone</span><span class="o">.</span><span class="n">jar</span>
+</pre></div>
 
+
+<p>This starts the Sling embedded Web Server on port 8080 and writes
+application files into the <em>sling</em> folder found in the current working
+directory.</p>
+<p>Once started, look at <a href="http://localhost:8080/system/console/bundles">http://localhost:8080/system/console/bundles</a>
+ with your browser. Use <em>admin</em> with password <em>admin</em> if Sling asks you for
+a login. Sling then displays the <em>Felix Web Management Console</em> page.</p>
+<p>On the bundles page, all bundles should be marked <em>Active</em>. They're all <a href="http://www.osgi.org/">OSGi</a>
+ bundles powered by [Apache Felix|http://felix.apache.org]
+, but that doesn't really matter to us right now.</p>
+<p>{tip:title=Log files}
+If things go wrong, have a look at the <em>sling/logs/error.log</em> log file -
+that's where Sling writes any error messages.
+{tip}</p>
+<p><a name="DiscoverSlingin15minutes-Createsomecontent"></a></p>
+<h2 id="create-some-content">Create some content</h2>
+<p>Until we have ready-to-test forms, you can create content with cURL, or you
+can create an HTML form that posts to the specified URL.</p>
+<p>To create a content node (nodes are a <a href="http://jackrabbit.apache.org/">JCR</a>
+ concept, a unit of storage) with cURL, use:</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;sling:resourceType=foo/bar&quot;</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;title=some title&quot;</span>
+</pre></div>
+
+
+<p>http://localhost:8080/content/mynode</p>
+<p>The resulting node can be seen at <a href="http://localhost:8080/content/mynode.html">http://localhost:8080/content/mynode.html</a>
+, or as json format under [http://localhost:8080/content/mynode.json|http://localhost:8080/content/mynode.json]
+. Lets try with cURL:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/content/m</span><span class="n">ynode</span><span class="o">.</span><span class="n">json</span>
+<span class="p">{</span><span class="s">&quot;title&quot;</span><span class="p">:</span><span class="err">&quot;</span><span class="n">some</span>
+</pre></div>
+
+
+<p>title","sling:resourceType":"foo/bar","jcr:primaryType":"nt:unstructured"}</p>
+<p>This returns the properties of the <em>/content/mynode</em> in JSON format as we
+have created it above. The additional property <em>jcr:primaryType</em> is a
+special JCR property indicating the JCR primary node type.</p>
+<p>{tip:title=Monitoring requests}
+Sling provides a simple tool (an OSGi console plugin) to monitor HTTP
+requests, which helps understand how things work internally. See the <a href="monitoring-requests.html">Monitoring Requests</a>
+ page for details.
+{tip}</p>
+<p><a name="DiscoverSlingin15minutes-Renderyourcontentusingserver-sidejavascript(ESP)"></a></p>
+<h2 id="render-your-content-using-server-side-javascript-esp">Render your content using server-side javascript (ESP)</h2>
+<p>Sling uses scripts or servlets to render and process content.</p>
+<p>Several scripting languages are available as additional Sling modules
+(packaged as OSGi <em>bundles</em> that can be installed via the Sling management
+console), but the launchpad currently includes the ESP (server-side
+ECMAscript), JSP (Java Server Pages), and Groovy language modules by
+default.</p>
+<p>To select a script, Sling uses the node's <em>sling:resourceType</em> property, if
+it is set.</p>
+<p>That is the case in our example, so the following script will be used by
+Sling to render the node in HTML, if the script is found at
+<em>/apps/foo/bar/html.esp</em> in the repository.</p>
+<p><DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>html.esp</B></DIV><DIV class="codeContent panelContent">
+    <html>
+      <body>
+        <h1>&lt;%= currentNode.title %&gt;</h1>
+      </body>
+    </html></p>
+<p>To select the script, Sling:
+<em> looks under <em>/apps</em></em> and appends the <em>sling:resourceType</em> value of our node ( which is
+<em>foo/bar</em> ) 
+* and appends <em>html.esp</em>, as the extension of our URL is <em>html</em> and the
+language of our script is <em>esp</em>.</p>
+<p>Store this script under <em>/apps/foo/bar/html.esp</em>, either using a WebDAV
+client (connected to <a href="http://admin:admin@localhost:8080/">http://admin:admin@localhost:8080/</a>
+), or using cURL as shown here, after creating the <em>html.esp</em> script in the
+current directory on your system:</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">X</span> <span class="n">MKCOL</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/apps/</span><span class="n">foo</span>
+<span class="n">curl</span> <span class="o">-</span><span class="n">X</span> <span class="n">MKCOL</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/apps/</span><span class="n">foo</span><span class="o">/</span><span class="n">bar</span>
+</pre></div>
+
+
+<p>create a local file <em>html.esp</em> and copy above content.</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="o">-</span><span class="n">T</span> <span class="n">html</span><span class="o">.</span><span class="n">esp</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/apps/</span><span class="n">foo</span><span class="sr">/bar/</span><span class="n">html</span><span class="o">.</span><span class="n">esp</span>
+</pre></div>
+
+
+<p>The HTML rendering of your node, at <a href="http://localhost:8080/content/mynode.html">http://localhost:8080/content/mynode.html</a>
+, is now created by this ESP script. You should see the node's title alone
+as an <h1> element in that page.</p>
+<p>A script named <em>POST.esp</em> instead of <em>html.esp</em> would be called for a POST
+request, <em>DELETE.esp</em> for DELETE, <em>xml.esp</em> for a GET request with a <em>.xml</em>
+extension, etc. See <a href="http://cwiki.apache.org/SLING/url-to-script-resolution.html">URL to Script Resolution</a>
+ on the Sling wiki for more info.</p>
+<p>Servlets can also be easily "wired" to handle specific resource types,
+extensions, etc., in the simplest case by using SCR annotations in the
+servlet source code. Servlets and scripts are interchangeable when it comes
+to processing Sling requests.</p>
+<p><a name="DiscoverSlingin15minutes-Whatnext?"></a></p>
+<h2 id="what-next">What next?</h2>
+<p>These simple examples show how Sling uses scripts to work with JCR data,
+based on <em>sling:resourceType</em> or node types.</p>
+<p>There's much more to Sling of course - you'll find some additional simple
+examples below, and above in the <em>see also</em> section.</p>
+<p>We are working on debugging features to help trace the way Sling processes
+requests. Have a look at <a href="https://issues.apache.org/jira/browse/SLING-3">SLING-3</a>
+ to see what's possible already.</p>
+<p><a name="DiscoverSlingin15minutes-Additionalexamples"></a></p>
+<h1 id="additional-examples">Additional examples</h1>
+<p><a name="DiscoverSlingin15minutes-LetSlinggeneratethepathofanewlycreatednode."></a></p>
+<h2 id="let-sling-generate-the-path-of-a-newly-created-node">Let Sling generate the path of a newly created node.</h2>
+<p>To create a node with a unique path at a given location, end the URL of the
+POST request with <em>/</em>.</p>
+<p>In this case, the Sling response redirects to the URL of the created node.</p>
+<p>Start by creating a new <em>/blog</em> folder:</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">X</span> <span class="n">POST</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="s">&quot;http://localhost:8080/content/blog&quot;</span>
+</pre></div>
+
+
+<p>And create a node with a Sling-generated name under it:</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">D</span> <span class="o">-</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;title=Adventures with Sling&quot;</span>
+</pre></div>
+
+
+<p>"http://localhost:8080/content/blog/"</p>
+<p>Using cURL's <em>-D</em> option shows the full HTTP response, which includes a
+<em>Location</em> header to indicate where the new node was created:</p>
+<div class="codehilite"><pre><span class="n">Location:</span> <span class="sr">/blog/</span><span class="n">adventures_with_slin</span>
+</pre></div>
+
+
+<p>The actual node name might not be <em>adventures_with_slin</em> - depending on
+existing content in your repository, Sling will find a unique name for this
+new node, based on several well-know property values like title,
+description, etc. which are used for this if provided.</p>
+<p>So, in our case, our new node can be displayed in HTML via the <a href="http://localhost:8080/blog/adventures_with_slin.html">http://localhost:8080/blog/adventures_with_slin.html</a>
+ URL.</p>
+<p>Note that we didn't set a <em>sling:resourceType</em> property on our node, so if
+you want to render that node with a script, you'll have to store the script
+under <em>/apps/nt/unstructured/html.esp</em>.</p>
+<p><a name="DiscoverSlingin15minutes-Addapageheaderwithsling.include"></a></p>
+<h2 id="add-a-page-header-with-slinginclude">Add a page header with sling.include</h2>
+<p>The <em>sling.include</em> function can be called from scripts to include the
+rendered result of another node.</p>
+<p>In this example, we create a node at <em>/content/header</em>, rendered with a
+logo using an <em>html.esp</em> script, then use that header at the top of the
+<em>html.esp</em> script that we created previously for the <em>foo/bar</em> resource
+type.</p>
+<p>Start by checking that <a href="http://localhost:8080/content/mynode.html">http://localhost:8080/content/mynode.html</a>
+ is rendered using the <em>html.esp</em> script created above.</p>
+<p>Create this script and name it <em>header.esp</em>:</p>
+<p><DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>header.esp</B></DIV><DIV class="codeContent panelContent">
+    <div>
+      <p style="color:blue;">
+        <img src="/images/sling.jpg" align="right"/>
+        &lt;%= currentNode.headline %&gt;
+      </p>
+    </div></p>
+<p>Upload it so that it is used to render resources having
+<em>sling:resourceType=foo/header</em>:</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">X</span> <span class="n">MKCOL</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/apps/</span><span class="n">foo</span><span class="sr">/header/</span>
+<span class="n">curl</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="o">-</span><span class="n">T</span> <span class="n">header</span><span class="o">.</span><span class="n">esp</span>
+</pre></div>
+
+
+<p>http://localhost:8080/apps/foo/header/html.esp</p>
+<p>Create the header node:</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="o">-</span><span class="n">F</span><span class="s">&quot;sling:resourceType=foo/header&quot;</span> <span class="o">-</span><span class="n">F</span><span class="err">&quot;</span><span class="n">headline</span><span class="o">=</span><span class="n">Hello</span><span class="p">,</span>
+</pre></div>
+
+
+<p>Sling world" http://localhost:8080/content/header</p>
+<p>Upload the logo that the script uses (using sling.jpg or another logo in
+the current directory):</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">X</span> <span class="n">MKCOL</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/images/</span>
+<span class="n">curl</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="o">-</span><span class="n">T</span> <span class="n">sling</span><span class="o">.</span><span class="n">jpg</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/images/s</span><span class="n">ling</span><span class="o">.</span><span class="n">jpg</span>
+</pre></div>
+
+
+<p>And check that the header is rendered with the logo at <a href="http://localhost:8080/content/header.html">http://localhost:8080/content/header.html</a>
+.</p>
+<p>Now, update the html.esp script that we created for our first example
+above, to include the header:</p>
+<p><DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>html.esp</B></DIV><DIV class="codeContent panelContent">
+    <html>
+      <body>
+        <div id="header">
+          &lt;% sling.include("/content/header"); %&gt;
+        </div>
+        <h1>&lt;%= currentNode.title %&gt;</h1>
+      </body>
+    </html></p>
+<p>And upload it again to replace the previous version:</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="o">-</span><span class="n">T</span> <span class="n">html</span><span class="o">.</span><span class="n">esp</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/apps/</span><span class="n">foo</span><span class="sr">/bar/</span><span class="n">html</span><span class="o">.</span><span class="n">esp</span>
+</pre></div>
+
+
+<p>The <a href="http://localhost:8080/content/mynode.html">http://localhost:8080/content/mynode.html</a>
+, once refreshed, now shows the blue headline and logo, and this layout
+also applies to any node created with <em>sling:resourceType=foo/bar</em>.</p>
     
         <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.

Modified: websites/staging/sling/trunk/content/dispatching-requests.html
==============================================================================
--- websites/staging/sling/trunk/content/dispatching-requests.html (original)
+++ websites/staging/sling/trunk/content/dispatching-requests.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,202 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Dispatching Requests</h1> -->
+<!-- -->
+<p><a name="DispatchingRequests-RequestProcessing"></a></p>
+<h1 id="request-processing">Request Processing</h1>
+<p><a name="DispatchingRequests-Mainprocess"></a></p>
+<h2 id="main-process">Main process</h2>
+<p>The following steps should give you an overview how a request is processed
+in Sling. Details can be found under provided links.</p>
+<p><a name="DispatchingRequests-Step1"></a></p>
+<h3 id="step-1">Step 1</h3>
+<p>The client sends the request</p>
+<p><a name="DispatchingRequests-Step2"></a></p>
+<h3 id="step-2">Step 2</h3>
+<p>This step applies only if a Servlet Container is installed and Sling is
+embedded:
+Servlet Container gets request and forwards to OSGi HttpService</p>
+<p><a name="DispatchingRequests-Step3"></a></p>
+<h3 id="step-3">Step 3</h3>
+<p>OSGi HttpService looks for responsible registered Servlet or resource (see
+102.4 of the OSGi compendium)</p>
+<p><a name="DispatchingRequests-Step4"></a></p>
+<h3 id="step-4">Step 4</h3>
+<p>OSGi HttpService calls <em>handleSecurity</em> of the HttpContext associated
+with the servlet/resource. In case of Sling this calls into
+SlingMainServlet.handleSecurity and then into
+SlingAuthenticator.authenticate</p>
+<p><a name="DispatchingRequests-Step4a"></a></p>
+<h3 id="step-4a">Step 4a</h3>
+<p>SlingAuthenticator selects an authentication handler for the request and
+forwards the authenticate call. On success a <em>javax.jcr.Session</em> is
+created, the request attributes required by the HTTP Service spec are set
+(like <em>org.osgi.service.http.authentication.remote.user</em> and
+<em>org.osgi.service.http.authentication.type</em>and also the
+<em>javax.jcr.Session</em> which is used later is set in the request attributes.
+On success, continue with step 5.</p>
+<p><a name="DispatchingRequests-Step4b"></a></p>
+<h3 id="step-4b">Step 4b</h3>
+<p>If authentication fails either an anonymous session is acquired (if
+anonymous is allowed per configuration) or the login method is called.
+If anonymous is allowed, continue with step 5.</p>
+<p><a name="DispatchingRequests-Step4c"></a></p>
+<h3 id="step-4c">Step 4c</h3>
+<p>The login method selects an AuthenticationHandler and forwards the login
+call to the AuthenticationHandler.requestAuthentication method to cause the
+client to authenticate. Request processing stops here
+(<em>SlingMainServlet.handleSecurity</em> returns false).</p>
+<p><a name="DispatchingRequests-Step5"></a></p>
+<h3 id="step-5">Step 5</h3>
+<p>After getting a response the HttpService either terminates the request (if
+authentication failed and <em>SlingMainServlet.handleSecurity</em> returned
+false) or continues by either spooling the resource or in the case of Sling
+calling the <em>SlingMainServlet.service</em> method.</p>
+<p><a name="DispatchingRequests-Step6"></a></p>
+<h3 id="step-6">Step 6</h3>
+<p>The <em>SlingMainServlet.service</em> method is the entry point into the Sling
+proper. This method sets up the request:
+<em> Wraps the </em>HttpServletRequest<em> and the </em>HttpServletResponse<em> into the
+</em>SlingHttpServletRequest<em> and the </em>SlingHttpServletResponse<em>
+</em> Checks if Sling is ready for processing the request (checks at the moment
+for an existing ResourceResolverFactory service, a ServletResolver service
+and a MimeTypeService)
+<em> Create the ResourceResolver based on the Session (by default creates a
+</em>JcrResourceResolver2<em>)
+</em> Locate the <a href="slingxsite:resources.html">Resource</a>
+ on the basis of the request by calling <em>ResourceResovler.resolve</em>
+through <em>RequestData.initResource</em> (see also [URL decomposition]
+)
+<em> Locate the servlet or script (see <a href="servlets.html">Servlets</a>
+) by calling </em>ServletResolver.resolveServlet<em> through
+</em>RequestData.initServlet*</p>
+<p><a name="DispatchingRequests-Step7"></a></p>
+<h3 id="step-7">Step 7</h3>
+<p>After this setup, the request level filters are called (the ones registered
+as <em>javax.servlet.Filter</em> with the property <em>filter.scope=request</em>, see <a href="filters.html">Filters</a>
+ for details).
+If any called filter doesn't call <em>FilterChain.doFilter</em> at the end of
+the <em>Filter.doFilter</em> method request processing stops here.</p>
+<p><a name="DispatchingRequests-Step8"></a></p>
+<h3 id="step-8">Step 8</h3>
+<p>After having called all request level filters, the component level filters
+(registered with the property <em>filter.scope=component</em>, see <a href="filters.html">Filters</a>
+ for details) are called.</p>
+<p><a name="DispatchingRequests-Step9"></a></p>
+<h3 id="step-9">Step 9</h3>
+<p>After having called the component level filters, the request servlet or
+script is finally called to process the request.</p>
+<p><a name="DispatchingRequests-Include/Forward"></a></p>
+<h2 id="includeforward">Include/Forward</h2>
+<p>If a servlet or script is including another resource for processing through
+the <em>RequestDispatcher.include</em> or <em>RequestDispatcher.forward</em> (or any
+JSP or feature of another scripting language which relies on one of this
+two methods) the following processing takes place:</p>
+<p><a name="DispatchingRequests-Step1"></a></p>
+<h3 id="step-1_1">Step 1</h3>
+<p>Code in the processing servlet or script calls
+<em>RequestDispatcher.include</em> or <em>RequestDispatcher.forward</em>.</p>
+<p><a name="DispatchingRequests-Step2"></a></p>
+<h3 id="step-2_1">Step 2</h3>
+<p>The resource is resolved though ResourceResolver.getResource (if the
+RequestDispatcher has not been created with a resource already)</p>
+<p><a name="DispatchingRequests-Step3"></a></p>
+<h3 id="step-3_1">Step 3</h3>
+<p>The servlet or script to handle the resource is resolved calling the
+<em>ServletResolver.resolverServlet</em> method.</p>
+<p><a name="DispatchingRequests-Step4"></a></p>
+<h3 id="step-4_1">Step 4</h3>
+<p>The component level filters (registered with the property
+<em>filter.scope=component</em>) are called again (see <a href="filters.html">Filters</a>
+ for details).</p>
+<p><a name="DispatchingRequests-Step5"></a></p>
+<h3 id="step-5_1">Step 5</h3>
+<p>The servlet or script is called to process the request.</p>
+<p>Note that these steps are processed for every include or forward call.</p>
+<p><a name="DispatchingRequests-IncludedRequestAttributes"></a></p>
+<h2 id="included-request-attributes">Included Request Attributes</h2>
+<p>When servlet or script is called as a result of
+<em>RequestDispatcher.include</em> the following request attributes are set:</p>
+<table>
+<tr><td> Attribute Name
+</tr>
+Attribute Type | Description |
+<tr><td> *org.apache.sling.api.include.servlet*
+</tr>
+*javax.servlet.Servlet* | The name of the request attribute containing
+the *Servlet* which included the servlet currently being active. |
+<tr><td> *org.apache.sling.api.include.resource*
+</tr>
+*org.apache.sling.api.resource.Resource* | The name of the request
+attribute containing the *Resource* underlying the *Servlet* which
+included the servlet currently being active. |
+<tr><td> *org.apache.sling.api.include.request_path_info*
+</tr>
+*org.apache.sling.api.request.RequestPathInfo* | The name of the request
+attribute containing the *RequestPathInfo* underlying the *Servlet*
+which included the servlet currently being active |
+<tr><td> *javax.servlet.include.request_uri*
+</tr>
+*String* | The name of the request attribute containing the
+*HttpServletRequest.getRequestURI()* of the request which included the
+servlet currently being active underlying the *Servlet* which included
+the servlet currently being active.
+*Note:* In Sling, the *HttpServletRequest.getRequestURI()* method will
+always return the same result regardless of whether it is called from the
+client request processing servlet or script or from an included servlet or
+script. This request attribute is set for compatibility with the Servlet
+API specification. |
+<tr><td> *javax.servlet.include.context_path*
+</tr>
+*String* | The name of the request attribute containing the
+*HttpServletRequest.getContextPath()* of the request which included the
+servlet currently being active underlying the *Servlet* which included
+the servlet currently being active.
+*Note:* In Sling, the *HttpServletRequest.getContextPath()* method will
+always return the same result regardless of whether it is called from the
+client request processing servlet or script or from an included servlet or
+script. This request attribute is set for compatibility with the Servlet
+API specification. |
+<tr><td> *javax.servlet.include.servlet_path*
+</tr>
+*String* | The name of the request attribute containing the
+*HttpServletRequest.getServletPath()* of the request which included the
+servlet currently being active underlying the *Servlet* which included
+the servlet currently being active.
+*Note:* In Sling, the *HttpServletRequest.getServletPath()* method will
+always return the same result regardless of whether it is called from the
+client request processing servlet or script or from an included servlet or
+script. This request attribute is set for compatibility with the Servlet
+API specification. |
+<tr><td> *javax.servlet.include.path_info*
+</tr>
+*String* | The name of the request attribute containing the
+*HttpServletRequest.getPathInfo()* of the request which included the
+servlet currently being active underlying the *Servlet* which included
+the servlet currently being active.
+*Note:* In Sling, the *HttpServletRequest.getPathInfo()* method will
+always return the same result regardless of whether it is called from the
+client request processing servlet or script or from an included servlet or
+script. This request attribute is set for compatibility with the Servlet
+API specification.
+<tr><td> *javax.servlet.include.query_string*
+</tr>
+*String* | The name of the request attribute containing the
+*HttpServletRequest.getQueryString()* of the request which included the
+servlet currently being active underlying the *Servlet* which included
+the servlet currently being active.
+*Note:* In Sling, the *HttpServletRequest.getQueryString()* method will
+always return the same result regardless of whether it is called from the
+client request processing servlet or script or from an included servlet or
+script. This request attribute is set for compatibility with the Servlet
+API specification. |
+</table>
 
+<p>Constants are defined in the <em>org.apache.sling.api.SlingConstants</em> class
+for these request attributes.</p>
+<p><em>Note:</em> These request attributes are not set if the servlet or script is
+called to handle the request or as a result of
+<em>RequestDispatcher.forward</em>.</p>
     
         <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.

Modified: websites/staging/sling/trunk/content/documentation.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation.html (original)
+++ websites/staging/sling/trunk/content/documentation.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,142 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Documentation</h1> -->
+<!-- -->
+<p><a name="Documentation-Documentation"></a></p>
+<h1 id="documentation">Documentation</h1>
+<p>The documentation is split into different parts:</p>
+<ul>
+<li><a href="getting-started.html">Getting Started</a>
+, the right place to start!</li>
+<li><a href="the-sling-engine.html">The Sling Engine</a>
+, all about the heart of Sling</li>
+<li><a href="development.html">Development</a>
+, how do I get and develop with Sling</li>
+<li><a href="bundles.html">Bundles</a>
+, which bundle delivers which features to Sling</li>
+<li><a href="tutorials-&amp;-how-tos.html">Tutorials &amp; How-Tos</a></li>
+<li><a href="http://cwiki.apache.org/SLING/">Wiki</a></li>
+<li><a href="configuration.html">Configuration</a></li>
+<li><a href="http://sling.apache.org/apidocs/sling5/index.html">API Doc</a></li>
+</ul>
+<p><a name="Documentation-Howcanyoucontribute"></a></p>
+<h2 id="how-can-you-contribute">How can you contribute</h2>
+<p>We're on the way to improve the documentation, but it's a long way. If you
+would like to contribute to the documentation you are very welcome. Please
+directly post your proposals to the <a href="http://cwiki.apache.org/SLING/">public wiki</a>
+ or post your suggestions to the mailing list.</p>
+<p><a name="Documentation-Howisthedocumentationgenerated"></a></p>
+<h2 id="how-is-the-documentation-generated">How is the documentation generated</h2>
+<p>The basic documentation of Sling is made up of four parts:</p>
+<ol>
+<li>The Sling Site at http://sling.apache.org/ (you are here)</li>
+<li>The Public Wiki at http://cwiki.apache.org/SLING</li>
+<li>The JavaDoc</li>
+<li>The Bundle documentation</li>
+</ol>
+<p>This page is about how this documentation is maintained and who is allowed
+to do what.</p>
+<p><a name="Documentation-TheSlingSite"></a></p>
+<h3 id="the-sling-site">The Sling Site</h3>
+<p><a name="Documentation-MainSite"></a></p>
+<h4 id="main-site">Main Site</h4>
+<p>The main Sling Site is maintained in the Confluence Wiki Space
+<em>SLINGxSITE</em>. The content of this space is automatically synchronized with
+the web server with a simple shell script <a href="^sling.sh.html">^sling.sh</a>
+ which is called regularly as per the following <em>crontab</em> entry:</p>
+<div class="codehilite"><pre><span class="c1"># sync wiki autoexport to Sling site</span>
+<span class="mi">1</span> <span class="o">*</span> <span class="o">*</span> <span class="o">*</span> <span class="o">*</span> <span class="p">(</span><span class="sr">/home/</span><span class="n">fmeschbe</span><span class="o">/</span><span class="n">sling</span><span class="o">.</span><span class="n">sh</span><span class="p">)</span>
+</pre></div>
 
+
+<p>Thus, after editing the site source in the Wiki, the rest happens
+automatically, it just takes some time -- in the order 2 hours or so --
+before the changes are visible at http://sling.apache.org/.</p>
+<p>Everybody is allowed to read the SLINGxSITE wiki and to add comments; but
+only committers of the Apache Sling project are allowed to edit the content
+and to manage the comments.</p>
+<p>The main site is located in the <em>site</em> folder below the Site URL <a href="http://sling.apache.org/">http://sling.apache.org/</a>
+ to which users are redirected automatically.</p>
+<p><a name="Documentation-SecondarySite"></a></p>
+<h4 id="secondary-site">Secondary Site</h4>
+<p>The Sling site contains secondary site parts that are maintained in the
+Apache SVN repository at <a href="http://svn.apache.org/repos/asf/sling/site">http://svn.apache.org/repos/asf/sling/site</a>
+. Updates to secondary parts of the site have to be done in the following
+steps:</p>
+<ol>
+<li>
+<p>Checkout or update the <a href="https://svn.apache.org/repos/asf/sling/site">site</a>
+ tree form SVN.</p>
+<p>$ svn checkout https://svn.apache.org/repos/asf/sling/site</p>
+</li>
+<li>
+<p>Apply your changes.</p>
+</li>
+<li>
+<p>Commit the changes back into SVN.</p>
+<p>$ svn commit -m"<enter your message here>"</p>
+</li>
+<li>
+<p>Login to <em>people.apache.org</em></p>
+<p>$ ssh people.apache.org</p>
+</li>
+<li>
+<p>Go to the location from where infrastructure mirroring is getting the
+actual sites and update from SVN.</p>
+<p>$ cd /x1/www/sling.apache.org
+$ svn update</p>
+</li>
+</ol>
+<p>After some time, the updates will be synchronized to the web servers and
+can be accessed.</p>
+<p><a name="Documentation-ThePublicWiki"></a></p>
+<h3 id="the-public-wiki">The Public Wiki</h3>
+<p>The public wiki of Sling is available at http://cwiki.apache.org/SLING and
+is maintained in the Confluence space <em>SLING</em>. This is a public wiki, in
+that after self-registration, everybody is allowed to edit content.</p>
+<p><a name="Documentation-TheJavaDoc"></a></p>
+<h3 id="the-javadoc">The JavaDoc</h3>
+<p>Up until now the JavaDoc of the Sling Bundles has not been published.</p>
+<p>I just polished the JavaDoc generation setup of Sling a bit, so that I
+could generate a first shot of aggregate JavaDocs. This draft can currently
+be found on my site at
+http://people.apache.org/~fmeschbe/slingdocs.762729/. This JavaDoc has been
+generated as follows:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">svn</span> <span class="n">export</span> <span class="o">-</span><span class="n">r</span> <span class="mi">762729</span>
+</pre></div>
+
+
+<p>http://svn.apache.org/repos/asf/incubator/sling/trunk sling
+    $ mvn -DexcludePackageNames="<em>.impl:</em>.internal:<em>.jsp:sun.misc:</em>.juli"
+org.apache.maven.plugins:maven-javadoc-plugin:2.5:aggregate</p>
+<p>I am still unsure whether it makes sense to generate aggregate JavaDoc for
+all (or part of) the bundles of Sling. See also below regarding the Sites.</p>
+<p><a name="Documentation-TheBundleDocumentation"></a></p>
+<h3 id="the-bundle-documentation">The Bundle Documentation</h3>
+<p>Apart from the documentation of Sling on the Site and in the Wiki, it would
+also be thinkable that we accompany the source modules with some
+documentation and generate this using the Maven Site plugin. My tests so
+far for generating a multi-module site have not been very successful. But
+generating the site in a module-by-module manner might be a good thing, at
+least to get the per-module JavaDoc and some more code-oriented information
+like Surefire Reports, fixed bugs, etc.</p>
+<p>To prepare such Bundle Documentation I added a first shot at site
+generation setup to the parent project. For now, this includes the module's
+JavaDoc (of course), the Surefire reports and a report on the issues fixed
+(or open) with respect to some version. This site generation setup can be
+configured per module with two properties:</p>
+<table>
+<tr><th> Property </th><th> Description </th></tr>
+<tr><td> *site.jira.version.id* </td><td> The ID of the JIRA version whose bugs are to
+be listed in the JIRA report. This is a number, such as 12313306 (Sling API
+version 2.0.4). </td></tr>
+<tr><td> *site.javadoc.exclude* </td><td> The Java packages to not include with the
+JavaDoc generation. By default all packages containing *impl* or
+*internal* in their name are excluded. To add more packages for
+exclusion, list them in the format suitable for the [*excludePackageNames*](http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#excludePackageNames)
+ property of the Maven JavaDoc plugin. For example, to exclude any *jsp*
+and *juli* packages (see the _scripting/jsp_ bundle), this property would
+be set to *\*.jsp:\*.juli*. </td></tr>
     
         <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.