com.ibm.wbi
Class RequestEvent

java.lang.Object
  |
  +--java.util.EventObject
        |
        +--com.ibm.wbi.RequestEvent

All Implemented Interfaces:

ResponseToRequest, java.io.Serializable

public abstract class RequestEvent

extends java.util.EventObject

implements ResponseToRequest

The RequestEvent that is passed to each Meg that contains the input and output streams and Meg data. The RequestEvent should not be referenced after the handleEvent() method call because it encapsulates a lot of Request data and can consume a lot of memory over time. The RequestEvent provides Meg/Plugin management api's as well as provide ability to spawn new Requests to the Proxy.

See Also:

Serialized Form

Fields inherited from class java.util.EventObject

source

Constructor Summary

RequestEvent(java.lang.Object source)
Construct a new RequestEvent specifying the source.

Method Summary

void	abort() Deprecated. Use getTransaction.abort( AbortEvent ).
abstract MegContext	getMegContext() Get the Meg context available with this request.
abstract MegInputStream	getMegInputStream() Get the input stream for reading binary (byte-based) streams.
abstract MegObject	getMegObject() returns the MegObject associated with this RequestEvent, if any.
abstract java.lang.Class	getMegObjectType() returns the class of the MegObject associated with this RequestEvent, if any.
abstract MegOutputStream	getMegOutputStream() Get the output stream for writing binary (byte-based) data.
abstract MegReader	getMegReader() Get the reader for reading character-based streams.
abstract MegReader	getMegReader(java.lang.String encoding) Get the reader for reading character-based streams.
abstract MegWriter	getMegWriter() Get the writer for writing out character-based streams.
abstract MegWriter	getMegWriter(java.lang.String encoding) Get the writer for writing out character-based streams.
MegInputStream	getRead() Deprecated. Use getMegInputStream().
abstract RequestInfo	getRequestInfo() Get the RequestInfo object that "describes" the Request.
abstract Transaction	getTransaction() Get the transaction object that this RequestEvent belongs to.
MegOutputStream	getWrite() Deprecated. Use getMegOutputStream().
boolean	isAborted() Deprecated. Use getTransaction.isAborted().
void	mayReject() Informs WBI that this RequestEvent may be rejected.
abstract void	putMegObject(MegObject mo) passes the MegObject to the next MEG.
void	wontReject() This undoes the effects of a previous call to mayReject().

Methods inherited from class java.util.EventObject

getSource, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

RequestEvent

public RequestEvent(java.lang.Object source)

Construct a new RequestEvent specifying the source.

Parameters:

source - The source of the event.

Method Detail

getRead

public final MegInputStream getRead()

Deprecated. Use getMegInputStream().

Get the input stream.

Returns:

The input stream.

getMegInputStream

public abstract MegInputStream getMegInputStream()

Get the input stream for reading binary (byte-based) streams. For reading from character-based streams, a MegReader is preferred over a MegInputStream.

Specified by:

getMegInputStream in interface ResponseToRequest

Returns:

The input stream.

See Also:

getMegReader()

getMegReader

public abstract MegReader getMegReader()
                                throws java.io.UnsupportedEncodingException,
                                       com.ibm.wbi.NotCharDataException

Get the reader for reading character-based streams. When a stream is known to contain character data, such as a stream with content type "text/html" it is preferable to use a MegReader instead of a MegInputStream. The encoding used by the reader will be determined automatically. You should not use both a MegReader and a MegInputStream from the same RequestEvent. If you do so, both the MegReader and the MegInputStream may behave in an undefined manner.

There can be only one MegReader per RequestEvent. This MegReader will always be returned by subsequent calls to getMegReader() or getMegReader(String), even if a different encoding is specified.

Specified by:

getMegReader in interface ResponseToRequest

Returns:

The reader.

Throws:

java.io.UnsupportedEncodingException - If the stream is encoded using an encoding not supported on this platform.

com.ibm.wbi.NotCharDataException - If the stream does not contain character data.

See Also:

MegReader

getMegReader

public abstract MegReader getMegReader(java.lang.String encoding)
                                throws java.io.UnsupportedEncodingException,
                                       com.ibm.wbi.NotCharDataException

Get the reader for reading character-based streams. When a stream is known to contain character data, such as a stream with content type "text/html" it is preferable to use a MegReader instead of a MegInputStream. You should not use both a MegReader and a MegInputStream from the same RequestEvent. If you do so, both the MegReader and the MegInputStream may behave in an undefined manner.

There can be only one MegReader per RequestEvent. This MegReader will always be returned by subsequent calls to getMegReader() or getMegReader(String), even if a different encoding is specified.

Parameters:

encoding - The encoding the reader will use.

Returns:

The reader.

Throws:

java.io.UnsupportedEncodingException - If the stream is encoded using an encoding not supported on this platform.

com.ibm.wbi.NotCharDataException - If the stream does not contain character data.

See Also:

MegReader

getWrite

public final MegOutputStream getWrite()

Deprecated. Use getMegOutputStream().

Get the output stream. Once the output stream is written to, a request can not be rejected and the request info object is copied and the next meg is dispatched.

Returns:

The output stream.

getMegOutputStream

public abstract MegOutputStream getMegOutputStream()

Get the output stream for writing binary (byte-based) data. For writing character-based data, a MegWriter is preferred over a MegOutputStream. Once the output stream is written to, a request can not be rejected and the request info object is copied and the next meg is dispatched.

Returns:

The output stream.

See Also:

getMegWriter()

getMegWriter

