Helma Logo
main list history
previous version  overview  next version

Version 3 by hannes on 15. June 2007, 16:02

=== Specialized and aggregated parameter collections ===

In previous versions of Helma, HTTP parameters, cookies, and selected HTTP headers were all coerced into the req.data collection. Helma 1.6 introduces separate collections for various data, with req.data acting as a combinator of the varous collections to maintain backwards compatibility.

The new collections are:

<dl>
<dt>req.postParams</dt>
<dd>Holds parameters passed from a HTTP POST request.</dd>
<dt>req.queryParams</dt>
<dd>Holds parameters passed from the HTTP query string.</dd>
<dt>req.params</dt>
<dd>Holds parameters combined from the HTTP query string and the HTTP POST request.</dd>
<dt>req.cookies</dt>
<dd>Holds cookies sent by the HTTP client. Access via <code>req.cookies.cookiename</code> to retrieve the cookie value as string, or <code>req.cookies.cookiename_cookie</code> to retieve the *javax.servlet.http.Cookie|http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/http/Cookie.html* instance.</dd>
<dt>req.data</dt>
<dd>Backwards compatible collection containing HTTP parameters, cookies, and assorted HTTP headers.</dd>
</dl>

=== Improved handling of multi-value parameters

Before version 1.6, Helma only set the req.data.paramname_array array value if a parameter value actually had more than one value. With Helma 1.6, it is always possible to access parameter values as arrays, even if they only have one value. This makes handling multi-valued parameters much easier, because it is no longer necessary to handle the one-value case separately.

=== HTTP parameter grouping

Helma allows HTTP parameters to be grouped into objects using a objectid[partid] syntax in the parameter name. For example, a parameter name of foo[bar] will result in a req.data.foo object being created. The actual parameter value will be available at req.data.foo.bar.

This feature can be used recursively, meaning that a parameter named foo[bar][dong] will result in req.data.foo.bar.dong.

=== HTTP header methods

Helma 1.6 provides the following new methods to access HTTP headers in the response and request objects:

  req.getHeader(name)
  req.getHeaders(name)
  req.getIntHeader(name)
  req.getDateHeader(name)
  
  res.setHeader(name, value)
  res.setDateHeader(name, value)
  res.addHeader(name, value)
  res.addDateHeader(name, value)

=== HTTP parameter remainders

Todo, see http://helma.org/bugs/show_bug.cgi?id=522

=== File upload memory requirements

File uploads in Helma 1.6 have a dramatically impoved memory footprint compared to previous versions by storing uploaded files to a temporary file rather than passing them in memory as byte arrays. With this, it is possible to handle really large files easily.

To preserve the benefit, it is necessary to take some care when dealing with file uploads. There is a new getInputStream() method in *helma.util.MimePart|http://adele.helma.org/source/viewcvs.cgi/helma/src/helma/util/MimePart.java?cvsroot=hop* which allows to read the content from an input stream rather than loading it into memory all at once using getContent().

To support this, the Helma Image constructor now can take an input stream as argument. The following code snippet shows how it is possible to use this feature in a way that is compatible with previous versions of Helma:

  // read image from input stream if available -
  // otherwise pass content as byte array.
  var img = new Image(req.data.file.inputStream ||
                      req.data.file.content);

=== File upload monitoring

Helma 1.6 supports tracking of file upload progress via a user's session. Upload tracking is activated by adding a <code>upload_id</code> parameter to the query string. The current upload status can be retrieved by using the <code>session.getUploadStatus(upload_id)</code> method, which returns null or an instance of *helma.framework.UploadStatus|http://adele.helma.org/source/viewcvs.cgi/helma/src/helma/framework/UploadStatus.java?cvsroot=hop*, whose toString() method handily returns a JSON representation of itself. 

There's a *demo available|Upload Demo* that includes source code.

=== TotalUploadLimit option

Before Helma 1.6, there was only an uploadLimit option to allow setting the maximum allowed upload size in apps.properties. However, this applied to both combined and individual upload size, resulting in the per-file upload limit to vary with the number of file input fields per form.

Helma 1.6 introduces the totalUploadLimit property, which allows to set the combined upload size independent from the per-file size.

  # upload limit per file
  gobi.uploadLimit = 2048
  # assuming maximum of 5 upload fields per form
  gobi.totalUploadLimit = 10240

By default, totalUploadLimit is set equal to uploadLimit.

     removed
     added