org.apache.struts.upload
Class MultipartIterator

java.lang.Object
  |
  +--org.apache.struts.upload.MultipartIterator

public class MultipartIterator

extends java.lang.Object

The MultipartIterator class is responsible for reading the input data of a multipart request and splitting it up into input elements, wrapped inside of a MultipartElement for easy definition. To use this class, create a new instance of MultipartIterator passing it a HttpServletRequest in the constructor. Then use the getNextElement method until it returns null, then you're finished. Example:

      MultipartIterator iterator = new MultipartIterator(request);
      MultipartElement element;

      while ((element = iterator.getNextElement()) != null) {
           //do something with element
      }
 

Author:

Mike Schachter

See Also:

MultipartElement

Field Summary

protected java.lang.String	boundary The boundary for this multipart request
protected int	bufferSize The amount of data read from a request at a time.
protected int	contentLength The content length of this request
protected java.lang.String	contentType The content-type.
private static java.lang.String	DEFAULT_ENCODING The default encoding of a text element if none is specified.
protected int	diskBufferSize The size in bytes written to the filesystem at a time [20K]
private static java.lang.String	FILE_PREFIX
static java.lang.String	HEADER_CONTENT_DISPOSITION The name of the Content-Disposition header.
static java.lang.String	HEADER_CONTENT_TYPE The name of the Content-Type header.
protected MultipartBoundaryInputStream	inputStream The InputStream to use to read the multipart data.
protected boolean	maxLengthExceeded Whether the maximum length has been exceeded.
protected long	maxSize The maximum file size in bytes allowed.
static java.lang.String	MESSAGE_CANNOT_RETRIEVE_BOUNDARY The exception message for when the boundary of a multipart request can't be determined.
private static java.lang.String	PARAMETER_BOUNDARY
protected javax.servlet.http.HttpServletRequest	request The request instance for this class
protected java.lang.String	tempDir The temporary directory to store files
private static int	TEXT_BUFFER_SIZE The size in bytes to copy of text data at a time.

Constructor Summary

MultipartIterator(javax.servlet.http.HttpServletRequest request)
Constructs a MultipartIterator with a default buffer size and no file size limit

MultipartIterator(javax.servlet.http.HttpServletRequest request, int bufferSize)
Constructs a MultipartIterator with the specified buffer size and no file size limit

MultipartIterator(javax.servlet.http.HttpServletRequest request, int bufferSize, long maxSize)
Constructs a MultipartIterator with the specified buffer size and the specified file size limit in bytes

MultipartIterator(javax.servlet.http.HttpServletRequest request, int bufferSize, long maxSize, java.lang.String tempDir)

Method Summary

protected MultipartElement	createFileMultipartElement() Create a multipart element instance representing the file in the stream.
protected java.io.File	createLocalFile() Creates a file on disk from the current mulitpart element.
protected MultipartElement	createTextMultipartElement(java.lang.String encoding) Create a text element from the data in the body of the element.
private void	getBoundaryFromContentType() Parses a content-type String for the boundary.
int	getBufferSize() Get the maximum amount of bytes read from a line at one time
private void	getContentTypeOfRequest() Gets the value of the Content-Type header of the request.
protected java.lang.String	getElementEncoding() Get the character encoding used for this current multipart element.
long	getMaxSize() Get the maximum post data size allowed for a multipart request
MultipartElement	getNextElement() Retrieves the next element in the iterator if one exists.
boolean	isMaxLengthExceeded() Whether or not the maximum length has been exceeded by the client.
protected void	parseRequest() Handles retrieving the boundary and setting the input stream
void	setBufferSize(int bufferSize) Set the maximum amount of bytes read from a line at one time
void	setMaxSize(long maxSize) Set the maximum post data size allowed for a multipart request

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ENCODING

private static final java.lang.String DEFAULT_ENCODING

The default encoding of a text element if none is specified.

See Also:

Constant Field Values

TEXT_BUFFER_SIZE

private static final int TEXT_BUFFER_SIZE

The size in bytes to copy of text data at a time.

See Also:

Constant Field Values

HEADER_CONTENT_TYPE

public static java.lang.String HEADER_CONTENT_TYPE

The name of the Content-Type header.

HEADER_CONTENT_DISPOSITION

public static final java.lang.String HEADER_CONTENT_DISPOSITION

The name of the Content-Disposition header.

See Also:

Constant Field Values

MESSAGE_CANNOT_RETRIEVE_BOUNDARY

public static final java.lang.String MESSAGE_CANNOT_RETRIEVE_BOUNDARY

