HttpMultiPartServletRequest (MapperXML Presentation Framework (1.9.8-GA))

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.taursys.servlet
Class HttpMultiPartServletRequest

java.lang.Object
  com.taursys.servlet.HttpMultiPartServletRequest

All Implemented Interfaces:: javax.servlet.http.HttpServletRequest, javax.servlet.ServletRequest

public class HttpMultiPartServletRequest
extends java.lang.Object
implements javax.servlet.http.HttpServletRequest

HttpMultiPartServletRequest is a wrapper/adapter for multipart type requests. This class is used specifically for handling multipart/form-data type resuests (which are not handled by the standard HttpServletRequest API). Multipart type requests are used when a browser submits form data that contains one or more files to upload. When receiving a multipart/form-data request, this class parses the data stream and extracts the form data and uploaded files.

To upload a file using an html form, you must set the enctype="multipart/form-data" in the form tag of the html. Below is an example of the required html:

 <html>
 <head></head>
 <body>
   ...
   <form enctype="multipart/form-data" method="post" action="MyServeltUrl.sf">
     <input type="text" name="color" value="enter your color choice"/>
     ...
     <input type="file" name="orderFile"/>
     <input type="file" name="photo"/>
     <input type="submit" name="action" value="Send Order"/>
   </form>
 </body>
 </html>

