jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Jackrabbit Wiki] Update of "ApacheSling/SlingGuideRequestParameters" by FelixMeschberger
Date Tue, 10 Jul 2007 09:13:00 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jackrabbit Wiki" for change notification.

The following page has been changed by FelixMeschberger:

The comment on the change is:

New page:
= Request Parameter Handling in Sling =

== Servlet API ==

The Servlet API specification provides the following methods to access the parameters of a

|| {{{HttpServletRequest.getQueryString()}}} || Returns the query part of the request URL
|| {{{ServletRequest.getParameter(String)}}} || Returns the (first) named parameter ||
|| {{{ServletRequest.getParameterValues(String)}}} || Returns all parameters of that name
|| {{{ServletRequest.getParameterMap()}}} || Returns all parameters as a map of {{{String[]}}}
|| {{{ServletRequest.getParameterNames()}}} || Returns an enumeration of the names of the
parameters ||

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 {{{application/x-www-form-encoded}}}.
That is file uploads using request data of type {{{multipart/form-data}}} 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.

== Component API ==

To overcome these restrictions and to provide uniform access to request parameters the Component
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 {{{RequestParameter}}}
interface. Through this interface, each parameter may be analyzed for these topics:

|| Raw Content || Byte array and {{{InputStream}}} representation of the request parameter
values. You will generally use the {{{InputStream}}} to handle uploaded files. ||
|| String Content || Access the values as strings is some given encoding (see below) or by
requesting the conversion using an explicit encoding. ||
|| File Uploads || 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. ||

To accomodate this new interface as well as to provide easy access in the traditional way
the {{{ComponentRequest}}} interface provides the standard Servlet API parameter access methods
and adds following methods:

|| {{{getRequestParameter(String)}}} || Returns the (first) named parameter as a {{{RequestParameter}}}
instance ||
|| {{{getRequestParameters(String)}}} || Returns the named parameter as an array of {{{RequestParameter}}}
|| {{{getRequestParameterMap()}}} || Returns a map of {{{RequestParameter}}} arrays indexed
by parameter names ||

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 {{{multipart/form-data}}} request.

== Character Encoding ==

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 {{{FormEncoding}}} 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 {{{FormEncoding}}}
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[]}}} where the
conversion to a string is done on the fly (and yes, the conversion using the {{{FormEncoding}}}
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

View raw message