The exception message for when the boundary of a multipart request can't be determined.

See Also:

Constant Field Values

PARAMETER_BOUNDARY

private static final java.lang.String PARAMETER_BOUNDARY

See Also:

Constant Field Values

FILE_PREFIX

private static final java.lang.String FILE_PREFIX

See Also:

Constant Field Values

request

protected javax.servlet.http.HttpServletRequest request

The request instance for this class

inputStream

protected MultipartBoundaryInputStream inputStream

The InputStream to use to read the multipart data.

boundary

protected java.lang.String boundary

The boundary for this multipart request

maxSize

protected long maxSize

The maximum file size in bytes allowed. Ignored if -1

contentLength

protected int contentLength

The content length of this request

diskBufferSize

protected int diskBufferSize

The size in bytes written to the filesystem at a time [20K]

bufferSize

protected int bufferSize

The amount of data read from a request at a time. This also represents the maximum size in bytes of a line read from the request [4KB]

tempDir

protected java.lang.String tempDir

The temporary directory to store files

contentType

protected java.lang.String contentType

The content-type.

maxLengthExceeded

protected boolean maxLengthExceeded

Whether the maximum length has been exceeded.

Constructor Detail

MultipartIterator

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

Constructs a MultipartIterator with a default buffer size and no file size limit

Parameters:

request - The multipart request to iterate

MultipartIterator

public MultipartIterator(javax.servlet.http.HttpServletRequest request,
                         int bufferSize)
                  throws java.io.IOException

Constructs a MultipartIterator with the specified buffer size and no file size limit

Parameters:

request - The multipart request to iterate

bufferSize - The size in bytes that should be read from the input stream at a times

MultipartIterator

public MultipartIterator(javax.servlet.http.HttpServletRequest request,
                         int bufferSize,
                         long maxSize)
                  throws java.io.IOException

Constructs a MultipartIterator with the specified buffer size and the specified file size limit in bytes

Parameters:

request - The multipart request to iterate

bufferSize - The size in bytes that should be read from the input stream at a times

maxSize - The maximum size in bytes allowed for a multipart element's data

MultipartIterator

public MultipartIterator(javax.servlet.http.HttpServletRequest request,
                         int bufferSize,
                         long maxSize,
                         java.lang.String tempDir)
                  throws java.io.IOException

Method Detail

parseRequest

protected void parseRequest()
                     throws java.io.IOException

Handles retrieving the boundary and setting the input stream

java.io.IOException

getNextElement

public MultipartElement getNextElement()
                                throws java.io.IOException

Retrieves the next element in the iterator if one exists.

Returns:

a MultipartElement representing the next element in the request data

Throws:

java.io.IOException - if the post size exceeds the maximum file size passed in the 3 argument constructor or if the "ISO-8859-1" encoding isn't found

getElementEncoding

protected java.lang.String getElementEncoding()

Get the character encoding used for this current multipart element.

createTextMultipartElement

protected MultipartElement createTextMultipartElement(java.lang.String encoding)
                                               throws java.io.IOException

Create a text element from the data in the body of the element.

Parameters:

encoding - The character encoding of the string.

java.io.IOException

createFileMultipartElement

protected MultipartElement createFileMultipartElement()
                                               throws java.io.IOException

Create a multipart element instance representing the file in the stream.

java.io.IOException

setBufferSize

public void setBufferSize(int bufferSize)

Set the maximum amount of bytes read from a line at one time

See Also:

ServletInputStream.readLine(byte[], int, int)

getBufferSize

public int getBufferSize()

Get the maximum amount of bytes read from a line at one time

See Also:

ServletInputStream.readLine(byte[], int, int)

setMaxSize

public void setMaxSize(long maxSize)

Set the maximum post data size allowed for a multipart request

Parameters:

maxSize - The maximum post data size in bytes, set to -1 for no limit

getMaxSize

public long getMaxSize()

Get the maximum post data size allowed for a multipart request

Returns:

The maximum post data size in bytes

isMaxLengthExceeded

public boolean isMaxLengthExceeded()

Whether or not the maximum length has been exceeded by the client.

getBoundaryFromContentType

private final void getBoundaryFromContentType()
                                       throws java.io.IOException

Parses a content-type String for the boundary.

java.io.IOException

getContentTypeOfRequest

private final void getContentTypeOfRequest()

Gets the value of the Content-Type header of the request.

createLocalFile

protected java.io.File createLocalFile()
                                throws java.io.IOException

Creates a file on disk from the current mulitpart element.

java.io.IOException