Author: buildbot
Date: Fri Feb 12 16:48:15 2016
New Revision: 980233
Log:
Staging update by buildbot for sling
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/the-sling-engine/request-parameters.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Feb 12 16:48:15 2016
@@ -1 +1 @@
-1730022
+1730069
Modified:
websites/staging/sling/trunk/content/documentation/the-sling-engine/request-parameters.html
==============================================================================
---
websites/staging/sling/trunk/content/documentation/the-sling-engine/request-parameters.html
(original)
+++
websites/staging/sling/trunk/content/documentation/the-sling-engine/request-parameters.html
Fri Feb 12 16:48:15 2016
@@ -144,11 +144,19 @@ h2:hover > .headerlink, h3:hover > .head
<td><code>ServletRequest.getParameterNames()</code></td>
<td>Returns an enumeration of the names of the parameters</td>
</tr>
+<tr>
+<td><code>ServletRequest.getParts()</code></td>
+<td>Returns all parts of the multipart request (since v3.0)</td>
+</tr>
+<tr>
+<td><code>ServletRequest.getPart(String)</code></td>
+<td>Returns the request part with that name in case of multipart requests
(since v3.0)</td>
+</tr>
</tbody>
</table>
-<p>As a special restriction only two kinds of parameters are supported: (1)
Query String parameters and (2) parameters contained in the request data of
content type <code>application/x-www-form-encoded</code>. That is file uploads
using request data of type <code>multipart/form-data</code> are not directly
supported by the servlet specification. Finally the actual encoding of the
parameters is all but safe because the encoding of URLs is not very well
defined and browsers do not set the character encoding when sending post data.
Fortunately, they use the same character encoding for sending back form content
as was used by the server to send the form.</p>
+<p>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. </p>
<h2 id="sling-api">Sling API<a class="headerlink" href="#sling-api"
title="Permanent link">¶</a></h2>
-<p>To overcome these restrictions and to provide uniform access to request
parameters the Sling API in addition to the Servlet API methods to access
parameters provides an abstraction of parameters which is applicable to all
parameters sent by clients, the <code>RequestParameter</code> interface.
Through this interface, each parameter may be analyzed for these topics:</p>
+<p>To overcome the restrictions and to provide uniform access to request
parameters the Sling API in addition to the Servlet API methods to access
parameters provides an abstraction of parameters which is applicable to all
parameters sent by clients, the <code>RequestParameter</code> interface.
Through this interface, each parameter may be analyzed for these topics:</p>
<table class="table">
<thead>
<tr>
@@ -201,6 +209,9 @@ h2:hover > .headerlink, h3:hover > .head
<li>After the servlet container provided parameters are parameters extracted
from the request in case <code>multipart/form-data</code> POST requests. The
order of these parameters is preserved as they are submitted in the request.
This conforms to HTML 4.01 spec on forms submitted with multipart/form-data
encoding: <em>A "multipart/form-data" message contains a series of parts, each
representing a successful control. The parts are sent to the processing agent
in the same order the corresponding controls appear in the document stream.
Part boundaries should not occur in any of the data; how this is done lies
outside the scope of this specification</em> (<a
href="http://www.w3.org/TR/html401/interact/forms.html";>17.13.4 Form content
types</a>)</li>
</ul>
<p>Be warned: Only rely on request parameter ordering
<code>multipart/form-data</code> POST requests without a query part in the
request URL.</p>
+<h3 id="implications-of-sling-on-servlet-api-methods">Implications of Sling on
Servlet API methods<a class="headerlink"
href="#implications-of-sling-on-servlet-api-methods" title="Permanent
link">¶</a></h3>
+<p>From within Sling servlets/scripts you can no longer rely on the original
semantics of the Servlet API methods for dealing with parameters as
<code>ServletRequest.getParameter(String)</code>,
<code>ServletRequest.getParameterValues(String)</code>,
<code>ServletRequest.getParameterMap()</code>,<code>ServletRequest.getParameterNames()</code>,<code>ServletRequest.getParts()</code>,<code>ServletRequest.getPart(String)</code>
internally use the Sling parameter support (and therefore have the same
implications on e.g. encoding). You should preferably use the Sling methods
<code>getRequestParameter*</code> instead.</p>
+<p>Calling <code>ServletRequest.getInputStream()</code> is not supported, nor
relying on some 3rd party libraries which are internally using that method like
<a href="https://commons.apache.org/proper/commons-fileupload/";>Apache Commons
Fileupload</a>. This is because the Sling parameter support needs exclusive
access to the request's input stream.</p>
<h2 id="character-encoding">Character Encoding<a class="headerlink"
href="#character-encoding" title="Permanent link">¶</a></h2>
<p>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:</p>
<ul>
@@ -218,7 +229,7 @@ h2:hover > .headerlink, h3:hover > .head
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 to
the desired encoding, which of course must be supported by the actual Java
Platform.
</div>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1550337 by cziegeler on Thu, 12 Dec 2013 03:17:06 +0000
+ Rev. 1730069 by kwin on Fri, 12 Feb 2016 16:47:54 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
