com.webobjects.appserver
Class WOMultipartIterator.WOFormData

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

Enclosing class:

WOMultipartIterator

public class WOMultipartIterator.WOFormData

extends Object

This class represents a form data element from a multipart/form data document as defined in http://www.ietf.org/rfc/rfc2388.txt.
Objects of this class are instantiated by WORequest's WOMultipartIterator, and returned by the iterator's nextFormData method.
A form data is made up of headers and a content. The content can be accessed as an NSData, a dictionary of form values, or as an InputStream. For large uploads, use the InputStream method, as both other methods will read all the form data into memory.

Constructor Summary

protected

WOMultipartIterator.WOFormData()

Method Summary

NSDictionary	contentDispositionHeaders() Returns the sub-headers dictionary for the content-disposition header.
NSTimestamp	dateFormValue(NSTimestampFormatter dateFormatter) Method to return an NSTimestamp for the form value.
NSData	formData() Equivalent to formData(4096)
NSData	formData(int bufferSize) Returns the form element data as an NSData.
InputStream	formDataInputStream() Returns the form element data as an InputStream.
String	formValue() Returns the contents of this form-data element as a properly encoded String.
NSDictionary	headers() Returns the headers dictionary for this form data.
boolean	isFileUpload() Returns true if this object represents a file upload.
boolean	isStreamAvailable() Returns true if formDataInputStream can be called.
boolean	isStreamValid() Returns true if the underlying stream is valid (has not been closed).
String	name() Returns the name of this form element.
Number	numericFormValue(NSNumberFormatter numericFormatter) Method to return a Number for the form value.
String	toString() Returns a String representation of this object.

Methods inherited from class java.lang.Object

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

Constructor Detail

WOMultipartIterator.WOFormData

protected WOMultipartIterator.WOFormData()

Method Detail

contentDispositionHeaders

public NSDictionary contentDispositionHeaders()

Returns the sub-headers dictionary for the content-disposition header. Note that the standard sub-headers are "name" and "filename".
The "content-type" header is a top level header for this form element, not part of the content-disposition header.

Returns:

the set of sub-headers for the content-disposition header

See Also:

formDataInputStream(), formData()

dateFormValue

public NSTimestamp dateFormValue(NSTimestampFormatter dateFormatter)
                          throws IOException

Method to return an NSTimestamp for the form value. This convenience method coerces the value into the proper time format using the NSTimestampFormatter provided. It will return null if it can't cast the form value into a valid NSTimestamp. NOTE: This method invokes formValue()

Parameters:

dateFormatter - the formatter used to coerce the form value to a date value.

Returns:

the NSTimestamp representation for the value or null.

See Also:

formValue(), #numericFormValueForKey( String aKey, NSNumberFormatter numericFormatter )

formData

public NSData formData()
                throws IOException

Equivalent to formData(4096)

formData

public NSData formData(int bufferSize)
                throws IOException

Returns the form element data as an NSData. This reads all of the form element data into memory, using bufferSize as the size of the transfer buffer. This method returns null if formDataInputStream has been called earlier on the object.

Parameters:

bufferSize - the size in bytes of the buffer to use to read in the underlying data from the stream

Returns:

an NSData containing the bytes as read in memory from the input stream.

See Also:

formDataInputStream()

formDataInputStream

public InputStream formDataInputStream()

Returns the form element data as an InputStream. This stream stops when it encounters the boundary string (see RFC2388) signaling the end of the form data. Be careful, once an input stream is read, it can not be unread, so the form data can only be read once using this method. This method returns null if formData has been called earlier on the object.

Returns:

the InputStream to read the actual data.

See Also:

formData()

formValue

public String formValue()
                 throws IOException

Returns the contents of this form-data element as a properly encoded String. Because of the encoding into a String, this should not be used for file uploads.
If this is a fileUpload, and the file has been read out of the request via a stream API, the value will return an empty string.
This method implicitly calls formData

Returns:

a String encoded from the form element data.

See Also:

formData()

headers

public NSDictionary headers()

Returns the headers dictionary for this form data. See the RFC 2388 for definition of these headers. Values in the dictionary are NSArrays, but the value(s) inside the NSArrays can be either a String or an NSDictionary. If you are looking for the content-disposition headers, use the contentDispositionHeader method.

Returns:

the set of headers for this form data

See Also:

formDataInputStream(), formData()

isFileUpload

public boolean isFileUpload()

Returns true if this object represents a file upload. The determination is made by seeing if there is a "filename" sub-header in the content-disposition header of the form element.

Returns:

true if this is a file upload

isStreamAvailable

public boolean isStreamAvailable()

Returns true if formDataInputStream can be called.

Returns:

true if formDataInputStream can be called.

See Also:

formDataInputStream(), formData()

isStreamValid

public boolean isStreamValid()

Returns true if the underlying stream is valid (has not been closed).

Returns:

true if the underlying stream is valid.

name

public String name()

Returns the name of this form element. This is equivalent to getting the "name" subheader from the content-disposition header.

Returns:

the name of this form element

numericFormValue

public Number numericFormValue(NSNumberFormatter numericFormatter)
                        throws IOException

Method to return a Number for the form value. This convenince method coerces the value into the proper numeric format using the NSNumberFormatter provided. It will return null if it can't cast the form value into a Number. NOTE: This method invokes formValue()

Parameters:

numericFormatter - the formatter used to coerce the form value to a numeric value.

Returns:

the Number representation for the value or null.

See Also:

formValue(), #dateFormValueForKey( String aKey , NSTimestampFormatter dateFormatter )

toString

public String toString()

Returns a String representation of this object.

Overrides:

toString in class Object

Returns:

String representation of the object.