sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1328899 [6/8] - in /sling/site/trunk: content/ templates/
Date Sun, 22 Apr 2012 16:52:16 GMT
Added: sling/site/trunk/content/project-license.mdtext
--- sling/site/trunk/content/project-license.mdtext (added)
+++ sling/site/trunk/content/project-license.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,212 @@
+Title: Project License
+    				 Apache License
+    			   Version 2.0, January 2004
+       1. Definitions.
+          "License" shall mean the terms and conditions for use, reproduction,
+          and distribution as defined by Sections 1 through 9 of this document.
+          "Licensor" shall mean the copyright owner or entity authorized by
+          the copyright owner that is granting the License.
+          "Legal Entity" shall mean the union of the acting entity and all
+          other entities that control, are controlled by, or are under common
+          control with that entity. For the purposes of this definition,
+          "control" means (i) the power, direct or indirect, to cause the
+          direction or management of such entity, whether by contract or
+          otherwise, or (ii) ownership of fifty percent (50%) or more of the
+          outstanding shares, or (iii) beneficial ownership of such entity.
+          "You" (or "Your") shall mean an individual or Legal Entity
+          exercising permissions granted by this License.
+          "Source" form shall mean the preferred form for making modifications,
+          including but not limited to software source code, documentation
+          source, and configuration files.
+          "Object" form shall mean any form resulting from mechanical
+          transformation or translation of a Source form, including but
+          not limited to compiled object code, generated documentation,
+          and conversions to other media types.
+          "Work" shall mean the work of authorship, whether in Source or
+          Object form, made available under the License, as indicated by a
+          copyright notice that is included in or attached to the work
+          (an example is provided in the Appendix below).
+          "Derivative Works" shall mean any work, whether in Source or Object
+          form, that is based on (or derived from) the Work and for which the
+          editorial revisions, annotations, elaborations, or other
+          represent, as a whole, an original work of authorship. For the
+          of this License, Derivative Works shall not include works that remain
+          separable from, or merely link (or bind by name) to the interfaces
+          the Work and Derivative Works thereof.
+          "Contribution" shall mean any work of authorship, including
+          the original version of the Work and any modifications or additions
+          to that Work or Derivative Works thereof, that is intentionally
+          submitted to Licensor for inclusion in the Work by the copyright
+          or by an individual or Legal Entity authorized to submit on behalf of
+          the copyright owner. For the purposes of this definition, "submitted"
+          means any form of electronic, verbal, or written communication sent
+          to the Licensor or its representatives, including but not limited to
+          communication on electronic mailing lists, source code control
+          and issue tracking systems that are managed by, or on behalf of, the
+          Licensor for the purpose of discussing and improving the Work, but
+          excluding communication that is conspicuously marked or otherwise
+          designated in writing by the copyright owner as "Not a Contribution."
+          "Contributor" shall mean Licensor and any individual or Legal Entity
+          on behalf of whom a Contribution has been received by Licensor and
+          subsequently incorporated within the Work.
+       2. Grant of Copyright License. Subject to the terms and conditions of
+          this License, each Contributor hereby grants to You a perpetual,
+          worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+          copyright license to reproduce, prepare Derivative Works of,
+          publicly display, publicly perform, sublicense, and distribute the
+          Work and such Derivative Works in Source or Object form.
+       3. Grant of Patent License. Subject to the terms and conditions of
+          this License, each Contributor hereby grants to You a perpetual,
+          worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+          (except as stated in this section) patent license to make, have made,
+          use, offer to sell, sell, import, and otherwise transfer the Work,
+          where such license applies only to those patent claims licensable
+          by such Contributor that are necessarily infringed by their
+          Contribution(s) alone or by combination of their Contribution(s)
+          with the Work to which such Contribution(s) was submitted. If You
+          institute patent litigation against any entity (including a
+          cross-claim or counterclaim in a lawsuit) alleging that the Work
+          or a Contribution incorporated within the Work constitutes direct
+          or contributory patent infringement, then any patent licenses
+          granted to You under this License for that Work shall terminate
+          as of the date such litigation is filed.
+       4. Redistribution. You may reproduce and distribute copies of the
+          Work or Derivative Works thereof in any medium, with or without
+          modifications, and in Source or Object form, provided that You
+          meet the following conditions:
+          (a) You must give any other recipients of the Work or
+    	  Derivative Works a copy of this License; and
+          (b) You must cause any modified files to carry prominent notices
+    	  stating that You changed the files; and
+          (c) You must retain, in the Source form of any Derivative Works
+    	  that You distribute, all copyright, patent, trademark, and
+    	  attribution notices from the Source form of the Work,
+    	  excluding those notices that do not pertain to any part of
+    	  the Derivative Works; and
+          (d) If the Work includes a "NOTICE" text file as part of its
+    	  distribution, then any Derivative Works that You distribute must
+    	  include a readable copy of the attribution notices contained
+    	  within such NOTICE file, excluding those notices that do not
+    	  pertain to any part of the Derivative Works, in at least one
+    	  of the following places: within a NOTICE text file distributed
+    	  as part of the Derivative Works; within the Source form or
+    	  documentation, if provided along with the Derivative Works; or,
+    	  within a display generated by the Derivative Works, if and
+    	  wherever such third-party notices normally appear. The contents
+    	  of the NOTICE file are for informational purposes only and
+    	  do not modify the License. You may add Your own attribution
+    	  notices within Derivative Works that You distribute, alongside
+    	  or as an addendum to the NOTICE text from the Work, provided
+    	  that such additional attribution notices cannot be construed
+    	  as modifying the License.
+          You may add Your own copyright statement to Your modifications and
+          may provide additional or different license terms and conditions
+          for use, reproduction, or distribution of Your modifications, or
+          for any such Derivative Works as a whole, provided Your use,
+          reproduction, and distribution of the Work otherwise complies with
+          the conditions stated in this License.
+       5. Submission of Contributions. Unless You explicitly state otherwise,
+          any Contribution intentionally submitted for inclusion in the Work
+          by You to the Licensor shall be under the terms and conditions of
+          this License, without any additional terms or conditions.
+          Notwithstanding the above, nothing herein shall supersede or modify
+          the terms of any separate license agreement you may have executed
+          with Licensor regarding such Contributions.
+       6. Trademarks. This License does not grant permission to use the trade
+          names, trademarks, service marks, or product names of the Licensor,
+          except as required for reasonable and customary use in describing the
+          origin of the Work and reproducing the content of the NOTICE file.
+       7. Disclaimer of Warranty. Unless required by applicable law or
+          agreed to in writing, Licensor provides the Work (and each
+          Contributor provides its Contributions) on an "AS IS" BASIS,
+          implied, including, without limitation, any warranties or conditions
+          PARTICULAR PURPOSE. You are solely responsible for determining the
+          appropriateness of using or redistributing the Work and assume any
+          risks associated with Your exercise of permissions under this
+       8. Limitation of Liability. In no event and under no legal theory,
+          whether in tort (including negligence), contract, or otherwise,
+          unless required by applicable law (such as deliberate and grossly
+          negligent acts) or agreed to in writing, shall any Contributor be
+          liable to You for damages, including any direct, indirect, special,
+          incidental, or consequential damages of any character arising as a
+          result of this License or out of the use or inability to use the
+          Work (including but not limited to damages for loss of goodwill,
+          work stoppage, computer failure or malfunction, or any and all
+          other commercial damages or losses), even if such Contributor
+          has been advised of the possibility of such damages.
+       9. Accepting Warranty or Additional Liability. While redistributing
+          the Work or Derivative Works thereof, You may choose to offer,
+          and charge a fee for, acceptance of support, warranty, indemnity,
+          or other liability obligations and/or rights consistent with this
+          License. However, in accepting such obligations, You may act only
+          on Your own behalf and on Your sole responsibility, not on behalf
+          of any other Contributor, and only if You agree to indemnify,
+          defend, and hold each Contributor harmless for any liability
+          incurred by, or claims asserted against, such Contributor by reason
+          of your accepting any such warranty or additional liability.
+       APPENDIX: How to apply the Apache License to your work.
+          To apply the Apache License to your work, attach the following
+          boilerplate notice, with the fields enclosed by brackets "[]
+          replaced with your own identifying information. (Don't include
+          the brackets!)  The text should be enclosed in the appropriate
+          comment syntax for the file format. We also recommend that a
+          file or class name and description of purpose be included on the
+          same "printed page" as the copyright notice for easier
+          identification within third-party archives.
+       Copyright [yyyy]
+ [name of copyright owner]
+       Licensed 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
+       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.

