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.ObjectOutput;
030: import java.io.OutputStream;
031: import org.cougaar.mts.std.AttributedMessage;
032: import org.cougaar.core.mts.Attributes; //for javadoc
033:
034: /**
035: * This is the final station in the sender for serializling
036: * LinkProyocols. MessageWriter and MessageReader allow aspect
037: * authors to examine and filter the serialized data stream.
038: *
039: * <p> Aspect implementers must either call the package-access
040: * addFilter AttribuedMessage method or use pushValue("Filter",
041: * className) to get the MessageWriter and MessageReader delegates to
042: * be attached. Each message has the aspect chain built for it and
043: * the target's aspect chain is governed by the list as given by the
044: * sender. Normally the attribute is added in the DestinationLink's
045: * forwardMessage or addAttributes method.
046: *
047: * <p>
048: * The previous stop is DestinationLink. The next stop is MessageReader
049: * on the receiving side.
050: *
051: * @see AttributedMessage#addFilter(Object)
052: * @see Attributes#pushValue(String, Object)
053: * @see SendLink
054: * @see SendQueue
055: * @see Router
056: * @see DestinationQueue
057: * @see DestinationLink
058: * @see MessageReader
059: * @see MessageDeliverer
060: * @see ReceiveLink
061: *
062: * Javadoc contributions by George Mount.
063: */
064: public interface MessageWriter {
065: /**
066: * Called during serialization to give the MessageWriter
067: * the opportunity to view and modify the message attributes.
068: *
069: * @param msg The message for which this MessageWriter is designated.
070: * @see #preProcess()
071: */
072: void finalizeAttributes(AttributedMessage msg);
073:
074: /**
075: * Called by AttributedMessage during serialization before
076: * getObjectOutputStream and after finalizeAttributes.
077: *
078: * @see #finalizeAttributes(AttributedMessage)
079: * @see #getObjectOutputStream(ObjectOutput)
080: */
081: void preProcess();
082:
083: /**
084: * Called by AttributedMessage during serialization. The
085: * stream is used to write the serialized message body. The
086: * returned OutputStream is usually a filtered stream that modifies
087: * the contents before writing them to out.
088: *
089: * @param out The next innermost stream in the nesting.
090: * @return An OutputStream to be used for serialization of the message.
091: * @see #preProcess
092: * @see #finishOutput
093: */
094: OutputStream getObjectOutputStream(ObjectOutput out)
095: throws java.io.IOException;
096:
097: /**
098: * Called during AttributedMessage serialization after the message body
099: * has been written to the OutputStream returned from getObjectOutputStream.
100: *
101: * @throws java.io.IOException The stream could be cached
102: * so an IOException can be thrown here.
103: * @see #getObjectOutputStream(ObjectOutput)
104: */
105: void finishOutput() throws java.io.IOException;
106:
107: /**
108: * Called after all data is written to the output stream in finishOutput.
109: *
110: * @see #finishOutput()
111: */
112: void postProcess();
113: }
|