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 org.cougaar.core.mts.MessageAddress;
030: import org.cougaar.mts.std.AttributedMessage;
031:
032: /**
033: * The fourth station for an outgoing message is a DestinationQueue. In
034: * this implementation, the DestinationQueueFactory instantiates one
035: * DestinationQueue per destination address and is accessible to
036: * certain impl classes as the MTS-internal service
037: * DestinationQueueProviderService.
038: * <p>
039: * The dispatching thread associated with this queue will send
040: * dequeued messages on to the 'best' DestinationLink, handling
041: * retries if an exception occurs.
042: * <p>
043: * The <strong>holdMessage</strong> method is used to queue messages
044: * in preparation for passing them onto the next stop, a
045: * transport-specific DestinationLink. Ordinarily this would only be
046: * called from a Router.
047: * <p>
048: * The <strong>matches</strong> method is used by the
049: * DestinationQueueFactory to avoid making more than one queue for a
050: * given destinationAddress.
051: * <p>
052: * The previous station is Router. The next station is DestinationLink.
053: *
054: * @see DestinationQueueFactory
055: * @see SendLink
056: * @see SendQueue
057: * @see Router
058: * @see DestinationLink
059: * @see MessageWriter
060: * @see MessageReader
061: * @see MessageDeliverer
062: * @see ReceiveLink
063: *
064: * Javadoc contributions by George Mount.
065: */
066:
067: public interface DestinationQueue {
068: /**
069: * Adds the message to the queue. Since the queue runs its own
070: * thread, this call is typically the last element in the Router
071: * thread's call sequence. */
072: void holdMessage(AttributedMessage message);
073:
074: /**
075: * Handles the next message popped off the queue. Finds the
076: * most appropriate DestinationLink based on the LinkSelectionPolicy
077: * and calls its <tt>addMessageAttributes</tt> before
078: * <tt>forwardMessage</tt> to dispatch.
079: *
080: * @see LinkSelectionPolicy
081: * @see Router#routeMessage(AttributedMessage)
082: * @see DestinationLink#addMessageAttributes(MessageAttributes)
083: * @see DestinationLink#forwardMessage(AttributedMessage)
084: */
085: void dispatchNextMessage(AttributedMessage message);
086:
087: /**
088: * Returns true iff this queue was created for the given
089: * destination. Used by the DestinationQueueFactory. */
090: boolean matches(MessageAddress address);
091:
092: /**
093: * Number of messages waiting in the queue.
094: */
095: int size();
096:
097: /**
098: * Returns the address for which this DestinationQueue was created.
099: */
100: MessageAddress getDestination();
101:
102: /**
103: * Return a snapshot of the current contents of the queue.
104: */
105: AttributedMessage[] snapshot();
106:
107: }
|