uws.service.request

Class MultipartParser

java.lang.Object

uws.service.request.MultipartParser

All Implemented Interfaces:

RequestParser

public class MultipartParser
extends java.lang.Object
implements RequestParser

Extract parameters encoded using the Content-type multipart/form-data in an HttpServletRequest.

Uploaded file storage

The created file(s) is(are) stored in the temporary upload directory (UWSFileManager.getTmpDirectory(). This directory is supposed to be emptied regularly in case it is forgotten at any moment by the service implementation to delete unused request files.

Upload limits

The size of the full request body as well as the size of a single uploaded file are both limited. To get and/or change these limits, use the functions:

• single file limit: getMaxFileSize() and setMaxFileSize(long)
• multipart request limit: getMaxRequestSize() and setMaxRequestSize(long)

By default, the limit for an uploaded file is -1 (i.e. unlimited) and the limit for the whole request (i.e. all uploaded files together + HTTP header) is -1 (i.e. unlimited}).

Parameter consumption

By default, this RequestParser overwrite parameter occurrences in the map: that's to say if a parameter is provided several times, only the last value will be kept. This behaviour can be changed by overwriting the function consumeParameter(String, Object, Map) of this class.

Since:

4.1

Version:

4.4 (09/2018)

Author:

Grégory Mantelet (ARI;CDS)

Field Summary

Fields