public abstract MegWriter getMegWriter()
                                throws java.io.UnsupportedEncodingException,
                                       com.ibm.wbi.NotCharDataException

Get the writer for writing out character-based streams. When a stream is known to contain character data, such as a stream with content type "text/html", it is preferable to use a MegWriter instead of a MegOutputStream. The encoding used by the writer will be determined automatically. You should not use both a MegWriter and a MegOutputStream from the same RequestEvent. If you do, both the MegWriter and the MegOutputStream may behave in an undefined manner.

There can be only one MegWriter per RequestEvent. This MegWriter will always be returned by subsequent calls to getMegWriter() or getMegWriter(String), even if a different encoding is specified.

Returns:

the writer.

Throws:

java.io.UnsupportedEncodingException - If the stream is encoded using an encoding not supported on this platform.

com.ibm.wbi.NotCharDataException - If the stream does not contain character data.

See Also:

MegWriter

getMegWriter

public abstract MegWriter getMegWriter(java.lang.String encoding)
                                throws java.io.UnsupportedEncodingException,
                                       com.ibm.wbi.NotCharDataException

Get the writer for writing out character-based streams. When a stream is known to contain character data, such as a stream with content type "text/html", it is preferable to use a MegWriter instead of a MegOutputStream. You should not use both a MegWriter and a MegOutputStream from the same RequestEvent. If you do, both the MegWriter and the MegOutputStream may behave in an undefined manner.

There can be only one MegWriter per RequestEvent. This MegWriter will always be returned by subsequent calls to getMegWriter() or getMegWriter(String), even if a different encoding is specified.

Parameters:

encoding - The encoding the writer will use.

Returns:

the writer.

Throws:

java.io.UnsupportedEncodingException - If the stream is encoded using an encoding not supported on this platform.

com.ibm.wbi.NotCharDataException - If the stream does not contain character data.

See Also:

MegWriter

getMegObject

public abstract MegObject getMegObject()
                                throws MegIOTypeUnavailableException

returns the MegObject associated with this RequestEvent, if any.

Returns:

the MegObject.

Throws:

MegIOTypeUnavailableException - if the InputStream or Reader have already been requested

putMegObject

public abstract void putMegObject(MegObject mo)
                           throws MegIOTypeUnavailableException

passes the MegObject to the next MEG. Please be careful, both MEGs have now access to the same object. Refer to the documentation of your implementation of MegObject whether you may change the MegObject after calling putMegObject()!

Parameters:

mo - The MegObject

Throws:

if - a Stream has already been used

getMegObjectType

public abstract java.lang.Class getMegObjectType()

returns the class of the MegObject associated with this RequestEvent, if any.

Returns:

The MegObject class.

getRequestInfo

public abstract RequestInfo getRequestInfo()

Get the RequestInfo object that "describes" the Request. The caller may modify the object that is returned, but any modifications must be performed before the Meg commits to handling the RequestEvent (i.e., calls MegOutputStream.write(), MegWriter.write(), or RequestEvent.putMegObject(). Any modifications performed after committing to the RequestEvent will be ignored.

Specified by:

getRequestInfo in interface ResponseToRequest

Returns:

The RequestInfo object describing the request.

abort

public void abort()

Deprecated. Use getTransaction.abort( AbortEvent ).

Making this call will abort the request; no other MEGs will be dispatched.

isAborted

public boolean isAborted()

Deprecated. Use getTransaction.isAborted().

Determines if this request has been aborted (any MEG or the proxy can at any time abort the request).

Returns:

true if the request was aborted; else false .

getMegContext

public abstract MegContext getMegContext()

Get the Meg context available with this request. Meg writers should be aware that this context may only be partially implemented (some methods return null) or be null if the Meg context does not pertain to the environment we are running under.

Returns:

The Meg context or null if not applicable.

getTransaction

public abstract Transaction getTransaction()

Get the transaction object that this RequestEvent belongs to. This object will be a unique instance for each request and the same object will be available to all Megs that are cooperating to complete a transaction.

Specified by:

getTransaction in interface ResponseToRequest

Returns:

The Transaction object that corresponds to this request.

mayReject

public void mayReject()
               throws java.io.IOException

Informs WBI that this RequestEvent may be rejected. This method can only be legally called if none of getMegInputStream(), getMegReader(), and getReader() have yet been called. After calling this method, any amount of data can be read from the streams before throwing a RequestRejectedException. Be aware that reading very large amounts of data from a stream before making the decision whether to reject or not may have adverse performance implications.

Subclasses of RequestEvent SHOULD implement mayReject() if they can support its functionality.

Throws:

java.io.IOException - If the method is called illegally, as above.

See Also:

wontReject(), RequestRejectedException, getMegInputStream(), getMegReader()

wontReject

public void wontReject()

This undoes the effects of a previous call to mayReject(). If no previous call to mayReject() was made, this method has no effect. It is optional to call this method, because it will automatically be called when the first write to the corresponding MegOutputStream or MegWriter occurs. It may save memory and improve performance to call this method yourself in certain cases, however. E.g., you call mayReject(). You get a MegReader and read some characters from it, and decide that you will definitely process the request. If your next action is to write to the MegWriter, then this method is called automatically and you need do nothing. However, if you read in the entire rest of the document before writing anything out (e.g., to send it to some non-streaming parser), you may benefit from calling this method, because you will relieve WBI of the burden of keeping an extra copy of everything you read.

Subclasses of RequestEvent SHOULD implement wontReject() if they implement mayReject().

See Also:

mayReject(), RequestRejectedException