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.core.service;
028:
029: import java.util.Map;
030: import java.util.Set;
031: import org.cougaar.core.agent.service.alarm.ExecutionTimer;
032: import org.cougaar.core.component.Service;
033: import org.cougaar.core.mts.MessageAddress;
034:
035: /**
036: * This service controls the execution time in {@link
037: * AlarmService#currentTimeMillis} and {@link
038: * AlarmService#addAlarm}.
039: * <p>
040: * Although the standard implementation for "setSocietyTime"
041: * uses a node-level {@link
042: * org.cougaar.core.node.service.NaturalTimeService}
043: * and "list all nodes" naming service targets list, some effort
044: * has been made to allow separate execution times both between
045: * nodes and in the agents within nodes.
046: */
047: public interface DemoControlService extends Service {
048:
049: /**
050: * Get the local node's execution rate.
051: */
052: double getExecutionRate();
053:
054: /**
055: * Schedule a thread to set the local agent's time at
056: * real-time <i>changeTime</i> to an execution-time of
057: * <i>changeTime + offset</i> and <i>rate</i>.
058: */
059: void setLocalTime(long offset, double rate, long changeTime);
060:
061: /**
062: * Backwards-compatible variations of {@link
063: * #setLocalTime(long,double,long)}.
064: * <p>
065: * These methods use <tt>ExecutionTimer.create</tt> to create an
066: * <tt>ExecutionTimer.Change</tt>, which may mangle the timestamps
067: * when converting a "time" to an "offset".
068: *
069: * @see #setLocalTime(long,double,long)
070: */
071: void setNodeTime(long time, double rate, long changeTime);
072:
073: void advanceNodeTime(long period, double rate);
074:
075: void setNodeTime(long time, double rate);
076:
077: /**
078: * Non-blocking method to set the node time at the specified nodes.
079: *
080: * @param offset offset of real-time at the changeTime
081: * @param rate time rate multiplier (e.g. 2 seconds per second)
082: * @param changeTime real-time when the change should take place,
083: * which should allow enough time for messaging.
084: * @param cb optional callback to monitor progress
085: * @return true if completed in this thread, which only happens
086: * if the targets list is empty or just the local node, otherwise
087: * the callback is required to monitor the asynchronous progress.
088: */
089: boolean setSocietyTime(long offset, double rate, long changeTime,
090: Set targets, Callback cb);
091:
092: /**
093: * Mostly non-blocking setSocietyTime to all nodes listed in the
094: * naming service, but the naming service lookup could block or
095: * return a partial list.
096: *
097: * @see #setSocietyTime(long,double,long,Set,DemoControlService.Callback)
098: * @see org.cougaar.core.wp.ListAllNodes
099: */
100: boolean setSocietyTime(long offset, double rate, long changeTime,
101: Callback cb);
102:
103: /**
104: * Blocking setSocietyTime variations with timeouts.
105: * <p>
106: * These are identical to the above Callback variations
107: * with a simple Callback that blocks on an
108: * "Object.wait(timeout)".
109: * <p>
110: * Callers should pass a timeout that's <= to the
111: * changeTime, since usually you'd want to stop blocking
112: * if a target was overly slow or unreachable.
113: *
114: * @param timeout time to wait in milliseconds, or zero
115: * to block forever -- usually changeTime makes sense.
116: * @return true if all advances completed before the timeout,
117: * otherwise false.
118: * @see #setSocietyTime(long,double,long,Set,DemoControlService.Callback)
119: */
120: boolean setSocietyTime(long offset, double rate, long changeTime,
121: Set targets, long timeout);
122:
123: /**
124: * @see #setSocietyTime(long,double,long,DemoControlService.Callback)
125: */
126: boolean setSocietyTime(long offset, double rate, long changeTime,
127: long timeout);
128:
129: /**
130: * A blocking setSocietyTime that uses the changeTime
131: * as the timeout -- this is the basis for all the other
132: * non-Callback/timeout setSocietyTime variations.
133: *
134: * @see #setSocietyTime(long,double,long,Set,DemoControlService.Callback)
135: */
136: boolean setSocietyTime(long offset, double rate, long changeTime);
137:
138: /**
139: * Backwards-compatible blocking variations of {@link
140: * #setSocietyTime(long,double,long)}.
141: * <p>
142: * For legacy reasons these return "void" instead of a "boolean".
143: * Also, they use <tt>ExecutionTimer.create</tt> to create an
144: * <tt>ExecutionTimer.Change</tt>, which may mangle the timestamps
145: * when converting a "time" to an "offset".
146: *
147: * @see #setSocietyTime(long,double,long,Set,DemoControlService.Callback)
148: */
149: void setSocietyTime(long time);
150:
151: void setSocietyTime(long time, boolean forceRunning);
152:
153: void setSocietyTimeRate(double rate);
154:
155: void advanceSocietyTime(long period);
156:
157: void advanceSocietyTime(long period, boolean forceRunning);
158:
159: void advanceSocietyTime(long period, double rate);
160:
161: void advanceSocietyTime(ExecutionTimer.Change[] changes);
162:
163: /**
164: * An optional {@link
165: * #setSocietyTime(long,double,long,Set,DemoControlService.Callback)}
166: * progress monitor supplied by the service user.
167: */
168: public interface Callback {
169: /**
170: * On the <tt>setSocietyTime</tt> call, the Set of targets
171: * that will be advanced.
172: */
173: public void sendingTimeAdvanceTo(Set addrs);
174:
175: /**
176: * An "ack" from a target, with the round-trip-time.
177: */
178: public void updatedTime(MessageAddress addr, long rtt);
179:
180: /**
181: * All targets have been advanced.
182: * @return a Map from the targets to their Long round-trip-times.
183: */
184: public void completed(Map addrsToRTT);
185: }
186: }
|