incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r813971 [5/11] - /websites/staging/sling/trunk/content/
Date Sun, 22 Apr 2012 17:20:13 GMT
Modified: websites/staging/sling/trunk/content/form-based-authenticationhandler.html
==============================================================================
--- websites/staging/sling/trunk/content/form-based-authenticationhandler.html (original)
+++ websites/staging/sling/trunk/content/form-based-authenticationhandler.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,197 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Form Based AuthenticationHandler</h1> -->
+<!-- -->
+<p><a name="FormBasedAuthenticationHandler-FormBasedAuthenticationHandler"></a></p>
+<h1 id="form-based-authenticationhandler">Form Based AuthenticationHandler</h1>
+<p>{toc:type=flat|separator=pipe|minLevel=2|maxLevel=3}</p>
+<p>The Form Based AuthenticationHandler has two authentication phases: The
+first phase is presenting a login form to the user and passing the entered
+user name and password to the server. The second phase is storing
+successful authentication in a Cookie or an HTTP Session.</p>
+<p>The implementation of the Form Based Authentication Handler follows the
+guidelines of the Servlet API 2.4 specification for <em>Form Based
+Authentication</em> in section SRV.12.5.3. Specifically the following
+requirements are implemented:</p>
+<ul>
+<li>For the initial form submission, the request URL must end with
+<em>/j_security_check</em> and the user name and password names must be
+<em>j_username</em> and <em>j_password</em>, resp.</li>
+<li>The authentication type as returned by
+<em>HttpServletRequest.getAuthType()</em> is set to
+<em>HttpServletRequest.FORM_AUTH</em>.</li>
+</ul>
+<p>The Form Based Authentication Handler is maintained in the <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/form">Sling SVN</a></p>
+<p><a name="FormBasedAuthenticationHandler-AuthenticationHandlerimplementation"></a></p>
+<h3 id="authenticationhandler-implementation">AuthenticationHandler implementation</h3>
+<ul>
+<li><em>extractCredentials</em> -- Prepares credentials for the form entered data
+or from the Cookie or HTTP Session attribute. Returns <em>null</em> if neither
+data is provided in the request</li>
+<li><em>requestCredentials</em> -- Redirects the client (browser) to the login
+form</li>
+<li><em>dropCredentials</em> -- Remove the Cookie or remove the HTTP Session
+attribute</li>
+</ul>
+<p><a name="FormBasedAuthenticationHandler-AuthenticationFeedbackHandlerimplementation"></a></p>
+<h3 id="authenticationfeedbackhandler-implementation">AuthenticationFeedbackHandler implementation</h3>
+<ul>
+<li><em>authenticationFailed</em> -- Remove the Cookie or remove the HTTP Session
+attribute</li>
+<li><em>authenticationSucceeded</em> -- Set (or update) the Cookie or HTTP Session
+attribute</li>
+</ul>
+<p><a name="FormBasedAuthenticationHandler-Phase1:FormSubmission"></a></p>
+<h3 id="phase-1-form-submission">Phase 1: Form Submission</h3>
+<p>The login form submitted in phase 1 to validate the user name and password
+must be provided in an HTTP <em>POST</em> request to an URL whose last segment
+is <em>j_security_check</em>. The request is ignored as a form submission if
+either the method is not <em>POST</em> or the last segment is no
+<em>j_security_check</em>.</p>
+<p>The form is rendered by redirecting the client to the URL indicated by the
+<em>form.login.form</em> configuration parameter. This redirection request may
+accompanyied by the following parameters:</p>
+<ul>
+<li><em>resource</em> -- The resource to which the user should be redirected after
+successful login. This request parameter should be submitted back to the
+server as the <em>resource</em> parameter.</li>
+<li><em>j_reason</em> -- This parameter indicates the reason for rendering the
+login form. If this parameter is set, it is set to <em>INVALID_CREDENTIALS</em>
+indicating a previous form submission presented invalid username and
+password or <em>TIMEOUT</em> indicating a login session has timed out. The login
+form servlet/script can present the user with an appropriate message.</li>
+</ul>
+<p>The Form Based Authentication Handlers supports the following request
+parameters submitted by the HTML form:</p>
+<ul>
+<li><em>j_username</em> -- Name of the user to authenticate</li>
+<li><em>j_password</em> -- Password to authenticate the user</li>
+<li><em>j_validate</em> -- Flag indicating whether to just validate the
+credentials</li>
+<li><em>resource</em> -- The location to go to on successful login</li>
+<li><em>sling.auth.redirect</em> -- The location to redirect to on successful
+login</li>
+</ul>
+<p>The <em>j_username</em> and <em>j_password</em> parameters are used to create a JCR
+<em>SimpleCredentials</em> object to log into the JCR Repository.</p>
+<p>The <em>j_validate</em> parameter may be used to implement login form submission
+using AJAX. If this parameter is set to <em>true</em> (case-insensitive) the
+credentials are used to login and after success or failure to return a
+status code:</p>
+<table>
+<tr><th> Status </th><th> Description </th></tr>
+<tr><td> *200 OK* </td><td> Authentication succeeded; credentials are valid for login;
+the Cookie or HTTP Session attribute is now set </td></tr>
+<tr><td> *403 FORBIDDEN* </td><td> Authentication failed; credentials are invalid for
+login; the Cookie or HTTP Session attribute is not set (if it was set, it
+is now cleared) </td></tr>
+</table>
 
