incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Sling Website > Request Parameters
Date Wed, 11 Nov 2009 09:54:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=SLINGxSITE&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Request+Parameters">Request
Parameters</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~fmeschbe">Felix
Meschberger</a>
    </h4>
     
          <br/>
     <div class="notificationGreySide">
         <h1><a name="RequestParameters-RequestParameterHandlinginSling"></a>Request
Parameter Handling in Sling</h1>



<h2><a name="RequestParameters-ServletAPI"></a>Servlet API</h2>

<p>The Servlet API specification provides the following methods to access the parameters
of a request</p>

<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> <tt>HttpServletRequest.getQueryString()</tt> </td>
<td class='confluenceTd'> Returns the query part of the request URL </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>ServletRequest.getParameter(String)</tt> </td>
<td class='confluenceTd'> Returns the (first) named parameter </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>ServletRequest.getParameterValues(String)</tt>
</td>
<td class='confluenceTd'> Returns all parameters of that name </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>ServletRequest.getParameterMap()</tt> </td>
<td class='confluenceTd'> Returns all parameters as a map of <tt>String[]</tt>
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>ServletRequest.getParameterNames()</tt> </td>
<td class='confluenceTd'> Returns an enumeration of the names of the parameters </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 <tt>application/x-www-form-encoded</tt>.
That is file uploads using request data of type <tt>multipart/form-data</tt> 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>


<h2><a name="RequestParameters-SlingAPI"></a>Sling API</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 <tt>RequestParameter</tt>
interface. Through this interface, each parameter may be analyzed for these topics:</p>

<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> Raw Content </td>
<td class='confluenceTd'> Byte array and <tt>InputStream</tt> representation
of the request parameter values. You will generally use the <tt>InputStream</tt>
to handle uploaded files. </td>
</tr>
<tr>
<td class='confluenceTd'> String Content </td>
<td class='confluenceTd'> Access the values as strings is some given encoding (see below)
or by requesting the conversion using an explicit encoding. </td>
</tr>
<tr>
<td class='confluenceTd'> File Uploads </td>
<td class='confluenceTd'> Find out whether a parameter is a file upload, get the size
in bytes of the parameter value and client side file name as sent by the browser. </td>
</tr>
</tbody></table>

<p>To accomodate this new interface as well as to provide easy access in the traditional
way the <tt>SlingHttpServletRequest</tt> interface adds following methods to the
standard Servlet API parameter access methods:</p>

<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'> <tt>getRequestParameter(String)</tt> </td>
<td class='confluenceTd'> Returns the (first) named parameter as a <tt>RequestParameter</tt>
instance </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>getRequestParameters(String)</tt> </td>
<td class='confluenceTd'> Returns the named parameter as an array of <tt>RequestParameter</tt>
instances </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>getRequestParameterMap()</tt> </td>
<td class='confluenceTd'> Returns <tt>RequestParameterMap</tt> being a map
of <tt>RequestParameter</tt> arrays indexed by parameter names </td>
</tr>
</tbody></table>

<p>All parameters are handled the same, that is all methods give access to the same
parameters regardless of whether the parameters were transmitted in the request query, as
part of form encoded data or as part of a <tt>multipart/form-data</tt> request.</p>

<p>As of Sling Engine 2.1.0 the order or request parameters in the <tt>getRequestParameterMap()</tt>,
<tt>getParameterMap()</tt>, and <tt>getParameterNams()</tt> is preserved
as follows:</p>

<ul>
	<li>The first entries are the parameters reported by the servlet container. The order
of these parameters amongst each other is not defined. The <tt>SlingHttpServletRequest</tt>
provides them in the same order as provided by the servlet container.</li>
	<li>After the servlet container provided parameters are parameters extracted from the
request in case <tt>multipart/form-data</tt> 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"
rel="nofollow">17.13.4 Form content types</a>)</li>
</ul>


<p>Be warned: Only rely on request parameter ordering <tt>multipart/form-data</tt>
POST requests without a query part in the request URL.</p>

<h2><a name="RequestParameters-CharacterEncoding"></a>Character Encoding</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>
	<li>All forms should contain a hidden field of the name <tt>&#95;charset&#95;</tt>
containing the actual encoding used to send the form from the server to the client</li>
	<li>All forms should be sent with <em>UTF-8</em> character encoding</li>
</ul>


<p>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 <em>UTF-8</em> is one of the best choices anyway.</p>

<p>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 <tt>ISO-8859-1</tt> encoding. The second
phase locates the <tt>&#95;charset&#95;</tt> parameter and fixes the character
encodings of the parameters as follows:</p>

<ul>
	<li>All names of the parameters are re-encoded</li>
	<li>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 <tt>byte[]</tt>
where the conversion to a string is done on the fly (and yes, the conversion using the <tt>&#95;charset&#95;</tt>
character encoding is of course cached for performance reasons)</li>
	<li>If the parameter is an uploaded file, the file name is re-encoded on the fly when
accessed</li>
</ul>

     </div>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>

       <a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Request+Parameters">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=76184&revisedVersion=4&originalVersion=3">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Request+Parameters?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message