01: /*
02: * <copyright>
03: *
04: * Copyright 2002-2004 BBNT Solutions, LLC
05: * under sponsorship of the Defense Advanced Research Projects
06: * Agency (DARPA).
07: *
08: * You can redistribute this software and/or modify it under the
09: * terms of the Cougaar Open Source License as published on the
10: * Cougaar Open Source Website (www.cougaar.org).
11: *
12: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
13: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
14: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
15: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
16: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
17: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
18: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
19: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
20: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
21: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
22: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23: *
24: * </copyright>
25: */
26:
27: package org.cougaar.core.relay;
28:
29: import org.cougaar.core.mts.MessageAddress;
30: import org.cougaar.core.util.UID;
31: import org.cougaar.core.util.UniqueObject;
32:
33: /**
34: * A blackboard object API to send a query object to a remote agent,
35: * which can optionally reply back to the sender.
36: * <p>
37: * Multiple rounds of query/reply are supported.
38: *
39: * @see SimpleRelaySource source-side relay implementation
40: */
41: public interface SimpleRelay extends UniqueObject {
42:
43: // from UniqueObject
44: UID getUID();
45:
46: void setUID(UID uid);
47:
48: /** The agent that created the query */
49: MessageAddress getSource();
50:
51: /** The agent that will set the reply */
52: MessageAddress getTarget();
53:
54: /** Get the query contents */
55: Object getQuery();
56:
57: /**
58: * Change the query, which is optional.
59: * <p>
60: * Only the agent who's address matches "getSource()" may call
61: * this method, which must be followed by a blackboard
62: * "publishChange" to resend the query to the target.
63: * <p>
64: * Note that the relay implementation may batch changes and
65: * only send the latest change.
66: *
67: * @param query the immutable query object
68: */
69: void setQuery(Object query);
70:
71: /**
72: * Get the remote reply to the query, if any.
73: * <p>
74: * Blackboard interactions are asynchronous, so the plugin should
75: * use a subscription to wake when the SimpleRelay has changed.
76: */
77: Object getReply();
78:
79: /**
80: * Change the reply, which is optional.
81: * <p>
82: * Only the agent who's address matches "getTarget()" should call
83: * this method, which must be followed by a blackboard
84: * "publishChange" to resend the reply to the target.
85: * <p>
86: * Note that the relay implementation may batch changes and
87: * only send the latest change.
88: *
89: * @param reply the immutable reply object
90: */
91: void setReply(Object reply);
92:
93: }
|