wt.util
Class MPInputStream

java.lang.Object
  java.io.InputStream
      java.io.FilterInputStream
          wt.util.MPInputStream

All Implemented Interfaces:

Closeable, wt.util.MPInputStreamIfc

public class MPInputStream
extends FilterInputStream
implements wt.util.MPInputStreamIfc

A MP input stream is a filter that allows a business class to read consecutive multipart data object bodies whilst alleviating the associated pain. It does this by parsing out object body headers and values, and reading the input stream for the business class whilst checking for the encapsulation boundaries. Analagous to other input streams, MP will respond to read requests as long as there is data in the present object body. Once the end of the data for said object body is reached, a negative one is returned on the next read.

The only required steps are to instantiate a new MPInputStream (passing in the HTTPRequest's input stream and CGI_MULTIPART_BOUNDARY), and to call MP's hasMoreObjectBodies method. Provided the the instantiation succeeds and the return value of the hasMoreObjectBodies method call is true, the business class is free to proceed with reading of the first object body.

Upon receipt of a negative one from a read request, said object body is finished. The return value of another call to hasMoreObjectBodies will indicate if another object body is available for reading.

Note that this input stream filter reads the object body data as bytes, and thus does not impinge any format nor conversion upon the data therein. Thus if the object body data is, for example, base64 encoded, the resultant reads of the business class will get base64 encoded data. It is in this way, that this filter can operate independant of the data enclosed in the object body. It is therefore incumbant on the business class to perform any post processing of the data that may be necessary.

Supported API: true
Extendable: false

Field Summary

Fields inherited from class java.io.FilterInputStream

in

Constructor Summary

MPInputStream(InputStream in, String boundary)
Creates a new MPInputStream initialized with the specified input stream and object body boundary

Supported API: true

Method Summary

int	available() Returns the number of bytes that can be read without blocking.
boolean	containsBodyHeader(String s) Public checker for specific Object Body Header.
String	getBodyHeader(String s) Public accessor to specific Object Body Header.
Enumeration	getBodyHeaders() Public accessor to Object Body Headers and values.
String	getEncoding() get the character encoding set by setEncoding method.
String	getEncoding(String encoding) Deprecated. Supported API: true
boolean	hasMoreObjectBodies() Setup read of next object body if one is available.
int	read() Reads a byte of data.
int	read(byte[] b) Reads up to b.length bytes of data from this input stream into an array of bytes.
int	read(byte[] b, int off, int len) Reads up to len bytes of data from this MP input stream into an array of bytes.
String	readString() Reads the remainder of the current body part into a string.
void	setEncoding(String encoding) Set character encoding to be returned by getEncoding method.
long	skip(long n) Skips bytes of input.

Methods inherited from class java.io.FilterInputStream

close, mark, markSupported, reset

Methods inherited from class java.lang.Object

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

Constructor Detail

MPInputStream

public MPInputStream(InputStream in,
                     String boundary)

Creates a new MPInputStream initialized with the specified input stream and object body boundary

Supported API: true

Parameters:

in - the input stream

boundary - the encapsulation boundary string

Method Detail

setEncoding

public void setEncoding(String encoding)

Set character encoding to be returned by getEncoding method. Useful if the creator of a MPInputStream want to communicate a known character encoding to a body part processing method.

Supported API: true

Parameters:

encoding - the character encoding

getEncoding

public String getEncoding(String encoding)

Deprecated.

Supported API: true

get the character encoding set by setEncoding method. Returns null if not encoding has been set for this MPInputStream.

Returns:

encoding the character encoding

getEncoding

public String getEncoding()

get the character encoding set by setEncoding method. Returns null if not encoding has been set for this MPInputStream.

Supported API: true

Returns:

encoding the character encoding

hasMoreObjectBodies

public boolean hasMoreObjectBodies()
                            throws IOException

Setup read of next object body if one is available. Accomplished by checking that the encapsulation boundary at the top of the header is what we expect, generate a hashtable of the object body headers for later retrieval, and set the stream to the top of the body data for subsequent reads.

Supported API: true

Throws:

IOException - is thrown if error on reading object body header(s) or encapsulation boundary doesn't match that which was passed into the constructor, of read from the boundary object body header.

Note: this method must be called and a value of true returned prior to getBodyHeaders() and/or getBodyHeader(String s) calls.

getBodyHeaders

public Enumeration getBodyHeaders()

Public accessor to Object Body Headers and values.

Supported API: true

getBodyHeader

public String getBodyHeader(String s)

Public accessor to specific Object Body Header.

Supported API: true

Parameters:

s - string key for which to get value.

containsBodyHeader

public boolean containsBodyHeader(String s)

Public checker for specific Object Body Header.

Supported API: true

Parameters:

s - string key for which to get value.

read

public final int read()
               throws IOException

Reads a byte of data. The method will block if no input is available.

Supported API: true

Overrides:

read in class FilterInputStream

Returns:

the byte read, or -1 if the end of the stream is reached.

Throws:

IOException - If an I/O error has occurred. We are overriding this to return 0 bytes for now. Should just call read (byte[], 0, 1)...maybe?

read

public final int read(byte[] b)
               throws IOException

Reads up to b.length bytes of data from this input stream into an array of bytes.

The read method of MPInputStream calls the read method of three arguments with the arguments b, 0, and b.length.

Supported API: true

Overrides:

read in class FilterInputStream

Parameters:

b - the buffer into which the data is read.

Returns:

the total number of bytes read into the buffer, or -1 is there is no more data because the end of the stream has been reached.

Throws:

IOException - if an I/O error occurs.

Since:

JDK1.0

See Also:

InputStream.read(byte[], int, int)

read

public final int read(byte[] b,
                      int off,
                      int len)
               throws IOException

Reads up to len bytes of data from this MP input stream into an array of bytes. This method blocks until some input is available.

This read method of MPInputStream reads bytes out of an internal buffer.

Supported API: true

Overrides:

read in class FilterInputStream

Parameters:

b - the buffer into which the data is read.

off - the start offset of the data.

len - the maximum number of bytes read.

Returns:

the total number of bytes read into the buffer, or -1 if there is no more data because the end of the object body has been reached.

Throws:

IOException - if an I/O error occurs.

skip

public long skip(long n)
          throws IOException

Skips bytes of input.

Supported API: true

Overrides:

skip in class FilterInputStream

Parameters:

n - bytes to be skipped

Returns:

actual number of bytes skipped

Throws:

IOException - If an I/O error has occurred.

available

public int available()

Returns the number of bytes that can be read without blocking. Returns number of bytes body bytes already read into local buffer.

Supported API: true

Overrides:

available in class FilterInputStream

Returns:

number of bytes available

readString

public String readString()
                  throws IOException

Reads the remainder of the current body part into a string.

Supported API: true

Returns:

String read using the encoding set for this stream

Throws:

IOException - if an I/O error occurs.