This request wrapper is used by default by the ServletForm to help service an incoming multipart/form-data type request. To use this adapter in a servlet, simply create an instance of this class, set the HttpServletRequest property to the incoming request and invoke the parseRequest method. Then used this class as the request object. Below is an example:

 public void doPost(HttpServletRequest request, HttpServletResponse response)
     throws IOException, MultiPartRequestContentException {
   HttpMultiPartServletRequest rq = new HttpMultiPartServletRequest(request);
   rq.parseRequest();
   String orderXML = rq.getParameter("orderFile");
   byte[] photo = rq.getParameterByteArray("");
   ...

In addition to the normal request parameters, information about uploaded files as well as the file data itself is available through special parameters. These special parameters names are made up of the input control's name with a suffix of "_FileName" and "_ContentType". For uploaded files with a Content-Type of "text/...", the following parameters are available:

Example where input control's "name" attribute is "myFile" and the user selected "readlist.txt" to upload.
request.getParameter("myFile") will return the String contents of the uploaded file.
request.getParameter("myFile_FileName") will return "readlist.txt", the name of the uploaded file. (Note: may contain path information depending on browser).
request.getParameter("myFile_ContentType") will return "text/plain", the mime content type of the uploaded file.
request.getParameterByteArray("myFile") will return a byte array of the file contents.

For all uploaded files with a Content-Type OTHER THAN "text/..." the following parameters are available:

Example where input control's "name" attribute is "myPicture" and the user selected "portrait.jpg" to upload.
request.getParameter("myPicture") will return the String value of the uploaded bytes (via new String(bytes[])).
request.getParameter("myPicture_FileName") will return "portrait.jpg", the name of the uploaded file. (Note: may contain path information depending on browser).
request.getParameter("myPicture_ContentType") will return "image/jpeg" the mime content type of the uploaded file.
request.getParameterByteArray("myPicture") will return a byte array containing the binary data of the picture.

This class implements the HttpServletRequest interface. In addition to the regular methods, there are a few additional methods of interest:

parseRequest This will parse the request and make all the parameters and content available. This is automatically invoked by used by a ServletForm.
get/setmaxFileSizeControls the maximum allowed size for an uploaded file. Files beyond this size will cause a MultiPartRequestContentException. The default size is 1 megabyte.
getParameter(String name)This method functions as specified in the servlet API. It will return the String value of the parameter.
getParameterByteArray(String name)Returns the requested parameter as an array of bytes rather than a String. No character conversion occurs.
getParameterByteArrays(String name)Returns an array of byte arrays. This is used when multiple files are uploaded with the same parameter name.
getParameterNames()Returns an enumeration of parameter names (as specified in servlet API).
getParameterValues(String name) Returns a String array of values for the given parameter. This is used when multiple values are sent under the same parameter name. (as specified in servlet API).
getReader()You should NOT invoke this method. It will always throw an IllegalStateException.
getRequest Provides access to the original underlying HttpServletRequest.

Most of the remaining methods of the HttpServletRequest API implemented in this class simply call the cooresponding method in the HttpServletRequest. There are a few additional public methods which are exposed for the sole purpose of unit testing: they are not intended for general use.

Version:: 1.0
Author:: Marty Phelan

Field Summary
`static java.lang.String`	`BASIC_AUTH` String identifier for Basic authentication.
`static java.lang.String`	`CLIENT_CERT_AUTH` String identifier for Basic authentication.
`static java.lang.String`	`DIGEST_AUTH` String identifier for Basic authentication.
`static java.lang.String`	`FORM_AUTH` String identifier for Basic authentication.
`static java.lang.String`	`MULTIPART_FORM_DATA` String identifier for multipart request type.
`static java.lang.String`	`PARM_BYTE_ARRAY_SUFFIX` String suffix for byte array parameter.
`static java.lang.String`	`PARM_CONTENT_TYPE_SUFFIX` String suffix for file content type.
`static java.lang.String`	`PARM_FILE_NAME_SUFFIX` String suffix for file name parameter.

Constructor Summary
`HttpMultiPartServletRequest(javax.servlet.http.HttpServletRequest request)` Constructs a new HttpMultiPartServletRequest for the given HttpServletRequest.

Method Summary
`java.lang.Object`	`getAttribute(java.lang.String name)` Calls same method on the underlying HttpServletRequest.
`java.util.Enumeration`	`getAttributeNames()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getAuthType()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getBoundary()` Unit testing method only - do not use.
`java.lang.String`	`getCharacterEncoding()` Calls same method on the underlying HttpServletRequest.
`int`	`getContentLength()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getContentType()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getContextPath()` Calls same method on the underlying HttpServletRequest.
`javax.servlet.http.Cookie[]`	`getCookies()` Calls same method on the underlying HttpServletRequest.
`long`	`getDateHeader(java.lang.String name)` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getHeader(java.lang.String name)` Calls same method on the underlying HttpServletRequest.
`java.util.Enumeration`	`getHeaderNames()` Calls same method on the underlying HttpServletRequest.
`java.util.Enumeration`	`getHeaders(java.lang.String name)` Calls same method on the underlying HttpServletRequest.
`javax.servlet.ServletInputStream`	`getInputStream()` Retrieves the body of the request as binary data using a `ServletInputStream`.
`int`	`getIntHeader(java.lang.String name)` Calls same method on the underlying HttpServletRequest.
`java.util.Locale`	`getLocale()` Calls same method on the underlying HttpServletRequest.
`java.util.Enumeration`	`getLocales()` Calls same method on the underlying HttpServletRequest.
`int`	`getMaxFileSize()` Get the maximum file size which can be uploaded.
`int`	`getMaxLineLength()` Get the maximum length for a single line.
`java.lang.String`	`getMethod()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getParameter(java.lang.String name)` Returns the value of a request parameter as a String, or null if the parameter does not exist.
`byte[]`	`getParameterByteArray(java.lang.String name)` Returns the binary value of a request parameter as a `byte` array, or null if the parameter does not exist.
`java.lang.Object[]`	`getParameterByteArrays(java.lang.String name)` Returns an array of `byte` arrays containing all of the binary file data the given request parameter has, or null if the parameter does not exist.
`java.util.Map`	`getParameterMap()` Returns a `java.util.Map` of the parameters of this request.
`java.util.Enumeration`	`getParameterNames()` Returns an Enumeration of String objects containing the names of the parameters contained in this request.
`java.lang.String[]`	`getParameterValues(java.lang.String name)` Returns an array of `String` objects containing all of the values the given request parameter has, or `null` if the parameter does not exist.
`java.lang.String`	`getPathInfo()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getPathTranslated()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getProtocol()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getQueryString()` Calls same method on the underlying HttpServletRequest.
`java.io.BufferedReader`	`getReader()` Do not invoke this method.
`java.lang.String`	`getRealPath(java.lang.String path)` Deprecated.
`java.lang.String`	`getRemoteAddr()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getRemoteHost()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getRemoteUser()` Calls same method on the underlying HttpServletRequest.
`javax.servlet.http.HttpServletRequest`	`getRequest()` Get the underlying `HttpServletRequest` for this object.
`javax.servlet.RequestDispatcher`	`getRequestDispatcher(java.lang.String path)` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getRequestedSessionId()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getRequestURI()` Calls same method on the underlying HttpServletRequest.
`java.lang.StringBuffer`	`getRequestURL()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getScheme()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getServerName()` Calls same method on the underlying HttpServletRequest.
`int`	`getServerPort()` Calls same method on the underlying HttpServletRequest.
`java.lang.String`	`getServletPath()` Calls same method on the underlying HttpServletRequest.
`javax.servlet.http.HttpSession`	`getSession()` Calls same method on the underlying HttpServletRequest.
`javax.servlet.http.HttpSession`	`getSession(boolean create)` Calls same method on the underlying HttpServletRequest.
`java.security.Principal`	`getUserPrincipal()` Calls same method on the underlying HttpServletRequest.
`boolean`	`isEndOfData()` Unit testing method only - do not use.
`boolean`	`isRequestedSessionIdFromCookie()` Calls same method on the underlying HttpServletRequest.
`boolean`	`isRequestedSessionIdFromUrl()` Deprecated.
`boolean`	`isRequestedSessionIdFromURL()` Calls same method on the underlying HttpServletRequest.
`boolean`	`isRequestedSessionIdValid()` Calls same method on the underlying HttpServletRequest.
`boolean`	`isSecure()` Calls same method on the underlying HttpServletRequest.
`boolean`	`isUserInRole(java.lang.String role)` Calls same method on the underlying HttpServletRequest.
`static void`	`main(java.lang.String[] args)` For testing purposes only.
`void`	`parseRequest()` Parse the servlet request and extract parameter information.
`void`	`processBlock()` Unit testing method only - do not use.
`int`	`readChars(char[] results, int offset, java.lang.String key)`
`void`	`removeAttribute(java.lang.String name)` Calls same method on the underlying HttpServletRequest.
`void`	`setAttribute(java.lang.String name, java.lang.Object o)` Calls same method on the underlying HttpServletRequest.
`void`	`setCharacterEncoding(java.lang.String encoding)` Calls same method on the underlying HttpServletRequest.
`void`	`setMaxFileSize(int newMaxFileSize)` Set the maximum file size which can be uploaded.
`void`	`setMaxLineLength(int newMaxLineLength)` Set the maximum length for a single line.
`void`	`setupBoundary()` Unit testing method only - do not use.

Methods inherited from class java.lang.Object

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

Field Detail

PARM_BYTE_ARRAY_SUFFIX

public static final java.lang.String PARM_BYTE_ARRAY_SUFFIX

String suffix for byte array parameter. Value "_ByteArray".

See Also:: Constant Field Values

PARM_FILE_NAME_SUFFIX

public static final java.lang.String PARM_FILE_NAME_SUFFIX

String suffix for file name parameter. Value "_FileName".

See Also:: Constant Field Values

PARM_CONTENT_TYPE_SUFFIX

public static final java.lang.String PARM_CONTENT_TYPE_SUFFIX

String suffix for file content type. Value "_ContentType".

See Also:: Constant Field Values

BASIC_AUTH

public static final java.lang.String BASIC_AUTH

String identifier for Basic authentication. Value "BASIC"

See Also:: Constant Field Values

FORM_AUTH

public static final java.lang.String FORM_AUTH

String identifier for Basic authentication. Value "FORM"

See Also:: Constant Field Values

CLIENT_CERT_AUTH

public static final java.lang.String CLIENT_CERT_AUTH

String identifier for Basic authentication. Value "CLIENT_CERT"

See Also:: Constant Field Values

DIGEST_AUTH

public static final java.lang.String DIGEST_AUTH

String identifier for Basic authentication. Value "DIGEST"

See Also:: Constant Field Values

MULTIPART_FORM_DATA

public static final java.lang.String MULTIPART_FORM_DATA

String identifier for multipart request type. Value "multipart/form-data"

See Also:: Constant Field Values

Constructor Detail

HttpMultiPartServletRequest

public HttpMultiPartServletRequest(javax.servlet.http.HttpServletRequest request)

Constructs a new HttpMultiPartServletRequest for the given HttpServletRequest. You must invoke the parseRequest() method before using this class.

Method Detail

parseRequest

public void parseRequest()
                  throws MultiPartRequestSizeException,
                         MultiPartRequestContentException,
                         java.io.IOException

Parse the servlet request and extract parameter information. This method checks to ensure that this is a multipart/form-data type request. It then uses the ServletInputStream to read the body of the request. It parses the request body and stores parameters and files in the parameter map.

Throws:: MultiPartRequestSizeException - if max line length or file size exceeded; MultiPartRequestContentException - if invalid data received; java.io.IOException - if problem reading data stream

setupBoundary

public void setupBoundary()
                   throws MultiPartRequestContentException,
                          java.io.IOException

Unit testing method only - do not use. Used by parseRequest to check content type and extract the boundary markers.

Throws:: MultiPartRequestContentException - if ContentType is not multipart/form-data; java.io.IOException

processBlock

public void processBlock()
                  throws MultiPartRequestSizeException,
                         MultiPartRequestContentException,
                         java.io.IOException

Unit testing method only - do not use. Used by parseRequest to process each part in a multipart request. throws MultiPartRequestContentException if invalid request format throws IOException if problem reading stream

Throws:: MultiPartRequestSizeException; MultiPartRequestContentException; java.io.IOException

getParameterNames

public java.util.Enumeration getParameterNames()

Returns an Enumeration of String objects containing the names of the parameters contained in this request. If the request has no parameters, the method returns an empty Enumeration.

Specified by:: getParameterNames in interface javax.servlet.ServletRequest

Returns:: an Enumeration of String objects, each String containing the name of a request parameter; or an empty Enumeration if the request has no parameters

getParameter

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

Returns the value of a request parameter as a String, or null if the parameter does not exist. Request parameters are extra information sent with the request. For HTTP servlets, parameters are contained in the query string or posted form data.

You should only use this method when you are sure the parameter has only one value. If the parameter might have more than one value, use getParameterValues(java.lang.String).

If you use this method with a multivalued parameter, the value returned is equal to the first value in the array returned by getParameterValues.

If the parameter data was sent in the request body, such as occurs with an HTTP POST request, then reading the body directly via getInputStream() or getReader() can interfere with the execution of this method.

Specified by:: getParameter in interface javax.servlet.ServletRequest

Parameters:: name - - a String specifying the name of the parameter
Returns:: a String representing the single value of the parameter

getParameterValues

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

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

If the parameter has a single value, the array has a length of 1.

Specified by:: getParameterValues in interface javax.servlet.ServletRequest

Parameters:: name - - a String containing the name of the parameter whose value is requested
Returns:: an array of String objects containing the parameter's values

getParameterMap

public java.util.Map getParameterMap()

Returns a java.util.Map of the parameters of this request. Request parameters are extra information sent with the request. For HTTP servlets, parameters are contained in the query string or posted form data.

Specified by:: getParameterMap in interface javax.servlet.ServletRequest

Returns:: an immutable java.util.Map containing parameter names as keys and parameter values as map values. The keys in the parameter map are of type String. The values in the parameter map are of type Object array.

getParameterByteArray

public byte[] getParameterByteArray(java.lang.String name)

Returns the binary value of a request parameter as a byte array, or null if the parameter does not exist. The parameter name MAY end with "_ByteArray" (eg "myFile_ByteArray").

You should only use this method when you are sure the parameter has only one value. If the parameter might have more than one value, use getParameterByteArrays(java.lang.String).

If you use this method with a multivalued parameter, the value returned is equal to the first value in the array returned by getParameterByteArrays.

Parameters:: name - - a String specifying the name of the parameter
Returns:: a byte array of the binary file data for the parameter.

getParameterByteArrays

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

Returns an array of byte arrays containing all of the binary file data the given request parameter has, or null if the parameter does not exist.

If the parameter has a single value, the array has a length of 1.

Parameters:: name - - a String specifying the name of the parameter
Returns:: an array of byte arrays of the binary file data for the parameter.

getInputStream

public javax.servlet.ServletInputStream getInputStream()
                                                throws java.io.IOException

Retrieves the body of the request as binary data using a ServletInputStream. This method caches the request stream after the first call.

Specified by:: getInputStream in interface javax.servlet.ServletRequest

Returns:: a ServletInputStream object containing the body of the request
Throws:: java.lang.IllegalStateException - if the getReader() method has already been called on the underlying request object.; java.io.IOException - if an input or output exception occurred

getReader

public java.io.BufferedReader getReader()
                                 throws java.io.IOException

Do not invoke this method. The parseRequest method will invoke the getInputStream() method, which will invalidate the use of this method. This method will always throw an IllegalStateException

Specified by:: getReader in interface javax.servlet.ServletRequest

Throws:: java.io.IOException - is never thrown in this implementation; java.lang.IllegalStateException - whenever this method is invoked.

getRequest

public javax.servlet.http.HttpServletRequest getRequest()

Get the underlying HttpServletRequest for this object.

Returns:: the underlying HttpServletRequest for this object.

getBoundary

public java.lang.String getBoundary()

Unit testing method only - do not use.

Returns:: the boundary String which separates the parts of this request.

isEndOfData

public boolean isEndOfData()

Unit testing method only - do not use.

Returns:: true if end of data stream is reached. This is always true after parseRequest() has been invoked.

setMaxFileSize

public void setMaxFileSize(int newMaxFileSize)

Set the maximum file size which can be uploaded. Files which exceed this size will cause an ArraySubscriptException. The default size is 1 megabyte.

Parameters:: newMaxFileSize - the maximum file size which can be uploaded.

getMaxFileSize

public int getMaxFileSize()

Get the maximum file size which can be uploaded. Files which exceed this size will cause an ArraySubscriptException. The default size is 1 megabyte.

Returns:: the maximum file size which can be uploaded.

setMaxLineLength

public void setMaxLineLength(int newMaxLineLength)

Set the maximum length for a single line. Lines which exceed this size will cause an ArraySubscriptException. The default size is 4,096 bytes.

Parameters:: newMaxLineLength - the maximum length for a single line.

getMaxLineLength

public int getMaxLineLength()

Get the maximum length for a single line. Lines which exceed this size will cause an ArraySubscriptException. The default size is 4,096 bytes.

Returns:: the maximum length for a single line.

readChars

public int readChars(char[] results,
                     int offset,
                     java.lang.String key)
              throws MultiPartRequestSizeException,
                     MultiPartRequestContentException,
                     java.io.IOException

Throws:: MultiPartRequestSizeException; MultiPartRequestContentException; java.io.IOException