+<p>If the <em>j_validate</em> parameter is not set or is set to any value other
+than <em>true</em>, the request processing depends on authentication success or
+failure:</p>
+<table>
+<tr><th> Authentication </th><th> Description </th></tr>
+<tr><td> Success </td><td> Client is redirected to the authenticated resource; the Cookie
+or HTTP Session attribute is now set. </td></tr>
+<tr><td> Failure </td><td> The request is redirected to the login form again; the Cookie
+or HTTP Session attribute is not set (if it was set, it is now cleared) </td></tr>
+</table>
+
+<p>The <em>resource</em> and <em>sling.auth.redirect</em> parameters provide similar
+functionality but with differing historical backgrounds. The <em>resource</em>
+parameter is based on the <em>resource</em> request attribute which is set by
+the login servlet to indicate the original target resource the client
+desired when it was forced to authenticate. The <em>sling.auth.redirect</em>
+parameter can be used by clients (applications like cURL or plain HTML
+forms) to request being redirected after successful login. If both
+parameters are set, the <em>sling.auth.redirect</em> parameter takes precedence.</p>
+<p>The Form Based Authentication Handler contains a <a href="http://http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/form/src/main/java/org/apache/sling/auth/form/impl/AuthenticationFormServlet.java">default form servlet</a>
+ and [HTML form template from|http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/form/src/main/resources/org/apache/sling/auth/form/impl/login.html]
+.</p>
+<p><a name="FormBasedAuthenticationHandler-Phase2:AuthenticatedRequests"></a></p>
+<h3 id="phase-2-authenticated-requests">Phase 2: Authenticated Requests</h3>
+<p>After the successful authentication of the user in phase 1, the
+authentication state is stored in a Cookie or an HTTP Session. The stored
+value is a security token with the following contents:</p>
+<div class="codehilite"><pre><span class="n">HmacSHA1</span><span class="p">(</span><span class="n">securetoken</span><span class="p">,</span>
+</pre></div>
+
+
+<p><securetokennumber><expirytime>@<userID>)@<securetokennumber><expirytime>@<userID></p>
+<p>The <em>securetoken</em> and <em>securetokennumber</em> are related in that an table
+of secure tokens is maintained where the <em>securetoken</em> is an entry in the
+table and the <em>securetokennumber</em> is the index in of the token in the
+table.</p>
+<p>The secure tokens are refreshed periodically causing the authentication
+state stored in the Cookie or the HTTP Session to be updated peridocally.
+This periodic update has two advantages:</p>
+<ul>
+<li>Login sessions time out after some period of inactivity: If a request
+is handled for an authentication state whose expiry time has passed, the
+request is considered unauthenticated.</li>
+<li>If a Cookie would be stolen or an HTTP Session be hijacked, the
+authentication state expires within a reasonable amount of time to try to
+prevent stealing the authentication.</li>
+</ul>
+<p>The authentication state may be transmitted with a Cookie which is
+configured as follows:</p>
+<ul>
+<li><em>Cookie Path</em> -- Set to the servlet context path</li>
+<li><em>Domain</em> -- See below</li>
+<li><em>Age</em> -- Set to -1 to indicate a session Cookie</li>
+<li><em>Secure</em> -- Set to the value returned by the
+<em>ServletRequest.isSecure()</em> method</li>
+</ul>
+<p>If the authentication state is kept in an HTTP Session the setup of the
+session ID cookie is maintained by the servlet container and is outside of
+the control of the Form Based AuthenticationHandler.</p>
+<p><a name="FormBasedAuthenticationHandler-Configuration"></a></p>
+<h3 id="configuration">Configuration</h3>
+<p>The Form Based Authentication Handler is configured with configuration
+provided by the OSGi Configuration Admin Service using the
+<em>org.apache.sling.formauth.FormAuthenticationHandler</em> service PID.</p>
+<table>
+<tr><th> Parameter </th><th> Default </th><th> Description </th></tr>
+<tr><td> *form.login.form* </td><td> */system/sling/form/login* </td><td> The URL (without any
+context path prefix) to redirect the client to to present the login form. </td></tr>
+<tr><td> *form.auth.storage* </td><td> *cookie* </td><td> The type of storage used to provide
+the authentication state. Valid values are *cookie* and *session*. The
+default value also applies if any setting other than the supported values
+is configured. </td></tr>
+<tr><td> *form.auth.name* </td><td> *sling.formauth* </td><td> The name of the Cookie or HTTP
+Session attribute providing the authentication state. </td></tr>
+<tr><td> *form.auth.timeout* </td><td> *30* </td><td>The number of minutes after which a login
+session times out. This value is used as the expiry time set in the
+authentication data. </td></tr>
+<tr><td> *form.credentials.name* </td><td> *sling.formauth* </td><td> The name of the
+*SimpleCredentials* attribute used to provide the authentication data to
+the *LoginModulePlugin*. </td></tr>
+<tr><td> *form.token.file* </td><td> *cookie-tokens.bin* </td><td> The name of the file used
+to persist the security tokens. </td></tr>
+<tr><td> *form.default.cookie.domain* </td><td> </td><td> The domain on which cookies will be
+set, unless overridden in the *AuthenticationInfo* object. </td></tr>
+</table>
+
+<p><em>Note:</em> The <em>form.token.file</em> parameter currently refers to a file stored
+in the file system. If the path is a relative path, the file is either
+stored in the Authentication Handler bundle private data area or -- if not
+possible -- below the location indicated by the <em>sling.home</em> framework
+property or -- if <em>sling.home</em> is not set -- the current working
+directory. In the future this file may be store in the JCR Repository to
+support clustering scenarios.</p>
+<p><a name="FormBasedAuthenticationHandler-SecurityConsiderations"></a></p>
+<h3 id="security-considerations">Security Considerations</h3>
+<p>Form Based Authentication has some limitations in terms of security:</p>
+<ol>
+<li>User name and password are transmitted in plain text in the initial form
+submission.</li>
+<li>The Cookie used to provide the authentication state or the HTTP Session
+ID may be stolen.</li>
+</ol>
+<p>To prevent eavesdroppers from sniffing the credentials or stealing the
+Cookie a secure transport layer should be used such as TLS/SSL, VPN or
+IPSec.</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/getting-and-building-sling.html
==============================================================================
--- websites/staging/sling/trunk/content/getting-and-building-sling.html (original)
+++ websites/staging/sling/trunk/content/getting-and-building-sling.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,284 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Getting and Building Sling</h1> -->
+<!-- -->
+<p><a name="GettingandBuildingSling-GettingandBuildingSling"></a></p>
+<h1 id="getting-and-building-sling">Getting and Building Sling</h1>
+<p>{excerpt}A quick guide for getting the Sling source, then building and
+running the resulting Sling instance; either without or with
+Eclipse.{excerpt}</p>
+<p>Sling can easily be built:
+<em> from the command line (using SVN and the Maven command line tool)
+</em> or using Eclipse</p>
+<p>Note that you don't <em>have</em> to build Sling yourself, if you don't need the
+bleeding-edge stuff you can get prebuilt binaries from the <a href="downloads.html">Downloads</a>
+ page.</p>
+<p>A full build of Sling takes 5-10 minutes on a recent computer once your
+local Maven repository is up to date. The first build may take much longer
+than that if you start with an empty local Maven repository, as Maven will
+then download its plugins and all the required dependencies.</p>
+<p><a name="GettingandBuildingSling-Prerequisites"></a></p>
+<h2 id="prerequisites">Prerequisites</h2>
+<p>Before you begin, you need to have the following tools installed on your
+system:
+<em> Java 5 or higher; Java 6 recommended
+</em> <a href="http://maven.apache.org">Maven</a>
+ 3.0.2 or later; enforced by the Sling parent pom</p>
+<p>If you want to set up Eclipse (not required to build Sling) you'll also
+need the following installed:
+<em> Eclipse (tested with 3.4.2 and 3.5.x on Win XP, SP3, 3.6.x on Win7, 3.7
+on MacOS X 10.6); just a plain installation of the platform runtime binary
+and the JDT will be adequate (you can install the IDE for Java Developers
+for convenience) 
+</em> M2Eclipse plugin for Eclipse (sonatype) -&gt; <a href="http://m2eclipse.sonatype.org/installing-m2eclipse.html">instructions</a>
+* <a href="http://www.polarion.com/products/svn/subversive.php">Subversive plugin</a>
+ or [Subclipse-plugin|http://subclipse.tigris.org]
+ for Eclipse</p>
+<p><a name="GettingandBuildingSling-EnvironmentSetup"></a></p>
+<h2 id="environment-setup">Environment Setup</h2>
+<p>The full build process requires quite a lot of resources, so you may run
+into limits. The following hints should show you what to setup before
+building Sling.</p>
+<p><a name="GettingandBuildingSling-JavaHeapSpace"></a></p>
+<h3 id="java-heap-space">Java Heap Space</h3>
+<ul>
+<li><em>Problem</em> - Build aborts with reports of {{java.lang.OutOfMemoryError:
+Java heap space}}. Alternatively the build may randomly fail during the
+integration tests.</li>
+<li><em>Platforms</em> - This happens on all platforms</li>
+<li><em>Fix</em> - Increase the values of the maximum heap and perm space for the
+build by setting or extending the <em>MAVEN_OPTS</em> environment variable.</li>
+</ul>
+<p>For 32bit platforms you should use</p>
+<div class="codehilite"><pre><span class="n">MAVEN_OPTS</span><span class="o">=</span><span class="s">&quot;-Xmx256M -XX:MaxPermSize=256m&quot;</span>
+</pre></div>
 
+
+<p>For 64bit platforms, you should use</p>
+<div class="codehilite"><pre><span class="n">MAVEN_OPTS</span><span class="o">=</span><span class="s">&quot;-Xmx512M -XX:MaxPermSize=512m&quot;</span>
+</pre></div>
+
+
+<p>For more information see <a href="https://issues.apache.org/jira/browse/SLING-443">SLING-443</a>
+ and [SLING-1782|https://issues.apache.org/jira/browse/SLING-1782]
+.</p>
+<p><a name="GettingandBuildingSling-EnvironmentVariableSpace"></a></p>
+<h3 id="environment-variable-space">Environment Variable Space</h3>
+<ul>
+<li>
+<p><em>Problem</em> - Build aborts when trying to launch the integration tests
+with the message</p>
+<p>[INFO]
+ Error while executing forked tests.; nested exception is
+org.apache.maven.surefire.booter.shade.org.codehaus.plexus.util.cli.CommandLineException:
+Error setting up environmental variables</p>
+<p>error=12, Not enough space</p>
+</li>
+</ul>
+<p>This problem is caused by insufficient swap space. When running the
+integration tests in the <em>launchpad/testing</em> modules, a process is
+launched by calling the <em>exec</em> system call. This copies the process
+(copy-on-write, though) and thus allocates as much virtual memory as is
+owned by the parent process. This may fail if swap space is exhausted.
+<em> </em>Platform<em> - OpenSolaris
+</em> <em>Fix</em> - If this issue persists you will need to check your system
+requirements and configuration with regard to swap, before taking action -
+if necessary.</p>
+<p><a name="GettingandBuildingSling-ConfiguringMaven"></a></p>
+<h2 id="configuring-maven">Configuring Maven</h2>
+<p>See <a href="maventipsandtricks.html">MavenTipsAndTricks</a>
+.</p>
+<p><a name="GettingandBuildingSling-GettingtheSlingSource"></a></p>
+<h2 id="getting-the-sling-source">Getting the Sling Source</h2>
+<p><a name="GettingandBuildingSling-WithSVN"></a></p>
+<h3 id="with-svn">With SVN</h3>
+<ol>
+<li>
+<p>Checkout Sling from the Repository.</p>
+<p>$ svn checkout http://svn.apache.org/repos/asf/sling/trunk sling</p>
+</li>
+</ol>
+<p><a name="GettingandBuildingSling-WithEclipseSubversiveorSubclipse"></a></p>
+<h3 id="with-eclipse-subversive-or-subclipse">With Eclipse Subversive or Subclipse</h3>
+<p>First note how simple the above SVN instructions are...but if you <em>really</em>
+want to do this, read on.</p>
+<p>If you use the Subversive plugin make sure you have installed the
+"Subversive Integration for M2Eclipse Project" which can be found under the
+following Eclipse update site: <a href="http://community.polarion.com/projects/subversive/download/integrations/update-site/">http://community.polarion.com/projects/subversive/download/integrations/update-site/</a>
+.</p>
+<p>Also, make sure that you have installed either the "Maven SCM handler for
+Subclipse" or the "Maven SCM handler for Subversive".</p>
+<p><a name="GettingandBuildingSling-Createanewworkspace"></a></p>
+<h4 id="create-a-new-workspace">Create a new workspace</h4>
+<p>It's best to create a new workspace for the sling project:
+1. Menu: File-&gt;Switch Workspace-&gt;Other...
+1. Enter a path for the new workspace and click OK
+1. When Eclipse has restarted it's time to adjust some configs
+1. Turn off automatic build (Menu: Project-&gt;Build Automatically)
+1. Go to menu: Eclipse-&gt;Preferences, in the preferences dialog select Java
+-&gt; Compiler -&gt; Errors/Warnings
+1. Expand the "Deprecated and restricted API" and change "Forbidden
+references (access rules)" from "Error" to "Warning"
+1. Click OK</p>
+<p><a name="GettingandBuildingSling-CheckouttheSlingsource"></a></p>
+<h4 id="checkout-the-sling-source">Checkout the Sling source</h4>
+<ol>
+<li>Menu: File-&gt;Import</li>
+<li>In the Import wizard select Maven-&gt;"Check out Maven Projects from SCM"</li>
+<li>Click next</li>
+<li>In the "SCM URL" field pick "SVN" and enter the url
+"http://svn.apache.org/repos/asf/sling/trunk"</li>
+<li>Click Finish</li>
+</ol>
+<p>Eclipse will now start to download the source and import the Maven
+projects. You might encounter some "Problem Occured" dialogs about "An
+internal error...", but just click OK on those and let Eclipse continue
+with the import. Be warned: This could take some time (it was 30 minutes on
+my laptop)!</p>
+<p>Possibly something in sling-builder might get a bit messed up (I didn't
+experience that problem, but Pontus reported it) then you can simply fix it
+with revert:
+1. In the Project Explorer right-click on the "sling-builder" project and
+select the Team-&gt;Revert... menu
+1. A couple of changes will be displayed
+1. Click OK</p>
+<p><a name="GettingandBuildingSling-BuildingSling"></a></p>
+<h2 id="building-sling">Building Sling</h2>
+<p><a name="GettingandBuildingSling-WiththeMavencommandlinetool"></a></p>
+<h3 id="with-the-maven-command-line-tool">With the Maven command line tool</h3>
+<ol>
+<li>
+<p>Enter the directory, then do a full build and local install (below are
+unix/linux commands, slightly different under windows)</p>
+<p>$ cd sling
+$ export MAVEN_OPTS="-Xmx256m -XX:MaxPermSize=128m"
+$ mvn -s /dev/null clean install</p>
+</li>
+</ol>
+<p>Note: On windows just leave out <em>/dev/null</em> and make sure you have an
+empty settings.xml file for maven (located in your user directory under
+.m2).
+1. Enter the <em>launchpad/builder</em> directory and launch Sling for the first
+time</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">cd</span> <span class="n">launchpad</span><span class="o">/</span><span class="n">builder</span>
+<span class="nv">$</span> <span class="nv">java</span> <span class="o">-</span><span class="n">jar</span> <span class="n">target</span><span class="o">/</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="n">standalone</span><span class="o">.</span><span class="n">jar</span> <span class="o">-</span><span class="n">c</span> <span class="n">test</span> <span class="o">-</span><span class="n">f</span> <span class="o">-</span>
+</pre></div>
+
+
+<p>{note}
+When starting Sling inside the <em>launchpad/builder</em> folder you should not
+use the default Sling Home folder name <em>sling</em> because this folder is
+removed when running <em>mvn clean</em>.
+{note}</p>
+<p>Messages should now be printed to the console which is being used as the
+"log file"; the <em>-f</em> command line option is set to <em>-</em>, indicating
+the use of standard output as the log file. The <em>-c sling</em> command line
+option instructs Sling to use the <em>sling</em> directory in the current
+directory for its data store, which is the Apache Felix bundle archive, the
+Jackrabbit repository data and configuration. You may also specify another
+directory here, either a relative or absolute path name (See also <a href="configuration.html">Configuration</a>
+ for more information). 
+Use the <em>-h</em> option to see the list of flags and options.
+After all messages have been printed you should be able to open the Sling Management Console by pointing your web browser at {{<a href="http://localhost:8080/system/console">http://localhost:8080/system/console</a>
+}}. You will be prompted for a user name and password. Enter <em>admin</em> for
+both the user name and the password (this may be set on the <em>Configuration</em>
+page later). From this console, you can manage the installed bundles,
+modify configuration objects, dump a configuration status and see some
+system information.
+To stop Sling, just hit <em>Ctrl-C</em> in the console or click the <em>Stop</em>
+button on the <em>System Information</em> page of the Sling Management Console.</p>
+<p><a name="GettingandBuildingSling-WithM2Eclipse"></a></p>
+<h3 id="with-m2eclipse">With M2Eclipse</h3>
+<ol>
+<li>Make sure you're in the Java perspective (Menu: Window-&gt;Open Perspective)</li>
+<li>Menu: Run-&gt;Run Configurations...</li>
+<li>In the Run Configurationa dialog right-click on "Maven Build" and select
+"New"</li>
+<li>Change Name to "Build Sling"</li>
+<li>Click "Browse Workspace..." and select "sling-builder"</li>
+<li>Enter "clean install" in Goals</li>
+<li>Click on the JRE tab</li>
+<li>Enter "-Xmx256m -XX:MaxPermSize=128m" in "VM arguments"</li>
+<li>Click Apply</li>
+<li>Click Run</li>
+</ol>
+<p><a name="GettingandBuildingSling-AlternativesetupinEclipsewithoutM2Eclipseplugin"></a></p>
+<h3 id="alternative-setup-in-eclipse-without-m2eclipse-plugin">Alternative setup in Eclipse without M2Eclipse plugin</h3>
+<p>In the case that you do not want to use the M2Eclipse plugin there's
+another setup that lets you have the automatic build turned on:
+1. Checkout the whole sling trunk (with subversive or the subclipse plugin)
+from SVN to a single project
+1. Then manually add all <em>src/main/java</em> and <em>src/test/java</em> of the
+bundles to the project as source folders
+1. Add all required libraries to the build path
+1. Now you can build either in Eclipse or even better use "mvn clean
+install" on the command line</p>
+<p>If you use "mvn clean install" to build Sling be sure you have set
+MAVEN_OPTS to "-Xmx384m -XX:PermSize=256m" otherwise you will probably get
+OutOfmemory errors.</p>
+<p>Congratulations ! You should now have a running Sling instance, that you
+can start playing around with.</p>
+<p><a name="GettingandBuildingSling-FurtherTipsandTricks"></a></p>
+<h2 id="further-tips-and-tricks">Further Tips and Tricks</h2>
+<p><a name="GettingandBuildingSling-DebugSlinginEclipse"></a></p>
+<h3 id="debug-sling-in-eclipse">Debug Sling in Eclipse</h3>
+<p>You can use remote debugging to debug Sling in Eclipse, here's a little
+How-To
+1. start Sling from the command line with</p>
+<div class="codehilite"><pre><span class="n">java</span> <span class="o">-</span><span class="n">Xmx384M</span>
+</pre></div>
+
+
+<p>-agentlib:jdwp=transport=dt_socket,address=30303,server=y,suspend=n -jar
+org.apache.sling.launchpad.app-6-SNAPSHOT.jar</p>
+<ol>
+<li>Open Menu Run-&gt; Debug configurations</li>
+<li>Right-click on "Remote Java Applications"</li>
+<li>Choose "New"</li>
+<li>In the "Connect" tab choose the Eclipse Sling Project for the field
+"Project" with the browse button</li>
+<li>Let the Connection type be "Standard (Socket Attach)"</li>
+<li>The host should be localhost</li>
+<li>Set the Port to 30303</li>
+<li>On the source tab click the "Add" button</li>
+<li>Select "Java Project"</li>
+<li>Select all Sling projects and click OK</li>
+<li>Click "Debug"</li>
+</ol>
+<p>Now you should be able to set breakpoints, evaluate properties, and so on
+as usual.</p>
+<p><a name="GettingandBuildingSling-DebugMavenTestsinEclipse"></a></p>
+<h3 id="debug-maven-tests-in-eclipse">Debug Maven Tests in Eclipse</h3>
+<p>In the same way as you can debug the sling app, you are also able to debug
+a maven test. Just run the maven tests like this</p>
+<div class="codehilite"><pre><span class="n">mvn</span> <span class="o">-</span><span class="n">Dmaven</span><span class="o">.</span><span class="n">surefire</span><span class="o">.</span><span class="n">debug</span> <span class="n">test</span>
+</pre></div>
+
+
+<p>The tests will automatically pause and await a remote debugger on port
+5005. You can then attach to the running tests using Eclipse. You can setup
+a "Remote Java Application" launch configuration via the menu command "Run"</p>
+<blockquote>
+<p>"Open Debug Dialog..." (see above).
+For more information on this see the <a href="http://maven.apache.org/plugins/maven-surefire-plugin/examples/debugging.html">Maven Surefire Docu</a>
+.</p>
+</blockquote>
+<p><a name="GettingandBuildingSling-SimplewaytodevelopnewbundleinEclipseforSling"></a></p>
+<h3 id="simple-way-to-develop-new-bundle-in-eclipse-for-sling">Simple way to develop new bundle in Eclipse for Sling</h3>
+<p>The easiest way that I found is to create a new folder in the existing
+Eclipse workspace. After that you can follow these steps:
+<em> Start by copying and adapting an existing Sling pom.xml (eg. the pom.xml
+from the espblog sample)
+</em> Generate the Eclipse project files using mvn eclipse:eclipse
+<em> Choose File/Import in Eclipse and select "Existing projects into
+workspace"
+</em> Now you can create, edit and compile the files in Eclipse
+<em> To create the bundle jar and install it, just use the command line "mvn
+clean install" in the project directory
+</em> If you have a running Sling app you can install the bundle from the command line with "mvn -P autoInstallBundle clean install -Dsling.url=<a href="http://localhost:8080/system/console">http://localhost:8080/system/console</a>
+"</p>
+<p>If adding dependencies to the poms, run mvn eclipse:eclipse again and
+refresh the project in Eclipse. Debugging works as described above.</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/getting-resources-and-properties-in-sling.html
==============================================================================
--- websites/staging/sling/trunk/content/getting-resources-and-properties-in-sling.html (original)
+++ websites/staging/sling/trunk/content/getting-resources-and-properties-in-sling.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,108 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Getting Resources and Properties in Sling</h1> -->
+<!-- -->
+<p><a name="GettingResourcesandPropertiesinSling-GettingResourcesandPropertiesinSling"></a></p>
+<h1 id="getting-resources-and-properties-in-sling">Getting Resources and Properties in Sling</h1>
+<p>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 paradigm of the REST
+architecture.</p>
+<p>In this article we will explore a few ways to programmatically map a
+resource path (String) to a resource object (Resource) and its properties
+in Sling, from within an OSGI service, a servlet and a JSP.</p>
+<p>The whole game consists in first getting a <em>ResourceResolver</em> and then
+getting the <em>Resource</em> itself.</p>
+<p><a name="GettingResourcesandPropertiesinSling-WithinanOSGIService/Compoment"></a></p>
+<h2 id="within-an-osgi-servicecompoment">Within an OSGI Service/Compoment</h2>
+<p>You can access a resource through the <em>ResourceResolverFactory</em> service:</p>
+<div class="codehilite"><pre><span class="sr">/** @scr.reference */</span>
+<span class="n">private</span> <span class="n">ResourceResolverFactory</span> <span class="n">resolverFactory</span><span class="p">;</span>
 
+<span class="n">public</span> <span class="n">void</span> <span class="n">myMethod</span><span class="p">()</span> <span class="p">{</span>
+    <span class="n">try</span> <span class="p">{</span>
+    <span class="n">String</span> <span class="n">resourcePath</span> <span class="o">=</span> <span class="s">&quot;path/to/resource&quot;</span><span class="p">;</span>
+    <span class="n">ResourceResolver</span> <span class="n">resourceResolver</span> <span class="o">=</span>
+</pre></div>
+
+
+<p>resolverFactory.getAdministrativeResourceResolver(null);
+        Resource res = resourceResolver.getResource(resourcePath);
+        // do something with the resource
+        // when done, close the ResourceResolver
+        resourceResolver.close();
+        } catch (LoginException e) {
+        // log the error
+        }
+    }</p>
+<p><a name="GettingResourcesandPropertiesinSling-WithinaServlet"></a></p>
+<h2 id="within-a-servlet">Within a Servlet</h2>
+<p>You can access the resource defined by the request URL through the
+<em>SlingHttpServletRequest</em>:</p>
+<div class="codehilite"><pre><span class="n">Resource</span> <span class="n">res</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">getResource</span><span class="p">();</span>
+<span class="sr">//</span> <span class="n">req</span> <span class="n">is</span> <span class="n">the</span> <span class="n">SlingHttpServletRequest</span>
+</pre></div>
+
+
+<p>You can access any resource by first accessing the <em>ResourceResolver</em>:</p>
+<div class="codehilite"><pre><span class="n">String</span> <span class="n">resourcePath</span> <span class="o">=</span> <span class="s">&quot;path/to/resource&quot;</span><span class="p">;</span>
+<span class="n">ResourceResolver</span> <span class="n">resourceResolver</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">getResourceResolver</span><span class="p">();</span>
+<span class="sr">//</span> <span class="n">req</span> <span class="n">is</span> <span class="n">the</span> <span class="n">SlingHttpServletRequest</span>
+<span class="n">Resource</span> <span class="n">res</span> <span class="o">=</span> <span class="n">resourceResolver</span><span class="o">.</span><span class="n">getResource</span><span class="p">(</span><span class="n">resourcePath</span><span class="p">);</span>
+</pre></div>
+
+
+<p><a name="GettingResourcesandPropertiesinSling-WithinaJSPfile"></a></p>
+<h2 id="within-a-jsp-file">Within a JSP file</h2>
+<p>When you use the <em><sling:defineObjects></em> tag in a JSP file, you have
+access to a few handy objects, one of them is <em>resource</em>, the resource
+that is resolved from the URL. Another one is <em>resourceResolver</em>, the
+<em>ResourceResolver</em> defined through the <em>SlingHttpServletRequest</em>. </p>
+<p>To access a resource:</p>
+<div class="codehilite"><pre><span class="x">&lt;sling:defineObjects&gt;</span>
+<span class="cp">&lt;%</span>
+<span class="nb">String</span> <span class="n">resourcePath</span> <span class="o">=</span> <span class="s2">&quot;path/to/resource&quot;</span><span class="p">;</span>
+<span class="no">Resource</span> <span class="n">res</span> <span class="o">=</span> <span class="n">resourceResolver</span><span class="o">.</span><span class="n">getResource</span><span class="p">(</span><span class="n">resourcePath</span><span class="p">);</span>
+<span class="cp">%&gt;</span><span class="x"></span>
+</pre></div>
+
+
+<p>If needed you can adapt a Sling Resource to a JCR Node:</p>
+<div class="codehilite"><pre><span class="n">Node</span> <span class="n">node</span> <span class="o">=</span> <span class="n">resource</span><span class="o">.</span><span class="n">adaptTo</span><span class="p">(</span><span class="n">Node</span><span class="o">.</span><span class="n">class</span><span class="p">);</span>
+</pre></div>
+
+
+<p>Note: <em>resource.adaptTo(Node.class)</em> may return null if the resource is
+not backed by a JCR node. This is particularly the case for
+<em>NonExistingResource</em> resources or resource provided by a non-JCR
+resource provider.</p>
+<p><a name="GettingResourcesandPropertiesinSling-AccessingaProperty"></a></p>
+<h2 id="accessing-a-property">Accessing a Property</h2>
+<p>The <em>ValueMap</em> is an easy way to access properties of a resource. With
+most resources you can use <em>Adaptable.adaptTo(Class)</em> to adapt the
+resource to a value map:</p>
+<div class="codehilite"><pre><span class="n">ValueMap</span> <span class="n">properties</span> <span class="o">=</span> <span class="n">res</span><span class="o">.</span><span class="n">adaptTo</span><span class="p">(</span><span class="n">ValueMap</span><span class="o">.</span><span class="n">class</span><span class="p">);</span>
+<span class="sr">//</span> <span class="n">res</span> <span class="n">is</span> <span class="n">the</span> <span class="n">Resource</span>
+</pre></div>
+
+
+<p>You can also access the properties through the <em>ResourceUtil</em> utility
+class:</p>
+<div class="codehilite"><pre><span class="n">ValueMap</span> <span class="n">properties</span> <span class="o">=</span> <span class="n">ResourceUtil</span><span class="o">.</span><span class="n">getValueMap</span><span class="p">(</span><span class="n">res</span><span class="p">);</span>
+<span class="sr">//</span> <span class="n">res</span> <span class="n">is</span> <span class="n">the</span> <span class="n">Resource</span>
+</pre></div>
+
+
+<p>Then, to access a specific String property called <em>propName</em>:</p>
+<div class="codehilite"><pre><span class="n">String</span> <span class="n">rule</span> <span class="o">=</span> <span class="n">properties</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">propName</span><span class="p">,</span> <span class="p">(</span><span class="n">String</span><span class="p">)</span> <span class="n">null</span><span class="p">);</span>
+</pre></div>
+
+
+<p>For more details about resources and how to access them in Sling, you can
+refer to the <a href="http://sling.apache.org/site/resources.html">Sling documentation about Resources</a>
+.</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/getting-started.html
==============================================================================
--- websites/staging/sling/trunk/content/getting-started.html (original)
+++ websites/staging/sling/trunk/content/getting-started.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,29 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Getting Started</h1> -->
-
+<!-- -->
+<p><a name="GettingStarted-GettingStarted"></a></p>
+<h1 id="getting-started">Getting Started</h1>
+<p>We're on the way to update the documentation to make it more easy to get in
+touch with Sling. At the moment we can give you the following starting
+points:</p>
+<p>{children:all=true}</p>
+<p><a name="GettingStarted-Wheretoheadfromhere"></a></p>
+<h2 id="where-to-head-from-here">Where to head from here</h2>
+<p>We recommend you read through following topics to get as fast as possible
+into Sling: </p>
+<p>{show-to}
+<em> What is Sling
+{show-to}
+</em> <a href="getting-and-building-sling.html">Getting and building Sling</a>
+<em> <a href="architecture.html">Architecture</a>
+</em> <a href="dispatching-requests.html">Dispatching Requests</a>
+<em> <a href="resources.html">Resources</a>
+</em> <a href="http://cwiki.apache.org/SLING/setting-up-eclipse-34-for-sling.html">Setting up an Sling-Project with Eclipse</a>
+<em> <a href="manipulating-content---the-slingpostservlet-(servlets.post).html">Manipulating Content - The SlingPostServlet (servlets.post)</a>
+</em> <a href="request-parameters.html">Request Parameters</a>
+<em> <a href="authentication.html">Authentication</a>
+</em> <a href="eventing-and-jobs.html">Eventing and Jobs</a></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/groovy-support.html
==============================================================================
--- websites/staging/sling/trunk/content/groovy-support.html (original)
+++ websites/staging/sling/trunk/content/groovy-support.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,88 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Groovy Support</h1> -->
+<!-- -->
+<p>{excerpt:hidden=true}
+Explains how to add support for Groovy to Apache Sling.
+{excerpt}</p>
+<p>After meeting Paul King of the Groovy Team at Apache Con US 08 in New
+Orleans, I set out to take a stab at SLING-315 again to add Groovy support
+to Sling. It turned out, that the current Groovy 1.6 branch already
+contains the required setup to build the <em>groovy-all.jar</em> as an OSGi
+Bundle, which is directly usable with Sling by just installing that bundle.</p>
+<p>Currently the Groovy team is working hard towards the 1.6 release and many
+things are in flux, which is really great.</p>
+<p>So, on 11. Dec. 2008 Paul King of the Groovy Team has deployed a <a href="http://snapshots.repository.codehaus.org/org/codehaus/groovy/groovy-all/1.6-RC-1-SNAPSHOT/groovy-all-1.6-RC-1-20081211.113737-1.jar">first RC1 Snapshot of Groovy 1.6</a>
+ which contains all the required OSGi bundle manifest headers as well das
+the JSR-233 <em>ScriptEngine</em> to use the <em>groovy-all.jar</em> unmodified with
+Sling. So just go ahead, grab the Groovy-All 1.6 RC 1 SNAPSHOT deploy it
+into your Sling instance and enjoy the fun of Groovy.</p>
+<p>If you want to be on verge of development, you might want to go for Groovy 1.7: The second SNAPSHOT of beta-1 also contains the required headers and classes and may as well be used unmodified in Sling. You may download it here: {{<a href="http://snapshots.repository.codehaus.org/org/codehaus/groovy/groovy-all/1.7-beta-1-SNAPSHOT/groovy-all-1.7-beta-1-20081210.120632-2.jar">groovy-all-1.7-beta-1-20081210.120632-2.jar</a>
+}}.</p>
+<p>To deploy the bundle go to the Bundles page, for example at
+http://localhost:8888/system/console/bundles of the Apache Felix Web
+Console select the bundle file to upload, check the <em>Start</em> check box and
+click <em>Install or Update</em> button.</p>
+<p>You may check, whether the Groovy ScriptEngine has been "accepted" by
+Sling, by going to the Script Engines page of the Apache Felix Web Console.
+You should see the entry for Groovy there, somthing like this:</p>
+<div class="codehilite"><pre><span class="n">Groovy</span> <span class="n">Scripting</span> <span class="n">Engine</span><span class="p">,</span> <span class="mf">2.0</span>
+  <span class="n">Language</span>  <span class="n">Groovy</span><span class="p">,</span>
+  <span class="n">Extensions</span>    <span class="n">groovy</span>
+  <span class="n">MIME</span> <span class="n">Types</span>    <span class="n">application</span><span class="o">/</span><span class="n">x</span><span class="o">-</span><span class="n">groovy</span>
+  <span class="n">Names</span>     <span class="n">groovy</span><span class="p">,</span> <span class="n">Groovy</span>
+</pre></div>
 
+
+<p><a name="GroovySupport-Testing"></a></p>
+<h2 id="testing">Testing</h2>
+<p>To test create a simple Groovy script, for example</p>
+<div class="codehilite"><pre>response.setContentType(&quot;text/plain&quot;);
+response.setCharacterEncoding(&quot;UTF-8&quot;);
+
+println &quot;Hello World !&quot;
+println &quot;This is Groovy Speaking&quot;
+println &quot;You requested the Resource <span class="cp">${</span><span class="n">resource</span><span class="cp">}</span> (yes, this is a GString)&quot;
+</pre></div>
+
+
+<p>and upload it to the repository as <em>/apps/nt/folder/GET.groovy</em> using
+your favourite WebDAV client or use curl to upload the file (assuming Sling
+is running on localhost:8888) :</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="o">-</span><span class="n">FGET</span><span class="o">.</span><span class="n">groovy</span><span class="o">=</span><span class="nv">@GET</span><span class="o">.</span><span class="n">groovy</span>
+</pre></div>
+
+
+<p>-F../../nt/jcr:primaryType=sling:Folder http:host:8888/apps/nt/folder</p>
+<p>To test it create a <em>/sample</em> <em>nt:Folder</em> node using your favourite
+WebDAV client or use curl again:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span class="nv">curl</span> <span class="o">-</span><span class="n">u</span> <span class="n">admin:admin</span> <span class="o">-</span><span class="n">Fjcr:primaryType</span><span class="o">=</span><span class="n">nt:folder</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8888</span><span class="o">/</span>
+</pre></div>
+
+
+<p>Finally, request the <em>/sample</em> node using your favourite Browser or use
+curl again:</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:8888</span><span class="o">/</span><span class="n">sample</span>
+<span class="n">Hello</span> <span class="n">World</span> <span class="o">!</span>
+<span class="n">This</span> <span class="n">is</span> <span class="n">Groovy</span> <span class="n">Speaking</span>
+<span class="n">You</span> <span class="n">requested</span> <span class="n">Resource</span> <span class="n">JcrNodeResource</span><span class="p">,</span> <span class="n">type</span><span class="o">=</span><span class="n">nt:folder</span><span class="p">,</span> <span class="n">path</span><span class="o">=/</span><span class="n">sample</span> <span class="p">(</span><span class="n">yes</span><span class="p">,</span>
+</pre></div>
+
+
+<p>this is a GString)</p>
+<p><a name="GroovySupport-References"></a></p>
+<h2 id="references">References</h2>
+<ul>
+<li><a href="https://issues.apache.org/jira/browse/SLING-315">SLING-315</a>
+ -- The initial Sling issue proposing the addition of a Groovy ScriptEngine
+to Sling.</li>
+<li><a href="http://markmail.org/message/7sqscr5y2mbk6jko">Groovy Support in Apache Sling</a>
+ -- A short thread on turning the Groovy <em>groovy-all.jar</em> into an OSGi
+Bundle.</li>
+<li><a href="http://markmail.org/message/47n2ow2jlo553jvk">Groovy in Apache Sling</a>
+ -- Thread on adding the <em>DynamicImport-Package</em> header to the Groovy
+bundle manifest.</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/guides.html
==============================================================================
--- websites/staging/sling/trunk/content/guides.html (original)
+++ websites/staging/sling/trunk/content/guides.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,50 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Guides</h1> -->
+<!-- -->
+<p>These pages contain further information in a more informal way.</p>
+<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Discover</span> <span class="n">Sling</span> <span class="n">in</span> <span class="mi">15</span> <span class="n">minutes</span> <span class="p">](</span><span class="n">discover</span><span class="o">-</span><span class="n">sling</span><span class="o">-</span><span class="n">in</span><span class="o">-</span><span class="mi">15</span><span class="o">-</span><span class="n">minutes</span><span class="o">-.</span><span class="n">html</span><span class="p">)</span>
+</pre></div>
 
+
+<ul>
+<li>
+<p>title says it all</p>
+<ul>
+<li><a href="resources.html">Resources</a>
+ -- Presents the Resource as the object around which Sling is built</li>
+<li><a href="servlet-resolution.html">Servlet Resolution</a>
+ -- How Sling resolves the servlet or script responsible for rendering a
+Resource.</li>
+<li><a href="request-parameters.html">Request Parameters</a>
+ -- Explains how Sling provides request parameters to servlets, scripts and
+filters.</li>
+<li>
+<p><a href="repository-based-development.html">Repository Based Development</a>
+ -- Shows how WebDAV is supported by Sling.</p>
+</li>
+<li>
+<p><a href="installing-and-upgrading-bundles.html">Bundle Management</a>
+ -- Explains how to install, upgrade and uninstall Bundles using the Sling
+Management console.</p>
+</li>
+</ul>
+</li>
+</ul>
+<p>These pages refer to the old Component API and launcher, and remain
+referred to here until more up to date documentation has been prepared:</p>
+<div class="codehilite"><pre><span class="o">*</span> <span class="p">[</span><span class="n">Getting</span> <span class="ow">and</span> <span class="n">Building</span> <span class="n">Sling</span><span class="p">](</span><span class="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>
+</pre></div>
+
+
+<p>-- A short recount on the first step for getting a running Sling instance
+after checking out the source from the SVN repository
+    * <a href="default-mapping-and-rendering.html">Default Mapping and Rendering</a>
+ -- Explains default mapping of repository nodes to Content instances and
+selection of a default Component.
+    * <a href="dispatching-requests.html">Dispatching Requests</a>
+ -- Explains how a Component may dispatch requests to include further
+content renderings in the response to the client's request</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/how-to-manage-events-in-sling.html
==============================================================================
--- websites/staging/sling/trunk/content/how-to-manage-events-in-sling.html (original)
+++ websites/staging/sling/trunk/content/how-to-manage-events-in-sling.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,250 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">How to Manage Events in Sling</h1> -->
+<!-- -->
+<p><a name="HowtoManageEventsinSling-HowtoManageEventsinSling"></a></p>
+<h1 id="how-to-manage-events-in-sling">How to Manage Events in Sling</h1>
+<p>Apache Sling provides some mechanisms and support for managing events.</p>
+<p>The event mechanism is leveraging the OSGi Event Admin Specification (OSGi
+Compendium 113). The OSGi API is very simple and lightweight. Sending an
+event is just generating the event object and calling the event admin.
+Receiving the event is implementing a single interface and declaring
+through properties which topics one is interested in. 
+Sling makes a distinction between events and job events. Unlike events, job
+events are garanteed to be processed. In other words: someone has to do
+something with the job event (do the job). </p>
+<p>For more details please refer to the following resources:
+<em> <a href="http://sling.apache.org/site/eventing-and-jobs.html">Eventing, Jobs and Scheduling section</a>
+ to get detailed information on the eventing mechanisms in Sling.
+</em> package <a href="http://www.osgi.org/javadoc/r4v42/org/osgi/service/event/package-summary.html">org.osgi.service.event</a>
+ of the OSGI API.
+* package <a href="http://sling.apache.org/apidocs/sling6/org/apache/sling/event/package-summary.html">org.apache.sling.event</a>
+ of the Sling API.</p>
+<p>This page drives you through the implementation of two services that rely
+on the Sling eventing mechanisms. The services implement the following use
+case: whenever a file is uploaded to a temporary location in your web
+application, the file is moved to a specific location according to its MIME
+type.</p>
+<p><a name="HowtoManageEventsinSling-Introduction"></a></p>
+<h2 id="introduction">Introduction</h2>
+<p>You will now implement the logic to listen to files posted to
+<em>/tmp/dropbox</em> and to move them to the appropriate locations depending on
+the MIME type:
+<em> images (.png) are moved to </em>/dropbox/images/<em>
+</em> music (.mp3) are moved to <em>/dropbox/music/</em>
+<em> movies (.avi) are moved to </em>/dropbox/movies/<em>
+</em> otherwise the files are moved to <em>/dropbox/other/</em></p>
+<p>To do that, you will implement two services. The first one, called
+<em>DropBoxService</em>:
+<em> Listens to OSGI events.
+</em> Sends a job event if a resource has been added to <em>/tmp/dropbox</em>.</p>
+<p>The second one, called <em>DropBoxEventHandler</em>:
+<em> Listens to the former job event.
+</em> Moves the file according to its extension.</p>
+<p><a name="HowtoManageEventsinSling-ListeningtoOSGIEvents"></a></p>
+<h2 id="listening-to-osgi-events">Listening to OSGI Events</h2>
+<p>To listen to the specific OSGI event <em>"resource added"</em>:
+<em> The property </em>event.topics<em> needs to be set to
+</em>org.apache.sling.api.SlingConstants.TOPIC_RESOURCE_ADDED* in the class
+annotations.</p>
+<div class="codehilite"><pre> <span class="o">*</span> <span class="nv">@scr</span><span class="o">.</span><span class="n">property</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;event.topics&quot;</span>
+</pre></div>
 
+
+<p>valueRef="org.apache.sling.api.SlingConstants.TOPIC_RESOURCE_ADDED"</p>
+<p>You can refer to the <a href="http://sling.apache.org/apidocs/sling6/org/apache/sling/api/SlingConstants.html">org.apache.sling.api.SlingConstants</a>
+ class in the Javadocs to know about other events available in Sling.</p>
+<p><a name="HowtoManageEventsinSling-SendingJobEvents"></a></p>
+<h2 id="sending-job-events">Sending Job Events</h2>
+<p>To send a job event the service needs to implement:
+<em> the </em>org.osgi.service.event.EventHandler<em> interface.
+</em> the <em>org.apache.sling.event.JobProcessor</em> interface.</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">DropBoxService</span> <span class="n">implements</span> <span class="n">JobProcessor</span><span class="p">,</span> <span class="n">EventHandler</span> <span class="p">{</span>
+</pre></div>
+
+
+<p>To send the job event the Event Admin service needs to be referenced:</p>
+<div class="codehilite"><pre>    <span class="o">/**</span> 
+     <span class="o">*</span> <span class="n">The</span> <span class="n">OSGI</span> <span class="n">event</span> <span class="n">admin</span> <span class="n">used</span> <span class="k">for</span> <span class="n">sending</span> <span class="n">events</span> 
+     <span class="o">*</span> <span class="nv">@scr</span><span class="o">.</span><span class="n">reference</span>
+     <span class="o">*/</span>
+    <span class="n">private</span> <span class="n">EventAdmin</span> <span class="n">eventAdmin</span><span class="p">;</span>
+</pre></div>
+
+
+<p>The job topic for dropbox job events needs to be defined:</p>
+<div class="codehilite"><pre>    <span class="sr">/** The job topic for dropbox job events. */</span>
+    <span class="n">public</span> <span class="n">static</span> <span class="n">final</span> <span class="n">String</span> <span class="n">JOB_TOPIC</span> <span class="o">=</span>
+</pre></div>
+
+
+<p>"com/sling/eventing/dropbox/job";</p>
+<p>The <em>org.osgi.service.event.EventHandler#handleEvent(Event event)</em> method
+needs to be implemented:</p>
+<div class="codehilite"><pre>    <span class="n">public</span> <span class="n">void</span> <span class="n">handleEvent</span><span class="p">(</span><span class="n">Event</span> <span class="n">event</span><span class="p">)</span> <span class="p">{</span>
+        <span class="k">if</span> <span class="p">(</span><span class="n">EventUtil</span><span class="o">.</span><span class="n">isLocal</span><span class="p">(</span><span class="n">event</span><span class="p">))</span> <span class="p">{</span>
+        <span class="n">EventUtil</span><span class="o">.</span><span class="n">processJob</span><span class="p">(</span><span class="n">event</span><span class="p">,</span> <span class="n">this</span><span class="p">);</span>
+        <span class="p">}</span>
+    <span class="p">}</span>
+</pre></div>
+
+
+<p>The <em>org.apache.sling.event.JobProcessor#process(Event event)</em> method needs
+to be implemented.</p>
+<p>Its logic is as follows:
+<em> The OSGI event is analyzed.
+</em> If the event is a file that has been added to <em>/tmp/dropbox</em>:
+<strong> An event is created with 2 properties:
+<strong><em> A property to set the event as a job event.
+</em></strong> A property for the file path.
+</strong> The job event is sent to all the listeners that subscribe to the topic
+of the event.</p>
+<div class="codehilite"><pre>    <span class="n">public</span> <span class="n">boolean</span> <span class="n">process</span><span class="p">(</span><span class="n">Event</span> <span class="n">event</span><span class="p">)</span> <span class="p">{</span>
+        <span class="n">String</span> <span class="n">propPath</span> <span class="o">=</span> <span class="p">(</span><span class="n">String</span><span class="p">)</span>
+</pre></div>
+
+
+<p>event.getProperty(SlingConstants.PROPERTY_PATH);
+            String propResType = (String)
+event.getProperty(SlingConstants.PROPERTY_RESOURCE_TYPE);
+            // an event is sent if a file is added to /tmp/dropbox
+            if (propPath.startsWith("/tmp/dropbox") &amp;&amp;
+propResType.equals("nt:file")) {
+                final Dictionary<String, Object> props = new
+Hashtable<String, Object>();
+                props.put(EventUtil.PROPERTY_JOB_TOPIC, JOB_TOPIC);
+                props.put("resourcePath", propPath);
+                Event dropboxJobEvent = new
+Event(EventUtil.TOPIC_JOB, props);
+                eventAdmin.sendEvent(dropboxJobEvent);
+                log.info("the dropbox job has been sent: {}",
+propPath);
+            }
+            return true;
+        }</p>
+<p>The complete code for the <em>DropBoxService</em> service is available <a href="^dropboxservice.java.html">here</a>
+.</p>
+<p><a name="HowtoManageEventsinSling-ListeningtoJobEvents"></a></p>
+<h2 id="listening-to-job-events">Listening to Job Events</h2>
+<p>Now that you have implemented a service that sends a job event when a file
+is uploaded to <em>/tmp/dropbox</em>, you will implement the service
+<em>DropBoxEventHandler</em> that listens to those job events and moves the files
+to a location according to their MIME types.</p>
+<p>To listen to the job events that have been defined before:
+<em> The property </em>event.topics<em> needs to be set to
+</em>mypackage.DropBoxService.JOB_TOPIC* in the class annotations.</p>
+<div class="codehilite"><pre> <span class="o">*</span> <span class="nv">@scr</span><span class="o">.</span><span class="n">property</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;event.topics&quot;</span>
+</pre></div>
+
+
+<p>valueRef="mypackage.DropBoxService.JOB_TOPIC"</p>
+<p><a name="HowtoManageEventsinSling-HandlingJobEvents"></a></p>
+<h2 id="handling-job-events">Handling Job Events</h2>
+<p>To move the files the service needs to implement:
+<em> the </em>org.osgi.service.event.EventHandler<em> interface.
+</em> the <em>org.apache.sling.event.JobProcessor</em> interface.</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">DropBoxEventHandler</span> <span class="n">implements</span> <span class="n">JobProcessor</span><span class="p">,</span> <span class="n">EventHandler</span> <span class="p">{</span>
+</pre></div>
+
+
+<p>Some class fields need to be defined for:
+<em> The default log.
+</em> The references to the SlingRepository and the JcrResourceResolverFactory
+services, which are used in the implementation.
+* The destination paths of the files.</p>
+<p>{code}
+   /*<em> Default log. </em>/
+    protected final Logger log = LoggerFactory.getLogger(this.getClass());</p>
+<div class="codehilite"><pre><span class="sr">/** @scr.reference */</span>
+<span class="n">private</span> <span class="n">SlingRepository</span> <span class="n">repository</span><span class="p">;</span>
+
+<span class="o">/**</span>
+ <span class="o">*</span> <span class="nv">@scr</span><span class="o">.</span><span class="n">reference</span>
+ <span class="o">*/</span>
+<span class="n">private</span> <span class="n">JcrResourceResolverFactory</span> <span class="n">resolverFactory</span><span class="p">;</span>
+
+<span class="n">private</span> <span class="n">final</span> <span class="n">static</span> <span class="n">String</span> <span class="n">IMAGES_PATH</span> <span class="o">=</span> <span class="s">&quot;/dropbox/images/&quot;</span><span class="p">;</span>
+<span class="n">private</span> <span class="n">final</span> <span class="n">static</span> <span class="n">String</span> <span class="n">MUSIC_PATH</span> <span class="o">=</span> <span class="s">&quot;/dropbox/music/&quot;</span><span class="p">;</span>
+<span class="n">private</span> <span class="n">final</span> <span class="n">static</span> <span class="n">String</span> <span class="n">MOVIES_PATH</span> <span class="o">=</span> <span class="s">&quot;/dropbox/movies/&quot;</span><span class="p">;</span>
+<span class="n">private</span> <span class="n">final</span> <span class="n">static</span> <span class="n">String</span> <span class="n">OTHER_PATH</span> <span class="o">=</span> <span class="s">&quot;/dropbox/other/&quot;</span><span class="p">;</span>
+
+<span class="n">The</span> <span class="o">*</span><span class="n">org</span><span class="o">.</span><span class="n">osgi</span><span class="o">.</span><span class="n">service</span><span class="o">.</span><span class="n">event</span><span class="o">.</span><span class="n">EventHandler</span><span class="c1">#handleEvent(Event event)* method</span>
+</pre></div>
+
+
+<p>needs to be implemented:</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">void</span> <span class="n">handleEvent</span><span class="p">(</span><span class="n">Event</span> <span class="n">event</span><span class="p">)</span> <span class="p">{</span>
+    <span class="k">if</span> <span class="p">(</span><span class="n">EventUtil</span><span class="o">.</span><span class="n">isLocal</span><span class="p">(</span><span class="n">event</span><span class="p">))</span> <span class="p">{</span>
+    <span class="n">EventUtil</span><span class="o">.</span><span class="n">processJob</span><span class="p">(</span><span class="n">event</span><span class="p">,</span> <span class="n">this</span><span class="p">);</span>
+    <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="n">The</span> <span class="o">*</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">event</span><span class="o">.</span><span class="n">JobProcessor</span><span class="c1">#process(Event event)* method needs</span>
+</pre></div>
+
+
+<p>to be implemented.</p>
+<div class="codehilite"><pre><span class="n">Its</span> <span class="n">logic</span> <span class="n">is</span> <span class="n">as</span> <span class="n">follows:</span>
+<span class="o">*</span> <span class="n">The</span> <span class="n">resource</span> <span class="n">path</span> <span class="n">is</span> <span class="n">extracted</span> <span class="n">from</span> <span class="n">the</span> <span class="n">job</span> <span class="n">event</span> <span class="n">property</span><span class="o">.</span>
+<span class="o">*</span> <span class="n">The</span> <span class="n">resource</span> <span class="n">is</span> <span class="n">obtained</span> <span class="n">from</span> <span class="n">the</span> <span class="n">resource</span> <span class="n">path</span><span class="o">.</span>
+<span class="o">*</span> <span class="n">If</span> <span class="n">the</span> <span class="n">resource</span> <span class="n">is</span> <span class="n">a</span> <span class="n">file</span><span class="p">,</span> <span class="n">the</span> <span class="n">destination</span> <span class="n">path</span> <span class="n">is</span> <span class="nb">defined</span> <span class="n">based</span> <span class="n">on</span> <span class="n">the</span>
+</pre></div>
+
+
+<p>file MIME type.
+    * The file is moved to the new location.</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">boolean</span> <span class="n">process</span><span class="p">(</span><span class="n">Event</span> <span class="n">event</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">Session</span> <span class="n">adminSession</span> <span class="o">=</span> <span class="n">null</span><span class="p">;</span>
+    <span class="n">try</span> <span class="p">{</span>
+        <span class="n">String</span> <span class="n">resourcePath</span> <span class="o">=</span> <span class="p">(</span><span class="n">String</span><span class="p">)</span>
+</pre></div>
+
+
+<p>event.getProperty("resourcePath");
+            String resourceName =
+resourcePath.substring(resourcePath.lastIndexOf("/") + 1);
+        adminSession = repository.loginAdministrative(null);
+        ResourceResolver resourceResolver =
+resolverFactory.getResourceResolver(adminSession);
+        Resource res = resourceResolver.getResource(resourcePath);
+        if (ResourceUtil.isA(res, "nt:file")) {
+            String mimeType =
+res.getResourceMetadata().getContentType();
+            String destDir;
+            if (mimeType.equals("image/png")) {
+                destDir = IMAGES_PATH;
+            }
+            else if (mimeType.equals("audio/mpeg")) {
+                destDir = MUSIC_PATH;
+            }
+            else if (mimeType.equals("video/x-msvideo")) {
+                destDir = MOVIES_PATH;
+            }
+            else {
+                destDir = OTHER_PATH;
+            }
+            adminSession.move(resourcePath, destDir +
+resourceName);
+            adminSession.save();
+            log.info("The file {} has been moved to {}",
+resourceName, destDir);
+        }
+        return true;
+        } catch (RepositoryException e) {
+            log.error("RepositoryException: " + e);
+            return false;
+    } finally {
+        if (adminSession != null &amp;&amp; adminSession.isLive()) {
+        adminSession.logout();
+        adminSession = null;
+        }
+    }
+    }</p>
+<div class="codehilite"><pre><span class="n">The</span> <span class="n">complete</span> <span class="n">code</span> <span class="k">for</span> <span class="n">the</span> <span class="o">*</span><span class="n">DropBoxEventHandler</span><span class="o">*</span> <span class="n">service</span> <span class="n">is</span> <span class="n">available</span> <span class="p">[</span><span class="n">here</span><span class="o">|^</span><span class="n">DropBoxEventHandler</span><span class="o">.</span><span class="n">java</span><span class="p">]</span>
+</pre></div>
+
+
+<p>.</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/index.html
==============================================================================
--- websites/staging/sling/trunk/content/index.html (original)
+++ websites/staging/sling/trunk/content/index.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,145 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Apache Sling - Bringing Back the Fun!</h1> -->
-
+<!-- -->
+<p>{tm}Apache Sling{tm} is an innovative web framework that is intended to
+bring back the fun to web development.</p>
+<p>Discussions about Sling happen on our mailing lists, see the <a href="project-information.html">Project Information</a>
+ page for more info.</p>
+<p><a name="ApacheSling-bringingbackthefun!-ApacheSlinginfivebulletspoints"></a></p>
+<h1 id="apache-sling-in-five-bullets-points">Apache Sling in five bullets points</h1>
+<ul>
+<li>REST based web framework</li>
+<li>Content-driven, using a JCR content repository</li>
+<li>Powered by OSGi</li>
+<li>Scripting inside, multiple languages (JSP, server-side javascript, Scala,
+etc.)</li>
+<li>Apache Open Source project</li>
+</ul>
+<p><a name="ApacheSling-bringingbackthefun!-ApacheSlinginahundredwords"></a></p>
+<h1 id="apache-sling-in-a-hundred-words">Apache Sling in a hundred words</h1>
+<p>Apache Sling is a web framework that uses a <a href="http://en.wikipedia.org/wiki/JSR-170">Java Content Repository</a>
+, such as [Apache Jackrabbit|http://jackrabbit.apache.org/]
+, to store and manage content.</p>
+<p>Sling applications use either scripts or Java servlets, selected based on
+simple name conventions, to process HTTP requests in a RESTful way.</p>
+<p>The embedded <a href="http://felix.apache.org/">Apache Felix</a>
+ OSGi framework and console provide a dynamic runtime environment, where
+code and content bundles can be loaded, unloaded and reconfigured at
+runtime.</p>
+<p>As the first web framework dedicated to <a href="http://jcp.org/en/jsr/detail?id=170">JSR-170</a>
+ Java Content Repositories, Sling makes it very simple to implement simple
+applications, while providing an enterprise-level framework for more
+complex applications. </p>
+<p><a name="ApacheSling-bringingbackthefun!-News"></a></p>
+<h2 id="news">News</h2>
+<p>{excerpt-include:News|nopanel=true}
+* <a href="news.html">all news...</a></p>
+<p><a name="ApacheSling-bringingbackthefun!-History"></a></p>
+<h2 id="history">History</h2>
+<p>Sling started as an internal project at <a href="http://www.day.com">Day Software</a>
+, and entered the Apache Incubator in September 2007. As of June, 17th,
+2009 Apache Sling is a top level project of the Apache Software Foundation.</p>
+<p>The name "Sling" has been proposed by Roy Fielding who explained it like
+this:</p>
+<p>{quote}
+[The name is](the-name-is.html)
+ Biblical in nature.  The story of David: the weapon he uses to slay the
+giant Goliath is a sling.  Hence, our David's [David Nuescheler, CTO of
+Day Software] favorite weapon.</p>
+<p>It is also the simplest device for delivering content very fast.
+{quote}</p>
+<p><a name="ApacheSling-bringingbackthefun!-WhousesSling?"></a></p>
+<h2 id="who-uses-sling">Who uses Sling?</h2>
+<p>See <a href="http://cwiki.apache.org/SLING/who-is-using-sling-.html">Who is using Sling</a>
+ on our public wiki.</p>
+<p><a name="ApacheSling-bringingbackthefun!-Gettingstarted"></a></p>
+<h2 id="getting-started">Getting started</h2>
+<p>If you prefer doing rather than reading, please proceed to <a href="discover-sling-in-15-minutes.html">Discover Sling in 15 minutes</a>
+ or read through the recommended links in the [Getting Started]
+ section, where you can quickly get started on your own instance of Sling.</p>
+<p>{note:title=Excuse our mess while we redesign}
+Sling has undergone an important redesign in the last few months, and we're
+not done updating this website yet.</p>
+<p>The status of each page is indicated by a note like this at the top of each
+page.</p>
+<p>Pages which do not have such a note should be considered <em>not reviewed</em>:
+the information that they contain might be out of sync with the current
+Sling codebase.
+{note}</p>
+<p><a name="ApacheSling-bringingbackthefun!-Contents"></a></p>
+<h2 id="contents">Contents</h2>
+<ul>
+<li><a href="documentation.html">Documentation</a>
+ - Here you will find the documentation on Sling</li>
+<li><a href="development.html">Development</a>
+ -- Documentation on how to develop web applications with Sling and what
+tools you have at your disposal</li>
+<li><a href="links.html">Links</a></li>
+<li><a href="http://cwiki.apache.org/SLING/">Wiki</a></li>
+<li><a href="http://cwiki.apache.org/SLING/faq.html">FAQ</a></li>
+<li><a href="project-information.html">Project Information</a></li>
+</ul>
+<p><a name="ApacheSling-bringingbackthefun!-UseCasesforSling"></a></p>
+<h2 id="use-cases-for-sling">Use Cases for Sling</h2>
+<p><a name="ApacheSling-bringingbackthefun!-Wiki"></a></p>
+<h4 id="wiki">Wiki</h4>
+<p>Day built a Wiki system on Sling. Each Wiki page is a node (with optional
+child nodes) in the repository. As a page is requested, the respective node
+is accessed and through the applying Component is rendered.</p>
+<p>Thanks to the JCR Mapping and the resolution of the Component from the
+mapped Content, the system does not care for what actual node is addressed
+as long as there is a Content mapping and a Component capable of handling
+the Content.</p>
+<p>Thus in the tradition of REST, the attachement of a Wiki page, which
+happens to be in a node nested below the wiki page node is easily accessed
+using the URL of the wiki page attaching the relative path of the
+attachement  ode. The system resolves the URL to the attachement Content
+and just calls the attachement's Component to spool the attachement.</p>
+<p><a name="ApacheSling-bringingbackthefun!-DigitalAssetManagement"></a></p>
+<h4 id="digital-asset-management">Digital Asset Management</h4>
+<p>Day has implemented a Digital Asset Management (DAM) Application based on
+Sling. Thanks to the flexibility of the Content/Component combo as well as
+the service registration/access functionality offered by OSGi, extending
+DAM for new content type is merely a matter of implementing one or two
+interfaces and registering the respective service(s).</p>
+<p>Again, the managed assets may be easily spooled by directly accessing them.</p>
+<p><a name="ApacheSling-bringingbackthefun!-WebContentManagement"></a></p>
+<h4 id="web-content-management">Web Content Management</h4>
+<p>Last but not least, Sling offers itself very well to implementing a Web
+Content Management system. Thanks to the flexibility of rendering the
+output - remember: the system does not care what to render, as long as the
+URL resolves to a Content object for which a Component exists, which is
+called to render the Content - providing support for Web Content authors
+(not PHP programmers but users out in the field) to build pages to their
+likings can easily be done.</p>
+<p><a name="ApacheSling-bringingbackthefun!-References"></a></p>
+<h2 id="references">References</h2>
+<p><a name="ApacheSling-bringingbackthefun!-ApacheJackrabbit"></a></p>
+<h4 id="apache-jackrabbit">Apache Jackrabbit</h4>
+<p>The main purpose of Sling is to develop a content-centric Web Application
+framework for Java Content Repository (JCR) based data stores. Sling is
+implemented - with the notable exception of JCR Node Type management -
+purely in terms of the JCR API and as such may use any JCR compliant
+repository. The default implementation for <a href="http://jackrabbit.apache.org">Apache Jackrabbit</a>
+ is provided out of the box.</p>
+<p><a name="ApacheSling-bringingbackthefun!-OSGi"></a></p>
+<h4 id="osgi">OSGi</h4>
+<p>Sling is implemented as a series of <a href="http://www.osgi.org">OSGi</a>
+ Bundles and makes extensive use of the OSGi functionality, such as
+lifecycle management and the service layer. In addition, Sling requires
+several OSGi compendium services to be available, such as the Log Service,
+Http Service, Configuration Admin Service, Metatype Service, and
+Declarative Services.</p>
+<p><a name="ApacheSling-bringingbackthefun!-ApacheFelix"></a></p>
+<h4 id="apache-felix">Apache Felix</h4>
+<p>While Sling does not require a specific OSGi framework implementation to
+run in, Sling is being developed using <a href="http://felix.apache.org">Apache Felix</a>
+ as the OSGi framework implementation. It has not been tested yet, but it
+is expected that Sling also operates perfectly inside other OSGi frameworks
+such as [Equinox|http://www.eclipse.org/equinox]
+ and [Knopflerfish|http://www.knopflerfish.org]
+.</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/installing-and-upgrading-bundles.html
==============================================================================
--- websites/staging/sling/trunk/content/installing-and-upgrading-bundles.html (original)
+++ websites/staging/sling/trunk/content/installing-and-upgrading-bundles.html Sun Apr 22 17:20:11 2012
@@ -82,7 +82,121 @@
 <a href="/">Home</a>
       </div>
    <!--   <h1 class="title">Installing and Upgrading Bundles</h1> -->
+<!-- -->
+<p><a name="InstallingandUpgradingBundles-InstallingandUpgradingBundles"></a></p>
+<h1 id="installing-and-upgrading-bundles">Installing and Upgrading Bundles</h1>
+<p>{note}
+We recommend to use the Apache Felix Web Console. The documentation below
+describes the old Sling Management Console, which isn't in use any more.
+Please refer to the documentation of the <a href="http://felix.apache.org/site/apache-felix-web-console.html">Apache Felix Web Console</a>
+.
+{note}</p>
+<p>{excerpt:hidden=true}Explains how to install, upgrade and uninstall Bundles
+using the Sling Management console.{excerpt}</p>
+<p>OSGi bundles installed in the OSGi framework, which is provided by Sling,
+may be upgraded or removed and new bundles may be installed by using the
+Sling Management Console. This page is about using the Sling Management
+Console for those tasks.</p>
+<p>Basically, you have two choices to install and upgrade bundles: Upload the
+bundle files or install them from a Bundle Repository.</p>
+<p><a name="InstallingandUpgradingBundles-SlingManagementConsole"></a></p>
+<h2 id="sling-management-console">Sling Management Console</h2>
+<p>The Sling Management Console is installed by default when Sling is running
+and may be reached at on the page <em>/system/console</em> in the Sling Context
+by default. For example if you installed the Sling Web Application in the
+<em>/sample</em> context of the Servlet Container running at
+<em>http<strong>://somehost:4402<em>, you would access the Sling Management Console
+at </em>http</strong>://somehost:4402/sample/system/console</em>.</p>
+<p>You will be prompted for a user name and password to access the Sling
+Management Console. This password is preset to be <em>admin</em> for the user name
+and <em>admin</em> for the password.</p>
+<p>NB: Both the username and password and the location of the Sling Management
+Console inside the Web Application Context is configurable in the <em>Sling
+Management Console</em> configuration on the <em>Configuration</em> page.</p>
+<p><a name="InstallingandUpgradingBundles-InstallingandupgradingbundlesbyUpload"></a></p>
+<h2 id="installing-and-upgrading-bundles-by-upload">Installing and upgrading bundles by Upload</h2>
+<p>To install a new bundle or upgrade an already installed bundle, go to the
+<em>Bundles</em> page in the Sling Management Console. At the top and the bottom
+of the page you have a form to specify and upload a bundle as a file :</p>
+<ul>
+<li>Select the bundle file to upload</li>
+<li>Click the <em>Start</em> checkbox, if you want to start the bundle after
+installation. If the bundle is upgraded, this checkbox is ignored.</li>
+<li>Specify the start level of the bundle in the <em>Start Level</em> field. This
+must be a number higher than 0 and is ignored for bundles, which are
+already installed. Most of the time, you will use the default value.</li>
+<li>Click the <em>Install or Update</em> button</li>
+</ul>
+<p>After clicking the button, the bundle file will be uploaded. If a bundle
+with the same bundle symbolic name is already installed, the respective
+bundle will be updated with the new bundle file. Otherwise the bundle file
+will be installed as a new bundle and its start level is set as defined.
+Additionally the bundle will optionally be started.</p>
+<p>After having updated a bundle, you should also refresh the packages by
+clicking on the <em>Refresh Packages</em> button. The reson for this is, that the
+old version of the bundle is still used by other bundles even after
+upgrading to a new version. Only when the packages are refreshed any users
+of the bundle will be relinked to use the new bundle version. As this might
+be a somewhat lengthy operation, which also stops and restarts using
+bundles, this operation has to be executed explicitly.</p>
+<p>Also, if you plan to upgrade multiple bundles, you may wish to upgrade all
+bundles before repackaging the using bundles.</p>
+<p><a name="InstallingandUpgradingBundles-InstallingandupgradingbundlesfromtheBundleRepository"></a></p>
+<h2 id="installing-and-upgrading-bundles-from-the-bundle-repository">Installing and upgrading bundles from the Bundle Repository</h2>
+<p>The OSGi Bundle Repository is a repository of bundles, from which Sling may
+download and install or upgrade bundles very easily. Unlike the
+installation of bundles by file upload, the OSGi Bundle Repository has the
+functionality to resolve and dependencies of bundles to be installed.</p>
+<p>Say you wish to install bundle <em>X</em> which depends on packages provided by
+bundle <em>Y</em>. When uploading bundle <em>X</em> as a file it will not resolve, that
+is Sling (the OSGi framework actually) is not able to ensure proper
+operation of bundle <em>X</em> and thus prevents the bundle from being started and
+used. You will have to manually upload bundle <em>Y</em> yourself. When using the
+OSGi Bundle Repository, you just select bundle <em>X</em> for installation and the
+bundle repository will find out, that bundle <em>Y</em> is also required and will
+automatically download and install it along with bundle <em>X</em>.</p>
+<p><a name="InstallingandUpgradingBundles-TheBundleRepositorypage"></a></p>
+<h3 id="the-bundle-repository-page">The Bundle Repository page</h3>
+<p>Installation or update of bundles may be done on the <em>Bundle Repository</em>
+page of the Sling Management Console. In the upper part of the page, you
+will see a list (usually just a single entry) of OSGi Bundle Repositories
+known to Sling. In the lower part of the list you see the bundles available
+from these repositories. To install or update bundles, just check the
+respective button and click on the <em>Deploy Selected</em> or <em>Deploy and Start
+Selected</em> button at the bottom of the page depending on whether you want to
+start the bundle(s) after installation or not.</p>
+<p>See below for more information on OSGi Bundle Repository management.</p>
+<p><a name="InstallingandUpgradingBundles-TheBundlespage"></a></p>
+<h3 id="the-bundles-page">The Bundles page</h3>
+<p>You may also want to upgrade already installed bundles from the <em>Bundles</em>
+page of the Sling Management Console. For each bundle listed in this page,
+there is an <em>Upgrade</em> button. If there is an upgrade to the installed
+bundle available in the OSGi Bundle Repository, the button is enabled and
+clicking on the button will upgrade the respective bundle. If no upgrade is
+available from the OSGi Bundle Repository, this button is disabled.</p>
+<p><a name="InstallingandUpgradingBundles-ManagingOSGiBundleRepositories"></a></p>
+<h3 id="managing-osgi-bundle-repositories">Managing OSGi Bundle Repositories</h3>
+<p>Currently management of known OSGi Bundle Repositories is very simple. If a
+configured bundle repository is not available on startup, it will be marked
+as being inactive. If you know the repository is now available, you may
+click on the <em>Refresh</em> button, to activate it. Similarly, the contents of
+the repository may be modified by for example adding new bundles or
+updating bundles in the repository, these changes will be made known to
+Sling by clicking the <em>Refresh</em> button.</p>
+<p>There exists no GUI functionality yet to add a new repository to the list
+of known repositories. Instead you may submit a request with parameters
+<em>action</em> whose value must be <em>refreshOBR</em> and <em>repository</em> whose
+value must be the URL to the repository descriptor file generally called
+<em>repository.xml</em>.</p>
+<p>For example, if you run Sling on <em>http</em><em>://localhost:7402/sample</em> with
+default location of the Sling Management Console, the following request
+would add a repository at <em>/tmp/repo/repository.xml</em> in the filesystem:</p>
+<div class="codehilite"><pre><span class="n">http:</span><span class="sr">//</span><span class="n">localhost:7402</span><span class="sr">/sample/s</span><span class="n">ystem</span><span class="sr">/console/</span><span class="n">bundlerepo</span><span class="p">?</span><span class="n">action</span><span class="o">=</span><span class="n">refreshOBR</span><span class="o">&amp;</span><span class="n">repository</span><span class="o">=</span><span class="n">file:</span><span class="sr">///tmp/</span><span class="n">repo</span><span class="o">/</span><span class="n">repository</span><span class="o">.</span><span class="n">xml</span>
+</pre></div>
 
+
+<p>Note: Only use <em>file:</em> URLs if you know Sling has access to the named
+file !</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.



Mime
View raw message