Modifier and Type	Field and Description
boolean	allowUpload Indicates whether this parser should allow inline files or not.
static int	DEFAULT_FILE_SIZE_LIMIT Default maximum allowed size for a single uploaded file: -1 (i.e.
static int	DEFAULT_SIZE_LIMIT Default maximum allowed size for an HTTP request content: -1 (i.e.
static java.lang.String	EXPECTED_CONTENT_TYPE HTTP content-type for HTTP request formated in multipart.
protected UWSFileManager	fileManager File manager to use to create UploadFile instances.
protected org.apache.commons.fileupload.servlet.ServletFileUpload	fileUpload Tool to parse Multipart HTTP request and fetch files when necessary.
protected static int	SIZE_BEFORE_DISK_STORAGE Size threshold (in bytes) for an individual file before being stored on disk.
static int	SIZE_LIMIT Deprecated. Since 4.4 ; barely used and never worked (with COS).

Constructor Summary

Constructors

Modifier	Constructor and Description
	MultipartParser() Build a MultipartParser forbidding uploads (i.e.
protected	MultipartParser(boolean uploadEnabled, UWSFileManager fileManager) Build a MultipartParser.
protected	MultipartParser(boolean uploadEnabled, UWSFileManager fileManager, long maxFileSize, long maxRequestSize) Build a MultipartParser.
	MultipartParser(UWSFileManager fileManager) Build a MultipartParser allowing uploads (i.e.

Method Summary

Modifier and Type	Method and Description
protected void	consumeParameter(java.lang.String name, java.lang.Object value, java.util.Map<java.lang.String,java.lang.Object> allParams) Consume the specified parameter: add it inside the given map.
protected java.io.File	getFileFromParam(javax.servlet.http.HttpServletRequest request, java.lang.String parentFile, java.lang.String inputFileName) Return the path of a non-existing file inside the given directory and whose the name is built using the given file name and the HTTP request ID.
long	getMaxFileSize() Get the maximum size (in bytes) of a single uploaded file.
long	getMaxRequestSize() Get the maximum size (in bytes) of a whole multipart request.
static boolean	isMultipartContent(javax.servlet.http.HttpServletRequest request) Utility method that determines whether the content of the given request is a multipart/form-data.
java.util.Map<java.lang.String,java.lang.Object>	parse(javax.servlet.http.HttpServletRequest request) Extract parameters from the given HTTP request.
void	setMaxFileSize(long maxFileSize) Set the maximum size (in bytes) of a single uploaded file.
void	setMaxRequestSize(long maxRequestSize) Set the maximum size (in bytes) of a whole multipart request.

Methods inherited from class java.lang.Object

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

Field Detail

EXPECTED_CONTENT_TYPE

public static final java.lang.String EXPECTED_CONTENT_TYPE

HTTP content-type for HTTP request formated in multipart.

See Also:

Constant Field Values

DEFAULT_FILE_SIZE_LIMIT

public static final int DEFAULT_FILE_SIZE_LIMIT

Default maximum allowed size for a single uploaded file: -1 (i.e. unlimited).

Since:

4.4

See Also:

Constant Field Values

DEFAULT_SIZE_LIMIT

public static final int DEFAULT_SIZE_LIMIT

Default maximum allowed size for an HTTP request content: -1 (i.e. unlimited).

See Also:

Constant Field Values

SIZE_BEFORE_DISK_STORAGE

protected static final int SIZE_BEFORE_DISK_STORAGE

Size threshold (in bytes) for an individual file before being stored on disk. Below this threshold, the file is only stored in memory.

Note: By default, set to 10 kiB.

Since:

4.4

See Also:

Constant Field Values

SIZE_LIMIT

@Deprecated
public static int SIZE_LIMIT

Deprecated. Since 4.4 ; barely used and never worked (with COS).

Maximum allowed size for an HTTP request content. Over this limit, an exception is thrown and the request is aborted.

Note 1: The default value is DEFAULT_SIZE_LIMIT (= -1 MiB).

Note 2: This limit is expressed in bytes and can not be negative. Its smallest possible value is 0. If the set value is though negative, it will be ignored and DEFAULT_SIZE_LIMIT will be used instead.

allowUpload

public final boolean allowUpload

Indicates whether this parser should allow inline files or not.

fileManager

protected final UWSFileManager fileManager

File manager to use to create UploadFile instances. It is required by this new object to execute open, move and delete operations whenever it could be asked.

fileUpload

protected final org.apache.commons.fileupload.servlet.ServletFileUpload fileUpload

Tool to parse Multipart HTTP request and fetch files when necessary.

Since:

4.4

Constructor Detail

MultipartParser

public MultipartParser()

Build a MultipartParser forbidding uploads (i.e. inline files).

With this parser, when an upload (i.e. submitted inline files) is detected, an exception is thrown by parse(HttpServletRequest) which cancels immediately the request.

MultipartParser

public MultipartParser(UWSFileManager fileManager)

Build a MultipartParser allowing uploads (i.e. inline files).

Parameters:

fileManager - The file manager to use in order to store any eventual upload. MUST NOT be NULL

MultipartParser

protected MultipartParser(boolean uploadEnabled,
                          UWSFileManager fileManager)

Build a MultipartParser.

If the first parameter is false, then when an upload (i.e. submitted inline files) is detected, an exception is thrown by parse(HttpServletRequest) which cancels immediately the request.

Parameters:

uploadEnabled - true to allow uploads (i.e. inline files), false otherwise. If false, the two other parameters are useless.

fileManager - The file manager to use in order to store any eventual upload. MUST NOT be NULL

MultipartParser

protected MultipartParser(boolean uploadEnabled,
                          UWSFileManager fileManager,
                          long maxFileSize,
                          long maxRequestSize)

Build a MultipartParser.

If the first parameter is false, then when an upload (i.e. submitted inline files) is detected, an exception is thrown by parse(HttpServletRequest) which cancels immediately the request.

Parameters:

uploadEnabled - true to allow uploads (i.e. inline files), false otherwise. If false, the two other parameters are useless.

fileManager - The file manager to use in order to store any eventual upload. MUST NOT be NULL

maxFileSize - Maximum size of a single upload file (in bytes). A negative value for "unlimited".

maxRequestSize - Maximum size of a whole multipart request (in bytes). A negative value for "unlimited".

Since:

4.4

Method Detail

getMaxFileSize

public final long getMaxFileSize()

Get the maximum size (in bytes) of a single uploaded file.

Returns:

Maximum upload file size (in bytes), or -1 if no limit.

Since:

4.4

setMaxFileSize

public void setMaxFileSize(long maxFileSize)

Set the maximum size (in bytes) of a single uploaded file.

Parameters:

maxFileSize - New maximum upload file size (in bytes). If -1, then there will be no limit.

Since:

4.4

getMaxRequestSize

public final long getMaxRequestSize()

Get the maximum size (in bytes) of a whole multipart request.

Returns:

Maximum multipart request size (in bytes), or -1 if no limit.

Since:

4.4

setMaxRequestSize

public void setMaxRequestSize(long maxRequestSize)

Set the maximum size (in bytes) of a whole multipart request.

Parameters:

maxRequestSize - New maximum multipart request size (in bytes). If -1, then there will be no limit.

Since:

4.4

parse

public final java.util.Map<java.lang.String,java.lang.Object> parse(javax.servlet.http.HttpServletRequest request)
                                                             throws UWSException

Description copied from interface: RequestParser

Extract parameters from the given HTTP request.

These parameters can be fetched from ServletRequest.getParameterMap() or directly from the full request content. In this last case, a parsing is necessary ; hence this function.

In case a parameter is provided several times with the same time and the same case, the request parser can choose to keep only the last occurrence or all occurrences. If all occurrences are kept, this function MUST return an array of Objects (in which types may be mixed), otherwise a map value MUST be an elementary object.

Note: A parameter item can be a simple value (e.g. String, integer, ...) or a more complex object (e.g. File, InputStream, ...).

IMPORTANT: This function MUST NOT be used to check the parameters' value. It only aims to parse the given request in order to extract its embedded parameters.
Consequently, if this function throws an exception, it could be only because the request can not be read, and not because a parameter format or value is incorrect.
Parameter checks should be done in UWSParameters and more particularly by an InputParamController.

Specified by:

parse in interface RequestParser

Parameters:

request - An HTTP request.

Returns:

A map listing all extracted parameters. Values are either an elementary object (whatever is the type), or an array of Objects (in which types can be mixed).

Throws:

UWSException - If any error provides this function to read the parameters.

getFileFromParam

protected java.io.File getFileFromParam(javax.servlet.http.HttpServletRequest request,
                                        java.lang.String parentFile,
                                        java.lang.String inputFileName)

Return the path of a non-existing file inside the given directory and whose the name is built using the given file name and the HTTP request ID.

Parameters:

request - The received HTTP request.

parentFile - The directory in which the file should be created.

inputFileName - The file name provided by the user.

Returns:

Path of a non-existing file for the specified input file.

Since:

4.4

consumeParameter

protected void consumeParameter(java.lang.String name,
                                java.lang.Object value,
                                java.util.Map<java.lang.String,java.lang.Object> allParams)

Consume the specified parameter: add it inside the given map.

By default, this function is just putting the given value inside the map. So, if the parameter already exists in the map, its old value will be overwritten by the given one.

Note: If the old value was a file, it will be deleted from the file system before its replacement in the map.

Parameters:

name - Name of the parameter to consume.

value - Its value.

allParams - The list of all parameters read until now.

isMultipartContent

public static final boolean isMultipartContent(javax.servlet.http.HttpServletRequest request)

Utility method that determines whether the content of the given request is a multipart/form-data.

Important: This function just test the content-type of the request. The HTTP method (e.g. GET, POST, ...) is not tested.

Parameters:

request - The servlet request to be evaluated. Must be non-null.

Returns:

true if the request is multipart, false otherwise.