http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/the-sling-engine/filters.md ---------------------------------------------------------------------- diff --git a/content/documentation/the-sling-engine/filters.md b/content/documentation/the-sling-engine/filters.md index 1d42d90..2371b54 100644 --- a/content/documentation/the-sling-engine/filters.md +++ b/content/documentation/the-sling-engine/filters.md @@ -1,7 +1,10 @@ -title=Servlet Filter Support -type=page +title=TODO title for filters.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: 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. @@ -9,7 +12,7 @@ Sling supports filter processing by applying filter chains to the requests befor See <a href="https://issues.apache.org/jira/browse/SLING-1213";>SLING-1213</a>, <a href="https://issues.apache.org/jira/browse/SLING-1734";>SLING-1734</a>, and <a href="http://markmail.org/message/quxhm7d5s6u66crr";>Registering filters with Sling</a> -for more details. The + for more details. The <a href="https://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/src/main/java/org/apache/sling/launchpad/testservices/filters/NoPropertyFilter.java";>NoPropertyFilter</a> from our integration tests shows an example Sling Filter. </div> @@ -45,24 +48,24 @@ Note on `INCLUDE` and `FORWARD` with respect to JSP tags: These filters are also Filter processing is part of the Sling request processing, which may be sketched as follows: * *Request Level*: -* Authentication -* Resource Resolution -* Servlet/Script Resolution -* Request Level Filter Processing + * Authentication + * Resource Resolution + * Servlet/Script Resolution + * Request Level Filter Processing 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: * *Component Level*: -* Component Level Filter Processing -* Call Servlet or Script + * Component Level Filter Processing + * Call Servlet or Script 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: * *Dispatch*: -* Resolve the resource to dispatch to if not already defined when getting the `RequestDispatcher` -* Servlet/Script resolution -* Call include or forward filters depending on the kind of dispatch -* Call Servlet or Script + * Resolve the resource to dispatch to if not already defined when getting the `RequestDispatcher` + * Servlet/Script resolution + * Call include or forward filters depending on the kind of dispatch + * Call Servlet or Script 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. @@ -72,42 +75,42 @@ Apart form the logs which tell you when filters are executed, two Sling plugins ### Recent Requests plugin The request traces provided at `/system/console/requests` contain information about filter execution, as in this example: -0 (2010-09-08 15:22:38) TIMER_START{Request Processing} -... -0 (2010-09-08 15:22:38) LOG Method=GET, PathInfo=/some/path.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: org.apache.sling.i18n.impl.I18NFilter -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 Applying inner filters -3 (2010-09-08 15:22:38) TIMER_START{/some/script.jsp#0} -... -8 (2010-09-08 15:22:38) TIMER_END{8,Request Processing} Request Processing + 0 (2010-09-08 15:22:38) TIMER_START{Request Processing} + ... + 0 (2010-09-08 15:22:38) LOG Method=GET, PathInfo=/some/path.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: org.apache.sling.i18n.impl.I18NFilter + 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 Applying inner filters + 3 (2010-09-08 15:22:38) TIMER_START{/some/script.jsp#0} + ... + 8 (2010-09-08 15:22:38) TIMER_END{8,Request Processing} Request Processing ### 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: -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) --700 : class org.apache.sling.i18n.impl.I18NFilter (2334) -0 : class org.apache.sling.engine.impl.debug.RequestProgressTrackerLogFilter (2402) - -Error Filters: ---- - -Include Filters: - -Forward Filters: -1000 : class some.package.DebugFilter (2449) - -Component Filters: --200 : class some.package.SomeComponentFilter (2583) + 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) + -700 : class org.apache.sling.i18n.impl.I18NFilter (2334) + 0 : class org.apache.sling.engine.impl.debug.RequestProgressTrackerLogFilter (2402) + + Error Filters: + --- + + Include Filters: + + Forward Filters: + 1000 : class some.package.DebugFilter (2449) + + Component Filters: + -200 : class some.package.SomeComponentFilter (2583) The first numbers on those lines are the filter priorities, and the last number in parentheses is the OSGi service ID.
http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/the-sling-engine/mappings-for-resource-resolution.md ---------------------------------------------------------------------- diff --git a/content/documentation/the-sling-engine/mappings-for-resource-resolution.md b/content/documentation/the-sling-engine/mappings-for-resource-resolution.md index 34e009f..789db2f 100644 --- a/content/documentation/the-sling-engine/mappings-for-resource-resolution.md +++ b/content/documentation/the-sling-engine/mappings-for-resource-resolution.md @@ -1,7 +1,10 @@ -title=Mappings for Resource Resolution -type=page +title=TODO title for mappings-for-resource-resolution.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Mappings for Resource Resolution [TOC] @@ -16,7 +19,7 @@ That way you can even make it [run mode specific](/documentation/bundles/sling-s When dealing with the new resource resolution we have a number of properties influencing the process: -* `sling:match` – This property when set on a node in the `/etc/map` tree (see below) defines a partial regular expression which is used instead of the node's name to match the incoming request. This property is only needed if the regular expression includes characters which are not valid JCR name characters. The list of invalid characters for JCR names is: `/, :, [, ], *, ', ", , |` and any whitespace except blank space. In addition a name without a name space may not be `.` or `..` and a blank space is only allowed inside the name. +* `sling:match` – This property when set on a node in the `/etc/map` tree (see below) defines a partial regular expression which is used instead of the node's name to match the incoming request. This property is only needed if the regular expression includes characters which are not valid JCR name characters. The list of invalid characters for JCR names is: `/, :, [, ], *, ', ", \, |` and any whitespace except blank space. In addition a name without a name space may not be `.` or `..` and a blank space is only allowed inside the name. * `sling:redirect` – This property when set on a node in the `/etc/map` tree (see below) causes a redirect response to be sent to the client, which causes the client to send in a new request with the modified location. The value of this property is applied to the actual request and sent back as the value of `Location` response header. * `sling:status` – This property defines the HTTP status code sent to the client with the `sling:redirect` response. If this property is not set, it defaults to 302 (Found). Other status codes supported are 300 (Multiple Choices), 301 (Moved Permanently), 303 (See Other), and 307 (Temporary Redirect). * `sling:internalRedirect` – This property when set on a node in the `/etc/map` tree (see below) causes the current path to be modified internally to continue with resource resolution. This is a multi-value property, i.e. multiple paths can be given here, which are tried one after another until one resolved to a resource. @@ -53,7 +56,7 @@ Namespace mangling operates such, that any namespace prefix identified in resour Conversely the `resolve` methods must undo such namespace mangling to get back at the resource path. This is simple done by modifying any path such that segments starting with an underscore enclosed prefix are changed by removing the underscores and adding a colon after the prefix. There is one catch, tough: Due to the way the SlingPostServlets automatically generates names, there may be cases where the actual name would be matching this mechanism. Therefore only prefixes are modified which are actually namespace prefixes. -*Example*: The path `/content/*a*sample/*jcr*content/*jcr*data.png{*`} *is modified by namespace mangling in the* `{*}resolve{*`} *method to get* `*/content/*a*sample/jcr:content/jcr:data.png{*}{`}*. The prefix* `**a{*}{`}`{`} is not modified because there is no registered namespace with prefix `a`. On the other hand the prefix `{*}jcr{*`} is modified because there is of course a registered namespace with prefix `jcr`. +*Example*: The path `/content/*a*sample/*jcr*content/*jcr*data.png{*`} *is modified by namespace mangling in the* `{*}resolve{*`} *method to get* `*/content/*a*sample/jcr:content/jcr:data.png{*}{`}*. The prefix* `*\*a{*}{`}`{`} is not modified because there is no registered namespace with prefix `a`. On the other hand the prefix `{*}jcr{*`} is modified because there is of course a registered namespace with prefix `jcr`. ## Root Level Mappings @@ -67,27 +70,27 @@ Each entry in the mapping table is a regular expression, which is constructed fr Consider the following content -/etc/map -+-- http -+-- example.com.80 -| +-- sling:redirect = "http://www.example.com/"; -+-- www.example.com.80 -| +-- sling:internalRedirect = "/example" -+-- any_example.com.80 -| +-- sling:match = ".+.example.com.80" -| +-- sling:redirect = "http://www.example.com/"; -+-- localhost_any -| +-- sling:match = "localhost.d*" -| +-- sling:internalRedirect = "/content" -| +-- cgi-bin -| | +-- sling:internalRedirect = "/scripts" -| +-- gateway -| | +-- sling:internalRedirect = "http://gbiv.com"; -| +-- (stories) -| +-- sling:internalRedirect = "/anecdotes/$1" -+-- regexmap -+-- sling:match = "$1.example.com/$2" -+-- sling:internalRedirect = "/content/([^/]+)/(.*)" + /etc/map + +-- http + +-- example.com.80 + | +-- sling:redirect = "http://www.example.com/"; + +-- www.example.com.80 + | +-- sling:internalRedirect = "/example" + +-- any_example.com.80 + | +-- sling:match = ".+\.example\.com\.80" + | +-- sling:redirect = "http://www.example.com/"; + +-- localhost_any + | +-- sling:match = "localhost\.\d*" + | +-- sling:internalRedirect = "/content" + | +-- cgi-bin + | | +-- sling:internalRedirect = "/scripts" + | +-- gateway + | | +-- sling:internalRedirect = "http://gbiv.com"; + | +-- (stories) + | +-- sling:internalRedirect = "/anecdotes/$1" + +-- regexmap + +-- sling:match = "$1.example.com/$2" + +-- sling:internalRedirect = "/content/([^/]+)/(.*)" This would define the following mapping entries: @@ -95,32 +98,32 @@ This would define the following mapping entries: |--|--|--|--| | http/example.com.80 | http://www.example.com | no | Redirect all requests to the Second Level Domain to www | | http/www.example.com.80 | /example | yes | Prefix the URI paths of the requests sent to this domain with the string `/example` | -| http/.+.example.com.80 | http://www.example.com | no | Redirect all requests to sub domains to www. The actual regular expression for the host.port segment is taken from the `sling:match` property. | -| http/localhost.d* | /content | yes | Prefix the URI paths with `/content` for requests to localhost, regardless of actual port the request was received on. This entry only applies if the URI path does not start with `/cgi-bin`, `gateway` or `stories` because there are longer match entries. The actual regular expression for the host.port segment is taken from the `sling:match` property. | -| http/localhost.d*/cgi-bin | /scripts | yes | Replace the `/cgi-bin` prefix in the URI path with `/scripts` for requests to localhost, regardless of actual port the request was received on. | -| http/localhost.d*/gateway | http://gbiv.com | yes | Replace the `/gateway` prefix in the URI path with `http://gbiv.com` for requests to localhost, regardless of actual port the request was received on. | -| http/localhost.d*/(stories) | /anecdotes/stories | yes | Prepend the URI paths starting with `/stories` with `/anecdotes` for requests to localhost, regardless of actual port the request was received on. | +| http/.+\.example\.com\.80 | http://www.example.com | no | Redirect all requests to sub domains to www. The actual regular expression for the host.port segment is taken from the `sling:match` property. | +| http/localhost\.\d\* | /content | yes | Prefix the URI paths with `/content` for requests to localhost, regardless of actual port the request was received on. This entry only applies if the URI path does not start with `/cgi-bin`, `gateway` or `stories` because there are longer match entries. The actual regular expression for the host.port segment is taken from the `sling:match` property. | +| http/localhost\.\d*/cgi-bin | /scripts | yes | Replace the `/cgi-bin` prefix in the URI path with `/scripts` for requests to localhost, regardless of actual port the request was received on. | +| http/localhost\.\d*/gateway | http://gbiv.com | yes | Replace the `/gateway` prefix in the URI path with `http://gbiv.com` for requests to localhost, regardless of actual port the request was received on. | +| http/localhost\.\d*/(stories) | /anecdotes/stories | yes | Prepend the URI paths starting with `/stories` with `/anecdotes` for requests to localhost, regardless of actual port the request was received on. | ### Regular Expression Matching -As said above the mapping entries are regular expressions which are matched against path. As such these regular expressions may also contain capturing groups as shown in the example above: `http/localhost.d*/(stories)`. After matching the path against the regular expression, the replacement pattern is applied which allows references back to the capturing groups. +As said above the mapping entries are regular expressions which are matched against path. As such these regular expressions may also contain capturing groups as shown in the example above: `http/localhost\.\d*/(stories)`. After matching the path against the regular expression, the replacement pattern is applied which allows references back to the capturing groups. To illustrate the matching and replacement is applied according to the following pseudo code: -#!java -String path = request.getScheme + "/" + request.getServerName() -+ "." + request.getServerPort() + "/" + request.getPathInfo(); -String result = null; -for (MapEntry entry: mapEntries) { -Matcher matcher = entry.pattern.matcher(path); -if (matcher.find()) { -StringBuffer buf = new StringBuffer(); -matcher.appendReplacement(buf, entry.getRedirect()); -matcher.appendTail(buf); -result = buf.toString(); -break; -} -} + #!java + String path = request.getScheme + "/" + request.getServerName() + + "." + request.getServerPort() + "/" + request.getPathInfo(); + String result = null; + for (MapEntry entry: mapEntries) { + Matcher matcher = entry.pattern.matcher(path); + if (matcher.find()) { + StringBuffer buf = new StringBuffer(); + matcher.appendReplacement(buf, entry.getRedirect()); + matcher.appendTail(buf); + result = buf.toString(); + break; + } + } At the end of the loop, `result` contains the mapped path or `null` if no entry matches the request `path`. @@ -128,18 +131,18 @@ At the end of the loop, `result` contains the mapped path or `null` if no entry #### Regular Expressions for Reverse Mappings -By default using regular expressions with wildcards will prevent to use the mapping entry for reverse mappings (see above). +By default using regular expressions with wildcards will prevent to use the mapping entry for reverse mappings (see above). -There is one exception though: If there is a `sling:internalRedirect` property containing a regular expression the map entry will be *exclusively used for reverse mappings* (i.e. used only for `ResourceResolver.map(...)`) (see also [SLING-2560](https://issues.apache.org/jira/browse/SLING-2560)). The same resource may carry a `sling:match` property with wildcards and groups referring to the groups being defined in the `sling:internalRedirect` property. +There is one exception though: If there is a `sling:internalRedirect` property containing a regular expression the map entry will be *exclusively used for reverse mappings* (i.e. used only for `ResourceResolver.map(...)`) (see also [SLING-2560](https://issues.apache.org/jira/browse/SLING-2560)). The same resource may carry a `sling:match` property with wildcards and groups referring to the groups being defined in the `sling:internalRedirect` property. -This example - -/etc/map -+-- http -+-- example.com.80 -| +-- sling:internalRedirect = "/content/([^/]+)/home/(.*)" -| +-- sling:match = "$1/index/$2" +This example + /etc/map + +-- http + +-- example.com.80 + | +-- sling:internalRedirect = "/content/([^/]+)/home/(.*)" + | +-- sling:match = "$1/index/$2" + leads to the following entry being used in the reverse mapping table: | Pattern | Replacement | @@ -153,12 +156,12 @@ The result of matching the request path and getting the redirection is either a The following pseudo code summarizes this behaviour: -#!java -String path = ....; -String result = path; -do { -result = applyMapEntries(result); -} while (isURL(result)); + #!java + String path = ....; + String result = path; + do { + result = applyMapEntries(result); + } while (isURL(result)); As soon as the result of applying the map entries is an absolute or relative path (or no more map entries match), Root Level Mapping terminates and the next step in resource resolution, resource tree access, takes place. @@ -168,7 +171,7 @@ The result of Root Level Mapping is an absolute or relative path to a resource. Accessing the resource tree after applying the Root Level Mappings has four options: -* Check whether the path addresses a so called Star Resource. A Star Resource is a resource whose path ends with or contains `/*`. Such resources are used by the `SlingPostServlet` to create new content below an existing resource. If the path after Root Level Mapping is absolute, it is made absolute by prepending the first search path entry. +* Check whether the path addresses a so called Star Resource. A Star Resource is a resource whose path ends with or contains `/\*`. Such resources are used by the `SlingPostServlet` to create new content below an existing resource. If the path after Root Level Mapping is absolute, it is made absolute by prepending the first search path entry. * Check whether the path exists in the repository. if the path is absolute, it is tried directly. Otherwise the search path entries are prepended to the path until a resource is found or the search path is exhausted without finding a resource. * Drill down the resource tree starting from the root, optionally using the search path until a resource is found. * If no resource can be resolved, a Missing Resource is returned. @@ -179,32 +182,32 @@ Drilling down the resource tree starts at the root and for each segment in the p The following pseudo code shows this algorithm assuming the path is absolute: -#!java -String path = ...; // the absolute path -Resource current = getResource("/"); -String[] segments = path.split("/"); -for (String segment: segments) { -Resource child = getResource(current, segment); -if (child == null) { -Iterator<Resource> children = listChildren(current); -current = null; -while (children.hasNext()) { -child = children.next(); -if (segment.equals(getSlingAlias(child))) { -current = child; -break; -} -} -if (current == null) { -// fail -break; -} -} else { -current = child; -} -} - -## Rebuild The Vanity Bloom Filter + #!java + String path = ...; // the absolute path + Resource current = getResource("/"); + String[] segments = path.split("/"); + for (String segment: segments) { + Resource child = getResource(current, segment); + if (child == null) { + Iterator<Resource> children = listChildren(current); + current = null; + while (children.hasNext()) { + child = children.next(); + if (segment.equals(getSlingAlias(child))) { + current = child; + break; + } + } + if (current == null) { + // fail + break; + } + } else { + current = child; + } + } + +## Rebuild The Vanity Bloom Filter [SLING-4216](https://issues.apache.org/jira/browse/SLING-4216) introduced the usage of a bloom filter in order to resolve long startup time with many vanityPath entries. The bloom filter is handled automatically by the Sling framework. In some cases though, as changing the maximum number of vanity bloom filter bytes, a rebuild of the vanity bloom filter is needed. http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/the-sling-engine/request-listeners.md ---------------------------------------------------------------------- diff --git a/content/documentation/the-sling-engine/request-listeners.md b/content/documentation/the-sling-engine/request-listeners.md index d661e70..20f6ccf 100644 --- a/content/documentation/the-sling-engine/request-listeners.md +++ b/content/documentation/the-sling-engine/request-listeners.md @@ -1,29 +1,32 @@ -title=Request Listeners -type=page +title=TODO title for request-listeners.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Request Listeners Sling provides the possibility to "listen" to a request processed by the Sling Engine (`SlingMainServlet`). To get notified you implement the service interface `org.apache.sling.api.request.SlingRequestListener`. -#!java -public interface SlingRequestListener { - -static final String SERVICE_NAME = "org.apache.sling.api.request.SlingRequestListener"; - -/** -* This method is called from the Sling application for every -* <code>EventType</code> appearing during the dispatching of -* a Sling request -* -* @param sre the object representing the event -* -* @see org.apache.sling.api.request.SlingRequestEvent.EventType -*/ -public void onEvent( SlingRequestEvent sre ); -} - - -There are no special properties to set. + #!java + public interface SlingRequestListener { + + static final String SERVICE_NAME = "org.apache.sling.api.request.SlingRequestListener"; + + /** + * This method is called from the Sling application for every + * <code>EventType</code> appearing during the dispatching of + * a Sling request + * + * @param sre the object representing the event + * + * @see org.apache.sling.api.request.SlingRequestEvent.EventType + */ + public void onEvent( SlingRequestEvent sre ); + } + + +There are no special properties to set. ## Supported types of events http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/the-sling-engine/request-parameters.md ---------------------------------------------------------------------- diff --git a/content/documentation/the-sling-engine/request-parameters.md b/content/documentation/the-sling-engine/request-parameters.md index 2fdea31..a6b610d 100644 --- a/content/documentation/the-sling-engine/request-parameters.md +++ b/content/documentation/the-sling-engine/request-parameters.md @@ -1,7 +1,10 @@ -title=Request Parameter Handling in Sling -type=page +title=TODO title for request-parameters.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Request Parameter Handling in Sling Excerpt: Explains how Sling provides request parameters to the `Component`. ## Servlet API @@ -18,7 +21,7 @@ The Servlet API specification provides the following methods to access the param | `ServletRequest.getParts()` | Returns all parts of the multipart request (since v3.0) | | `ServletRequest.getPart(String)` | Returns the request part with that name in case of multipart requests (since v3.0) | -The actual encoding of the parameters is all but safe because the encoding of URLs is not very well defined and browsers do not set the character encoding when sending post data. Fortunately, they use the same character encoding for sending back form content as was used by the server to send the form. +The actual encoding of the parameters is all but safe because the encoding of URLs is not very well defined and browsers do not set the character encoding when sending post data. Fortunately, they use the same character encoding for sending back form content as was used by the server to send the form. ## Sling API @@ -57,7 +60,7 @@ From within Sling servlets/scripts you can no longer rely on the original semant * `ServletRequest.getParameterMap()` * `ServletRequest.getParameterNames()` * `ServletRequest.getParts()` and -* `ServletRequest.getPart(String)` +* `ServletRequest.getPart(String)` internally use the Sling parameter support (and therefore have the same implications on e.g. encoding). You should preferably use the Sling methods `getRequestParameter*` instead. @@ -67,18 +70,18 @@ Calling `ServletRequest.getInputStream()` is not supported, nor relying on some Traditionally, the encoding of parameters, especially in text area input forms, has been a big issue. To solve this issue Sling introduces the following convention: -* All forms should contain a hidden field of the name `_charset_` containing the actual encoding used to send the form from the server to the client -* All forms should be sent with *UTF-8* character encoding + * All forms should contain a hidden field of the name `_charset_` containing the actual encoding used to send the form from the server to the client + * All forms should be sent with *UTF-8* character encoding The first rule is essential as it helps decoding the form input correctly. The second rule is not actually a very hard requirement but to enable support for all (or most) character sets used, using *UTF-8* is one of the best choices anyway. When Sling is now receiving a request and is asked for the parameters, the parameters are parsed in two phases: The first phase just parses the raw input data using an identity transformation of bytes to characters. This identity transformation happens to generate strings as the original data was generated with `ISO-8859-1` encoding. The second phase locates the `_charset_` parameter and fixes the character encodings of the parameters as follows: -* All names of the parameters are re-encoded -* The parameter values are re-encoded, unless the parameter value is an uploaded file. Actually the parameter (not the files of course) are internally as `byte[]({{ refs..path }})` where the conversion to a string is done on the fly (and yes, the conversion using the `_charset_` character encoding is of course cached for performance reasons) -* If the parameter is an uploaded file, the file name is re-encoded on the fly when accessed + * All names of the parameters are re-encoded + * The parameter values are re-encoded, unless the parameter value is an uploaded file. Actually the parameter (not the files of course) are internally as `byte[]({{ refs..path }})` where the conversion to a string is done on the fly (and yes, the conversion using the `_charset_` character encoding is of course cached for performance reasons) + * If the parameter is an uploaded file, the file name is re-encoded on the fly when accessed <div class="info"> -Up to and including Sling Engine 2.2.2 request parameters are always decoded with ISO-8859-1 encoding if the <code>_charset_</code> request parameter is missing. As of Sling Engine 2.2.4 the <code>_charset_</code> request parameter is optional. As of this version the Sling Main Servlet supports a configuration setting which allows to change the default character encoding used if the <code>_charset_</code> request parameter is missing. +Up to and including Sling Engine 2.2.2 request parameters are always decoded with ISO-8859-1 encoding if the <code>_charset_</code> request parameter is missing. As of Sling Engine 2.2.4 the <code>_charset_</code> request parameter is optional. As of this version the Sling Main Servlet supports a configuration setting which allows to change the default character encoding used if the <code>_charset_</code> request parameter is missing. To enable this functionality set the <code>sling.default.parameter.encoding</code> parameter of the Sling Main Servlet (PID <code>org.apache.sling.engine.impl.SlingMainServlet</code>) configuration (for Sling Engine < 2.3.0) or the same parameter of the Sling Request Parameter Handling (PID <code>org.apache.sling.engine.parameters</code>) configuration (for Sling Engine >= 2.3.0 ) to the desired encoding, which of course must be supported by the actual Java Platform. </div> http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/the-sling-engine/resources.md ---------------------------------------------------------------------- diff --git a/content/documentation/the-sling-engine/resources.md b/content/documentation/the-sling-engine/resources.md index 387a192..99dd73a 100644 --- a/content/documentation/the-sling-engine/resources.md +++ b/content/documentation/the-sling-engine/resources.md @@ -1,7 +1,10 @@ -title=Resources -type=page +title=TODO title for resources.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Resources [TOC] @@ -59,18 +62,18 @@ As has been said, the absolute path mapping methods `resolve(HttpServletRequest, The general algorithm of the two methods is as follows: -1. Call `HttpServletRequest.getScheme(), .getServerName(), getServerPort` to get an absolute path out of the request URL: [scheme]({{ refs.scheme.path }})/[host].[port][path] (`resolve(HttpServletRequest, String)` method only, which) +1. Call `HttpServletRequest.getScheme(), .getServerName(), getServerPort` to get an absolute path out of the request URL: \[scheme\]({{ refs.scheme.path }})/\[host\].\[port\]\[path\] (`resolve(HttpServletRequest, String)` method only, which) 1. Check whether any virtual path matches the absolute path. If such a match exists, the next step is entered with the match. 1. Apply a list of mappings in order to create a mapped path. The first mapped path resolving to a Resource is assumed success and the Resource found is returned. -1. If no mapping created a mapped path addressing an existing Resource, the method fails and returns a `NonExistingResource` (for the -`resolve(String)` and `resolve(HttpServletRequest,String)`) or null (for the `getResource(String path)` +1. If no mapping created a mapped path addressing an existing Resource, the method fails and returns a `NonExistingResource` (for the +`resolve(String)` and `resolve(HttpServletRequest,String)`) or null (for the `getResource(String path)` and `getResource(Resource base, String path)` methods). The virtual path mapping may be used to create shortcut URLs for otherwise long and complicated URLs. An example of such an URL might be the main administrative page of a CMS system. So, administrators may access the root of the web application and directed to the main administrative page. The path mapping functionality may be used to hide internal resource organization from the request URL space. For example to better control the structure of your repository, you might decide to store all accessible data inside a `/content` subtree. To hide this fact from the users, a mapping may be defined to prefix all incoming paths with `/content` to get at the actual Resource. -The `map(String)` applies the path mapping algorithm in the reverse order. That is, first the path mappings are reversed and then any virtual mappings are checked. So, a path `/content/sample` might be mapped `/sample` to revers the `/content` prefixing. Or the main administrative page - say `/system/admin/main.html` - may be mapped to the virtual URL `/`. +The `map(String)` applies the path mapping algorithm in the reverse order. That is, first the path mappings are reversed and then any virtual mappings are checked. So, a path `/content/sample` might be mapped `/sample` to revers the `/content` prefixing. Or the main administrative page - say `/system/admin/main.html` \- may be mapped to the virtual URL `/`. More details on mappings can be found at [Mappings for Resource Resolution](/documentation/the-sling-engine/mappings-for-resource-resolution.html). @@ -117,7 +120,7 @@ JCR-based Resources are provided with the default `JcrResourceProvider`. This Re Resources may by provided by OSGi bundles. Providing bundles have a Bundle manifest header `Sling-Bundle-Resources` containing a list of absolute paths provided by the bundle. The path are separated by comma or whitespace (SP, TAB, VTAB, CR, LF). -The `BundleResourceProvider` supporting bundle-based Resources provides directories as Resources of type `nt:folder` and files as Resources of type `nt:file`. This matches the default primary node types intended to be used for directories and files in JCR repositories. +The `BundleResourceProvider` supporting bundle-based Resources provides directories as Resources of type `nt:folder` and files as Resources of type `nt:file`. This matches the default primary node types intended to be used for directories and files in JCR repositories. For details see [Bundle Resource.](/documentation/bundles/bundle-resources-extensions-bundleresource.html) @@ -127,7 +130,7 @@ Servlet Resources are registered by the Servlet Resolver bundle for Servlets reg ### File System Resources -The Filesystem Resource Provider provides access to the operating system's filesystem through the Sling ResourceResolver. Multiple locations may be mapped into the resource tree by configuring the filesystem location and the resource tree root path for each location to be mapped. +The Filesystem Resource Provider provides access to the operating system's filesystem through the Sling ResourceResolver. Multiple locations may be mapped into the resource tree by configuring the filesystem location and the resource tree root path for each location to be mapped. For details see [File System Resources](/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html). @@ -169,12 +172,12 @@ Resource events are sent out via the OSGi Event Admin. You can subscribe to thos The Sling API provides an easy way to wrap or decorate a resource before returning. Details see [Wrap or Decorate Resources](/documentation/the-sling-engine/wrap-or-decorate-resources.html). -[1]: http://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/ResourceMetadata.html "ResourceMetadata" -[2]: http://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/Resource.html "Resource" -[3]: http://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/AbstractResource.html "AbstractResource" -[4]: https://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/src/main/java/org/apache/sling/launchpad/testservices/resourceprovider/ -[5]: https://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/src/main/java/org/apache/sling/launchpad/testservices/serversidetests/WriteableResourcesTest.java -[6]: https://svn.apache.org/repos/asf/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChangeListener.java -[7]: https://svn.apache.org/repos/asf/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ExternalResourceChangeListener.java -[8]: https://osgi.org/javadoc/r6/cmpn/org/osgi/service/event/EventHandler.html -[9]: http://sling.apache.org/apidocs/sling8/org/apache/sling/api/SlingConstants.html + [1]: http://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/ResourceMetadata.html "ResourceMetadata" + [2]: http://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/Resource.html "Resource" + [3]: http://sling.apache.org/apidocs/sling8/org/apache/sling/api/resource/AbstractResource.html "AbstractResource" + [4]: https://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/src/main/java/org/apache/sling/launchpad/testservices/resourceprovider/ + [5]: https://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/src/main/java/org/apache/sling/launchpad/testservices/serversidetests/WriteableResourcesTest.java + [6]: https://svn.apache.org/repos/asf/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ResourceChangeListener.java + [7]: https://svn.apache.org/repos/asf/sling/trunk/bundles/api/src/main/java/org/apache/sling/api/resource/observation/ExternalResourceChangeListener.java + [8]: https://osgi.org/javadoc/r6/cmpn/org/osgi/service/event/EventHandler.html + [9]: http://sling.apache.org/apidocs/sling8/org/apache/sling/api/SlingConstants.html http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/the-sling-engine/service-authentication.md ---------------------------------------------------------------------- diff --git a/content/documentation/the-sling-engine/service-authentication.md b/content/documentation/the-sling-engine/service-authentication.md index be77891..b34e221 100644 --- a/content/documentation/the-sling-engine/service-authentication.md +++ b/content/documentation/the-sling-engine/service-authentication.md @@ -1,7 +1,10 @@ -title=Service Authentication -type=page +title=TODO title for service-authentication.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Service Authentication Excerpt: Introduce new service level authentication to replace `loginAdministrative` [TOC] @@ -55,8 +58,8 @@ a Resource Resolver and/or JCR Repository user ID for authentication. Thus the actual service identification (service ID) is defined as: -#!text -service-id = service-name [ ":" subservice-name ] . + #!text + service-id = service-name [ ":" subservice-name ] . The `service-name` is the symbolic name of the bundle providing the service. @@ -87,7 +90,7 @@ would be consituting the `mta` service. The sub systems would be called `smtp`, `queue`, and `deliver`. Thus the SMTP server daemon would be represented by a user for the -`mta:smtp` Service. queueing with `mta:queue`, and delivery with `mta:deliver`. +`mta:smtp` Service. queueing with `mta:queue`, and delivery with `mta:deliver`. ## Implementation @@ -105,9 +108,9 @@ such that system administrators are in full control of assigning users to servic The `ServiceUserMapper` defines the following API: -#!java -String getServiceUserID(Bundle bundle, String subServiceName); - + #!java + String getServiceUserID(Bundle bundle, String subServiceName); + The implementation uses two fallbacks in case no mapping can be found for the given subServiceName 1. Use user mapping for the serviceName only (not considering subServiceName) @@ -121,10 +124,10 @@ The second part is support for service access to the Resource Tree. To this avail, the `ResourceResolverFactory` service is enhanced with a new factory method -#!java -ResourceResolver getServiceResourceResolver(Map<String, Object> authenticationInfo) -throws LoginException; - + #!java + ResourceResolver getServiceResourceResolver(Map<String, Object> authenticationInfo) + throws LoginException; + This method allows for access to the resource tree for services where the service bundle is the bundle actually using the `ResourceResolverFactory` service. The optional Subservice Name may be provided as an entry @@ -143,9 +146,9 @@ The default implementation leverages `ServiceUserMapper.getServiceUserID()` to r The third part is an extension to the `SlingRepository`service interface to support JCR Repository access for services: -#!java -Session loginService(String subServiceName, String workspace) -throws LoginException, RepositoryException; + #!java + Session loginService(String subServiceName, String workspace) + throws LoginException, RepositoryException; This method allows for access to the JCR Repository for services where the service bundle is the bundle actually using the `SlingRepository` @@ -159,23 +162,23 @@ service. The additional Subservice Name may be provided with the For each service/subservice name combination an according mapping needs to be provided. The mapping binds a service name/subservice name to a JCR system user. This is configured through an OSGi configuration for the factory configuration with PID `org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended` [SLING-3578](https://issues.apache.org/jira/browse/SLING-3578). There you can set one configuration property named `user.mapping` getting a String array as value where each entry must stick to the following format: -<service-name>[:<subservice-name>]=<authorizable id of a JCR system user>] + <service-name>[:<subservice-name>]=<authorizable id of a JCR system user>] The according user must exist at the point in time where `ResourceResolverFactory.getServiceResourceResolver(...)` or `SlingRepository.loginService(...)` is called. If you rely on one of those methods in your `activate` method of an OSGi component you should make sure that you defer starting your OSGi component until the according service user mapping is in place. For that you can reference the OSGi service `ServiceUserMapped` ([SLING-4312](https://issues.apache.org/jira/browse/SLING-4312)), optionally with a target filter on property `subServiceName` (in case such a subservice name is used). The service `ServiceUserMapped` does not expose any methods but is only a marker interface exclusively used to defer starting of other OSGi components. However this waits only for the mapping configuration to be available, it does not wait for the service user itself to be available. Example OSGi DS Component -:::java -@Component( -reference = { -// this waits with the activation of this component until a service user mapping with the service name = current bundle's id and the sub service name 'my-subservice-name' is available. -// you can leave out "target" if the sub service name is not used. -// Please note that this only waits for the mapping to be available, it does not wait for the service user itself to be available! -@Reference(name ="scriptsServiceUser", target="(subServiceName=my-subservice-name)", service=ServiceUserMapped.class) -} -) -class MyComponent { -} + :::java + @Component( + reference = { + // this waits with the activation of this component until a service user mapping with the service name = current bundle's id and the sub service name 'my-subservice-name' is available. + // you can leave out "target" if the sub service name is not used. + // Please note that this only waits for the mapping to be available, it does not wait for the service user itself to be available! + @Reference(name ="scriptsServiceUser", target="(subServiceName=my-subservice-name)", service=ServiceUserMapped.class) + } + ) + class MyComponent { + } There is a default mapping applied if no OSGi configuration is available for the mapping. The default is: "serviceuser--" + bundleId [ + "--" + subservice-name]. Please note, that these default mappings are not represented as a ServiceUserMapped service and therefore the above mentioned reference does not work. @@ -195,7 +198,7 @@ The following methods are deprecated: * `ResourceProviderFactory.getAdministrativeResourceProvider` * `SlingRepository.loginAdministrative` -The implementations we have in Sling's bundle will remain implemented +The implementations we have in Sling's bundle will remain implemented in the near future. But there will be a configuration switch to disable support for these methods: If the method is disabled, a `LoginException` is always thrown from these methods. The JavaDoc of the methods is @@ -211,15 +214,15 @@ _whitelist fragment configuration_. It can be created as an OSGi factory configuration with the factoryPID `org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment`. E.g. a typical configuration file might be called `org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment-myapp.config` -and could look as follows: - -whitelist.name="myapp" -whitelist.bundles=[ -"com.myapp.core", -"com.myapp.commons" -] - -| Property | Type | Default | Description | +and could look as follows: + + whitelist.name="myapp" + whitelist.bundles=[ + "com.myapp.core", + "com.myapp.commons" + ] + +| Property | Type | Default | Description | |---------------------|----------|-------------|-------------| | `whitelist.name` | String | `[unnamed]` | Purely informational property that allows easy identification of different fragments. | | `whitelist.bundles` | String[] | [] | An array of bundle symbolic names that should be allowed to make use of the administrative login functionality. | @@ -243,13 +246,13 @@ bundle symbolic names follow a set pattern but have randomly generated parts. Example: to whitelist all bundles generated by PaxExam a configuration file named `org.apache.sling.jcr.base.internal.LoginAdminWhitelist.config` might look as follows: -whitelist.bypass=B"false" -whitelist.bundles.regexp="^PAXEXAM.*$" - + whitelist.bypass=B"false" + whitelist.bundles.regexp="^PAXEXAM.*$" + The configuration PID is `org.apache.sling.jcr.base.internal.LoginAdminWhitelist`. It supports the following configuration properties. - -| Property | Type | Default | Description | + +| Property | Type | Default | Description | |----------------------------|----------|-------------|-------------| | `whitelist.bypass` | Boolean | false | Allow all bundles to use administrative login. This is __NOT__ recommended for production and warnings will be logged. | | `whitelist.bundles.regexp` | String | "" | A regular expression that whitelists all matching bundle symbolic names. This is __NOT__ recommended for production and warnings will be logged. | http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/the-sling-engine/servlets.md ---------------------------------------------------------------------- diff --git a/content/documentation/the-sling-engine/servlets.md b/content/documentation/the-sling-engine/servlets.md index 477e00e..ca21533 100644 --- a/content/documentation/the-sling-engine/servlets.md +++ b/content/documentation/the-sling-engine/servlets.md @@ -1,11 +1,14 @@ -title=Servlets and Scripts -type=page +title=TODO title for servlets.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Servlets and Scripts [TOC] -See also [URL to Script Resolution](/documentation/the-sling-engine/url-to-script-resolution.html) which explains how Sling maps URLs +See also [URL to Script Resolution](/documentation/the-sling-engine/url-to-script-resolution.html) which explains how Sling maps URLs to a script or and servlet. ## Servlet Registration @@ -25,7 +28,7 @@ A `SlingServletResolver` listens for `Servlet` services and - given the correct For a Servlet registered as an OSGi service to be used by the Sling Servlet Resolver, either one or both of the `sling.servlet.paths` or the `sling.servlet.resourceTypes` service reference properties must be set. If neither is set, the Servlet service is ignored. -Each path to be used for registration - either from the `sling.servlet.paths` property or constructed from the other `sling.servlet.*` properties - must be absolute. Any relative path is made absolute by prefixing it with a root path. This prefix may be set with the `sling.servlet.prefix` service registration property. If this property is not set, the first entry in the `ResourceResolver` search path for the `ResourceResolver.getResource(String)` method is used as the prefix. If this entry cannot be derived, a simpe slash - `/` - is used as the prefix. +Each path to be used for registration - either from the `sling.servlet.paths` property or constructed from the other `sling.servlet.\*` properties - must be absolute. Any relative path is made absolute by prefixing it with a root path. This prefix may be set with the `sling.servlet.prefix` service registration property. If this property is not set, the first entry in the `ResourceResolver` search path for the `ResourceResolver.getResource(String)` method is used as the prefix. If this entry cannot be derived, a simpe slash - `/` \- is used as the prefix. If `sling.servlet.methods` is not specified, the servlet is only registered for handling GET and HEAD requests. Make sure to list all methods you want to be handled by this servlet. @@ -38,54 +41,54 @@ Binding servlets by paths has several disadvantages when compared to binding by * if a path-bound servlet is not active, e.g. if the bundle is missing or not started, a POST might result in unexpected results. usually creating a node at /bin/xyz which subsequently overlays the servlets path binding * the mapping is not transparent to a developer looking just at the repository -Given these drawbacks it is strongly recommended to bind servlets to resource types rather than paths. +Given these drawbacks it is strongly recommended to bind servlets to resource types rather than paths. ### Registering a Servlet using Java Annotations -If you are working with the default Apache Sling development stack you can either use +If you are working with the default Apache Sling development stack you can either use -* [OSGi DS annotations](https://osgi.org/javadoc/r6/cmpn/org/osgi/service/component/annotations/package-summary.html) (introduced with DS 1.2/OSGi 5, properly supported since [bnd 3.0](https://github.com/bndtools/bndtools/wiki/Changes-in-3.0.0), being used in [maven-bundle-plugin 3.0.0](http://felix.apache.org/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html)) or +* [OSGi DS annotations](https://osgi.org/javadoc/r6/cmpn/org/osgi/service/component/annotations/package-summary.html) (introduced with DS 1.2/OSGi 5, properly supported since [bnd 3.0](https://github.com/bndtools/bndtools/wiki/Changes-in-3.0.0), being used in [maven-bundle-plugin 3.0.0](http://felix.apache.org/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html)) or * Generic Felix SCR or Sling-specific `@SlingServlet` annotations from [Apache Felix Maven SCR Plugin](http://felix.apache.org/documentation/subprojects/apache-felix-maven-scr-plugin.html) to register your Sling servlets: The following examples show example code how you can register Servlets with Sling 1. OSGi DS annotations (recommended) -:::java -@Component( -service = { Servlet.class }, -property = { -SLING_SERVLET_RESOURCE_TYPES + "=/apps/my/type" -SLING_SERVLET_METHODS + "=GET", -SLING_SERVLET_EXTENSIONS + "=html", -SLING_SERVLET_SELECTORS + "=hello", -} -) -public class MyServlet extends SlingSafeMethodsServlet { - -@Override -protected void doGet(SlingHttpServletRequest request, SlingHttpServletResponse response) throws ServletException, IOException { -... -} -} - -Custom OSGi DS annotations (e.g. for Sling servlets) are not yet supported by the OSGi spec (and therefore by bnd), but this is supposed to be fixed with DS 1.4 (OSGi 7), see also [FELIX-5396](https://issues.apache.org/jira/browse/FELIX-5396). + :::java + @Component( + service = { Servlet.class }, + property = { + SLING_SERVLET_RESOURCE_TYPES + "=/apps/my/type" + SLING_SERVLET_METHODS + "=GET", + SLING_SERVLET_EXTENSIONS + "=html", + SLING_SERVLET_SELECTORS + "=hello", + } + ) + public class MyServlet extends SlingSafeMethodsServlet { + + @Override + protected void doGet(SlingHttpServletRequest request, SlingHttpServletResponse response) throws ServletException, IOException { + ... + } + } + + Custom OSGi DS annotations (e.g. for Sling servlets) are not yet supported by the OSGi spec (and therefore by bnd), but this is supposed to be fixed with DS 1.4 (OSGi 7), see also [FELIX-5396](https://issues.apache.org/jira/browse/FELIX-5396). 2. The `@SlingServlet` annotation (evaluated by maven-scr-plugin) -:::java -@SlingServlet( -resourceTypes = "/apps/my/type", -selectors = "hello", -extensions = "html", -methods = "GET") -public class MyServlet extends SlingSafeMethodsServlet { + :::java + @SlingServlet( + resourceTypes = "/apps/my/type", + selectors = "hello", + extensions = "html", + methods = "GET") + public class MyServlet extends SlingSafeMethodsServlet { -@Override -protected void doGet(SlingHttpServletRequest request, SlingHttpServletResponse response) throws ServletException, IOException { -... -} -} + @Override + protected void doGet(SlingHttpServletRequest request, SlingHttpServletResponse response) throws ServletException, IOException { + ... + } + } ### Automated tests @@ -98,9 +101,9 @@ Such tests run as part of our continuous integration process, to demonstrate and ### Example: Registration by Path -sling.servlet.paths = [ "/libs/sling/sample/html", "/libs/sling/sample/txt" ] -sling.servlet.selectors = [ "img" ] -sling.servlet.extensions = [ "html", "txt", "json" ] + sling.servlet.paths = [ "/libs/sling/sample/html", "/libs/sling/sample/txt" ] + sling.servlet.selectors = [ "img" ] + sling.servlet.extensions = [ "html", "txt", "json" ] A Servlet service registered with these properties is registered under the following paths: @@ -114,9 +117,9 @@ The registration properties `sling.servlet.selectors` and `sling.servlet.extensi ### Example: Registration by Resource Type etc. -sling.servlet.resourceTypes = [ "sling/unused" ] -sling.servlet.selectors = [ "img", "tab" ] -sling.servlet.extensions = [ "html", "txt", "json" ] + sling.servlet.resourceTypes = [ "sling/unused" ] + sling.servlet.selectors = [ "img", "tab" ] + sling.servlet.extensions = [ "html", "txt", "json" ] A Servlet service registered with these properties is registered for the following resource types: http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/the-sling-engine/sling-api-crud-support.md ---------------------------------------------------------------------- diff --git a/content/documentation/the-sling-engine/sling-api-crud-support.md b/content/documentation/the-sling-engine/sling-api-crud-support.md index 23fe6a8..1fb2aba 100644 --- a/content/documentation/the-sling-engine/sling-api-crud-support.md +++ b/content/documentation/the-sling-engine/sling-api-crud-support.md @@ -1,7 +1,10 @@ -title=Sling API CRUD Support -type=page +title=TODO title for sling-api-crud-support.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Sling API CRUD Support [TOC] @@ -9,13 +12,13 @@ status=published As of version 2.3.0, the Sling API provides full Create Read Update Delete (CRUD) features. CRUD support is provided by the addition of the following methods to the ResourceResolver: -* [void delete(Resource resource) throws PersistenceException](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#delete-org.apache.sling.api.resource.Resource-) -* [Resource create(Resource parent, String name, Map<String, Object> properties) throws PersistenceException](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#create-org.apache.sling.api.resource.Resource-java.lang.String-java.util.Map-) -* [void revert()](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#revert--) -* [void commit() throws PersistenceException](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#commit--) -* [boolean hasChanges()](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#hasChanges--) -* [void refresh()](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#refresh--) - + * [void delete(Resource resource) throws PersistenceException](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#delete-org.apache.sling.api.resource.Resource-) + * [Resource create(Resource parent, String name, Map<String, Object> properties) throws PersistenceException](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#create-org.apache.sling.api.resource.Resource-java.lang.String-java.util.Map-) + * [void revert()](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#revert--) + * [void commit() throws PersistenceException](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#commit--) + * [boolean hasChanges()](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#hasChanges--) + * [void refresh()](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#refresh--) + Which provide the ability to create and delete resources as well as the addition of the ModifiableValueMap interface which is similar to the ValueMap interface, but allows for updating properties on a resource. ## Comparing Sling API CRUD to Sling Post Servlet @@ -28,37 +31,37 @@ Update /myresource, setting the title and body: **Sling Post Servlet** -<form action="/myresource" method="POST"> -<input type="text" name="title"> -<textarea name="body"> -</form> - + <form action="/myresource" method="POST"> + <input type="text" name="title"> + <textarea name="body"> + </form> + **Sling API CRUD** -Resource myResource = resourceResolver.getResource("/myresource"); -ModifiableValueMap properties = myNode.adaptTo(ModifiableValueMap.class); -properties.put("title", {TITLE}); -properties.put("body", {BODY}); -resourceResolver.commit(); - + Resource myResource = resourceResolver.getResource("/myresource"); + ModifiableValueMap properties = myNode.adaptTo(ModifiableValueMap.class); + properties.put("title", {TITLE}); + properties.put("body", {BODY}); + resourceResolver.commit(); + ### Create New Resource Create a new resource below /myresource **Sling Post Servlet** -<form action="/myresource/" method="POST"> -<input type="text" name="dummy"> -</form> + <form action="/myresource/" method="POST"> + <input type="text" name="dummy"> + </form> **Sling API CRUD** -Resource myResource = resourceResolver.getResource("/myresource"); -Map<String,Object> properties = new HashMap<String,Object>(); -properties.put("jcr:primaryType", "nt:unstructured"); -properties.put("sling:resourceType", "myapp/components/mytype"); -Resource dummy = resourceResolver.create(myResource, "dummy", properties); -resourceResolver.commit(); + Resource myResource = resourceResolver.getResource("/myresource"); + Map<String,Object> properties = new HashMap<String,Object>(); + properties.put("jcr:primaryType", "nt:unstructured"); + properties.put("sling:resourceType", "myapp/components/mytype"); + Resource dummy = resourceResolver.create(myResource, "dummy", properties); + resourceResolver.commit(); ### Remove a Property @@ -66,16 +69,16 @@ Remove the property title **Sling Post Servlet** -<form action="/myresource" method="POST"> -<input type="hidden" name="title@Delete"> -</form> + <form action="/myresource" method="POST"> + <input type="hidden" name="title@Delete"> + </form> **Sling API CRUD** -Resource myResource = resourceResolver.getResource("/myresource"); -ModifiableValueMap properties = myResource.adaptTo(ModifiableValueMap.class); -properties.remove("title"); -resourceResolver.commit(); + Resource myResource = resourceResolver.getResource("/myresource"); + ModifiableValueMap properties = myResource.adaptTo(ModifiableValueMap.class); + properties.remove("title"); + resourceResolver.commit(); ### Copy a Resource @@ -83,17 +86,17 @@ Copy the resource /myresource to /myresource2 **Sling Post Servlet** -<form action="/myresource" method="POST"> -<input type="hidden" name=":operation" value="copy"> -<input type="hidden" name=":dest" value="/myresource2"> -<input type="hidden" name=":replace" value="true"> -</form> + <form action="/myresource" method="POST"> + <input type="hidden" name=":operation" value="copy"> + <input type="hidden" name=":dest" value="/myresource2"> + <input type="hidden" name=":replace" value="true"> + </form> **Sling API CRUD** -Map<String,Object> properties = myResource.adaptTo(ValueMap.class); -Resource myResource2 = resourceResolver.create(null, "myresource2", properties); -resourceResolver.commit(); + Map<String,Object> properties = myResource.adaptTo(ValueMap.class); + Resource myResource2 = resourceResolver.create(null, "myresource2", properties); + resourceResolver.commit(); ### Move a Resource @@ -101,18 +104,18 @@ Move the resource /myresource2 to /myresource3 **Sling Post Servlet** -<form action="/myresource2" method="POST"> -<input type="hidden" name=":operation" value="move"> -<input type="hidden" name=":dest" value="/myresource3"> -</form> + <form action="/myresource2" method="POST"> + <input type="hidden" name=":operation" value="move"> + <input type="hidden" name=":dest" value="/myresource3"> + </form> **Sling API CRUD** -Resource myResource2 = resourceResolver.getResource("/myresource2"); -Map<String,Object> properties = myResource2.adaptTo(ValueMap.class); -Resource myResource3 = resourceResolver.create(null, "myresource3", properties); -resourceResolver.delete(myResource2); -resourceResolver.commit(); + Resource myResource2 = resourceResolver.getResource("/myresource2"); + Map<String,Object> properties = myResource2.adaptTo(ValueMap.class); + Resource myResource3 = resourceResolver.create(null, "myresource3", properties); + resourceResolver.delete(myResource2); + resourceResolver.commit(); ### Setting non-String Value @@ -120,18 +123,18 @@ Set the property date to a particular date **Sling Post Servlet** -<form action="/myresource3" method="POST"> -<input type="text" name="date" value="2008-06-13T18:55:00"> -<input type="hidden" name="date@TypeHint" value="Date"> -</form> + <form action="/myresource3" method="POST"> + <input type="text" name="date" value="2008-06-13T18:55:00"> + <input type="hidden" name="date@TypeHint" value="Date"> + </form> **Sling API CRUD** -Resource myResource3 = resourceResolver.getResource("/myresource3"); -Calendar calendar = [SOME_DATE]; -ModifiableValueMap properties = myResource3.adaptTo(ModifiableValueMap.class); -properties.put("date", calendar); -resourceResolver.commit(); + Resource myResource3 = resourceResolver.getResource("/myresource3"); + Calendar calendar = [SOME_DATE]; + ModifiableValueMap properties = myResource3.adaptTo(ModifiableValueMap.class); + properties.put("date", calendar); + resourceResolver.commit(); ### Delete a Resource @@ -139,34 +142,34 @@ Delete the resource /myresource **Sling Post Servlet** -<form action="/myresource" method="POST"> -<input type="hidden" name=":operation" value="delete"> -</form> - + <form action="/myresource" method="POST"> + <input type="hidden" name=":operation" value="delete"> + </form> + **Sling API CRUD** - -Resource myResource = resourceResolver.getResource("/myresource"); -resourceResolver.delete(myResource); -resourceResolver.commit(); + + Resource myResource = resourceResolver.getResource("/myresource"); + resourceResolver.delete(myResource); + resourceResolver.commit(); ## Value Class Support <div class="info"> -Please note, this information is specific to the Sling JCR Resource implementation provided by the Apache Sling project. Other implementations may have different value class support. + Please note, this information is specific to the Sling JCR Resource implementation provided by the Apache Sling project. Other implementations may have different value class support. </div> The Classes implementing the following types are supported directly when setting properties: -* [Calendar](http://docs.oracle.com/javase/8/docs/api/java/util/Calendar.html) -* [InputStream](http://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html) -* [Node](http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/Node.html) -* [BigDecimal](http://docs.oracle.com/javase/8/docs/api/java/math/BigDecimal.html) -* [Long](http://docs.oracle.com/javase/8/docs/api/java/lang/Long.html) -* [Short](http://docs.oracle.com/javase/8/docs/api/java/lang/Short.html) -* [Integer](http://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html) -* [Number](http://docs.oracle.com/javase/8/docs/api/java/lang/Number.html) -* [Boolean](http://docs.oracle.com/javase/8/docs/api/java/lang/Boolean.html) -* [String](http://docs.oracle.com/javase/8/docs/api/java/lang/String.html) - + * [Calendar](http://docs.oracle.com/javase/8/docs/api/java/util/Calendar.html) + * [InputStream](http://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html) + * [Node](http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/Node.html) + * [BigDecimal](http://docs.oracle.com/javase/8/docs/api/java/math/BigDecimal.html) + * [Long](http://docs.oracle.com/javase/8/docs/api/java/lang/Long.html) + * [Short](http://docs.oracle.com/javase/8/docs/api/java/lang/Short.html) + * [Integer](http://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html) + * [Number](http://docs.oracle.com/javase/8/docs/api/java/lang/Number.html) + * [Boolean](http://docs.oracle.com/javase/8/docs/api/java/lang/Boolean.html) + * [String](http://docs.oracle.com/javase/8/docs/api/java/lang/String.html) + As well as the corresponding primitive types. Any object which implements the Serializable interface will be serialized and the result of the serialization will be saved as a binary value for the property. http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/the-sling-engine/sling-properties.md ---------------------------------------------------------------------- diff --git a/content/documentation/the-sling-engine/sling-properties.md b/content/documentation/the-sling-engine/sling-properties.md index 8e5d417..1dd2ee2 100644 --- a/content/documentation/the-sling-engine/sling-properties.md +++ b/content/documentation/the-sling-engine/sling-properties.md @@ -1,7 +1,10 @@ -title=Well-known Sling Properties -type=page +title=TODO title for sling-properties.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Well-known Sling Properties This table lists properties which have known functionality in the OSGi and Sling frameworks. http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/the-sling-engine/the-sling-launchpad.md ---------------------------------------------------------------------- diff --git a/content/documentation/the-sling-engine/the-sling-launchpad.md b/content/documentation/the-sling-engine/the-sling-launchpad.md index 8f4ad76..77066a6 100644 --- a/content/documentation/the-sling-engine/the-sling-launchpad.md +++ b/content/documentation/the-sling-engine/the-sling-launchpad.md @@ -1,7 +1,10 @@ -title=The Sling Launchpad -type=page +title=TODO title for the-sling-launchpad.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: The Sling Launchpad [TOC] @@ -34,10 +37,10 @@ The Java Standalone Application supports a number of command line options, which | `status` | -- | Check whether a (remote) Sling application is running. Uses option `-j` to define the address of the Sling instance to check. Note, that the Sling application terminates after checking for the (remote) Sling status. | | `stop` | -- | Stop a (remote) Sling application is running. Uses option `-j` to define the address of the Sling instance to stop. Note, that the Sling application tesrminates after stopping the (remote) Sling instance. | | `-j` | [ host ":" ] port | The socket address to listen on for control connections (`start` or to use as the remote endpoint for the control connection (`status` and `stop`. If this parameter has no arguments or is not specified, the address defaults to any free port on localhost/127.0.0.1. If only the port is specified localhost/127.0.0.1 is used as the host part of the address. | -| `-c` | slinghome | The directory in which Sling locates its initial configuration file `sling.properties` and where files of Sling itself such as the Apache Felix bundle archive or the JCR repository files are stored. This defaults to the `sling` folder in the current working directory. This is the value which is commonly refered to as `${sling.home}.` -| `-i` | launchpadhome | The launchpad directory. If not set, this is the same as `${sling.home}.` (since Sling Launchpad 2.4.0) | +| `-c` | slinghome | The directory in which Sling locates its initial configuration file `sling.properties` and where files of Sling itself such as the Apache Felix bundle archive or the JCR repository files are stored. This defaults to the `sling` folder in the current working directory. This is the value which is commonly refered to as `$\{sling.home}.` +| `-i` | launchpadhome | The launchpad directory. If not set, this is the same as `$\{sling.home}.` (since Sling Launchpad 2.4.0) | | `-l` | loglevel | Sets the initial loglevel as an integer in the range 0 to 4 or as one of the well known level strings `ERROR`, `WARN`, `INFO`, or `DEBUG`. This option overwrites the `org.apache.sling.osg.log.level` setting the `sling.properties` file. The default is `INFO`. | -| `-f` | logfile | The log file to use or `-` to log to standard out. This option overwrites the `org.apache.sling.osg.log.file` setting in the `sling.properties` file. The default is `${sling.home}/logs/error.log`. | +| `-f` | logfile | The log file to use or `-` to log to standard out. This option overwrites the `org.apache.sling.osg.log.file` setting in the `sling.properties` file. The default is `$\{sling.home}/logs/error.log`. | | `-a` | address | The interfact to bind to (use 0.0.0.0 for any). This option overwrites the `org.apache.felix.http.host` setting in the `sling.properties` file and requires the embedded Http Service implementation to honor this property. (supported since Sling Launchpad 2.4.0) | | `-p` | port | The port to listen (default 8080) to handle HTTP requests. This option overwrites the `org.osgi.service.http.port` setting in the `sling.properties` file. | | `-r` | path | The root servlet context path for the Http Service (default is /). This option overwrites the `org.apache.felix.http.context_path` setting in the `sling.properties` file and requires the embedded Http Service implementation to honor this property. (since Sling Launchpad 2.4.0) | @@ -65,7 +68,7 @@ Currently supported commands are For the Whole Truth about this functionality see the [ControlListener class source code](https://svn.apache.org/repos/asf/sling/trunk/launchpad/base/src/main/java/org/apache/sling/launchpad/app/ControlListener.java). -The interface and port is configurable with the `-j` command line option. The actual address and port used are written to the `${sling.home}/conf/controlport` file. So technically the `-j` option is not required for the `status` and `stop` operations because the port information can be read from that file. +The interface and port is configurable with the `-j` command line option. The actual address and port used are written to the `$\{sling.home}/conf/controlport` file. So technically the `-j` option is not required for the `status` and `stop` operations because the port information can be read from that file. Note that using a control connection for the Sling Standalone Application presents a potential security issue. For this reason the following defaults apply: @@ -77,28 +80,28 @@ For additional security, do not allow the control port to be opened on an extern Here's an example session where a Sling Standalone Application is started with the control port active: -$ java -jar target/org.apache.sling.launchpad-9-SNAPSHOT.jar start -05.04.2016 11:50:45.003 *INFO * [main] Setting sling.home=sling (default) -05.04.2016 11:50:45.006 *INFO * [main] Starting Apache Sling in /foo/sling/launchpad/builder/sling -... -05.04.2016 11:50:45.012 *INFO * [Apache Sling Control Listener@/127.0.0.1:59239] Apache Sling Control Listener started -... - + $ java -jar target/org.apache.sling.launchpad-9-SNAPSHOT.jar start + 05.04.2016 11:50:45.003 *INFO * [main] Setting sling.home=sling (default) + 05.04.2016 11:50:45.006 *INFO * [main] Starting Apache Sling in /foo/sling/launchpad/builder/sling + ... + 05.04.2016 11:50:45.012 *INFO * [Apache Sling Control Listener@/127.0.0.1:59239] Apache Sling Control Listener started + ... + And stopped using its control port, from another terminal: -$ cat sling/conf/controlport -127.0.0.1:59239 -mdsryh1k5fpcgvm7suqnckxkr7fvluzv - -$ telnet 127.0.0.1 59239 -Trying 127.0.0.1... -Connected to localhost. -Escape character is '^]'. - -mdsryh1k5fpcgvm7suqnckxkr7fvluzv stop - -OK -Connection closed by foreign host. + $ cat sling/conf/controlport + 127.0.0.1:59239 + mdsryh1k5fpcgvm7suqnckxkr7fvluzv + + $ telnet 127.0.0.1 59239 + Trying 127.0.0.1... + Connected to localhost. + Escape character is '^]'. + + mdsryh1k5fpcgvm7suqnckxkr7fvluzv stop + + OK + Connection closed by foreign host. ### Shutdown Hook @@ -146,7 +149,7 @@ The `sling.properties` file contains the initial setup of the Sling Application One thing to note is, that the `sling.properties` file is a simple Java Properties file with support for property references. That is, the value of properties may refer other property values by means of the well known `${name}` notation. Such property references may even be nested as in -java.packages=${jre-${java.specification.version}} + java.packages=${jre-${java.specification.version}} @@ -164,7 +167,7 @@ The *Launchpad Base* projects creates the following artifacts, which are require * *App JAR* -- The secondary artifact with classifier *app* is a minimal Standalone Java Application which may be started by simply typing -$ java -jar org.apache.sling.launchpad.base-app.jar + $ java -jar org.apache.sling.launchpad.base-app.jar * *Web App Archive* -- The secondary artifact with classifier *webapp* is a minimal Web Application, which may simply be deployed into your favirourite servlet container, provided it supports at least Servlet API 2.4. @@ -179,7 +182,7 @@ The *Launchpad App* and *Launchpad WebApp* bundles are actually projects which j * Take the appropriate secondary artifact from the *Launchpad Base* project: *app* for the Standalone Java Application or *webapp* for the Web Application and unpack * Take the *Launchpad Base* primary artifact and place it under the name `org.apache.sling.launchpad.base.jar` into the `resources` folder -* Copies the list of artifacts defined in the [Provisioning model](/documentation/development/slingstart.html) +* Copies the list of artifacts defined in the [Provisioning model](/documentation/development/slingstart.html) * Finally pack all together into a single big JAR or WAR file The artifacts can be configured to use different JCR repository implementations, based on the value of the `-Dsling.run.modes` property. The following run modes are available for the 8 version of the Sling Launchpad: http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/the-sling-engine/url-decomposition.md ---------------------------------------------------------------------- diff --git a/content/documentation/the-sling-engine/url-decomposition.md b/content/documentation/the-sling-engine/url-decomposition.md index d29eba0..35b8114 100644 --- a/content/documentation/the-sling-engine/url-decomposition.md +++ b/content/documentation/the-sling-engine/url-decomposition.md @@ -1,7 +1,10 @@ -title=URL decomposition -type=page +title=TODO title for url-decomposition.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: URL decomposition [TOC] @@ -11,7 +14,7 @@ During the *Resource Resolution* step, the client request URI (as being returned 1. **Resource Path** - For existing resources the resource path is the longest match (also considering its [mappings](/documentation/the-sling-engine/mappings-for-resource-resolution.html)) pointing to a resource where the next character is either a dot (`.`) or it is the full request URI. Otherwise (for a path not matching any existing resource) the resource path ends at the *first dot (`.`)* in the request url. The exact logic for retrieving the resource path is implemented at [ResourceResolver.resolve(HttpServletRequest,String)](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#resolve-javax.servlet.http.HttpServletRequest-java.lang.String-). *It is impossible to tell from just looking at the request URI where the resource path part ends. You have to know the underlying resource structure to know how a URL is decomposed. You cannot safely assume that the resource path will always end at the first dot!*. 1. **Selectors** - If the first character in the request URL after the resource path is a dot (`.`), the string after the dot up to but not including the last dot before the next slash character or the end of the request URL comprises the selectors. If the resource path spans the complete request URL no selectors exist. If only one dot follows the resource path before the end of the request URL or the next slash, also no selectors exist. -1. **Extension** - The string after the last dot after the resource path in the request URL but before the end of the request URL or the next slash after the resource path in the request URL is the extension. +1. **Extension** - The string after the last dot after the resource path in the request URL but before the end of the request URL or the next slash after the resource path in the request URL is the extension. 1. **Suffix** - If the request URL contains a slash character after the resource path and optional selectors and extension, the path starting with the slash up to the end of the request URL is the suffix path. Otherwise, the suffix path is empty. Note, that after the resource path at least a dot must be in the URL to let Sling detect the suffix. Those decomposed parts can be accessed through the `RequestPathInfo` object, which is retrieved via [SlingHttpServletRequest.getPathInfo()](https://sling.apache.org/apidocs/sling7/org/apache/sling/api/SlingHttpServletRequest.html#getRequestPathInfo--).
