MegObject OverviewWith WBI Development Kit version 4.5, we are introducing the MegObject interface, which enables Meg authors to pass objects rather than streamed data between Megs. In many cases, passing objects can eliminate the need for repeated serialization of objects onto streams and repeated parsing of data flowing along streams. Using MegObjects can be efficient when several Megs work together using the same parsed representation of a document. For example, if the one Meg in a chain converts data flowing along the MegInputStream to some DomMegObject, following Megs can work on the same DomMegObject without having to parse the data themselves. If any Meg expects normal streamed data, WBI will handle the conversion of the data from its MegObject form to its stream form, but of course, in this case the data might need to be serialized and reparsed later.
Normally, a Meg reads data from the MegInputStream or the MegReader, and it writes data to MegOutputStream or to the MegWriter. ith MegObjects, the Meg can try to retrieve a MegObject from the RequestEvent, and pass a MegObject to the next Meg directly without serializing it on the stream.
To use MegObjects, the Meg author must use or create a class that implements the MegObject interface. This class is responsible for converting an object to an appropriate stream-based representation, and for providing the method to copy or clone an object. A MegObject might, for example, contain the HTML document in a Document Object Model (DOM) or a preparsed TokenStream representation.
DetailsTo obtain its input data, a Meg's handleRequest method can either (a) read from its RequestEvent's MegInputStream, (b) read from its RequestEvent's MegReader, or (c) get the RequestEvent's MegObject. Of course, the Meg's RequestEvent is guaranteed to provide an input stream or a reader, but it is not guaranteed to provide an object. Moreover, even when there is a MegObject available for a particular transaction, this object might not be of the type that the Meg expects. To determine whether there is a MegObject and if so what its class is, a Meg can use the RequestEvent.getMegObjectType() method. If the object is of the appropriate type,the object can then be obtained using the RequestEvent.getMegObject() method. After getMegObject() has been called, no input stream or reader may be retrieved from the RequestEvent. Similarly, if an input stream or reader has been read from, the MegObject cannot be retrieved.
The output side works similarly. Normally, a Meg will pass binary or character data to the next Meg using the write() method of MegOutputStream or of MegWriter. With MegObjects, however, the Meg can pass an object directly to the next Meg in the chain using RequestEvent.putMegObject().
Note that when passing objects rather thn streamed data between Megs, Meg authors must be careful not to modify an object inadvertantly after it has been passed. That is, MegObjects are not routinely copied as they flow from Meg to Meg (copying would, of course, eliminate some of the benefit of object passing the first place). However, there are some cases in which Meg authors might to use the MegObject itself to communicate between Megs, for example, when passing several objects along an object stream that is held inside a MegObject (rather than using the binary or character data streams the WBI infrastructure normally provides).
There are two cases in which MegObjects are copied. First, Monitors actually receive clones of the MegObject so that Monitors can operate on the object without worrying about downstream effects (i.e., cloning the object is like Monitors not having an output stream to write to). Second, if a handleRequest() method might throw a RequestRejectedException, then WBI must internally clone the MegObject in case the request is rejected and the original object must be restored. In this case, the Meg author must tell WBI that the request might be rejected using the new RequestEvent.mayReject() method. If this is not noted and the Meg rejects the request and the Meg also modified the object, then the modified object will be passed along.
ExamplesTo learn how to use and implement MegObjects, see the MegObjectExamplePlugin.