de.mguennewig.pobjform.html
Class MultipartRequest

java.lang.Object
  de.mguennewig.pobjform.html.MultipartRequest

public class MultipartRequest
extends java.lang.Object

The class MultipartRequest allows servlets to process file uploads.

Formally speaking, it supports requests with multipart/form-data content type. This content type is used to submit forms that has the multipart/form-data encoding type, which is used to upload files and is not directly supported by the Servlet Specification.

The class MultipartRequest takes an HttpServletRequest, parses it extracting any parameters and files and exposes them through an API. Notice that the class MultipartRequest supports regular requests as well so that it is possible to process any request using a single API.

File parameters are passed as MultipartRequest.File objects, which encapsulates the file's properties and contents. Regular parameters are passed as String objects.

Notice that the class MultipartRequest supports a simplified version of MIME entity headers, specifically it does not support character escaping, header wrapping, comments nor any extensions. Finally, it does not support multipart/mixed parts, which are used to send multiple files as a single parameter, and it assumes that the request is well formed, so no error checking is performed.

Nested Class Summary

static class

MultipartRequest.File The class MultipartRequest.File encapsulates uploaded files.

Constructor Summary

MultipartRequest()
Creates a new, empty MultipartRequest with a default expiration date.

Method Summary

static MultipartRequest	get(int id) Gets a MultipartRequest object given its id.
long	getExpiration() Gets the expiration of this MultipartRequest object.
java.lang.String	getFile() Gets the file being uploaded.
MultipartRequest.File	getFileParameter(java.lang.String name) Convenient method that returns the value of a MultipartRequest.File parameter.
int	getId() Gets the id of this MultipartRequest.
java.lang.Object	getParameter(java.lang.String name) Returns the value of a given parameter, or null if the parameter doesn't exist.
java.util.Iterator<java.lang.String>	getParameterNames() Returns an Iterator that iterates over the names of the parameters contained in this MultipartRequest.
java.lang.Object[]	getParameterValues(java.lang.String name) Returns an array of objects containing all of the values the given request parameter has, or null if the parameter does not exist.
int	getProcessed() Gets the number of bytes of the request's body already processed.
javax.servlet.http.HttpServletRequest	getRequest() Gets the request corresponding to this MultipartRequest.
java.lang.String	getStringParameter(java.lang.String name) Convenient method that returns the value of a String parameter.
int	getTotal() Gets the total number of bytes of the request.
void	release() Releases this MultipartRequest object and all of its parameters.
void	setExpiration(long expiration) Sets the expiration date for this MultipartRequest.
void	setRequest(javax.servlet.http.HttpServletRequest request) Sets a request for this MultipartRequest.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MultipartRequest

public MultipartRequest()

Creates a new, empty MultipartRequest with a default expiration date.

Method Detail

get

public static MultipartRequest get(int id)

Gets a MultipartRequest object given its id.

Parameters:

id - Object ID

Returns:

The object with the given ID or null if it doesn't exist or if it was released

getExpiration

public final long getExpiration()

Gets the expiration of this MultipartRequest object.

Returns:

The expiration of this object

getFile

public java.lang.String getFile()

Gets the file being uploaded.

Returns:

The name of the file being uploaded or an empty string if there is no file being uploaded

getFileParameter

public final MultipartRequest.File getFileParameter(java.lang.String name)

Convenient method that returns the value of a MultipartRequest.File parameter.

If the parameter has multiple values, returns just the first one. Use the method getParameterValues(String) to get all values.

Parameters:

name - Name of the desired parameter

Returns:

The value of the given parameter, casted to a MultipartRequest.File, or null if the parameter does not exist

getId

public final int getId()

Gets the id of this MultipartRequest.

Each object is guaranteed to have a unique id.

Returns:

The id of this object

getParameter

public java.lang.Object getParameter(java.lang.String name)

Returns the value of a given parameter, or null if the parameter doesn't exist.

The value of the parameter is a String or a MultipartRequest.File object. If the parameter has multiple values, returns just the first one. Use the method getParameterValues(String) to get all values.

Parameters:

name - Name of the desired parameter

Returns:

The value of the given parameter

getParameterNames

public java.util.Iterator<java.lang.String> getParameterNames()

Returns an Iterator that iterates over the names of the parameters contained in this MultipartRequest.

The names of the parameters are String objects.

Returns:

The names of the parameters, as an Iterator

getParameterValues

public java.lang.Object[] getParameterValues(java.lang.String name)

Returns an array of objects containing all of the values the given request parameter has, or null if the parameter does not exist.

The values of the parameters are String or MultipartRequest.File objects.

Parameters:

name - Name of the parameter desired

Returns:

The values of the requested parameter

getProcessed

public final int getProcessed()

Gets the number of bytes of the request's body already processed.

This method can be called by another thread.

Returns:

Number of bytes already processed

getRequest

public final javax.servlet.http.HttpServletRequest getRequest()

Gets the request corresponding to this MultipartRequest.

Returns:

The original HttpServletRequest

getStringParameter

public java.lang.String getStringParameter(java.lang.String name)

Convenient method that returns the value of a String parameter.

If the parameter has multiple values, returns just the first one. Use the method getParameterValues(String) to get all values.

Parameters:

name - Name of the desired parameter

Returns:

The value of the given parameter, casted to a String, or null if the parameter does not exist

getTotal

public final int getTotal()

Gets the total number of bytes of the request.

Returns:

The total number of bytes

release

public void release()
             throws java.io.IOException

Releases this MultipartRequest object and all of its parameters.

This method should be called when this object is not needed anymore. If this object is not explicitly released before its expiration, it will be automatically released when it expires.

Throws:

java.io.IOException - if an error occurs while releasing the temporary files

setExpiration

public void setExpiration(long expiration)

Sets the expiration date for this MultipartRequest.

The expiration date is specified using the same base time as the one used by the method System.currentTimeMillis().

Parameters:

expiration - Expiration date

setRequest

public void setRequest(javax.servlet.http.HttpServletRequest request)
                throws java.io.IOException

Sets a request for this MultipartRequest.

Parses the request and populates this object with the parameters from it. Notice that MultipartRequest are meant to be used only once, that is, they can process just one request.

Parameters:

request - Client's request

Throws:

java.io.IOException - if an error occurs while processing the request