Added: sling/site/trunk/content/project-team.mdtext
--- sling/site/trunk/content/project-team.mdtext (added)
+++ sling/site/trunk/content/project-team.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,66 @@
+Title: Project Team
+<a name="ProjectTeam-TheProjectTeam"></a>
+# The Project Team
+A successful project requires many people to play many roles. Some members
+write code or documentation, while others are valuable as testers,
+submitting patches and suggestions.
+The team is comprised of Committers and Contributors. Committers have
+direct access to the source of a project and actively evolve the code-base.
+Contributors improve the project through submission of patches and
+suggestions to the Members. The number of Contributors to the project is
+unbounded. Get involved today. All contributions to the project are greatly
+<a name="ProjectTeam-CommittersandPMCmembers"></a>
+## Committers and PMC members
+The following is a list of developers with commit privileges that have
+directly contributed to the project in one way or another.
+<tr><th> Id </th><th> Name </th><th> Organization </th><th> Roles </th><th> Time Zone </th></tr>
+<tr><td> apopescu (*) </td><td> Alexandru Popescu </td><td> </td><td> Java Developer </td><td> \+1 </td></tr>
+<tr><td> bdelacretaz (*) </td><td> Bertrand Delacretaz </td><td> Adobe </td><td> Java Developer </td><td> \+1 </td></tr>
+<tr><td>  </td><td> Clemens Wyss </td><td> MySign AG </td><td> </td><td> \+1 </td></tr>
+<tr><td> clombart (*) </td><td> Christophe Lombart </td><td> </td><td> Java Developer </td><td> \+1 </td></tr>
+<tr><td> cziegeler (*) </td><td> Carsten Ziegeler </td><td> Adobe </td><td> Chair, Java Developer </td><td> \+1 </td></tr>
+<tr><td> fmeschbe (*) </td><td> Felix Meschberger </td><td> Adobe </td><td> Java Developer </td><td> \+1 </td></tr>
+<tr><td> enorman </td><td> Eric Norman </td><td> </td><td> Java Developer </td><td> </td></tr>
+<tr><td> gianugo (*) </td><td> Gianugo Rabellino </td><td> </td><td> </td><td> \+1 </td></tr>
+<tr><td> justin (*) </td><td> Justin Edelson </td><td> Adobe </td><td> Java Developer </td><td> </td></tr>
+<tr><td> hannonpi (*) </td><td> Padraic Hannon </td><td> Edmunds Inc. </td><td> Java Developer </td><td> </td></tr>
+<tr><td> ieb (*) </td><td> Ian Boston </td><td> University of Cambridge </td><td> Java Developer </td><td> </td></tr>
+<tr><td> juanjo (*) </td><td> Juan José Vázquez Delgado </td><td> </td><td> Java Developer </td><td> </td></tr>
+<tr><td> mykee (*) </td><td> Mike Müller </td><td> MySign AG </td><td> </td><td> \+1 </td></tr>
+<tr><td> pauls (*) </td><td> Karl Pauls </td><td> </td><td> Java Developer </td><td> \+1 </td></tr>
+<tr><td> thecarlhall </td><td> Carl Hall </td><td> Hallway Technologies </td><td> Java Developer </td><td> -5 </td></tr>
+<tr><td> vramdal (*) </td><td> Vidar Ramdal </td><td> </td><td> Java Developer </td><td> \+1 </td></tr>
+Committers marked with an asterisk (*) are also members of the Sling Project Management Commitee ([PMC](
+) as defined in [Apache Sling Community Roles and Processes]
+<a name="ProjectTeam-EmeritusCommittersandPMCmembers"></a>
+## Emeritus Committers and PMC members
+The following list of former committers and/or PMC members have chosen to
+go emeritus. We are still thankful for their help and guidance during
+earlier phases of the Sling project.
+<tr><th> Id </th><th> Name </th><th> Organization </th><th> Roles </th><th> Time Zone </th></tr>
+<tr><td> farra </td><td> *J Aaron Farr* </td><td> </td><td> Mentor </td><td> </td></tr>
+<tr><td> jukka </td><td> *Jukka Zitting* </td><td> Day Software </td><td> Champion, Mentor </td><td> +1 </td></tr>
+Committers with their names printed in bold face have also been members of
+the PMC (or PPMC during Sling incubation) as defined in [Apache Sling Community Roles and Processes](apache-sling-community-roles-and-processes.html)
+<a name="ProjectTeam-Contributors"></a>
+## Contributors
+There are no contributors listed for this project.

Added: sling/site/trunk/content/release-management.mdtext
--- sling/site/trunk/content/release-management.mdtext (added)
+++ sling/site/trunk/content/release-management.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,513 @@
+Title: Release Management
+<a name="ReleaseManagement-ReleaseManagement"></a>
+# Release Management
+Sling releases (and SNAPSHOTS) are deployed to the [Nexus repository](
+ instead of the traditional deployment via the Maven 2 mirros source on
+**. This makes the release process much leaner and
+simpler. In addtion we can benefit from the Apache Parent POM 6, which has
+most of the release profile setup built-in.
+Most of the hard work of preparing and deploying the release is done by
+<a name="ReleaseManagement-Prerequisites"></a>
+## Prerequisites
+* To prepare or perform a release you *MUST BE* at least be an Apache Sling
+* Each and every release must be signed; therefore the public key should be
+cross signed by other Apache committers (not required but suggested) and
+this public key should be added to [](
+ and either on or (See Appendix A)
+* When preparing the release on Mac OS X, check out Appendix B before
+trying the steps in the next chapter.
+* Make sure you have all Apache servers defined in your [settings.xml](
+*Note*: Listing the Apache servers in the *settings.xml* file also
+requires adding the password to that file. Starting with Maven 2.1 this
+password may be encrypted and needs not be give in plaintext. Please refer
+to [Password Encryption](
+ for more information.
+In the past we staged release candidates on our local machines using a
+semi-manual process. Now that we inherit from the Apache parent POM version
+6, a repository manager will automatically handle staging for you. This
+means you now only need to specify your GPG passphrase in the release
+profile of your *$\{user.home\}/.m2/settings.xml*:
+    <settings>
+        ...
+        <profiles>
+    	<profile>
+    	    <id>apache-release</id>
+    	    <properties>
+    		<gpg.passphrase> <!-- YOUR KEY PASSPHRASE -->
+    	    </properties>
+    	</profile>
+        </profiles>
+        ...
+    </settings>
+Everything else has been configured in the latest Sling Parent POM:
+    <parent>
+        <groupId></groupId>
+        <artifactId>sling</artifactId>
+        <version>6</version>
+    </parent>
+<a name="ReleaseManagement-StagingtheReleaseCandidates"></a>
+## Staging the Release Candidates
+First prepare your POMs for release:
+1. Make sure there are no snapshots in the POMs to be released
+1. Check that your POMs will not lose content when they are rewritten during
+the release process
+    $ mvn release:prepare -DdryRun=true
+Compare the original *pom.xml* with the one called *pom.xml.tag* to see
+if the license or any other info has been removed. This has been known to
+happen if the starting *<project>* tag is not on a single line. The only
+things that should be different between these files are the *<version>*
+and *<scm>* elements. If there are any other changes, you must fix the
+original *pom.xml* file and commit before proceeding with the release.
+1. Publish a snapshot
+    $ mvn deploy
+    ...
+    [INFO]
+ [deploy:deploy]
+    [INFO]
+ Retrieving previous build number from apache.snapshots.https
+    ...
+1. * If you experience an error during deployment like a HTTP 401 check your
+settings for the required server entries as outlined in the *Prerequisites*
+1. * Be sure that the generated artifacts respect the Apache release [rules](
+: NOTICE and LICENSE files should be present in the META-INF directory
+within the jar. For \-sources artifacts, be sure that your POM does not use
+the maven-source-plugin:2.0.3 which is broken. The recommended version at
+this time is 2.0.4
+1. * You should verify the deployment under the [snapshot](
+ repository on Apache
+1. Prepare the release
+    $ mvn release:clean
+    $ mvn release:prepare
+1. * Preparing the release will create the new tag in SVN, automatically
+checking in on your behalf
+1. * If you get a build failure because of an SVN commit problem (namely _The
+specified baseline is not the latest baseline, so it may not be checked
+out._), just repeat the *mvn release:prepare* command until SVN is happy.
+This is based on a known timing issue when using the European SVN mirror.
+1. Stage the release for a vote
+    $ mvn release:perform
+1. * The release will automatically be inserted into a temporary staging
+repository for you, see the Nexus [staging documentation](
+ for full details
+1. * You can continue to use *mvn release:prepare* and {{mvn
+release:perform}} on other sub-projects as necessary on the same machine
+and they will be combined in the same staging repository - this is useful
+when making a release of multiple Sling modules.
+1. Close the staging repository
+1. * Login to [](
+ using your Apache SVN credentials. Click on *Staging* on the left. Then
+click on ** in the list of repositories. In the panel below
+you should see an open repository that is linked to your username and IP.
+Right click on this repository and select *Close*. This will close the
+repository from future deployments and make it available for others to
+view. If you are staging multiple releases together, skip this step until
+you have staged everything
+1. Verify the staged artifacts
+1. * If you click on your repository, a tree view will appear below. You can
+then browse the contents to ensure the artifacts are as you expect them.
+Pay particular attention to the existence of \*.asc (signature) files. If
+you don't like the content of the repository, right click your repository
+and choose *Drop*. You can then rollback your release (see *Canceling the
+Release*) and repeat the process
+1. * Note the staging repository URL (especially the number at the end of the
+URL) you will need this in your vote email
+<a name="ReleaseManagement-StartingtheVote"></a>
+## Starting the Vote
+Propose a vote on the dev list with the closed issues, the issues left, and
+the staging repository - for example:
+    To: "Sling Developers List" <>
+    Subject: [VOTE]
+ Release Apache Sling ABC version X.Y.Z
+    Hi,
+    We solved N issues in this release:
+    There are still some outstanding issues:
+    Staging repository:
+    You can use this UNIX script to download the release and verify the
+    Usage:
+ /tmp/sling-staging
+    Please vote to approve this release:
+     [ ]
+ +1 Approve the release
+     [ ]
+  0 Don't care
+     [ ]
+ -1 Don't release, because ...
+    This vote will be open for 72 hours.
+<a name="ReleaseManagement-WaitfortheResults"></a>
+## Wait for the Results
+From [Votes on Package Releases](
+{quote}Votes on whether a package is ready to be released follow a format
+similar to majority approval -- except that the decision is officially
+determined solely by whether at least three \+1 votes were registered.
+Releases may not be vetoed. Generally the community will table the vote to
+release if anyone identifies serious problems, but in most cases the
+ultimate decision, once three or more positive votes have been garnered,
+lies with the individual serving as release manager. The specifics of the
+process may vary from project to project, but the 'minimum of three \+1
+votes' rule is universal.{quote}
+The list of binding voters is available on the [Project Team](project-team.html)
+ page.
+If the vote is successful, post the result to the dev list - for example:
+    To: "Sling Developers List" <>
+    Subject: [RESULT]
+ [VOTE]
+ Release Apache Sling ABC version X.Y.Z
+    Hi,
+    The vote has passed with the following result :
+    +1 (binding): <<list of names>>
+    +1 (non binding): <<list of names>>
+    I will copy this release to the Sling dist directory and
+    promote the artifacts to the central Maven repository.
+Be sure to include all votes in the list and indicate which votes were
+binding. Consider \-1 votes very carefully. While there is technically no
+veto on release votes, there may be reasons for people to vote \-1. So
+sometimes it may be better to cancel a release when someone, especially a
+member of the PMC, votes \-1.
+If the vote is unsuccessful, you need to fix the issues and restart the
+process - see *Canceling the Release*.
+If the vote is successful, you need to promote and distribute the release -
+see *Promoting the Release*.
+<a name="ReleaseManagement-CancelingtheRelease"></a>
+## Canceling the Release
+If the vote fails, or you decide to redo the release:
+1. Remove the release tag from Subversion (*svn del ...*)
+1. Login to [](
+ using your Apache SVN credentials. Click on *Staging* on the left. Then
+click on ** in the list of repositories. In the panel below
+you should see a closed repository that is linked to your username and IP
+(if it's not yet closed you need to right click and select *Close*). Right
+click on this repository and select *Drop*.
+1. Rollback the version in the *pom.xml* and commit any fixes you need to
+<a name="ReleaseManagement-PromotingtheRelease"></a>
+## Promoting the Release
+If the vote passes:
+1. Copy the released artifacts to the Sling dist directory
+(*/x1/www/*) on **. This
+folder is replicated to [](
+ a few times a day.
+1. Delete the old release from the Sling dist directory (it's archived)
+1. Login to [](
+ with your Apache SVN credentials. Click on *Staging*. Find your closed
+staging repository and select it by checking the select box. Select the
+*Releases* repository from the drop-down list and click *Release* from the
+menu above.
+1. Once the release is promoted click on *Repositories*, select the
+*Releases* repository and validate that your artifacts are all there.
+1. If you're releasing bundles, you should also add them to the Sling
+Release OBR (see *Appendix C*).
+1. Update the news section on the website at [news](news.html)
+1. Update the download page on the website at [downloads](downloads.html)
+ to point to the new release.
+For the last two tasks, it's better to give the mirrors some time to
+distribute the uploaded artifacts (one day should be fine). This ensures
+that once the website (news and download page) is updated, people can
+actually download the artifacts.
+<a name="ReleaseManagement-UpdateJIRA"></a>
+## Update JIRA
+Go to [Manage Versions](
+ section on the SLING JIRA and mark the X.Y.Z version as released setting
+the release date to the date the vote has been closed.
+Also create a new version X.Y.Z+2, if that hasn't already been done.
+<a name="ReleaseManagement-CreateanAnnouncement"></a>
+## Create an Announcement
+    To: "Sling Developers List" <>, "Apache Announcements"
+    Subject: [ANN]
+ Apache Sling ABC version X.Y.Z Released
+    The Apache Sling team is pleased to announce the release of Apache Sling
+ABC version X.Y.Z
+    Apache Sling is a web framework that uses a Java Content Repository, such
+as Apache Jackrabbit, to store and manage content. Sling applications use
+either scripts or Java servlets, selected based on simple name conventions,
+to process HTTP requests in a RESTful way.
+    <<insert short description of the sub-project>>
+    This release is available from
+and Maven:
+    <dependency>
+        <groupId></groupId>
+        <artifactId></artifactId>
+        <version>X.Y.Z</version>
+    </dependency>
+    Release Notes:
+    <<insert release notes in text format from JIRA>>
+    Enjoy!
+    -The Sling team
+*Important*: Add the release to the Software section of the next board
+report below [Reports](
+<a name="ReleaseManagement-RelatedLinks"></a>
+## Related Links
+1. [](
+1. [](
+<a name="ReleaseManagement-AppendixA:CreateandAddyourkeyto[]("></a>
+## Appendix A: Create and Add your key to []
+Considering that you are using a \*nix system with a working OpenSSH,
+GnuPG, and bash you can create and add your own key with the following
+1. _Create a public/private pair key_:
+    $ gpg --gen-key
+When gpg asks for e-mail linked the key you *MUST USE* the
+<committer> one
+When gpg asks for comment linked the key you _SHOULD USE_ "CODE SIGNING
+1. _Add the key to_ [](
+ type the following command replacing the word e-mail with your Apache's
+one (<committer>
+    $ (gpg --list-sigs e-mail && gpg --export --armor e-mail) > toadd.key
+    $ scp toadd.key
+    $ ssh "cat toadd.key >>
+1. You are *DONE*, but to see the changes on [](
+ you must wait 2 hours
+You also have to add your public key either on or (for the statging repository).
+<a name="ReleaseManagement-AppendixB:preparingreleasesonMacOSX"></a>
+## Appendix B: preparing releases on Mac OS X
+When running the *mvn release:prepare* command on Mac OS X, you might see
+the following error:
+    [INFO]
+ Working directory: /homedir/dev/sling/dependencymanager
+    [INFO]
+ ------------------------------------------------------------------------
+    [ERROR]
+    [INFO]
+ ------------------------------------------------------------------------
+    [INFO]
+ Unable to commit files
+    Provider message:
+    The svn command failed.
+    Command output:
+    svn: Commit failed (details follow):
+    svn: MKACTIVITY of
+'/repos/asf/!svn/act/4f11ad5d-9161-0410-b4dd-cb727141ea8c': authorization
+failed ({code}
+    This is due to a bug in Subversion on the Mac, as described by Brett Porter
+in his [blog|]
+. He proposes putting an "svn" script at the head of your path to fix the
+    h2. Appendix C: Deploy bundles on the Sling OBR
+    We are mainting an OSGi Bundle Repository providing all release of the
+Sling Bundles. This repository is maintained as part of the Apache Sling
+site and is available at []
+. The source for this page is maintained in the SVN repository below the
+_site_, that is at []
+. To update the Sling OBR repository you must be an Apache Sling Committer
+since this requires SVN write access.
+    To update the OBR you may use the Apache Felix Maven Bundle Plugin which
+prepares the bundle descriptor to be added to the OBR file. Follow these
+steps to update the OBR:
+    *1. Checkout or update the Site Source*
+$ svn checkout
+    Note, that you have to checkout the site using the {{https}} URL, otherwise
+you will not be able to commit the changes later.
+    *2. Deploy the Descriptor*
+    To deploy the project descriptor, checkout the tag of the bundle to deploy
+and run maven
+$ svn checkout
+$ mvn clean install \
+    org.apache.felix:maven-bundle-plugin:deploy \
+    -DprefixUrl= \
+    -DremoteOBR=sling.xml \
+    This generates the bundle descriptor and adds it to the {{sling.xml}} file
+of your site checkout.
+    *2a. Variant: Refer to Maven Repository*
+    Instead of checking out and building the project locally, you may also use
+the {{deploy-file}} goal of the Maven Bundle Plugin:
+$ wget
+$ wget
+$ mvn org.apache.felix:maven-bundle-plugin:deploy-file \
+    -Dfile=the_module-version.jar -DpomFile=the_module-version.pom \
+    -Durl=file:///path_to_site_checkout/obr \
+    -DprefixUrl= \
+    -DremoteOBR=sling.xml
+$ rm the_module-version.jar the_module-version.pom
+    *3. Commite the Site Changes*
+    In the Site checkout folder commit the changes to the {{obr/sling.xml}}
+files (you may also review the changes using the {{svn diff}} command).
+$ svn commit -m"Add Bundle ABC Version X.Y.Z" obr/sling.xml
+    *4. Update the Site on* {{{*}{*}}}
+    After committing the changes, you have to update the site source, which is
+getting mirrored to the web servers on {{}}
+$ ssh svn update /x1/www/
+    After updating the site source it will generally take an hour or two until
+the changes are visible on the web.

Added: sling/site/trunk/content/repository-based-development.mdtext
--- sling/site/trunk/content/repository-based-development.mdtext (added)
+++ sling/site/trunk/content/repository-based-development.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,164 @@
+Title: Repository Based Development
+<a name="RepositoryBasedDevelopment-RepositoryBasedDevelopment"></a>
+# Repository Based Development
+<a name="RepositoryBasedDevelopment-WebDAVSupport"></a>
+## WebDAV Support
+WebDAV support in Sling is based on the [Simple WebDAV](
+ implementation of Apache Jackrabbit which is integrated in the
+*jcr/webdav* project. This bundle provides WebDAV access to Sling's
+repository in two flavours: (1) Access to all workspaces of the repository
+on a separate URL space -- by default rooted at */dav* in the Sling
+context -- and (2) access to the workspace used by Sling itself at the root
+of the Sling context.
+<a name="RepositoryBasedDevelopment-Example"></a>
+#### Example
+Consider Sling be installed on a Servlet container in the */sling*
+context on **. Here you would access the Sling
+workspace by directing your WebDAV client to the URL
+**. To access the *sample* workspace,
+which is not used by Sling itself, you would direct your WebDAV client to
+the URL **.
+Please note that accessing the repository in the separate URI space is
+actually faster, since requests do not pass the Sling resource and script
+resolution framework but instead hit the Jackrabbit Simple WebDAV Servlet
+<a name="RepositoryBasedDevelopment-SeparateURISpaceWebDAV"></a>
+#### Separate URI Space WebDAV 
+When accessing the repository through WebDAV in its separate URI Space, the
+URLs have the following generic structure:
+   * **slingroot** is the URL of the Sling web application context. In
+the above example, this would **.
+   * **prefix** is the URL prefix to address the WebDAV servlet. By
+default this is set to */dav* but may be configured to any valid path.
+   * **workspace** is the name of the workspace to be accessed through
+   * **item** is the path to the JCR Item to access.
+If you access the WebDAV server at the prefix path -- e.g.
+*!http://localhost:8080/dav* -- you will be redirected to the default
+workspace with a temporary redirect status 302. Some clients, such as the
+Linux _davfs_, do not like this redirection and must be configured to
+explicitly address the default workspace.
+<a name="RepositoryBasedDevelopment-Configuration"></a>
+### Configuration
+The Jackrabbit Simple WebDAV support in Sling has the following
+configuration options:
+<tr><th> Property </th><th> Default </th><th> Description </th></tr>
+<tr><td> Root Path </td><td> */dav* </td><td> The root path at which the Simple WebDAV Servlet
+is accessible. Access to the repository is provided in two ways. You may
+connect your WebDAV client directly to the root of the Sling web
+application to access the workspace of Sling directly. The other way is
+required if you want to connect your WebDAV client to any other workspace
+besides the Sling workspace. In this case you connect your WebDAV client to
+another a path comprised of this root path plus the name of the workspace.
+For example to connect to the *some_other* workspace, you might connect
+to *http://slinghost/dav/some_other*. </td></tr>
+<tr><td> Authentication Realm	</td><td> *Sling WebDAV* </td><td> The name of the HTTP Basic
+Authentication Realm presented to the client to ask for authentication
+credentials to access the repository. </td></tr>
+<tr><td> Non Collection Node Typee </td><td> [ *nt:file*, *nt:resource* ](-*nt:file*,-*nt:resource*-.html)
+ </td><td> The JCR Node Types considered being non-collection resouces by WebDAV.
+Any node replying *true* to *Node.isNodeType()* for one of the listed
+types is considered a non-collection resource. Otherwise the respective
+node is considered a colleciton resource. </td></tr>
+<tr><td> Filter Prefixes </td><td> [ *jcr*, *rep* ](-*jcr*,-*rep*-.html)
+ </td><td> A list of namespace prefixes indicating JCR items filtered from being
+reported as collection members or properties. The default list includes jcr
+and rep (Jackrabbit internal namespace prefix) items. Do not modify this
+setting unless you know exactly what you are doing. </td></tr>
+<tr><td> Filter Node Types </td><td> -- </td><td> Nodetype names to be used to filter child nodes.
+A child node can be filtered if the declaring nodetype of its definition is
+one of the nodetype names specified in the nodetypes Element. E.g. defining
+rep:root as filtered nodetype whould result in jcr:system being hidden but
+no other child node of the root node, since those are defined by the
+nodetype nt:unstructered. The default is empty. Do not modify this setting
+unless you know exactly what you are doing. </td></tr>
+<tr><td> Filter URIs </td><td> -- </td><td> A list of namespace URIs indicating JCR items filtered
+from being reported as collection members or properties. The default list
+is empty. Do not modify this setting unless you know exactly what you are
+doing. </td></tr>
+<tr><td> Collection Primary Type </td><td> *sling:Folder* </td><td> The JCR Primary Node Type to
+assign to nodes created to reflect WebDAV collections. You may name any
+primary node type here, provided it allows the creation of nodex of this
+type and the defined Non-Collection Primary Type below it. </td></tr>
+<tr><td> Non-Collection Primary Type </td><td> *nt:file* </td><td> The JCR Primary Node Type to
+assign to nodes created to reflect WebDAV non-collection resources. You may
+name any primary node type here, provided the node type is allowed to be
+created below nodes of the type defined for the Collection Primary Type and
+that a child node with the name "jcr:content" may be created below the
+non-collection resource whose type is defined by the Content Primary Type.
+<tr><td> Content Primary Type </td><td> *nt:resource* </td><td> The JCR Primary Node Type to
+assign to the jcr:content child node of a WebDAV non-collection resource.
+You may name any primary node type here, provided the node type is allowed
+to be created as the jcr:content child node of the node type defined by the
+Non-Collection Primary Type. In addition the node type must allow at least
+the following properties: jcr:data (binary), jcr:lastModified (date), and
+jcr:mimeType (string). </td></tr>
+<a name="RepositoryBasedDevelopment-AdvancedTechnicalDetails"></a>
+#### Advanced Technical Details
+Since the Jackrabbit Simple WebDAV Servlet is originally configured using
+an XML configuration file, which provides a great deal of flexibility, the
+integration into Sling had to assume some simplifications, of which some of
+the above parameters are part:
+This implementation uses the standard
+** class and adds the
+** and
+** IO handlers as its only
+handlers. The *DefaultHandler* is configured from the three node types
+listed as configuration parameters above (collection, non-collection, and
+content primary node types).
+This implementation uses the standard
+** and adds the same
+*DirListingExportHandler* and *DefaultHanlder* instances as its own
+handlers as are used by the IO Manager.
+This implementation uses the standard
+*org.apache.jackrabbit.webdav.simple.DefaultItemFilter* implementation as
+its item filter and configures the filter with the namespace prefixes and
+URIs as well as the node types configured as parameters.
+*Collection Node Types*
+This implementation only supports listing node types which are considered
+representing non-collection resources. All nodes which are instances of any
+of the configured node types are considered non-collection resources. All
+other nodes are considere collection resources.
+<a name="RepositoryBasedDevelopment-EclipsepluginforJCR"></a>
+## Eclipse plugin for JCR

Added: sling/site/trunk/content/request-listeners.mdtext
--- sling/site/trunk/content/request-listeners.mdtext (added)
+++ sling/site/trunk/content/request-listeners.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,40 @@
+Title: Request Listeners
+<a name="RequestListeners-RequestListenersupport"></a>
+# Request Listener support
+Sling provides the possibility to "listen" to a request processed by the
+Sling Engine (*SlingMainServlet*). To get notified you implement the
+service interface **.
+<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>SlingRequestListener</B></DIV><DIV class="codeContent panelContent">
+    public interface SlingRequestListener {
+    	static final String SERVICE_NAME =
+    	/**
+    	 * This method is called from the Sling application for every
+    	 * <code>EventType</code> appearing during the dispatching of
+    	 * a Sling request  
+    	 * 
+    	 * @param sre the object representing the event
+    	 * 
+    	 * @see
+    	 */
+    	public void onEvent( SlingRequestEvent sre );
+    }
+There are no special properties to set. 
+<a name="RequestListeners-Supportedtypesofevents"></a>
+## Supported types of events
+At the moment you will get two different types of *SlingRequestEvent*:
+<tr><th> events types (*SlingRequestEvent.EventType*) </th><th> point in time </th></tr>
+<tr><td> EVENT_INIT </td><td> after entering the *service* method in
+*SlingMainServlet*. Note that this will be *after* the *handleSecurity*
+call. </td></tr>
+<tr><td> EVENT_DESTROY </td><td> at the end of the *service* method in
+*SlingMainServlet* </td></tr>

Added: sling/site/trunk/content/request-parameters.mdtext
--- sling/site/trunk/content/request-parameters.mdtext (added)
+++ sling/site/trunk/content/request-parameters.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,134 @@
+Title: Request Parameters
+<a name="RequestParameters-RequestParameterHandlinginSling"></a>
+# Request Parameter Handling in Sling
+{excerpt:hidden=true}Explains how Sling provides request parameters to the
+<a name="RequestParameters-ServletAPI"></a>
+## Servlet API
+The Servlet API specification provides the following methods to access the
+parameters of a request
+<tr><td> *HttpServletRequest.getQueryString()* </td><td> Returns the query part of the
+request URL </td></tr>
+<tr><td> *ServletRequest.getParameter(String)* </td><td> Returns the (first) named
+parameter </td></tr>
+<tr><td> *ServletRequest.getParameterValues(String)* </td><td> Returns all parameters of
+that name </td></tr>
+<tr><td> *ServletRequest.getParameterMap()* </td><td> Returns all parameters as a map of {{String[](.html)
+}} </td></tr>
+<tr><td> *ServletRequest.getParameterNames()* </td><td> Returns an enumeration of the
+names of the parameters </td></tr>
+As a special restriction only two kinds of parameters are supported: (1)
+Query String parameters and (2) parameters contained in the request data of
+content type *application/x-www-form-encoded*. That is file uploads using
+request data of type *multipart/form-data* are not directly supported by
+the servlet specification. Finally the actual encoding of the parameters is
+all but safe because the encoding of URLs is not very well defined and
+browsers do not set the character encoding when sending post data.
+Fortunately, they use the same character encoding for sending back form
+content as was used by the server to send the form.
+<a name="RequestParameters-SlingAPI"></a>
+## Sling API
+To overcome these restrictions and to provide uniform access to request
+parameters the Sling API in addition to the Servlet API methods to access
+parameters provides an abstraction of parameters which is applicable to all
+parameters sent by clients, the *RequestParameter* interface. Through
+this interface, each parameter may be analyzed for these topics:
+<tr><td> Raw Content </td><td> Byte array and *InputStream* representation of the
+request parameter values. You will generally use the *InputStream* to
+handle uploaded files. </td></tr>
+<tr><td> String Content </td><td> Access the values as strings is some given encoding (see
+below) or by requesting the conversion using an explicit encoding. </td></tr>
+<tr><td> File Uploads </td><td> Find out whether a parameter is a file upload, get the
+size in bytes of the parameter value and client side file name as sent by
+the browser. </td></tr>
+To accomodate this new interface as well as to provide easy access in the
+traditional way the *SlingHttpServletRequest* interface adds following
+methods to the standard Servlet API parameter access methods:
+<tr><td> *getRequestParameter(String)* </td><td> Returns the (first) named parameter as
+a *RequestParameter* instance </td></tr>
+<tr><td> *getRequestParameters(String)* </td><td> Returns the named parameter as an
+array of *RequestParameter* instances </td></tr>
+<tr><td> *getRequestParameterMap()* </td><td> Returns *RequestParameterMap* being a
+map of *RequestParameter* arrays indexed by parameter names </td></tr>
+All parameters are handled the same, that is all methods give access to the
+same parameters regardless of whether the parameters were transmitted in
+the request query, as part of form encoded data or as part of a
+*multipart/form-data* request.
+As of Sling Engine 2.1.0 the order or request parameters in the
+*getRequestParameterMap()*, *getParameterMap()*, and
+*getParameterNams()* is preserved as follows:
+* The first entries are the parameters reported by the servlet container.
+The order of these parameters amongst each other is not defined. The
+*SlingHttpServletRequest* provides them in the same order as provided by
+the servlet container.
+* After the servlet container provided parameters are parameters extracted from the request in case *multipart/form-data* POST requests. The order of these parameters is preserved as they are submitted in the request. This conforms to HTML 4.01 spec on forms submitted with multipart/form-data encoding: _A "multipart/form-data" message contains a series of parts, each representing a successful control. The parts are sent to the processing agent in the same order the corresponding controls appear in the document stream. Part boundaries should not occur in any of the data; how this is done lies outside the scope of this specification_ ([17.13.4 Form content types](
+Be warned: Only rely on request parameter ordering *multipart/form-data*
+POST requests without a query part in the request URL.
+<a name="RequestParameters-CharacterEncoding"></a>
+## Character Encoding
+Traditionally, the encoding of parameters, especially in text area input
+forms, has been a big issue. To solve this issue Sling introduces the
+following convention:
+   * All forms should contain a hidden field of the name *\_charset\_*
+containing the actual encoding used to send the form from the server to the
+   * All forms should be sent with _UTF-8_ character encoding
+The first rule is essential as it helps decoding the form input correctly.
+The second rule is not actually a very hard requirement but to enable
+support for all (or most) character sets used, using _UTF-8_ is one of the
+best choices anyway.
+When Sling is now receiving a request and is asked for the parameters, the
+parameters are parsed in two phases: The first phase just parses the raw
+input data using an identity transformation of bytes to characters. This
+identity transformation happens to generate strings as the original data
+was generated with *ISO-8859-1* encoding. The second phase locates the
+*\_charset\_* parameter and fixes the character encodings of the
+parameters as follows:
+   * All names of the parameters are re-encoded
+   * The parameter values are re-encoded, unless the parameter value is an uploaded file. Actually the parameter (not the files of course) are internally as {{byte[](.html)
+}} where the conversion to a string is done on the fly (and yes, the
+conversion using the *\_charset\_* character encoding is of course cached
+for performance reasons)
+   * If the parameter is an uploaded file, the file name is re-encoded on
+the fly when accessed
+Up to and including Sling Engine 2.2.2 request parameters are always
+decoded with ISO-8859-1 encoding if the *\_charset\_* request parameter
+is missing. As of Sling Engine 2.2.4 the *\_charset\_* request parameter
+is optional. As of this version the Sling Main Servlet supports a
+configuration setting which allows to change the default character encoding
+used if the *\_charset\_* request parameter is missing. To enable this
+functionality set the *sling.default.parameter.encoding* parameter of the
+Sling Main Servlet (PID **)
+configuration to the desired encoding, which of course must be supported by
+the actual Java Platform.

Added: sling/site/trunk/content/request-processing.mdtext
--- sling/site/trunk/content/request-processing.mdtext (added)
+++ sling/site/trunk/content/request-processing.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,339 @@
+Title: Request Processing
+<a name="RequestProcessing-HTTPRequestProcessing"></a>
+# HTTP Request Processing
+{note:title=Page Status}
+2008-02-13: this page is *out of sync* with the current codebase, needs to
+be reviewed and updated.
+One of the core problems towards understanding how Sling works is knowing
+how a Client Request is processed by Sling. This page describes the flow of
+processing requests inside Sling.
+<a name="RequestProcessing-CoreRequestProcessing"></a>
+## Core Request Processing
+The HTTP request enters Sling in the
+req, ServletResponse res)}} method as the *ComponentRequestHandlerImpl*
+is registered as the Servlet handling HTTP requests. This method sets up
+the initial *ComponentRequest* and *ComponentResponse* objects and
+hands the request over to the first *ComponentFilterChain*. This first
+filter chain calls all *ComponentFilter* instances registered as request
+level filters. After processing all filters in the request level filter
+chain, the request is handed over to the second *ComponentFilterChain*
+which calls all *ComponentFilter* instances registered as component level
+filters. At the end of the second filter chain the *service* method of
+the actual *Component* to which the request resolved is called.
+As the component is now processing the request, it may decide to dispatch
+the request to some other content such as for example a paragraph system or
+navigation component. To do this, the component will call the
+*RequestDispatcher.include* method. If the request dispatcher dispatches
+to a *Content* object Sling will hand the dispatch request over to the
+component level filter chain, which at the end will call the *service*
+method for the *Content* object to dispatched to. This process may be
+repeated at the component's discretion only limited by processing resources
+such as available memory.
+As can be seen Sling itself is absed on the Component API
+*ComponentFilter* mechanism. As such Sling provides and uses the
+following filters in the Sling Core bundle:
+{tr}{th:colspan=2|class=confluenceTh} Request Level Filters {th}{tr}
+{tr}{td:class=confluenceTd} *ErrorHandlerFilter*
+{td}{td:class=confluenceTd} Handles exceptions thrown while processing the
+request as well implements the *ComponentResponse.sendError()* method
+{tr}{td:class=confluenceTd} *AuthenticationFilter*
+{td}{td:class=confluenceTd} Implements authentication for the request and
+provides the JCR Session of the request {td}{tr}
+{tr}{td:class=confluenceTd} *BurstCacheFilter*
+{td}{td:class=confluenceTd} Checks whether the request may be handled by
+cached response data {td}{tr}
+{tr}{td:class=confluenceTd} *LocaleResolverFilter*
+{td}{td:class=confluenceTd} Provides information on the *Locale* to be
+used for request processing. This filter implements the
+*ComponentRequest.getLocale()* method {td}{tr}
+{tr}{td:class=confluenceTd} *ThemeResolverFilter*
+{td}{td:class=confluenceTd} Provides the *Theme* for the request. The
+theme is provided as a request attribute {td}{tr}
+{tr}{td:class=confluenceTd} *URLMapperFilter* {td}{td:class=confluenceTd}
+Resolves the request URL to a JCR Node which may be mapped into a
+*Content* object {td}{tr}
+{tr}{td:class=confluenceTd} *ZipFilter* {td}{td:class=confluenceTd}
+Sample filter showing how the request response might be compressed
+according to the _Accept-Encoding_ request header. This filter is not
+enabled by default. {td}{tr}
+Deducing from these lists of filters, the actual request processing can be
+refined into the following steps:
+1. Extract user authentication information and acquire the JCR session to
+access content. If the request has no user authentication data the such
+data may be requested from the user (for example by sending a HTTP 401
+status) or an anonymous repository session might be acquired.
+1. Check whether the request may be handled by data stored in the cache.
+If the request is cacheable and a cache entry exists for the request URL,
+the request data is returned to the client and request processing may
+terminate. Otherwise request processing will continue and optionally ensure
+that any response data is entered into the cache. Of course, if the request
+is not cacheable, for example because there are request parameters, or if
+any of the *Component* instances called during request processing decide
+to signal non-cacheability for whatever reason, the response data will of
+course not cached.
+1. Extract the *java.util.Locale* from the request such that further
+processing may use properly translated messages. By default, the locale of
+the underlying Servlet request is used as the request locale. Other
+possibilities would be to use special cookies or some locale encoding in
+the path.
+1. Find the theme (or skin) to use to render the response. This step will
+add a ** object as a request parameter, which
+may be used by *Component*s to decide on specific rendering. For example,
+the theme may encapsulate information on the CSS to use for responses
+rendered as HTML.
+1. Resolve the request URL into a *Content* object.
+The default request level filter chain setup ends with finding the
+*Content* object requested by the request URL. After having found this
+object, the request is handed over to the component level filter chain,
+which is concerned with handling filtering on a single *Content*
+instance. As such, the component level filter chain is used for each
+*Content* object which is to be serviced either on behalf of the HTTP
+request or on behalf of request dispatcher. Thus the component level filter
+chain will generally called multiple times during a single request.
+{tr}{th:colspan=2|class=confluenceTh} Component Level Filters {th}{tr}
+{tr}{td:class=confluenceTd} *CacheFilter* {td}{td:class=confluenceTd}
+Checks whether the request to the current *Content* object may be handled
+by cached response data {td}{tr}
+{tr}{td:class=confluenceTd} *ComponentResolverFilter*
+{td}{td:class=confluenceTd} Resolves the component ID returned by the
+*Content.getComponentId()* method into a *Component* instances, which
+will be called to service the request {td}{tr}
+Again, deducing from the list of filters, the following steps are taking to
+service a given *Content* object:
+1. Check whether the *Content* object processing may be handled from
+the cache. Same as with request level cache handling, a cache entry may
+exist for a single *Content* instance depending on whether the request is
+cacheable at all and on whether a cache entry exists. If a cache entry
+exists and may be used, the response data is simply spooled into the
+response and component level processing terminates for the *Content*
+object. Otherwise processing continues and may optionally lead to a new
+cache entry for the *Content* object to be reused later.
+1. Resolve the component ID returned by the *Content.getComponentId()*
+method into a *Component* object. Of course it is an error, if the
+component ID cannot be mapped into a *Component* object.
+After resolving the *Component* object default component filter chain
+terminates and control is handed over to the *service* method of the
+*Component* object resolved in the last step. At the discretion of the
+component request dispatchers may now be acquired to render other
+*Content* objects. In this case the component level filter chain is
+simply kicked of again resulting in the *service* method of another
+*Component* being called. And so forth.
+<a name="RequestProcessing-ResolvingContent"></a>
+## Resolving Content
+As we have seen, the last step in the request level filter chain is the
+resolution of the request URL into a *Content* object. The URL Mapper
+Filter implementing this resolution uses an instance of the
+** interface which is acquired by
+calling the ** with
+the repository session acquired by the authentication filter.
+The URL Mapper filter then tries to apply fixed mappings from request URL
+to destination paths to support shortcut URLs. For example the root path
+*/* may be mapped into the default landing page at */default/home*. The
+list of such mappings is configurable through the Configuration Admin
+Next the URL Mapper tries to apply prefix matching patterns. A list of
+patterns is iterated checking whether the prefix applies and, if so,
+replacing the prefix with another prefix and trying to resolve the result.
+This functionality enables relocation of a subtree of the repository. For
+example, all requests whose prefix is */here* might be remapped with the
+new prefix */content/there*. The result  of this remapping is then
+Resolution (currently) takes place on the last path segment of the request
+URL containing at least one dot. Parts of that segment are cut off after
+dots until no more dots exist in the URL. For each resulting substring, the
+*ContentManager.load(String)* method is called. This processing
+terminates if a *Content* object is found or if there is nothing to cut
+off any more.
+This resolution is very simple and straight forwards. Future development
+may add support for the following features:
+* *Vanity URLs* - Map the request URL according to the *Host* request
+* *Dynamic Mapping* - Add support for a set of variables in path and/or
+prefix mapping. For example, a prefix mapping  may contain the string
+*/content/$\{lang}/$\{user*} resulting in resolving a prefix according to
+the language of the current locale and the name of the authenticated used.
+<a name="RequestProcessing-RegisteringComponents"></a>
+## Registering Components
+The last step of the component level filter chain is resolving the
+*Component* from the component ID of the *Content* object. Sling
+implements this resolution by making use of the OSGi service registry. That
+is, each component is to be registered as a service with the name
+**. The *ComponentResolverFilter*
+is listening for these components and registers them internally in a map
+indexed by the IDs of the component as returned by the
+*Component.getId()* method.
+When a component has to be resolved, the component ID returned by the
+*Content* object is simply looked up in the component map. If found, that
+component is used. Otherwise a fall back algorithm is applied which is
+described on the [Default Content Mapping and Request Rendering](default-mapping-and-rendering.html)
+ page.
+<a name="RequestProcessing-ReqisteringFilters"></a>
+## Reqistering Filters
+Just as *Component* instances used by Sling are expected to be registered
+as OSGi services, the *ComponentFilter*s to be 
+used have to be registered as services under the name
+**. Sling picks up all
+registered component filters and adds them to the respective filter chains.
+Service properties set upon registration of the filter define the chain to
+which the filter belongs and the order in which the filters should be
+<tr><th> Property </th><th> Description </th></tr>
+<tr><td> *filter.scope* </td><td> Defines the chain to which the filter is added.
+Supported values are *component* for component level filters and
+*request* for request level filters. If this property is missing or set
+to an unknown value the filter is added to the request level filter chain.
+<tr><td> *filter.order* </td><td> Defines the weight of the filter to resolve the
+processing order. This property must be an *java.lang.Integer*. If not
+set or not an *Integer* the order defaults to *Integer.MAX_VALUE*. The
+lower the order number the earlier in the filter chain will the filter be
+inserted. If two filters are registered with the same order value, the
+filter with the lower ** value is called first. </td></tr>
+<a name="RequestProcessing-ContentisaJavaObject"></a>
+## Content is a Java Object
+It is crucial to understand that *Content* is an interface and the
+request processor of Sling does not actually care, how the *Content*
+instance comes to live as long as the is such an object and there is a
+*Component* instance capable of servicing the *Content* object.
+By default Sling uses the _URL Mapper_ to resolve the request URL into a
+*Content* object. When a *Component* is tasked with servicing a
+*Content* object it usually uses the *ComponentRequestDispatcher* to
+ask Sling to service another content object generally identified by a
+(relative or absolute) path to a JCR Repository Node from which the
+*Content* object is loaded.
+But instead of having Sling resolve a path into a *Content* object the
+component may just as well create a *Content* object and hand it over to
+the *ComponentRequestDispatcher* for service. Consider a request which is
+handled by a *PageComponent*. This component has to draw a navigation
+tree somewhere in the response. So the component could of course insist on
+having a *navigation* child node to dispatch rendering to as follows:
+    RequestDispatcher rd = request.getRequestDispatcher("navigation");
+    rd.include(request, response);
+What happens, though, if there is no *navigation* child node ? Probably,
+the request will fail with some error status. Of course the component could
+be more clever and do:
+    Content navigation = request.getContent("navigation");
+    if (navigation != null) {
+        RequestDispatcher rd = request.getRequestDispatcher(navigation);
+        rd.include(request, response);
+    }
+Still, if the *navigation* child node does not exist, there is no
+navigation drawn; at least there will be now error. Since Sling does not
+actually care, how a *Content* object comes to live, the component could
+do the following:
+    Content navigation = new Content() {
+        public String getPath() {
+    	return request.getContent().getPath() + "/navigation";
+        }
+        public String getComponentId() {
+    	return NavigationComponent.getClass().getName();
+        }
+    }
+    RequestDispatcher rd = request.getRequestDispatcher(navigation);
+    rd.include(request, response);
+Of course, the page component now has to have knowledge about the actual
+*Component* to use.
+Finally, as a further enhancement, the Component might even decide to first
+check for a *navigation* child node. If such a node does not exist the
+navigation *Content* object is just created:
+    Content navigation = request.getContent("navigation");
+    if (navigation == null) {
+        navigation = new Content() {
+    	public String getPath() {
+    	    return request.getContent().getPath() + "/navigation";
+    	}
+    	public String getComponentId() {
+    	    return NavigationComponent.getClass().getName();
+    	}
+        }
+    }
+    RequestDispatcher rd = request.getRequestDispatcher(navigation);
+    rd.include(request, response);
+This could for example be used to fall back to a default navigation setup
+while providing for specialized navigation configuration in an optional
+*navigation* child node.

Added: sling/site/trunk/content/resources.mdtext
--- sling/site/trunk/content/resources.mdtext (added)
+++ sling/site/trunk/content/resources.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,214 @@
+Title: Resources
+<a name="Resources-Resources"></a>
+# Resources
+<a name="Resources-WhatisaResource"></a>
+## What is a Resource
+The Resource is one of the central parts of Sling. Extending from JCR's
+_Everything is Content_, Sling assumes _Everthing is a Resource_. Thus
+Sling is maintaining a virtual tree of resources, which is a merger of the
+actual contents in the JCR Repository and resources provided by so called
+resource providers. By doing this Sling fits very well in the paradigma of
+the REST architecture.
+<a name="Resources-HowtogetaResource"></a>
+## How to get a Resource
+To get at Resources, you need a *ResourceResolver*. This interface
+defines four kinds of methods to access resources:
+* Absolute Path Mapping Resource Resolution: The
+*resolve(HttpServletRequest, String)* and *resolve(String)* methods are
+called to apply some implementation specific path matching algorithm to
+find a Resource. These methods are mainly used to map external paths - such
+as path components of request URLs - to Resources. To support creating
+external paths usable in an URL a third method *map(String)* is defined,
+which allows for round-tripping.
+* Absolute or Relative Path Resolution (including search path): The
+*getResource(String path)* and {{getResource(Resource base, String
+path)}} methods may be used to access a resource with an absolute path
+directly. If it can't be found the path is assumed to be relative and the
+search path retrieved from *getSearchPath()* is used to retrieve the
+resource. This mechanism is similar to resolving a programm with the
+*PATH* environment variable in your favourite operating system.
+* Resource Enumeration: To enumerate resources and thus iterate the
+resource tree, the *listChildren(Resource)* method may be used. This
+method returns an *Iterator<Resource>* listing all resources whose path
+prefix is the path of the given Resource. This method will of course also
+cross boundaries of registered *ResourceProvider* instances to enable
+iterating the complete resource tree.
+* Resource Querying: Querying resources is currently only supported for JCR
+Resources through the *findResources(String query, String language)* and
+*queryResources(String query, String language)* methods. For more
+information see the section on [Querying_Resources](#querying_resources.html)
+ below.
+<a name="Resources-AbsolutePathMapping"></a>
+### Absolute Path Mapping
+As has been said, the absolute path mapping methods
+*resolve(HttpServletRequest, String)* and *resolve(String)* apply some
+implementation specific path matching algorithm to find a Resource. The
+difference between the two methods is that the former may take more
+properties of the *HttpServletRequest* into account when resolving the
+Resoure, while the latter just has an absolute path to work on.
+The general algorithm of the two methods is as follows:
+1. Call *HttpServletRequest.getScheme(), .getServerName(), getServerPort* to get an absolute path out of the request URL: \[scheme\](scheme\.html)
+/\[host\].\[port\]\[path\] (*resolve(HttpServletRequest, String)* method
+only, which)
+1. Check whether any virtual path matches the absolute path. If such a match
+exists, the next step is entered with the match.
+1. Apply a list of mappings in order to create a mapped path. The first
+mapped path resolving to a Resource is assumed success and the Resource
+found is returned.
+1. If no mapping created a mapped path addressing an existing Resource, the
+method fails and returns:
+* The *resolve(String)* and *resolve(HttpServletRequest,String)*
+methods return a *NonExistingResource*
+* The *getResource(String path)* and {{getResource(Resource base, String
+path)}} methods return null
+The virtual path mapping may be used to create shortcut URLs for otherwise
+long and complicated URLs. An example of such an URL might be the main
+administrative page of a CMS system. So, administrators may access the root
+of the web application and directed to the main administrative page.
+The path mapping functionality may be used to hide internal resource
+organization from the request URL space. For example to better control the
+structure of your repository, you might decide to store all accessible data
+inside a */content* subtree. To hide this fact from the users, a mapping
+may be defined to prefix all incoming paths with */content* to get at the
+actual Resource.
+The *map(String)* applies the path mapping algorithm in the reverse
+order. That is, first the path mappings are reversed and then any virtual
+mappings are checked. So, a path */content/sample* might be mapped
+*/sample* to revers the */content* prefixing. Or the main
+administrative page - say */system/admin/main.html* \- may be mapped to
+the virtual URL */*.
+<a name="Resources-RelativePathResolution"></a>
+### Relative Path Resolution
+Sometimes it is required to resolve relative paths to Resources. An example
+of such a use case is Script and Servlet resolution which starts with a
+relative path consisting of the Resource type, optional selectors and the
+request extension or method name. By scanning a search path for these
+relative paths a system provided Resource may be overwritten with some user
+defined implementation.
+Consider for example, the system would provide a Servlet to render Resources of type *nt:file*. This Servlet would be registered under the path */libs/nt/file/html*. For a certain web application, this default HTML rendering might not be appropriate, so a Script is created as */apps/nt/file/html.jsp* with a customized HTML rendering. By defining the search path to be _\[_ *_/apps{_}{*}_,_ *_/libs{_*} _\](_-*_/apps{_}{*}_,_-*_/libs{_*}-_\.html)
+_ the Servlet resolver would call the
+*ResourceResolver.getResource(String)* method with the relative path
+*nt/file/html* and be provided with the first matching resource -
+*/apps/nt/file/html.jsp* in this example.
+Of course the search path is not used for absolute path arguments.
+<a name="Resources-QueryingResources"></a>
+### Querying Resources
+For convenience the *ResourceResolver* provides two Resource querying
+methods *findResources* and *queryResources* both methods take as
+arguments a JCR query string and a query language name. These parameters
+match the parameter definition of the {{QueryManager.createQuery(String
+statement, String language)}} method of the JCR API.
+The return value of these two methods differ in the use case:
+* *findResources* returns an *Iteratory<Resource>* of all Resources
+matching the query. This method is comparable to calling *getNodes()* on
+the *QueryResult* returned from executing the JCR query.
+* *queryResources* returns an *Iterator<Map<String, Object>>*. Each
+entry in the iterator is a *Map<String, Object* representing a JCR result
+*Row* in the *RowIterator* returned from executing the JCR query. The
+map is indexed by the column name and the value of each entry is the value
+of the named column as a Java Object.
+These methods are convenience methods to more easily post queries to the
+repository and to handle results in very straight forward way using only
+standard Java functionality.
+Please note, that Resource querying is currently only supported for
+repository based Resources. These query methods are not reflected in the
+*ResourceProvider* interface used to inject non-repository Resources into
+the Resource tree.
+<a name="Resources-ProvidingResources"></a>
+## Providing Resources
+The virtual Resource tree to which the the Resource accessor methods
+*resolve* and *getResource* provide access is implemented by a
+collection of registered *ResourceProvider* instances. The main Resource
+provider is of course the repository based *JcrResourceProvider* which
+supports Node and Property based resources. This Resource provider is
+always available in Sling. Further Resource providers may or may not exist.
+Each Resource provider is registered as an OSGi service with a required
+service registration property *provider.roots*. This is a multi-value
+String property listing the absolute paths Resource tree entries serving as
+roots to provided subtrees. For example, if a Resource provider is
+registered with the service registration property *provider.roots* set to
+_/some/root_, all paths starting with */some/root* are first looked up in
+the given Resource Provider.
+When looking up a Resource in the registered Resource providers, the
+*ResourceResolver* applies a longest prefix matching algorithm to find
+the best match. For example consider three Resource provider registered as
+* JCR Resource provider as */*
+* Resource provider R1 as */some*
+* Resource provider R2 as */some/path*
+When accessing a Resource with path */some/path/resource* the Resource
+provider _R2_ is first asked. If that cannot provide the resource, Resource
+provider _R1_ is asked and finally the JCR Resource provider is asked. The
+first Resource provider having a Resource with the requested path will be
+<a name="Resources-JCR-basedResources"></a>
+### JCR-based Resources
+JCR-based Resources are provided with the default *JcrResourceProvider*.
+This Resource provider is always available and is always asked last. That
+is Resources provided by other Resource providers may never be overruled by
+repository based Resources.
+<a name="Resources-Bundle-basedResources"></a>
+### Bundle-based Resources
+Resources may by provided by OSGi bundles. Providing bundles have a Bundle
+manifest header *Sling-Bundle-Resources* containing a list of absolute
+paths provided by the bundle. The path are separated by comma or whitespace
+The *BundleResourceProvider* supporting bundle-based Resources provides
+directories as Resources of type *nt:folder* and files as Resources of
+type *nt:file*. This matches the default primary node types intended to
+be used for directories and files in JCR repositories. For details see [Bundle Resource.](slingxsite:bundle-resources-(extensions.bundleresource).html)
+<a name="Resources-ServletResources"></a>
+### Servlet Resources
+Servlet Resources are registered by the Servlet Resolver bundle for
+Servlets registered as OSGi services. See [Servlet Resolution](slingxsite:servlets.html)
+ for information on how Servlet Resources are provided.
+<a name="Resources-FileSystemResources"></a>
+### File System Resources
+The Filesystem Resource Provider provides access to the operating system's
+filesystem through the Sling ResourceResolver. Multiple locations may be
+mapped into the resource tree by configuring the filesystem location and
+the resource tree root path for each location to be mapped. For details see [File System Resources](slingxsite:accessing-filesystem-resources-(extensions.fsresource).html)
+<a name="Resources-Wrap/DecorateResources"></a>
+## Wrap/Decorate Resources
+The Sling API provides an easy way to wrap or decorate a resource before
+returning. Details see [Wrap or Decorate Resources](wrap-or-decorate-resources.html)

Added: sling/site/trunk/content/scriptengineintegration.mdtext
--- sling/site/trunk/content/scriptengineintegration.mdtext (added)
+++ sling/site/trunk/content/scriptengineintegration.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,24 @@
+Title: ScriptEngineIntegration
+<a name="ScriptEngineIntegration-IntegratingScriptingLanguages"></a>
+# Integrating Scripting Languages
+This page should be extended with more concrete and detailed information.
+For now, we have the following information:
+   * There will be a talk at ApacheCon US 08 in New Orleans about creating
+JSR-223 ScriptEngineFactory and ScriptEngine implementaitons as well as how
+to integrate such implementations with Sling.
+   * From a mail on the mailing list, this is a very condensed how-to:
+         ** Create the ScriptEngine\[Factory](factory.html)
+ implementations
+	 ** Create a bundle comprising the above implementations as well as
+the script language implementation.
+	 ** Create the
+*META-INF/services/javax.script.ScriptEngineFactory* file listing the
+fully qualified name of your ScriptEngineFactory implementaiton
+<a name="ScriptEngineIntegration-NotesonScriptEngines"></a>
+# Notes on ScriptEngines

Added: sling/site/trunk/content/security.mdtext
--- sling/site/trunk/content/security.mdtext (added)
+++ sling/site/trunk/content/security.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,48 @@
+Title: Security
+<a name="Security-ReportingNewSecurityProblemswithApacheSling"></a>
+# Reporting New Security Problems with Apache Sling
+The Apache Software Foundation takes a very active stance in eliminating
+security problems and denial of service attacks against Apache Sling.
+We strongly encourage folks to report such problems to our private security
+mailing list first, before disclosing them in a public forum.
+*Please note that the security mailing list should only be used for
+reporting undisclosed security vulnerabilities in Apache Sling and managing
+the process of fixing such vulnerabilities. We cannot accept regular bug
+reports or other queries at this address. All mail sent to this address
+that does not relate to an undisclosed security problem in the Apache Sling
+source code will be ignored.*
+If you need to report a bug that isn't an undisclosed security
+vulnerability, please use the bug reporting page.
+Questions about:
+* how to configure Sling securely
+* if a vulnerability applies to your particular application
+* obtaining further information on a published vulnerability
+* availability of patches and/or new releases
+should be addressed to the users mailing list. Please see the [Project Information](project-information.html)
+ page for details of how to subscribe.
+The private security mailing address is: [](
+Note that all networked servers are subject to denial of service attacks,
+and we cannot promise magic workarounds to generic problems (such as a
+client streaming lots of data to your server, or re-requesting the same URL
+repeatedly). In general our philosophy is to avoid any attacks which can
+cause the server to consume resources in a non-linear relationship to the
+size of inputs.
+For more information on handling security issues at the Apache Software
+Foundation please refer to the [ASF Security Team](
+ page.
+<a name="Security-Errorsandomissions"></a>
+# Errors and omissions
+Please report any errors or omissions to [](

View raw message