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.util.ArrayList;
030:
031: import org.cougaar.core.mts.AgentState;
032: import org.cougaar.core.mts.MessageAddress;
033: import org.cougaar.core.mts.MessageTransportClient;
034: import org.cougaar.mts.std.AttributedMessage;
035:
036: /**
037: * SendLink is the first station after the MessageTransportService
038: * implementation class. Its primary job is to validate the
039: * originator and add the message to the SendQueue, thereby ending the
040: * call sequence from the caller's point of view (sendMessage). <p>
041: * @see org.cougaar.core.service.MessageTransportService
042: * @see SendQueue
043: * @see Router
044: * @see DestinationQueue
045: * @see DestinationLink
046: * @see MessageWriter
047: * @see MessageReader
048: * @see MessageDeliverer
049: * @see ReceiveLink
050: *
051: * Javadoc contribuions from George Mount.
052: */
053: public interface SendLink {
054: /**
055: * Validates the originator and add the message to the SendQueue,
056: * thereby ending the call sequence from the caller's point of view.
057: * Invoked from the MessageTransportService impl class method of the
058: * same name, which will have already wrapped the original message
059: * in an AttributedMessage, using the original message target
060: * address's attributes.
061: *
062: * @param message The AttributedMessage to be sent.
063: * @see SendQueue#sendMessage(AttributedMessage)
064: * @see org.cougaar.core.service.MessageTransportService#sendMessage(Message)
065: */
066: void sendMessage(AttributedMessage message);
067:
068: /**
069: * Causes any queued or pending messages from the address
070: * associated with the SendLink to be removed from the queues,
071: * The list of flushed messages is returned in the supplied
072: * ArrayList.
073: *
074: * @param messages Dropped messages are added to this list.
075: * @see org.cougaar.core.service.MessageTransportService#flushMessages()
076: */
077: void flushMessages(ArrayList messages);
078:
079: /**
080: * Releases hooks into the MTS and invalidates the SendLink.
081: * Called when the MessageTransportService is released by the
082: * MessageTransportClient associated with this SendLink.
083: */
084: void release();
085:
086: /**
087: * Returns the MessageAddress that this SendLink is associated with.
088: */
089: MessageAddress getAddress();
090:
091: /**
092: * Returns <tt>true</tt> if it is possible to send message.
093: * SendLinkImpl only checks that the target MessageAddress is properly formed
094: * and release() has not been called.
095: *
096: * @param message The message to should be checked for validity.
097: * @see org.cougaar.core.service.MessageTransportService#sendMessage(Message)
098: */
099: boolean okToSend(AttributedMessage message);
100:
101: /**
102: * Calls the MessageTransportRegistry's registerClient, which in turn
103: * calls the registerClient for all LinkProtocols. One and only one client
104: * should be registered with a SendLink. Once registered, a ReceiveLink
105: * is created so that the client can receive messages.
106: *
107: * @param client The MTS client to register.
108: * @see org.cougaar.core.service.MessageTransportService#registerClient(MessageTransportClient)
109: * @see MessageTransportRegistryService#registerClient(MessageTransportClient)
110: */
111: void registerClient(MessageTransportClient client);
112:
113: /**
114: * Unregisters the client from all LinkProtocols. The client should
115: * be the client that was previously passed in registerClient. The client
116: * will no longer be able to receive messages.
117: *
118: * @param client The MTS client to unregister.
119: * @see org.cougaar.core.service.MessageTransportService#unregisterClient(MessageTransportClient)
120: * @see MessageTransportRegistryService#unregisterClient(MessageTransportClient)
121: */
122: void unregisterClient(MessageTransportClient client);
123:
124: /**
125: * Returns the internal name of the Node's MTS. In the current
126: * implementation this is just the Node's name, but no assumption
127: * should be made that this wll always be true. All SendLinks in
128: * a given MTS will always return the same value here.
129: */
130: String getIdentifier();
131:
132: /**
133: * Returns <tt>true</tt> iff some LinkProtocol recognizes the
134: * given address.
135: *
136: * @param address MessageAddress whose status is to be determined.
137: * @return <tt>true</tt> iff one of the registered LinkProtocols
138: * knows address.
139: */
140: boolean addressKnown(MessageAddress address);
141:
142: /**
143: * Returns an AgentState that can be used by aspects to store and retrieve
144: * MTS-client-based data.
145: */
146: AgentState getAgentState();
147:
148: }
|