You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by fm...@apache.org on 2012/04/22 18:52:16 UTC
svn commit: r1328899 [4/8] - in /sling/site/trunk: content/ templates/
Added: sling/site/trunk/content/filters.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/filters.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/filters.mdtext (added)
+++ sling/site/trunk/content/filters.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,241 @@
+Title: Filters
+<a name="Filters-ServletFilterSupport"></a>
+# Servlet Filter Support
+
+Sling supports filter processing by applying filter chains to the requests
+before actually dispatching to the servlet or script for processing.
+Filters to be used in such filter processing are plain OSGi services of
+type *javax.servlet.Filter* which of course means that the services
+implement this interface.
+
+{note}
+
+
+See [SLING-1213](https://issues.apache.org/jira/browse/SLING-1213)
+, [SLING-1734|https://issues.apache.org/jira/browse/SLING-1734]
+, and [Registering filters with Sling|http://markmail.org/message/quxhm7d5s6u66crr]
+ for more details.
+{note}
+
+For Sling to pick up a *javax.servlet.Filter* service for filter
+processing two service registration properties are inspected:
+
+<table>
+<tr><th> Property </th><th> Type </th><th> Default Value </th><th> Valid Values </th><th> Description </th></tr>
+<tr><td> *sling.filter.scope* </td><td> *String*, {{String[](.html)
+}} or *Vector<String>* </td><td> *request* </td><td> *REQUEST*, *INCLUDE*,
+*FORWARD*, *ERROR*, *COMPONENT* </td><td> Indication of which chain the
+filter should be added to. This property is required. If it is missing from
+the service, the service is ignored because it is assumed another consumer
+will be interested in using the service. Any unknown values of this
+property are also ignored causing the service to be completely ignored if
+none of the values provided by the property are valid. See below for the
+description of the filter chains. </td></tr>
+<tr><td> *service.ranking* </td><td> *Integer* </td><td> *0* </td><td> Any *Integer* value </td><td>
+Indication of where to place the filter in the filter chain. The higher the
+number the earlier in the filter chain. This value may span the whole range
+of integer values. Two filters with equal *service.ranking* property
+value (explicitly set or default value of zero) will be ordered according
+to their *service.id* service property as described in section 5.2.5,
+Service Properties, of the OSGi Core Specification R 4.2. </td></tr>
+</table>
+
+
+<a name="Filters-FilterChains"></a>
+## Filter Chains
+
+Sling maintains five filter chains: request level, component level, include
+filters, forward filters and error filters. Except for the component level
+filter these filter chains correspond to the filter *<dispatcher>*
+configurations as defined for Servlet API 2.5 web applications (see section
+SRV.6.2.5 Filters and the RequestDispatcher).
+
+The following table summarizes when each of the filter chains is called and
+what value must be defined in the *sling.filter.scope* property to have a
+filter added to the respective chain:
+
+<table>
+<tr><th> *sling.filter.scope* </th><th> Servlet API Correspondence </th><th> Description </th></tr>
+<tr><td> *REQUEST* </td><td> *REQUEST* </td><td> Filters are called once per request hitting
+Sling from the outside. These filters are called after the resource
+addressed by the request URL and the Servlet or script to process the
+request has been resolved before the *COMPONENT* filters (if any) and the
+Servlet or script are called. </td></tr>
+<tr><td> *INCLUDE* </td><td> *INCLUDE* </td><td> Filters are called upon calling the
+*RequestDispatcher.include* method after the included resource and the
+Servlet or script to process the include have been resolved before the
+Servlet or script is called. </td></tr>
+<tr><td> *FORWARD* </td><td> *FORWARD* </td><td> Filters are called upon calling the
+*RequestDispatcher.forward* method after the included resource and the
+Servlet or script to process the include have been resolved before the
+Servlet or script is called. </td></tr>
+<tr><td> *ERROR* </td><td> *ERROR* </td><td> Filters are called upon
+*HttpServletResponse.sendError* or any uncaught *Throwable* before
+resolving the error handler Servlet or script. </td></tr>
+<tr><td> *COMPONENT* </td><td> *REQUEST,INCLUDE,FORWARD* </td><td> The *COMPONENT* scoped
+filters are present for backwards compatibility with earlier Sling Engine
+releases. These filters will be called among the *INCLUDE* and
+*FORWARD* filters upon *RequestDispatcher.include* or
+*RequestDispatcher.forward* as well as before calling the request level
+Servlet or script after the *REQUEST* filters. </td></tr>
+</table>
+
+Note on *INCLUDE* and *FORWARD* with respect to JSP tags: These filters
+are also called if the respective including (e.g. *<jsp:include>* or
+*<sling:include>*) or forwarding (e.g. *<jsp:forward>* or
+*<sling:forward>*) ultimately calls the *RequestDispatcher*.
+
+
+<a name="Filters-FilterProcessing"></a>
+## Filter Processing
+
+Filter processing is part of the Sling request processing, which may be
+sketched as follows:
+
+<table>
+<tr><td> _Request Level_ </td></tr>
+<tr><td> Authentication </td></tr>
+<tr><td> Resource Resolution </td></tr>
+<tr><td> Servlet/Script Resolution </td></tr>
+<tr><td> Request Level Filter Processing </td></tr>
+<tr><td> _Component Level_ </td></tr>
+</table>
+
+The first step of request processing is the _Request Level_ processing
+which is concerned with resolving the resource, finding the appropriate
+servlet and calling into the request level filter chain. The next step is
+the _Component Level_ processing, calling into the component level filters
+before finally calling the servlet or script:
+
+<table>
+<tr><td> _Component Level_ </td></tr>
+<tr><td> Component Level Filter Processing </td></tr>
+<tr><td> Call Servlet or Script </td></tr>
+</table>
+
+When a servlet or script is including or forwarding to another resource for
+processing through the *RequestDispatcher* (or any JSP tag or other
+language feature ultimately using a *RequestDispatcher*) the following
+_Dispatch_ processing takes place:
+
+<table>
+<tr><td> _Dispatch_ </td></tr>
+<tr><td> Resolve the resource to dispatch to if not already defined when getting
+the *RequestDispatcher* </td></tr>
+<tr><td> Servlet/Script resolution </td></tr>
+<tr><td> Call include or forward filters depending on the kind of dispatch </td></tr>
+<tr><td> Call Servlet or Script </td></tr>
+</table>
+
+As a consequence, request level filters will be called at most once during
+request processing (they may not be called at all if a filter earlier in
+the filter chain decides to terminate the request) while the component
+level, include, and forward filters may be called multiple times while
+processing a request.
+
+
+<a name="Filters-Troubleshooting"></a>
+## Troubleshooting
+Apart form the logs which tell you when filters are executed, two Sling
+plugins provide information about filters in the OSGi console.
+
+<a name="Filters-RecentRequestsplugin"></a>
+### Recent Requests plugin
+The request traces provided at */system/console/requests* contain
+information about filter execution, as in this example:
+
+<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>Recent Requests plugin info</B></DIV><DIV class="codeContent panelContent">
+ 0 (2010-09-08 15:22:38) TIMER_START{Request Processing}
+ ...
+ 0 (2010-09-08 15:22:38) LOG Method=GET,
+PathInfo=/libs/wcm/core/content/siteadmin.html
+ 3 (2010-09-08 15:22:38) LOG Applying request filters
+ 3 (2010-09-08 15:22:38) LOG Calling filter:
+org.apache.sling.bgservlets.impl.BackgroundServletStarterFilter
+ 3 (2010-09-08 15:22:38) LOG Calling filter:
+org.apache.sling.portal.container.internal.request.PortalFilter
+ 3 (2010-09-08 15:22:38) LOG Calling filter:
+org.apache.sling.rewriter.impl.RewriterFilter
+ 3 (2010-09-08 15:22:38) LOG Calling filter:
+com.day.cq.wcm.core.impl.WCMRequestFilter
+ 3 (2010-09-08 15:22:38) LOG Calling filter:
+org.apache.sling.i18n.impl.I18NFilter
+ 3 (2010-09-08 15:22:38) LOG Calling filter:
+com.day.cq.theme.impl.ThemeResolverFilter
+ 3 (2010-09-08 15:22:38) LOG Calling filter:
+com.day.cq.wcm.foundation.forms.impl.FormsHandlingServlet
+ 3 (2010-09-08 15:22:38) LOG Calling filter:
+org.apache.sling.engine.impl.debug.RequestProgressTrackerLogFilter
+ 3 (2010-09-08 15:22:38) LOG Calling filter:
+com.day.cq.wcm.mobile.core.impl.redirect.RedirectFilter
+ 3 (2010-09-08 15:22:38) LOG RedirectFilter did not redirect
+(MobileUtil.isMobileResource() returns false)
+ 3 (2010-09-08 15:22:38) LOG Applying inner filters
+ 3 (2010-09-08 15:22:38) LOG Calling filter:
+com.day.cq.wcm.core.impl.WCMComponentFilter
+ 3 (2010-09-08 15:22:38) LOG Calling filter:
+com.day.cq.wcm.core.impl.WCMDebugFilter
+ 3 (2010-09-08 15:22:38)
+TIMER_START{/libs/cq/ui/components/widget/html.jsp#0}
+ ...
+ 8 (2010-09-08 15:22:38) TIMER_END{8,Request Processing} Request Processing
+
+
+<a name="Filters-ConfigStatusplugin"></a>
+### Config Status plugin
+The configuration status page at */system/console/config* includes the
+current list of active filters in its _Servlet Filters_ category, as in
+this example:
+
+<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>Config Status plugin info</B></DIV><DIV class="codeContent panelContent">
+ Current Apache Sling Servlet Filter Configuration
+
+ Request Filters:
+ -2147483648 : class
+org.apache.sling.bgservlets.impl.BackgroundServletStarterFilter (2547)
+ -3000 : class
+org.apache.sling.portal.container.internal.request.PortalFilter (2562)
+ -2500 : class org.apache.sling.rewriter.impl.RewriterFilter (3365)
+ -2000 : class com.day.cq.wcm.core.impl.WCMRequestFilter (2548)
+ -700 : class org.apache.sling.i18n.impl.I18NFilter (2334)
+ -600 : class com.day.cq.theme.impl.ThemeResolverFilter (2244)
+ -600 : class com.day.cq.wcm.foundation.forms.impl.FormsHandlingServlet
+(2268)
+ 0 : class
+org.apache.sling.engine.impl.debug.RequestProgressTrackerLogFilter (2402)
+ 1000 : class com.day.cq.wcm.mobile.core.impl.redirect.RedirectFilter (3363)
+
+ Error Filters:
+ ---
+
+ Include Filters:
+ -200 : class com.day.cq.wcm.core.impl.WCMComponentFilter (2583)
+ 1000 : class com.day.cq.wcm.core.impl.WCMDebugFilter (2449)
+
+ Forward Filters:
+ -200 : class com.day.cq.wcm.core.impl.WCMComponentFilter (2583)
+ 1000 : class com.day.cq.wcm.core.impl.WCMDebugFilter (2449)
+
+ Component Filters:
+ -200 : class com.day.cq.wcm.core.impl.WCMComponentFilter (2583)
+ 1000 : class com.day.cq.wcm.core.impl.WCMDebugFilter (2449)
+
+
+The first numbers on those lines are the filter priorities, and the last
+number in parentheses is the OSGi service ID.
+
+
+<a name="Filters-SupportinSlingEngine2.1.0"></a>
+## Support in Sling Engine 2.1.0
+
+Up to and including Sling Engine 2.1.0 support for Servlet Filters has been
+as follows:
+
+* Any *javax.servlet.Filter* service is accepted as a filter for Sling
+unless the *pattern* property used by the [Apache Felix HttpService whiteboard support](http://felix.apache.org/site/apache-felix-http-service.html#ApacheFelixHTTPService-UsingtheWhiteboard)
+ is set in the service registration properties.
+* The *filter.scope* property is optional and supports the case-sensitive
+values *request* and *component*.
+* Filter ordering is defined by the *filter.order* property whose default
+value is *Integer.MAX_VALUE* where smaller values have higher priority
+over higher values.
Added: sling/site/trunk/content/form-based-authenticationhandler.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/form-based-authenticationhandler.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/form-based-authenticationhandler.mdtext (added)
+++ sling/site/trunk/content/form-based-authenticationhandler.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,219 @@
+Title: Form Based AuthenticationHandler
+<a name="FormBasedAuthenticationHandler-FormBasedAuthenticationHandler"></a>
+# Form Based AuthenticationHandler
+
+{toc:type=flat|separator=pipe|minLevel=2|maxLevel=3}
+
+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.
+
+The implementation of the Form Based Authentication Handler follows the
+guidelines of the Servlet API 2.4 specification for _Form Based
+Authentication_ in section SRV.12.5.3. Specifically the following
+requirements are implemented:
+
+* For the initial form submission, the request URL must end with
+*/j_security_check* and the user name and password names must be
+*j_username* and *j_password*, resp.
+* The authentication type as returned by
+*HttpServletRequest.getAuthType()* is set to
+*HttpServletRequest.FORM_AUTH*.
+
+The Form Based Authentication Handler is maintained in the [Sling SVN](http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/form)
+
+
+<a name="FormBasedAuthenticationHandler-AuthenticationHandlerimplementation"></a>
+### AuthenticationHandler implementation
+
+
+* *extractCredentials* -- Prepares credentials for the form entered data
+or from the Cookie or HTTP Session attribute. Returns *null* if neither
+data is provided in the request
+* *requestCredentials* -- Redirects the client (browser) to the login
+form
+* *dropCredentials* -- Remove the Cookie or remove the HTTP Session
+attribute
+
+
+<a name="FormBasedAuthenticationHandler-AuthenticationFeedbackHandlerimplementation"></a>
+### AuthenticationFeedbackHandler implementation
+
+* *authenticationFailed* -- Remove the Cookie or remove the HTTP Session
+attribute
+* *authenticationSucceeded* -- Set (or update) the Cookie or HTTP Session
+attribute
+
+
+<a name="FormBasedAuthenticationHandler-Phase1:FormSubmission"></a>
+### Phase 1: Form Submission
+
+
+The login form submitted in phase 1 to validate the user name and password
+must be provided in an HTTP *POST* request to an URL whose last segment
+is *j_security_check*. The request is ignored as a form submission if
+either the method is not *POST* or the last segment is no
+*j_security_check*.
+
+The form is rendered by redirecting the client to the URL indicated by the
+*form.login.form* configuration parameter. This redirection request may
+accompanyied by the following parameters:
+
+* *resource* -- The resource to which the user should be redirected after
+successful login. This request parameter should be submitted back to the
+server as the *resource* parameter.
+* *j_reason* -- This parameter indicates the reason for rendering the
+login form. If this parameter is set, it is set to *INVALID_CREDENTIALS*
+indicating a previous form submission presented invalid username and
+password or *TIMEOUT* indicating a login session has timed out. The login
+form servlet/script can present the user with an appropriate message.
+
+The Form Based Authentication Handlers supports the following request
+parameters submitted by the HTML form:
+
+* *j_username* -- Name of the user to authenticate
+* *j_password* -- Password to authenticate the user
+* *j_validate* -- Flag indicating whether to just validate the
+credentials
+* *resource* -- The location to go to on successful login
+* *sling.auth.redirect* -- The location to redirect to on successful
+login
+
+The *j_username* and *j_password* parameters are used to create a JCR
+*SimpleCredentials* object to log into the JCR Repository.
+
+The *j_validate* parameter may be used to implement login form submission
+using AJAX. If this parameter is set to *true* (case-insensitive) the
+credentials are used to login and after success or failure to return a
+status code:
+
+<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>
+
+If the *j_validate* parameter is not set or is set to any value other
+than *true*, the request processing depends on authentication success or
+failure:
+
+<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>
+
+The *resource* and *sling.auth.redirect* parameters provide similar
+functionality but with differing historical backgrounds. The *resource*
+parameter is based on the *resource* 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 *sling.auth.redirect*
+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 *sling.auth.redirect* parameter takes precedence.
+
+The Form Based Authentication Handler contains a [default form servlet](http://http://svn.apache.org/repos/asf/sling/trunk/bundles/auth/form/src/main/java/org/apache/sling/auth/form/impl/AuthenticationFormServlet.java)
+ 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]
+.
+
+
+<a name="FormBasedAuthenticationHandler-Phase2:AuthenticatedRequests"></a>
+### Phase 2: Authenticated Requests
+
+
+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:
+
+
+ HmacSHA1(securetoken,
+<securetokennumber><expirytime>@<userID>)@<securetokennumber><expirytime>@<userID>
+
+
+The *securetoken* and *securetokennumber* are related in that an table
+of secure tokens is maintained where the *securetoken* is an entry in the
+table and the *securetokennumber* is the index in of the token in the
+table.
+
+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:
+
+ * 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.
+ * 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.
+
+The authentication state may be transmitted with a Cookie which is
+configured as follows:
+
+* *Cookie Path* -- Set to the servlet context path
+* *Domain* -- See below
+* *Age* -- Set to -1 to indicate a session Cookie
+* *Secure* -- Set to the value returned by the
+*ServletRequest.isSecure()* method
+
+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.
+
+
+<a name="FormBasedAuthenticationHandler-Configuration"></a>
+### Configuration
+
+The Form Based Authentication Handler is configured with configuration
+provided by the OSGi Configuration Admin Service using the
+*org.apache.sling.formauth.FormAuthenticationHandler* service PID.
+
+<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>
+
+_Note:_ The *form.token.file* 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 *sling.home* framework
+property or -- if *sling.home* is not set -- the current working
+directory. In the future this file may be store in the JCR Repository to
+support clustering scenarios.
+
+
+<a name="FormBasedAuthenticationHandler-SecurityConsiderations"></a>
+### Security Considerations
+
+Form Based Authentication has some limitations in terms of security:
+
+1. User name and password are transmitted in plain text in the initial form
+submission.
+1. The Cookie used to provide the authentication state or the HTTP Session
+ID may be stolen.
+
+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.
Added: sling/site/trunk/content/getting-and-building-sling.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/getting-and-building-sling.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/getting-and-building-sling.mdtext (added)
+++ sling/site/trunk/content/getting-and-building-sling.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,315 @@
+Title: Getting and Building Sling
+<a name="GettingandBuildingSling-GettingandBuildingSling"></a>
+# Getting and Building Sling
+{excerpt}A quick guide for getting the Sling source, then building and
+running the resulting Sling instance; either without or with
+Eclipse.{excerpt}
+
+Sling can easily be built:
+* from the command line (using SVN and the Maven command line tool)
+* or using Eclipse
+
+Note that you don't _have_ to build Sling yourself, if you don't need the
+bleeding-edge stuff you can get prebuilt binaries from the [Downloads](downloads.html)
+ page.
+
+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.
+
+<a name="GettingandBuildingSling-Prerequisites"></a>
+## Prerequisites
+
+Before you begin, you need to have the following tools installed on your
+system:
+* Java 5 or higher; Java 6 recommended
+* [Maven](http://maven.apache.org)
+ 3.0.2 or later; enforced by the Sling parent pom
+
+If you want to set up Eclipse (not required to build Sling) you'll also
+need the following installed:
+* 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)
+* M2Eclipse plugin for Eclipse (sonatype) \-> [instructions](http://m2eclipse.sonatype.org/installing-m2eclipse.html)
+* [Subversive plugin](http://www.polarion.com/products/svn/subversive.php)
+ or [Subclipse-plugin|http://subclipse.tigris.org]
+ for Eclipse
+
+<a name="GettingandBuildingSling-EnvironmentSetup"></a>
+## Environment Setup
+
+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.
+
+
+<a name="GettingandBuildingSling-JavaHeapSpace"></a>
+### Java Heap Space
+
+* *Problem* \- Build aborts with reports of {{java.lang.OutOfMemoryError:
+Java heap space}}. Alternatively the build may randomly fail during the
+integration tests.
+* *Platforms* \- This happens on all platforms
+* *Fix* \- Increase the values of the maximum heap and perm space for the
+build by setting or extending the *MAVEN_OPTS* environment variable.
+
+For 32bit platforms you should use
+
+ MAVEN_OPTS="-Xmx256M -XX:MaxPermSize=256m"
+
+
+For 64bit platforms, you should use
+
+ MAVEN_OPTS="-Xmx512M -XX:MaxPermSize=512m"
+
+
+For more information see [SLING-443](https://issues.apache.org/jira/browse/SLING-443)
+ and [SLING-1782|https://issues.apache.org/jira/browse/SLING-1782]
+.
+
+
+<a name="GettingandBuildingSling-EnvironmentVariableSpace"></a>
+### Environment Variable Space
+
+* *Problem* \- Build aborts when trying to launch the integration tests
+with the message
+
+ [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
+
+ error=12, Not enough space
+
+This problem is caused by insufficient swap space. When running the
+integration tests in the *launchpad/testing* modules, a process is
+launched by calling the *exec* 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.
+* *Platform* \- OpenSolaris
+* *Fix* \- If this issue persists you will need to check your system
+requirements and configuration with regard to swap, before taking action -
+if necessary.
+
+<a name="GettingandBuildingSling-ConfiguringMaven"></a>
+## Configuring Maven
+
+See [MavenTipsAndTricks](maventipsandtricks.html)
+.
+
+
+<a name="GettingandBuildingSling-GettingtheSlingSource"></a>
+## Getting the Sling Source
+
+
+<a name="GettingandBuildingSling-WithSVN"></a>
+### With SVN
+
+1. Checkout Sling from the Repository.
+
+ $ svn checkout http://svn.apache.org/repos/asf/sling/trunk sling
+
+
+<a name="GettingandBuildingSling-WithEclipseSubversiveorSubclipse"></a>
+### With Eclipse Subversive or Subclipse
+First note how simple the above SVN instructions are...but if you _really_
+want to do this, read on.
+
+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: [http://community.polarion.com/projects/subversive/download/integrations/update-site/](http://community.polarion.com/projects/subversive/download/integrations/update-site/)
+.
+
+Also, make sure that you have installed either the "Maven SCM handler for
+Subclipse" or the "Maven SCM handler for Subversive".
+
+<a name="GettingandBuildingSling-Createanewworkspace"></a>
+#### Create a new workspace
+
+It's best to create a new workspace for the sling project:
+1. Menu: File->Switch Workspace->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->Build Automatically)
+1. Go to menu: Eclipse->Preferences, in the preferences dialog select Java
+\-> Compiler \-> Errors/Warnings
+1. Expand the "Deprecated and restricted API" and change "Forbidden
+references (access rules)" from "Error" to "Warning"
+1. Click OK
+
+<a name="GettingandBuildingSling-CheckouttheSlingsource"></a>
+#### Checkout the Sling source
+
+1. Menu: File->Import
+1. In the Import wizard select Maven->"Check out Maven Projects from SCM"
+1. Click next
+1. In the "SCM URL" field pick "SVN" and enter the url
+"http://svn.apache.org/repos/asf/sling/trunk"
+1. Click Finish
+
+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)\!
+
+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->Revert... menu
+1. A couple of changes will be displayed
+1. Click OK
+
+<a name="GettingandBuildingSling-BuildingSling"></a>
+## Building Sling
+
+
+<a name="GettingandBuildingSling-WiththeMavencommandlinetool"></a>
+### With the Maven command line tool
+
+1. Enter the directory, then do a full build and local install (below are
+unix/linux commands, slightly different under windows)
+
+ $ cd sling
+ $ export MAVEN_OPTS="-Xmx256m -XX:MaxPermSize=128m"
+ $ mvn -s /dev/null clean install
+
+Note: On windows just leave out */dev/null* and make sure you have an
+empty settings.xml file for maven (located in your user directory under
+.m2).
+1. Enter the *launchpad/builder* directory and launch Sling for the first
+time
+
+ $ cd launchpad/builder
+ $ java -jar target/org.apache.sling.launchpad-*-standalone.jar -c test -f -
+
+
+{note}
+When starting Sling inside the *launchpad/builder* folder you should not
+use the default Sling Home folder name *sling* because this folder is
+removed when running *mvn clean*.
+{note}
+
+Messages should now be printed to the console which is being used as the
+"log file"; the *\-f* command line option is set to *\-*, indicating
+the use of standard output as the log file. The *\-c sling* command line
+option instructs Sling to use the *sling* 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 [Configuration](configuration.html)
+ for more information).
+Use the *-h* 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 {{[http://localhost:8080/system/console](http://localhost:8080/system/console)
+}}. You will be prompted for a user name and password. Enter *admin* for
+both the user name and the password (this may be set on the _Configuration_
+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 *Ctrl-C* in the console or click the _Stop_
+button on the _System Information_ page of the Sling Management Console.
+
+<a name="GettingandBuildingSling-WithM2Eclipse"></a>
+### With M2Eclipse
+
+1. Make sure you're in the Java perspective (Menu: Window->Open Perspective)
+1. Menu: Run->Run Configurations...
+1. In the Run Configurationa dialog right-click on "Maven Build" and select
+"New"
+1. Change Name to "Build Sling"
+1. Click "Browse Workspace..." and select "sling-builder"
+1. Enter "clean install" in Goals
+1. Click on the JRE tab
+1. Enter "-Xmx256m \-XX:MaxPermSize=128m" in "VM arguments"
+1. Click Apply
+1. Click Run
+
+<a name="GettingandBuildingSling-AlternativesetupinEclipsewithoutM2Eclipseplugin"></a>
+### Alternative setup in Eclipse without M2Eclipse plugin
+
+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 *src/main/java* and *src/test/java* 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
+
+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.
+
+Congratulations \! You should now have a running Sling instance, that you
+can start playing around with.
+
+<a name="GettingandBuildingSling-FurtherTipsandTricks"></a>
+## Further Tips and Tricks
+
+
+<a name="GettingandBuildingSling-DebugSlinginEclipse"></a>
+### Debug Sling in Eclipse
+
+You can use remote debugging to debug Sling in Eclipse, here's a little
+How-To
+1. start Sling from the command line with
+
+ java -Xmx384M
+-agentlib:jdwp=transport=dt_socket,address=30303,server=y,suspend=n -jar
+org.apache.sling.launchpad.app-6-SNAPSHOT.jar
+
+1. Open Menu Run-> Debug configurations
+1. Right-click on "Remote Java Applications"
+1. Choose "New"
+1. In the "Connect" tab choose the Eclipse Sling Project for the field
+"Project" with the browse button
+1. Let the Connection type be "Standard (Socket Attach)"
+1. The host should be localhost
+1. Set the Port to 30303
+1. On the source tab click the "Add" button
+1. Select "Java Project"
+1. Select all Sling projects and click OK
+1. Click "Debug"
+
+Now you should be able to set breakpoints, evaluate properties, and so on
+as usual.
+
+<a name="GettingandBuildingSling-DebugMavenTestsinEclipse"></a>
+### Debug Maven Tests in Eclipse
+
+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
+
+ mvn -Dmaven.surefire.debug test
+
+
+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"
+> "Open Debug Dialog..." (see above).
+For more information on this see the [Maven Surefire Docu](http://maven.apache.org/plugins/maven-surefire-plugin/examples/debugging.html)
+.
+
+
+<a name="GettingandBuildingSling-SimplewaytodevelopnewbundleinEclipseforSling"></a>
+### Simple way to develop new bundle in Eclipse for Sling
+
+The easiest way that I found is to create a new folder in the existing
+Eclipse workspace. After that you can follow these steps:
+* Start by copying and adapting an existing Sling pom.xml (eg. the pom.xml
+from the espblog sample)
+* Generate the Eclipse project files using mvn eclipse:eclipse
+* Choose File/Import in Eclipse and select "Existing projects into
+workspace"
+* Now you can create, edit and compile the files in Eclipse
+* To create the bundle jar and install it, just use the command line "mvn
+clean install" in the project directory
+* If you have a running Sling app you can install the bundle from the command line with "mvn \-P autoInstallBundle clean install \-Dsling.url=[http://localhost:8080/system/console](http://localhost:8080/system/console)
+"
+
+If adding dependencies to the poms, run mvn eclipse:eclipse again and
+refresh the project in Eclipse. Debugging works as described above.
Added: sling/site/trunk/content/getting-resources-and-properties-in-sling.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/getting-resources-and-properties-in-sling.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/getting-resources-and-properties-in-sling.mdtext (added)
+++ sling/site/trunk/content/getting-resources-and-properties-in-sling.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,121 @@
+Title: Getting Resources and Properties in Sling
+<a name="GettingResourcesandPropertiesinSling-GettingResourcesandPropertiesinSling"></a>
+# Getting Resources and Properties in Sling
+
+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.
+
+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.
+
+The whole game consists in first getting a *ResourceResolver* and then
+getting the *Resource* itself.
+
+<a name="GettingResourcesandPropertiesinSling-WithinanOSGIService/Compoment"></a>
+## Within an OSGI Service/Compoment
+
+You can access a resource through the *ResourceResolverFactory* service:
+
+
+ /** @scr.reference */
+ private ResourceResolverFactory resolverFactory;
+
+ public void myMethod() {
+ try {
+ String resourcePath = "path/to/resource";
+ ResourceResolver resourceResolver =
+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
+ }
+ }
+
+
+
+<a name="GettingResourcesandPropertiesinSling-WithinaServlet"></a>
+## Within a Servlet
+
+You can access the resource defined by the request URL through the
+*SlingHttpServletRequest*:
+
+
+ Resource res = req.getResource();
+ // req is the SlingHttpServletRequest
+
+
+You can access any resource by first accessing the *ResourceResolver*:
+
+
+ String resourcePath = "path/to/resource";
+ ResourceResolver resourceResolver = req.getResourceResolver();
+ // req is the SlingHttpServletRequest
+ Resource res = resourceResolver.getResource(resourcePath);
+
+
+<a name="GettingResourcesandPropertiesinSling-WithinaJSPfile"></a>
+## Within a JSP file
+
+When you use the *<sling:defineObjects>* tag in a JSP file, you have
+access to a few handy objects, one of them is *resource*, the resource
+that is resolved from the URL. Another one is *resourceResolver*, the
+*ResourceResolver* defined through the *SlingHttpServletRequest*.
+
+To access a resource:
+
+
+ <sling:defineObjects>
+ <%
+ String resourcePath = "path/to/resource";
+ Resource res = resourceResolver.getResource(resourcePath);
+ %>
+
+
+If needed you can adapt a Sling Resource to a JCR Node:
+
+
+ Node node = resource.adaptTo(Node.class);
+
+
+Note: *resource.adaptTo(Node.class)* may return null if the resource is
+not backed by a JCR node. This is particularly the case for
+*NonExistingResource* resources or resource provided by a non-JCR
+resource provider.
+
+<a name="GettingResourcesandPropertiesinSling-AccessingaProperty"></a>
+## Accessing a Property
+
+The *ValueMap* is an easy way to access properties of a resource. With
+most resources you can use *Adaptable.adaptTo(Class)* to adapt the
+resource to a value map:
+
+
+ ValueMap properties = res.adaptTo(ValueMap.class);
+ // res is the Resource
+
+
+You can also access the properties through the *ResourceUtil* utility
+class:
+
+
+ ValueMap properties = ResourceUtil.getValueMap(res);
+ // res is the Resource
+
+
+Then, to access a specific String property called *propName*:
+
+
+ String rule = properties.get(propName, (String) null);
+
+
+For more details about resources and how to access them in Sling, you can
+refer to the [Sling documentation about Resources](http://sling.apache.org/site/resources.html)
+.
Added: sling/site/trunk/content/getting-started.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/getting-started.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/getting-started.mdtext (added)
+++ sling/site/trunk/content/getting-started.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,28 @@
+Title: Getting Started
+<a name="GettingStarted-GettingStarted"></a>
+# Getting Started
+
+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:
+
+{children:all=true}
+
+<a name="GettingStarted-Wheretoheadfromhere"></a>
+## Where to head from here
+
+We recommend you read through following topics to get as fast as possible
+into Sling:
+
+{show-to}
+* What is Sling
+{show-to}
+* [Getting and building Sling](getting-and-building-sling.html)
+* [Architecture](architecture.html)
+* [Dispatching Requests](dispatching-requests.html)
+* [Resources](resources.html)
+* [Setting up an Sling-Project with Eclipse](http://cwiki.apache.org/SLING/setting-up-eclipse-34-for-sling.html)
+* [Manipulating Content - The SlingPostServlet (servlets.post)](manipulating-content---the-slingpostservlet-(servlets.post).html)
+* [Request Parameters](request-parameters.html)
+* [Authentication](authentication.html)
+* [Eventing and Jobs](eventing-and-jobs.html)
Added: sling/site/trunk/content/groovy-support.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/groovy-support.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/groovy-support.mdtext (added)
+++ sling/site/trunk/content/groovy-support.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,97 @@
+Title: Groovy Support
+{excerpt:hidden=true}
+Explains how to add support for Groovy to Apache Sling.
+{excerpt}
+
+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 *groovy-all.jar* as an OSGi
+Bundle, which is directly usable with Sling by just installing that bundle.
+
+Currently the Groovy team is working hard towards the 1.6 release and many
+things are in flux, which is really great.
+
+So, on 11. Dec. 2008 Paul King of the Groovy Team has deployed a [first RC1 Snapshot of Groovy 1.6](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)
+ which contains all the required OSGi bundle manifest headers as well das
+the JSR-233 *ScriptEngine* to use the *groovy-all.jar* 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.
+
+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: {{[groovy-all-1.7-beta-1-20081210.120632-2.jar](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)
+}}.
+
+
+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 _Start_ check box and
+click _Install or Update_ button.
+
+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:
+
+
+ Groovy Scripting Engine, 2.0
+ Language Groovy,
+ Extensions groovy
+ MIME Types application/x-groovy
+ Names groovy, Groovy
+
+
+
+<a name="GroovySupport-Testing"></a>
+## Testing
+
+To test create a simple Groovy script, for example
+
+
+ response.setContentType("text/plain");
+ response.setCharacterEncoding("UTF-8");
+
+ println "Hello World !"
+ println "This is Groovy Speaking"
+ println "You requested the Resource ${resource} (yes, this is a GString)"
+
+
+and upload it to the repository as */apps/nt/folder/GET.groovy* using
+your favourite WebDAV client or use curl to upload the file (assuming Sling
+is running on localhost:8888) :
+
+
+ $ curl -u admin:admin -FGET.groovy=@GET.groovy
+-F../../nt/jcr:primaryType=sling:Folder http:host:8888/apps/nt/folder
+
+
+To test it create a */sample* *nt:Folder* node using your favourite
+WebDAV client or use curl again:
+
+
+ $ curl -u admin:admin -Fjcr:primaryType=nt:folder http://localhost:8888/
+
+
+
+Finally, request the */sample* node using your favourite Browser or use
+curl again:
+
+
+ $ curl http://localhost:8888/sample
+ Hello World !
+ This is Groovy Speaking
+ You requested Resource JcrNodeResource, type=nt:folder, path=/sample (yes,
+this is a GString)
+
+
+
+<a name="GroovySupport-References"></a>
+## References
+
+* [SLING-315](https://issues.apache.org/jira/browse/SLING-315)
+ -- The initial Sling issue proposing the addition of a Groovy ScriptEngine
+to Sling.
+* [Groovy Support in Apache Sling](http://markmail.org/message/7sqscr5y2mbk6jko)
+ -- A short thread on turning the Groovy *groovy-all.jar* into an OSGi
+Bundle.
+* [Groovy in Apache Sling](http://markmail.org/message/47n2ow2jlo553jvk)
+ -- Thread on adding the *DynamicImport-Package* header to the Groovy
+bundle manifest.
Added: sling/site/trunk/content/guides.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/guides.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/guides.mdtext (added)
+++ sling/site/trunk/content/guides.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,34 @@
+Title: Guides
+These pages contain further information in a more informal way.
+
+ * [Discover Sling in 15 minutes ](discover-sling-in-15-minutes-.html)
+ - title says it all
+
+ * [Resources](resources.html)
+ -- Presents the Resource as the object around which Sling is built
+ * [Servlet Resolution](servlet-resolution.html)
+ -- How Sling resolves the servlet or script responsible for rendering a
+Resource.
+ * [Request Parameters](request-parameters.html)
+ -- Explains how Sling provides request parameters to servlets, scripts and
+filters.
+ * [Repository Based Development](repository-based-development.html)
+ -- Shows how WebDAV is supported by Sling.
+
+ * [Bundle Management](installing-and-upgrading-bundles.html)
+ -- Explains how to install, upgrade and uninstall Bundles using the Sling
+Management console.
+
+
+These pages refer to the old Component API and launcher, and remain
+referred to here until more up to date documentation has been prepared:
+
+ * [Getting and Building Sling](getting-and-building-sling.html)
+ -- A short recount on the first step for getting a running Sling instance
+after checking out the source from the SVN repository
+ * [Default Mapping and Rendering](default-mapping-and-rendering.html)
+ -- Explains default mapping of repository nodes to Content instances and
+selection of a default Component.
+ * [Dispatching Requests](dispatching-requests.html)
+ -- Explains how a Component may dispatch requests to include further
+content renderings in the response to the client's request
Added: sling/site/trunk/content/how-to-manage-events-in-sling.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/how-to-manage-events-in-sling.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/how-to-manage-events-in-sling.mdtext (added)
+++ sling/site/trunk/content/how-to-manage-events-in-sling.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,261 @@
+Title: How to Manage Events in Sling
+<a name="HowtoManageEventsinSling-HowtoManageEventsinSling"></a>
+# How to Manage Events in Sling
+
+Apache Sling provides some mechanisms and support for managing events.
+
+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).
+
+For more details please refer to the following resources:
+* [Eventing, Jobs and Scheduling section](http://sling.apache.org/site/eventing-and-jobs.html)
+ to get detailed information on the eventing mechanisms in Sling.
+* package [org.osgi.service.event](http://www.osgi.org/javadoc/r4v42/org/osgi/service/event/package-summary.html)
+ of the OSGI API.
+* package [org.apache.sling.event](http://sling.apache.org/apidocs/sling6/org/apache/sling/event/package-summary.html)
+ of the Sling API.
+
+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.
+
+<a name="HowtoManageEventsinSling-Introduction"></a>
+## Introduction
+
+You will now implement the logic to listen to files posted to
+*/tmp/dropbox* and to move them to the appropriate locations depending on
+the MIME type:
+* images (.png) are moved to */dropbox/images/*
+* music (.mp3) are moved to */dropbox/music/*
+* movies (.avi) are moved to */dropbox/movies/*
+* otherwise the files are moved to */dropbox/other/*
+
+To do that, you will implement two services. The first one, called
+*DropBoxService*:
+* Listens to OSGI events.
+* Sends a job event if a resource has been added to */tmp/dropbox*.
+
+The second one, called *DropBoxEventHandler*:
+* Listens to the former job event.
+* Moves the file according to its extension.
+
+<a name="HowtoManageEventsinSling-ListeningtoOSGIEvents"></a>
+## Listening to OSGI Events
+
+To listen to the specific OSGI event *"resource added"*:
+* The property *event.topics* needs to be set to
+*org.apache.sling.api.SlingConstants.TOPIC_RESOURCE_ADDED* in the class
+annotations.
+
+
+ * @scr.property name="event.topics"
+valueRef="org.apache.sling.api.SlingConstants.TOPIC_RESOURCE_ADDED"
+
+
+You can refer to the [org.apache.sling.api.SlingConstants](http://sling.apache.org/apidocs/sling6/org/apache/sling/api/SlingConstants.html)
+ class in the Javadocs to know about other events available in Sling.
+
+<a name="HowtoManageEventsinSling-SendingJobEvents"></a>
+## Sending Job Events
+
+To send a job event the service needs to implement:
+* the *org.osgi.service.event.EventHandler* interface.
+* the *org.apache.sling.event.JobProcessor* interface.
+
+
+ public class DropBoxService implements JobProcessor, EventHandler {
+
+
+To send the job event the Event Admin service needs to be referenced:
+
+ /**
+ * The OSGI event admin used for sending events
+ * @scr.reference
+ */
+ private EventAdmin eventAdmin;
+
+
+The job topic for dropbox job events needs to be defined:
+
+ /** The job topic for dropbox job events. */
+ public static final String JOB_TOPIC =
+"com/sling/eventing/dropbox/job";
+
+
+The *org.osgi.service.event.EventHandler#handleEvent(Event event)* method
+needs to be implemented:
+
+ public void handleEvent(Event event) {
+ if (EventUtil.isLocal(event)) {
+ EventUtil.processJob(event, this);
+ }
+ }
+
+
+The *org.apache.sling.event.JobProcessor#process(Event event)* method needs
+to be implemented.
+
+Its logic is as follows:
+* The OSGI event is analyzed.
+* If the event is a file that has been added to */tmp/dropbox*:
+** An event is created with 2 properties:
+*** A property to set the event as a job event.
+*** A property for the file path.
+** The job event is sent to all the listeners that subscribe to the topic
+of the event.
+
+
+ public boolean process(Event event) {
+ String propPath = (String)
+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") &&
+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;
+ }
+
+
+The complete code for the *DropBoxService* service is available [here](^dropboxservice.java.html)
+.
+
+<a name="HowtoManageEventsinSling-ListeningtoJobEvents"></a>
+## Listening to Job Events
+
+Now that you have implemented a service that sends a job event when a file
+is uploaded to */tmp/dropbox*, you will implement the service
+*DropBoxEventHandler* that listens to those job events and moves the files
+to a location according to their MIME types.
+
+To listen to the job events that have been defined before:
+* The property *event.topics* needs to be set to
+*mypackage.DropBoxService.JOB_TOPIC* in the class annotations.
+
+
+ * @scr.property name="event.topics"
+valueRef="mypackage.DropBoxService.JOB_TOPIC"
+
+
+<a name="HowtoManageEventsinSling-HandlingJobEvents"></a>
+## Handling Job Events
+
+To move the files the service needs to implement:
+* the *org.osgi.service.event.EventHandler* interface.
+* the *org.apache.sling.event.JobProcessor* interface.
+
+
+ public class DropBoxEventHandler implements JobProcessor, EventHandler {
+
+
+Some class fields need to be defined for:
+* The default log.
+* The references to the SlingRepository and the JcrResourceResolverFactory
+services, which are used in the implementation.
+* The destination paths of the files.
+
+ {code}
+ /** Default log. */
+ protected final Logger log = LoggerFactory.getLogger(this.getClass());
+
+ /** @scr.reference */
+ private SlingRepository repository;
+
+ /**
+ * @scr.reference
+ */
+ private JcrResourceResolverFactory resolverFactory;
+
+ private final static String IMAGES_PATH = "/dropbox/images/";
+ private final static String MUSIC_PATH = "/dropbox/music/";
+ private final static String MOVIES_PATH = "/dropbox/movies/";
+ private final static String OTHER_PATH = "/dropbox/other/";
+
+
+ The *org.osgi.service.event.EventHandler#handleEvent(Event event)* method
+needs to be implemented:
+
+ public void handleEvent(Event event) {
+ if (EventUtil.isLocal(event)) {
+ EventUtil.processJob(event, this);
+ }
+ }
+
+
+ The *org.apache.sling.event.JobProcessor#process(Event event)* method needs
+to be implemented.
+
+ Its logic is as follows:
+ * The resource path is extracted from the job event property.
+ * The resource is obtained from the resource path.
+ * If the resource is a file, the destination path is defined based on the
+file MIME type.
+ * The file is moved to the new location.
+
+
+ public boolean process(Event event) {
+ Session adminSession = null;
+ try {
+ String resourcePath = (String)
+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 && adminSession.isLive()) {
+ adminSession.logout();
+ adminSession = null;
+ }
+ }
+ }
+
+
+ The complete code for the *DropBoxEventHandler* service is available [here|^DropBoxEventHandler.java]
+.
Added: sling/site/trunk/content/installing-and-upgrading-bundles.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/installing-and-upgrading-bundles.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/installing-and-upgrading-bundles.mdtext (added)
+++ sling/site/trunk/content/installing-and-upgrading-bundles.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,151 @@
+Title: Installing and Upgrading Bundles
+<a name="InstallingandUpgradingBundles-InstallingandUpgradingBundles"></a>
+# Installing and Upgrading Bundles
+
+{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 [Apache Felix Web Console](http://felix.apache.org/site/apache-felix-web-console.html)
+.
+{note}
+
+{excerpt:hidden=true}Explains how to install, upgrade and uninstall Bundles
+using the Sling Management console.{excerpt}
+
+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.
+
+Basically, you have two choices to install and upgrade bundles: Upload the
+bundle files or install them from a Bundle Repository.
+
+
+
+<a name="InstallingandUpgradingBundles-SlingManagementConsole"></a>
+## Sling Management Console
+
+The Sling Management Console is installed by default when Sling is running
+and may be reached at on the page */system/console* in the Sling Context
+by default. For example if you installed the Sling Web Application in the
+*/sample* context of the Servlet Container running at
+*http**://somehost:4402*, you would access the Sling Management Console
+at *http**://somehost:4402/sample/system/console*.
+
+You will be prompted for a user name and password to access the Sling
+Management Console. This password is preset to be _admin_ for the user name
+and _admin_ for the password.
+
+NB: Both the username and password and the location of the Sling Management
+Console inside the Web Application Context is configurable in the _Sling
+Management Console_ configuration on the _Configuration_ page.
+
+
+
+<a name="InstallingandUpgradingBundles-InstallingandupgradingbundlesbyUpload"></a>
+## Installing and upgrading bundles by Upload
+
+To install a new bundle or upgrade an already installed bundle, go to the
+_Bundles_ 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 :
+
+ * Select the bundle file to upload
+ * Click the _Start_ checkbox, if you want to start the bundle after
+installation. If the bundle is upgraded, this checkbox is ignored.
+ * Specify the start level of the bundle in the _Start Level_ 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.
+ * Click the _Install or Update_ button
+
+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.
+
+After having updated a bundle, you should also refresh the packages by
+clicking on the _Refresh Packages_ 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.
+
+Also, if you plan to upgrade multiple bundles, you may wish to upgrade all
+bundles before repackaging the using bundles.
+
+
+
+<a name="InstallingandUpgradingBundles-InstallingandupgradingbundlesfromtheBundleRepository"></a>
+## Installing and upgrading bundles from the Bundle Repository
+
+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.
+
+Say you wish to install bundle _X_ which depends on packages provided by
+bundle _Y_. When uploading bundle _X_ as a file it will not resolve, that
+is Sling (the OSGi framework actually) is not able to ensure proper
+operation of bundle _X_ and thus prevents the bundle from being started and
+used. You will have to manually upload bundle _Y_ yourself. When using the
+OSGi Bundle Repository, you just select bundle _X_ for installation and the
+bundle repository will find out, that bundle _Y_ is also required and will
+automatically download and install it along with bundle _X_.
+
+
+<a name="InstallingandUpgradingBundles-TheBundleRepositorypage"></a>
+### The Bundle Repository page
+
+Installation or update of bundles may be done on the _Bundle Repository_
+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 _Deploy Selected_ or _Deploy and Start
+Selected_ button at the bottom of the page depending on whether you want to
+start the bundle(s) after installation or not.
+
+See below for more information on OSGi Bundle Repository management.
+
+
+
+<a name="InstallingandUpgradingBundles-TheBundlespage"></a>
+### The Bundles page
+
+You may also want to upgrade already installed bundles from the _Bundles_
+page of the Sling Management Console. For each bundle listed in this page,
+there is an _Upgrade_ 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.
+
+
+
+<a name="InstallingandUpgradingBundles-ManagingOSGiBundleRepositories"></a>
+### Managing OSGi Bundle Repositories
+
+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 _Refresh_ 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 _Refresh_ button.
+
+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
+*action* whose value must be *refreshOBR* and *repository* whose
+value must be the URL to the repository descriptor file generally called
+*repository.xml*.
+
+For example, if you run Sling on *http**://localhost:7402/sample* with
+default location of the Sling Management Console, the following request
+would add a repository at */tmp/repo/repository.xml* in the filesystem:
+
+
+ http://localhost:7402/sample/system/console/bundlerepo?action=refreshOBR&repository=file:///tmp/repo/repository.xml
+
+
+Note: Only use *file:* URLs if you know Sling has access to the named
+file !
Added: sling/site/trunk/content/issue-tracker.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/issue-tracker.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/issue-tracker.mdtext (added)
+++ sling/site/trunk/content/issue-tracker.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,123 @@
+Title: Issue Tracker
+Apache Sling uses Jira for tracking bug reports and requests for
+improvements, new features, and other changes.
+
+The issue tracker is available at
+https://issues.apache.org/jira/browse/SLING and is readable by everyone. A
+Jira account is needed to create new issues and to comment on existing
+issues. Use the [registration form](https://issues.apache.org/jira/secure/Signup!default.jspa)
+ to request an account if you do not already have one.
+
+See below for guidelines on creating and managing issues.
+
+
+<a name="IssueTracker-Issuetype"></a>
+## Issue type
+
+When creating a new issue, select the issue type based as follows:
+
+<table>
+<tr><th> Issue type </th><th> Description </th></tr>
+<tr><td> *Bug* </td><td> Bug reports are used for cases where Sling fails not
+function as it should (as defined by some documentation). If you are not
+certain whether the issue you've found is actually a bug, please ask the [Sling mailing lists](project-information#projectinformation-mailinglists.html)
+ first for help. </td></tr>
+<tr><td> *New Feature* </td><td> Use a feature request when Sling does not have some
+functionality you need. </td></tr>
+<tr><td> *Improvement* </td><td> Use an improvement request to suggest improvements to
+existing features. Typical improvement requests are about updating
+documentation, increasing stability and performance, simplifying the
+implementation, or other such changes that make Sling better without
+introducing new features or fixing existing bugs. </td></tr>
+<tr><td> *Test* </td><td> Use this type when contributing test cases for
+existing features. Normally test cases should be contributed as a part of
+the original feature request or as regression tests associated with bug
+reports, but sometimes you just want to extend test coverage by introducing
+new test cases. This issue type is for such cases. </td></tr>
+<tr><td> *Task* </td><td> Used only for issues related to project
+infrastructure. </td></tr>
+</table>
+
+
+<a name="IssueTracker-Summary"></a>
+## Summary
+
+The issue summary should be a short and clear statement that indicates the
+scope of the issue. You are probably being too verbose if you exceed the
+length of the text field. Use the Environment and Description fields to
+provide more detailed information.
+
+
+<a name="IssueTracker-Issuepriority"></a>
+## Issue priority
+
+Issue priority should be set according to the following:
+
+<table>
+<tr><th> Issue priority </th><th> Description </td></tr>
+<tr><td> *Blocker* </td><td> Legal or other fundamental issue that makes it
+impossible to release Jackrabbit code </td></tr>
+<tr><td> *Critical* </td><td> Major loss of functionality that affects many
+Slingusers </td></tr>
+<tr><td> *Major* </td><td> Important issue that should be resolved soon </td></tr>
+<tr><td> *Minor* </td><td> Nice to have issues </td></tr>
+<tr><td> *Trivial* </td><td> Trivial changes that can be applied whenever someone
+has extra time </td></tr>
+</table>
+
+
+
+<a name="IssueTracker-IssueStates"></a>
+## Issue States
+
+Sling issues can transition through a number of states while being
+processed:
+
+<table>
+<tr><th> State </th><th> Description </th><th> Next States in Workflow </th></tr>
+<tr><td> *Open* </td><td> The issue has just been created </td><td> _In Pogress_ </td></tr>
+<tr><td> *In Progress* </td><td> Work has started on the issue </td><td> _Documentation Required_,
+_Testcase Required_, _Documentation/Testcase required_, _Resolved_, _Open_
+</td></tr>
+<tr><td> *Documentation Required* </td><td> Implementation work has finished for this
+issue. To complete it documentation must be created and/or updated. </td><td>
+_Resolved_ </td></tr>
+<tr><td> *Testcase Required* </td><td> Implementation work has finished for this issue. To
+complete it test cases must be created and/or updated. </td><td> _Resolved_ </td></tr>
+<tr><td> *Documentation/Testcase Required* </td><td> Implementation work has finished for
+this issue. To complete it documentation and test cases must be created
+and/or updated. </td><td> _Resolved_, _Documentation Required_, _Testcase Required_
+</td></tr>
+<tr><td> *Resolved* </td><td> The issue has been resolved from the developers point of
+view. Documentation and Testcases have been created and updated as
+required. Issue is ready for release. </td><td> _Reopened_, _Closed_ </td></tr>
+<tr><td> *Reopened* </td><td> A resolved issue has been recognized to contain bugs or to
+be incomplete and thus has been reopened. </td><td> _In Progress_, _Resolved_ </td></tr>
+<tr><td> *Closed* </td><td> Work on this issue has finished and it is included in the
+release. </td><td> -- </td></tr>
+</table>
+
+Users generally create issues and provide feedback while work on the issue
+is in progress. When the developer thinks the issue has been resolved, he
+resolves the issue. At this point, the user may test the resolution and
+reopen the issue if it has not really be solved. Otherwise the user may
+just acknowledge the fix.
+
+Developers transition the issue through the workflow while working on it.
+When done with the issue, they mark the issue resolved with the appropriate
+resolution and ask the reporting user to confirm.
+
+Issues are closed once the project against which it has been reported has
+been released. Issues once closed cannot be opened again. Rather new issues
+should be created against the new release to have broken implementations
+fixed or extended.
+
+
+
+<a name="IssueTracker-Patches"></a>
+## Patches
+
+When reporting a bug, requesting a feature or propose an improvement, it is
+a good thing to attach a patch to the issue. This may speed up issue
+processing and helps you being recognized as a good community member
+leading to closer involvement with Sling.
Added: sling/site/trunk/content/jackrabbit-persistence.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/jackrabbit-persistence.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/jackrabbit-persistence.mdtext (added)
+++ sling/site/trunk/content/jackrabbit-persistence.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,146 @@
+Title: Jackrabbit Persistence
+<a name="JackrabbitPersistence-JackrabbitPersistence"></a>
+# Jackrabbit Persistence
+
+Out-of-the-box the embedded Jackrabbit repository used by Sling (the
+Embedded Jackrabbit Repository bundle) uses Derby to persist the JCR nodes
+and properties. For some applications or environments it may be required or
+required to replace Derby with another backing store such as PostgreSQL or
+Oracle.
+
+This page is based on the journey of Tony Giaccone to get Sling running
+with a PostgreSQL based Jackrabbit instance.
+
+
+<a name="JackrabbitPersistence-ManagementSummary"></a>
+## Management Summary
+
+To replace Derby as the persistence manager for Jackrabbit the following
+steps are required:
+
+1. Provide a JDBC driver for your database as an OSGi bundle
+1. Reconfigure Jackrabbit to use your database
+1. (Re-) Start the Embedded Jackrabbit bundle
+
+When you are not using the Derby persistence manager, you may safely remove
+the Derby bundle from your Sling instance.
+
+
+<a name="JackrabbitPersistence-JDBCDriver"></a>
+## JDBC Driver
+
+The hardest thing to do is probably getting the JDBC driver for your
+database. One option is to look at the bundles provided by Spring Source in
+their repository at http://www.springsource.com/repository/.
+
+Another option is to create the bundle on your own using Peter Kriens' [BND Tool](http://www.aqute.biz/Code/Bnd)
+:
+
+1. Get the JDBC driver for your database from the driver provider
+1. Wrap the JDBC driver library into an OSGi bundle:
+
+ # Example for PostgreSQL JDBC 3 driver 8.4-701
+ $ java -jar bnd.jar wrap postgresql-8.4-701.jdbc3.jar
+ $ mv postgresql-8.4-701.jdbc3.bar postgresql-8.4-701.jdbc3-bnd.jar
+
+1. Deploy the driver to your local Maven 2 Repository (Required if adding
+the JDBC driver to a Maven build, e.g. using the Sling Launchpad Plugin)
+
+ $ mvn install:install-file -DgroupId=postgresql -DartifactId=postgresql
+-Dversion=8.4.701.jdbc3 \
+ -Dpackaging=jar -Dfile=postgresql-8.4-701.jdbc3-bnd.jar
+
+
+Tony reports no success with the Spring Source bundle, whily the BND
+approach worked for the PostgreSQL JDBC driver.
+
+
+<a name="JackrabbitPersistence-ReplaceDerbyinarunningSlingInstance"></a>
+## Replace Derby in a running Sling Instance
+
+To replace Derby in a running Sling instance follow these steps (e.g.
+through the Web Console at */system/console*):
+
+1. Uninstall the Apache Derby bundle
+1. Install the JDBC bundle prepared in the first step
+1. Stop the Jackrabbit Embedded Repository bundle\
+This needs to be reconfigured and restarted anyway. So lets just stop it to
+prevent failures in the next step.
+1. Refresh the packages (click the _Refresh Packages_ button)
+
+Alternatively, you may wish to stop Sling after uninstalling Derby and
+installing the JDBC bundle. Technically, this is not required, though.
+
+
+<a name="JackrabbitPersistence-ReconfiguringJackrabbit"></a>
+## Reconfiguring Jackrabbit
+
+To actually use a persistence manager other than the default (Derby)
+persistence manager, you have to configure Jackrabbit to use it. Create a
+*repository.xml* file in the *sling/jackrabbit* folder before starting
+Sling for the first time. If the repository was already started, you can
+also modify the existing file.
+
+To prepare a repository.xml file before first startup, use the {{[repository.xml](http://svn.apache.org/repos/asf/sling/trunk/bundles/jcr/jackrabbit-server/src/main/resources/repository.xml)
+}} as a template and modify it by replacing the *<PersistenceManager>*
+elements to refer to the selected persistence manager.
+
+If the file already exists, you can modifiy this existing file and there is
+no need to get the original from the SVN repository.
+
+For example to use PostgreSQL instead of Derby modify the
+*<PersistenceManager>* elements as follows:
+
+
+ <Repository>
+ ...
+ <Workspace name="${wsp.name}">
+ ...
+ <PersistenceManager
+class="org.apache.jackrabbit.core.persistence.bundle.PostgreSQLPersistenceManager">
+ <param name="driver" value="org.postgresql.Driver"/>
+ <param name="url"
+value="jdbc:postgresql://localhost:5432/YOUR_DB_NAME_HERE"/>
+ <param name="schema" value="postgresql"/>
+ <param name="user" value="YOUR_USER_HERE"/>
+ <param name="password" value="YOUR_PASSWORD_HERE"/>
+ <param name="schemaObjectPrefix" value="jcr_${wsp.name}_"/>
+ <param name="externalBLOBs" value="false"/>
+ </PersistenceManager>
+ ...
+ </Workspace>
+
+ <Versioning rootPath="${rep.home}/version">
+ ...
+ <PersistenceManager
+class="org.apache.jackrabbit.core.persistence.bundle.PostgreSQLPersistenceManager">
+ <param name="driver" value="org.postgresql.Driver"/>
+ <param name="url"
+value="jdbc:postgresql://localhost:5432/YOUR_DB_NAME_HERE"/>
+ <param name="schema" value="postgresql"/>
+ <param name="user" value="YOUR_USER_HERE"/>
+ <param name="password" value="YOUR_PASSWORD_HERE"/>
+ <param name="schemaObjectPrefix" value="version_"/>
+ <param name="externalBLOBs" value="false"/>
+ </PersistenceManager>
+ </Versioning>
+ ...
+ </Repository>
+
+
+Modify the *url*, *user*, and *password* parameters to match your
+database setup.
+
+If you reconfigure Jackrabbit to use the new persistence manager, the
+existing repository data in the *sling/jackrabbit* directory, except the
+*repository.xml* file, of course, should now be removed.
+
+Finally either start Sling or start the Jackrabbit Embedded Repository
+bundle.
+
+
+<a name="JackrabbitPersistence-Credits"></a>
+## Credits
+
+This description is based on Tony Giaccone's description [Swapping Postgres for Derby](http://markmail.org/message/wlbfrukmjjsl33hh)
+ sent to the Sling Users mailing list.
Added: sling/site/trunk/content/jcr-installer-provider.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/jcr-installer-provider.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/jcr-installer-provider.mdtext (added)
+++ sling/site/trunk/content/jcr-installer-provider.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,192 @@
+Title: JCR Installer Provider
+The JCR installer provider scans the JCR repository for artifacts and
+provides them to the [OSGI installer](slingxsite:osgi-installer.html)
+.
+
+<a name="JCRInstallerProvider-ConfigurationandScanning"></a>
+## Configuration and Scanning
+
+The JCR installer provider can be configured with weighted paths which are
+scanned. By default, the installer scans in */apps* and */libs* where
+artifacts found in */apps* get a higher priority. The installer does a deep
+scan and uses a regular expression to detect folders containing artifacts
+to be installed. By default, artifacts from within a folder named _install_
+are provided to the OSGi installer.
+
+If such an install folder contains a binary artifact (e.g. a bundle) this
+is provided to the OSGi installer. In addition a node of type
+_sling:OsgiConfig_ is provided as a configuration to the installer.
+
+The jcr installer provider does not check or scan the artifacts itself, the
+detection and installation is deferred to the OSGi installer.
+
+<a name="JCRInstallerProvider-RunmodeSupport"></a>
+### Runmode Support
+
+The JCR installer supports run modes for installing artifacts. By default folders named _install_ are checked for artifacts. If Apache Sling is started with one (or more run modes), all folders named _install.[RUNMODE](runmode.html)
+_ are scanned as well. To be precise, the folder name can be followed by
+any number of run modes separated by comma. For example, if started with
+run modes _dev_, _a1_, and _public_, folders like _install.dev_,
+_install.a1_, _install.public_ are searched as well as _install.dev.a1_, or
+_install.a1.dev_.
+
+Artifacts from folders with a run mode get a higher priority. For example
+by default, an _install_ folder underneath _/libs_ gets the priority _50_.
+For each run mode in the folder name, this priority is increased by _1_, so
+_install.dev_ has _51_ and _install.a1.dev_ is _52_.
+
+<a name="JCRInstallerProvider-Example"></a>
+# Example
+Here's a quick walkthrough of the JCR installer functionality.
+
+<a name="JCRInstallerProvider-Installation"></a>
+## Installation
+Start the Sling [launchpad/app](http://svn.apache.org/repos/asf/sling/trunk/launchpad/app)
+ and install and start the following additional bundles:
+* [RunMode service](run-modes-(org.apache.sling.runmode).html)
+* OSGi installer service ([org.apache.sling.osgi.installer](http://svn.apache.org/repos/asf/sling/trunk/installer/core)
+)
+* JCR installer provider ([org.apache.sling.jcr.jcrinstall](http://svn.apache.org/repos/asf/sling/trunk/installer/providers/jcr)
+)
+
+To watch the logs produced by these modules, you can filter
+*sling/logs/error.log* using *egrep 'jcrinstall|osgi.installer'*.
+
+<a name="JCRInstallerProvider-Installandremoveabundle"></a>
+## Install and remove a bundle
+We'll use the [Knopflerfish Desktop](http://www.knopflerfish.org/releases/2.0.5/jars/desktop_awt/desktop_awt_all-2.0.0.jar)
+ bundle for this example, it is convenient as it displays a graphical user
+interface when started.
+
+We use *curl* to create content, to make it easy to reproduce the example
+by copying and pasting the *curl* commands. Any other way to create
+content in the repository will work, of course.
+
+By default, JCRInstall picks up bundles found in folders named _install_
+under */libs* and */apps*, so we start by creating such a folder:
+
+
+ curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest
+ curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest/install
+
+
+And we copy the bundle to install in that folder (a backslash in command
+lines means _continued on next line_):
+
+
+ curl -T desktop_awt_all-2.0.0.jar \
+
+http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar
+
+
+That's it. After 2-3 seconds, the bundle should be picked up by JCRInstall,
+installed and started. If this works you'll see a small _Knopflerfish
+Desktop_ window on your desktop, and Sling's OSGi console can of course be
+used to check the details.
+
+Removing the bundle from the repository will cause it to be uninstalled,
+so:
+
+
+ curl -X DELETE \
+
+http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar
+
+
+Should cause the _Knopflerfish Desktop_ window to disappear as the bundle
+is uninstalled.
+
+
+<a name="JCRInstallerProvider-Install,modifyandremoveaconfiguration"></a>
+## Install, modify and remove a configuration
+JCRInstall installs OSGi configurations from nodes having the
+_sling:OsgiConfig_ node type, found in folders named _install_ under the
+installation roots (/apps and /libs).
+
+Let's try this feature by creating a configuration with two properties:
+
+
+ curl \
+ -F "jcr:primaryType=sling:OsgiConfig" \
+ -F foo=bar -F works=yes \
+ http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid
+
+
+And verify the contents of our config node:
+
+ curl \
+
+http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid.json
+
+
+Which should display something like
+
+ {"foo":"bar",
+ "jcr:created":"Wed Aug 26 2009 17:06:40GMT+0200",
+ "jcr:primaryType":"sling:OsgiConfig","works":"yes"}
+
+
+At this point, JCRInstall should have picked up our new config and
+installed it. The logs would confirm that, but we can also use the OSGi
+console's config status page (http://localhost:8888/system/console/config)
+to check it. That page should now contain:
+
+
+ PID=some.config.pid
+ BundleLocation=Unbound
+ _jcr_config_path=jcrinstall:/apps/jcrtest/install/some.config.pid
+ foo=bars
+ service.pid=some.config.pid
+ works=yes
+
+
+Indicating that the configuration has been installed.
+
+Let's try modifying the configuration parameters:
+
+
+ curl \
+ -F works=updated -F even=more \
+ http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid
+
+
+And check the changes in the console page:
+
+
+ PID=some.config.pid
+ BundleLocation=Unbound
+ _jcr_config_path=jcrinstall:/apps/jcrtest/install/some.config.pid
+ even=more
+ foo=bars
+ service.pid=some.config.pid
+ works=updated
+
+
+We can now delete the configuration node:
+
+
+ curl -X DELETE \
+ http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid
+
+
+And verify that the corresponding configuration is gone in the console page
+(after 1-2 seconds, like for all other JCRInstall operations).
+
+*TODO:* A node named like *o.a.s.foo.bar-a* uses _o.a.s.foo.bar_ as its
+factory PID creating a configuration with an automatically generated PID.
+The value of _a_ is stored as an alias property in the configuration to
+correlate the configuration object with the repository node - demonstrate
+that.
+
+<a name="JCRInstallerProvider-AutomatedTests"></a>
+# Automated Tests
+The following modules contain lots of automated tests (under *src/test*,
+as usual):
+
+* OSGi installer integration tests ([org.apache.sling.installer.it](http://svn.apache.org/repos/asf/sling/trunk/installer/it)
+)
+* JCR installer service ([org.apache.sling.installer.providers.jcr](http://svn.apache.org/repos/asf/sling/trunk/installer/providers/jcr)
+)
+
+Many of these tests are fairly readable, and can be used to find out in
+more detail how these modules work.
Added: sling/site/trunk/content/jspc.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/jspc.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/jspc.mdtext (added)
+++ sling/site/trunk/content/jspc.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,92 @@
+Title: JspC
+<a name="JspC-MavenJspCPlugin"></a>
+# Maven JspC Plugin
+
+{excerpt:hidden=true}Compiles JSP scripts into class files and generates
+Declarative Service Descriptors to register the compiled JSPs as
+services{excerpt}
+
+The Maven JspC Plugin provides a single goal *jspc* which is by default
+executed in the *compile* phase of the Maven build process. This goal
+takes all JSP source files from a configured location (*src/main/scripts*
+by default) and compiles them into classes in a configurable location
+(*target/jspc-plugin-generated* by default). In addition, for each
+compiled JSP a Declarative Services descriptor is generated and written to
+a descriptor file (*OSGI-INF/jspServiceComponents.xml* in the output
+location). This descriptor will then be read by the Service Component
+Runtime of the deployment OSGi framework to register all contained JSP as
+*javax.servlet.Servlet* services.
+
+
+
+<a name="JspC-Use"></a>
+## Use
+
+To use the Maven JspC Plugin define the following elements in the
+*<plugins>* section of the POM:
+
+
+ <?xml version="1.0" encoding="ISO-8859-1"?>
+ <project>
+ ....
+ <build>
+ ....
+ <plugins>
+ ....
+ <plugin>
+ <groupId>org.apache.sling</groupId>
+ <artifactId>maven-jspc-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>compile-jsp</id>
+ <goals>
+ <goal>jspc</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ ....
+ <plugins>
+ ....
+ <build>
+ ....
+ <project>
+
+
+
+
+<a name="JspC-Configuration"></a>
+## Configuration
+
+The Maven JspC Plugin may be configured in the *<configuration>* element
+using the following properties:
+
+<table>
+<tr><th> Parameter </th><th> Default Value </th><th> Description </th></tr>
+<tr><td> *sourceDirectory* </td><td> *$\{project.build.scriptSourceDirectory*} </td><td>
+Location of the JSP source file; may be overwritten using the
+*jspc.sourceDirectory* system property. </td></tr>
+<tr><td> *outputDirectory* </td><td>
+*$\{project.build.directory}/jspc-plugin-generated* </td><td> Target directory
+for the compiled JSP classes; may be overwritten using the
+*jspc.outputDirectory* system propertiy. </td></tr>
+<tr><td> *compilerTargetVM* </td><td> *1.5* </td><td> The Target Virtual Machine Version to
+generate class files for; may be overwritten using the
+*jspc.compilerTargetVM* system property. </td></tr>
+<tr><td> *compilerSourceVM* </td><td> *1.5* </td><td> The Compiler Source Version of the Java
+source generated from the JSP files before compiling into classes; may be
+overwritten using the *jspc.compilerSourceVM* system property. </td></tr>
+<tr><td> *servletPackage* </td><td> *org.apache.jsp* </td><td> The root package name for the
+generated class files; may be overwritten using the *jspc.servletPackage*
+system property. </td></tr>
+</table>
+
+
+
+<a name="JspC-Notes"></a>
+## Notes
+
+The generated JSP classes as well as the Declarative Services descriptor
+are automatically copied to the generated bundle jar file if the Maven
+Bundle Plugin (from the Apache Felix) project is used to build the project
+package.
Added: sling/site/trunk/content/launch-sling.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/launch-sling.mdtext?rev=1328899&view=auto
==============================================================================
--- sling/site/trunk/content/launch-sling.mdtext (added)
+++ sling/site/trunk/content/launch-sling.mdtext Sun Apr 22 16:52:13 2012
@@ -0,0 +1,3 @@
+Title: Launch Sling
+Please refer to [The Sling Launchpad](the-sling-launchpad.html)
+ for up-to-date information on launching Sling.