com.webobjects.appserver
Class WOMultipartIterator

java.lang.Object
  |
  +--com.webobjects.appserver.WOMultipartIterator

public class WOMultipartIterator

extends Object

This class represents the content of a multipart/form-data HTTP request.
You get the iterator for such a request by calling multipartIterator on the WORequest object. Once you have this object, you get WOFormData objects by repeatedly calling nextFormData, until it returns null.
Each WOFormData allows you to introspect the sub-headers, as well as either look at the form value(s) or grab the entire content of the part as an InputStream subclass.
The InputStream subclass is a WOFormDataInpuStream and can be used to stream large file uploads to disk (or elsewhere).
The WOMultipartIterator should NOT be used with WOFileUpload component actions. It may be used with component actions where there is no WOFileUpload, and it may be used in DirectActions.

Inner Class Summary

class

WOMultipartIterator.WOFormData This class represents a form data element from a multipart/form data document as defined in http://www.ietf.org/rfc/rfc2388.txt.

Constructor Summary

WOMultipartIterator(WORequest aRequest)

Method Summary

String	boundary() Returns the boundary from the content-type header of the WORequest.
int	contentLengthRemaining() Returns the number of bytes left to be read from the request content stream.
boolean	didContentTerminatePrematurely() Returns true if the underlying content stream terminated early.
NSDictionary	multipartHeaders() Returns the parsed values from the content-type header of the WORequest.
WOMultipartIterator.WOFormData	nextFormData() This is the primary method for the iterator.

Methods inherited from class java.lang.Object

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

Constructor Detail

WOMultipartIterator

public WOMultipartIterator(WORequest aRequest)

Method Detail

boundary

public String boundary()

Returns the boundary from the content-type header of the WORequest. If this boundary doesn't exist, the iterator attempts to find one by looking at the first part of the content itself.

Returns:

String the boundary as represented in the content-type header of the WORequest.

contentLengthRemaining

public int contentLengthRemaining()

Returns the number of bytes left to be read from the request content stream. Note that this includes all delimiter information, some padding characters around each delimiter, headers for each form element and the content of each form element as well.
Also note that non-file upload elements are often pre-read, and so this number represents the number of bytes actually left on the client and in the socket/stream buffers.
If the underlying stream has been closed, this number cannot be depended upon.

Returns:

number of bytes remaining to be read from the request content stream

didContentTerminatePrematurely

public boolean didContentTerminatePrematurely()

Returns true if the underlying content stream terminated early. This implies that any subsequent form-elements are invalid, and cannot be relied upon to have consistent or useful data.
Typically, you would check this after getting an IOException while reading from the InputStream returned by a WOFormData
This API may be used to determine if the user canceled the upload.

Returns:

true if the underlying stream failed.

multipartHeaders

public NSDictionary multipartHeaders()

Returns the parsed values from the content-type header of the WORequest.

Returns:

NSDictionary of the values in the content-type header.

nextFormData

public WOMultipartIterator.WOFormData nextFormData()

This is the primary method for the iterator. By calling this method, the next form data element is returned, wrapped in a WOFormData object. When the end of the content data is reached, this method returns null. Note that each time this method is invoked, it looks at the previously returned object. If that object represents a file upload, by having the filename sub-header in its content-disposition headers, it will have the file data set to null. Thus, if you are using this method to upload files, you must use up the file data as you get the WOFormData objects. If the previous object was a file upload, even if you have a reference to the InputStream, it is summarily closed once nextFormData is called again.

Returns:

WOFormData representing the next form data element.