Need way to track progress of requests; proposal included #66
Description
Servlet 3.0 added multipart request processing to, in part, make handling file uploads easier (and easier it did make it). Before 3.0, many users used Commons FileUpload to accomplish this task. However, 3.0's multipart processing did not, unfortunately, completely eliminate the need for FileUpload. One of the major features lacking is the ability to track the progress of a large request.
This feature is sometimes called "file upload progress," but that name is misleading. It's actually "request progress," and it's the ability to measure and periodically report the number of bytes actually received versus the number of bytes indicated in the "Content-Length" header. As I propose below, I believe this should be relatively easy to add to the servlet spec, relatively easy to implement, and quite easy to use.
As proposed, this is independent of protocol (not strictly tied to HTTP/multipart/Content-Length). That could be changed, but I think this makes sense.
First, create a new interface:
**ServletRequestProgressListener**package javax.servlet;
public interface ServletRequestProgressListener
{
/**
* Called whenever the number of bytes read changes, at least every 64 kilobytes.
*
* @param bytesRead The number of bytes that have been read so far, at least 0
* @param bytesExpected The number of bytes expected to be read, -1 if unknown
* @param itemsRead The number of items (parts in an HTTP multipart) processed so far
*/
void update(long bytesRead, long bytesExpected, int itemsRead);
/**
* Called whenever the request has ended, either by being canceled or completed,
* normally or abnormally.
*/
void destroy();
}
Next, add a method to ServletRequest:
**ServletRequest**...
/**
* Attaches a progress listener to this request. Progress listeners must be attached in
* a filter, before the request gets to the Servlet, in order to be effective.
*
* @param progressListener The progress listener to update when the bytes read increases
* @throws UnsupportedOperationException if the protocol does not support progress listeners
*/
void setProgressListener(ServletRequestProgressListener progressListener);
...
Because the listener can be a source of performance problems, containers would only be required to call update (1) when first attached, and (2) every 64 kilobytes. Containers may call it more often, but do not have to. As proposed, I estimate 30 minutes to create the proposed interfaces and 1.5 hours to update the servlet specification documentation. Should only take 2-3 hours to add to the Tomcat implementation based on my examination of the code. Can't speak for the other implementations.
Using multipart as the primary example, since multipart processing is completed before the Servlet gets the request, the listener would have to be attached in a filter. A typical use case would be to create a listener and add it to a session so that it can later be queried by some Ajax call:
**Psuedo-Code**...
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
{
if(request-is-large)
{
MyProgressListener listener = new MyProgressListener(request);
request.getSession().addAttribute("progressListener", listener);
request.setProgressListener(listener);
}
}
...
Environment
n/a