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 byte[]	boundaryBytes The byte array representing 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 boolean	contentRead Whether or not the input stream is finished
protected int	diskBufferSize The size in bytes written to the filesystem at a time [20K]
protected BufferedMultipartInputStream	inputStream The input stream instance for this class
static int	MAX_LINE_SIZE The maximum size in bytes of the buffer used to read lines [4K]
protected long	maxSize The maximum file size in bytes allowed.
protected javax.servlet.http.HttpServletRequest	request The request instance for this class
protected java.lang.String	tempDir The temporary directory to store files
protected long	totalLength The total bytes read from this request

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 java.io.File	createLocalFile() Creates a file on disk from the current mulitpart element
static boolean	equals(byte[] comp, int offset, int length, byte[] source) Checks bytes for equality.
int	getBufferSize() Get the maximum amount of bytes read from a line at one time
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.
static java.lang.String	parseBoundary(java.lang.String contentType) Parses a content-type String for the boundary.
static java.lang.String	parseContentType(java.lang.String contentTypeString) Parses the "Content-Type" line of a multipart form for a content type
static java.lang.String	parseDispositionFilename(java.lang.String dispositionString) Retrieves the "filename" attribute from a content disposition line
static java.lang.String	parseDispositionName(java.lang.String dispositionString) Retrieves the "name" attribute from a content disposition line
static java.lang.String	parseForAttribute(java.lang.String attribute, java.lang.String parseString) Parses a string looking for a attribute-value pair, and returns the value.
protected void	parseRequest() Handles retrieving the boundary and setting the input stream
protected java.lang.String	readLine() Reads the input stream until it reaches a new line
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, registerNatives, toString, wait, wait, wait

Field Detail

MAX_LINE_SIZE

public static int MAX_LINE_SIZE

The maximum size in bytes of the buffer used to read lines [4K]

request

protected javax.servlet.http.HttpServletRequest request

The request instance for this class

inputStream

protected BufferedMultipartInputStream inputStream

The input stream instance for this class

boundary

protected java.lang.String boundary

The boundary for this multipart request

boundaryBytes

protected byte[] boundaryBytes

The byte array representing the boundary for this multipart request

contentRead

protected boolean contentRead

Whether or not the input stream is finished

maxSize

protected long maxSize

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

totalLength

protected long totalLength

The total bytes read from this request

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

Constructor Detail

MultipartIterator

public MultipartIterator(javax.servlet.http.HttpServletRequest request)
                  throws javax.servlet.ServletException

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 javax.servlet.ServletException

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 javax.servlet.ServletException

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 javax.servlet.ServletException

Method Detail

getNextElement

public MultipartElement getNextElement()
                                throws javax.servlet.ServletException,
                                       java.io.UnsupportedEncodingException

Retrieves the next element in the iterator if one exists.

Returns:

a MultipartElement representing the next element in the request data

Throws:

a - ServletException if the post size exceeds the maximum file size passed in the 3 argument constructor

an - UnsupportedEncodingException if the "ISO-8859-1" encoding isn't found

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

parseRequest

protected void parseRequest()
                     throws javax.servlet.ServletException

Handles retrieving the boundary and setting the input stream

parseBoundary

public static java.lang.String parseBoundary(java.lang.String contentType)

Parses a content-type String for the boundary. Appends a "--" to the beginning of the boundary, because thats the real boundary as opposed to the shortened one in the content type.

parseContentType

public static java.lang.String parseContentType(java.lang.String contentTypeString)

Parses the "Content-Type" line of a multipart form for a content type

Parameters:

contentTypeString - A String reprsenting the Content-Type line, with a trailing "\n"

Returns:

The content type specified, or null if one can't be found.

parseDispositionName

public static java.lang.String parseDispositionName(java.lang.String dispositionString)

Retrieves the "name" attribute from a content disposition line

Parameters:

dispositionString - The entire "Content-disposition" string

Returns:

null if no name could be found, otherwise, returns the name

See Also:

parseForAttribute(String, String)

parseDispositionFilename

public static java.lang.String parseDispositionFilename(java.lang.String dispositionString)

Retrieves the "filename" attribute from a content disposition line

Parameters:

dispositionString - The entire "Content-disposition" string

Returns:

null if no filename could be found, otherwise, returns the filename

See Also:

parseForAttribute(String, String)

parseForAttribute

public static java.lang.String parseForAttribute(java.lang.String attribute,
                                                 java.lang.String parseString)

Parses a string looking for a attribute-value pair, and returns the value. For example:

      String parseString = "Content-Disposition: filename=\"bob\" name=\"jack\"";
      MultipartIterator.parseForAttribute(parseString, "name");
 

That will return "bob".

Parameters:

attribute - The name of the attribute you're trying to get

parseString - The string to retrieve the value from

Returns:

The value of the attribute, or null if none could be found

readLine

protected java.lang.String readLine()
                             throws javax.servlet.ServletException,
                                    java.io.UnsupportedEncodingException

Reads the input stream until it reaches a new line

createLocalFile

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

Creates a file on disk from the current mulitpart element

Parameters:

fileName - the name of the multipart file

equals

public static boolean equals(byte[] comp,
                             int offset,
                             int length,
                             byte[] source)

Checks bytes for equality. Two byte arrays are equal if each of their elements are the same. This method checks comp[offset] with source[0] to source[length-1] with comp[offset + length - 1]

Parameters:

comp - The byte to compare to source

offset - The offset to start at in comp

length - The length of comp to compare to

source - The reference byte to test for equality