svn commit: r980233 - in /websites/staging/sling/trunk/content: ./ documentation/the-sling-engine/request-parameters.html

[bu...@apache.org]

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">&para;</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">&para;</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">&para;</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