001: /*
002: * <copyright>
003: *
004: * Copyright 1997-2004 BBNT Solutions, LLC
005: * under sponsorship of the Defense Advanced Research Projects
006: * Agency (DARPA).
007: *
008: * You can redistribute this software and/or modify it under the
009: * terms of the Cougaar Open Source License as published on the
010: * Cougaar Open Source Website (www.cougaar.org).
011: *
012: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
013: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
014: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
015: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
016: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
017: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
018: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
019: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
020: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
021: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
022: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
023: *
024: * </copyright>
025: */
026:
027: package org.cougaar.mts.base;
028:
029: import java.io.InputStream;
030: import java.io.ObjectInput;
031: import org.cougaar.core.mts.Attributes; //for javadoc
032:
033: import org.cougaar.mts.std.AttributedMessage;
034:
035: /**
036: * This is the first station in the receiver for serializling
037: * LinkProtocols. MessageWriter and MessageReader allow aspect
038: * authors to examine and filter the serialized data stream.
039: *
040: * <p>
041: * Aspect implementers must either call the package-access addFilter
042: * AttribuedMessage method or use pushValue("Filter", className) to
043: * get the MessageWriter and MessageReader delegates to be attached.
044: * Each message has the aspect chain built for it and the target's
045: * aspect chain is governed by the list as given by the sender.
046: * Normally the attribute is added in the DestinationLink's
047: * forwardMessage or addAttributes method.
048: * <p>
049: * The previous stop is MessageWriter on the sending side.
050: * The next stop is MessageDeliverer.
051: *
052: * @see AttributedMessage#addFilter(Object)
053: * @see Attributes#pushValue(String, Object)
054: * @see SendLink
055: * @see SendQueue
056: * @see Router
057: * @see DestinationQueue
058: * @see DestinationLink
059: * @see MessageWriter
060: * @see MessageDeliverer
061: * @see ReceiveLink
062: *
063: * Javadoc contributions from George Mount.
064: */
065: public interface MessageReader {
066:
067: /**
068: * Called during deserialization of an AttributedMessage
069: * after the message attributes have been read.
070: * Gives the MessageReader
071: * the opportunity to view and modify the message attributes.
072: *
073: * @param msg The message for which this MessageReader is designated.
074: * @see #preProcess()
075: */
076: void finalizeAttributes(AttributedMessage msg);
077:
078: /**
079: * Called by AttributedMessage during deserialization before
080: * getObjectInputStream and after finalizeAttributes.
081: *
082: * @see #finalizeAttributes(AttributedMessage)
083: * @see #getObjectInputStream(ObjectInput)
084: */
085: void preProcess();
086:
087: /**
088: * Called by AttributedMessage during deserialization. The
089: * stream is used to read the serialized message body. The
090: * returned InputStream is usually a filtered stream that modifies
091: * the contents as they are being read.
092: *
093: * @param in The next innermost stream in the nesting.
094: * @return An InputStream to be used for serialization of the message.
095: * @see #preProcess
096: * @see #finishInput
097: */
098: InputStream getObjectInputStream(ObjectInput in)
099: throws java.io.IOException, ClassNotFoundException;
100:
101: /**
102: * Called during AttributedMessage deserialization after the message body
103: * has been read.
104: *
105: * @throws java.io.IOException The stream could be cached
106: * so an IOException can be thrown here.
107: * @see #getObjectInputStream(ObjectInput)
108: */
109: void finishInput() throws java.io.IOException;
110:
111: /**
112: * Called after finishInput in the AttributedMessage deserialization.
113: *
114: * @see #finishInput()
115: */
116: void postProcess();
117:
118: }
|