01: /*
02: * <copyright>
03: *
04: * Copyright 1997-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.service;
28:
29: import java.util.Map;
30:
31: import org.cougaar.core.component.Service;
32:
33: /**
34: * This service is used by components to tell the node the initial
35: * quiescence numbering and to toggle between quiescence and
36: * non-quiescence.
37: * <p>
38: * "Quiescence" is partially a node-local concept, where all local
39: * agents have completed processing, and a society-wide concept,
40: * where all inter-agent messages have been delivered. The {@link
41: * EventService} is used to report node-local quiescence and
42: * incoming/outgoing message numbers to an external script that
43: * detects society-wide quiescence. Quiescence detection is
44: * primarily an execution-time planning tool used to advance the
45: * execution time ({@link DemoControlService}) past idle planning
46: * time (e.g. advance a day once all agents have planned the current
47: * day).
48: * <p>
49: * Usually blackboard activity is enough to detect quiescence,
50: * but a component that runs in a separate thread or queues work
51: * must often tell the node that the agent is non-quiescent even
52: * though blackboard activity has ceased.
53: */
54: public interface QuiescenceReportService extends Service {
55: /**
56: * Specifies the client agent's identity using his
57: * AgentIdentificationService. This method must be called before any
58: * other method and establishes the identity of the client agent in
59: * a more or less unforgable way.
60: * @param agentIdentificationService the agent's identification service
61: */
62: void setAgentIdentificationService(
63: AgentIdentificationService agentIdentificationService);
64:
65: /**
66: * Specify the maps of quiescence-relevant outgoing and incoming
67: * message numbers associated with a newly achieved state of
68: * quiescence. For efficiency, this method should be called before
69: * calling setQuiescentState().
70: * @param outgoingMessageNumbers a Map from agent MessageAddresses
71: * to Integers giving the number of the last message sent. The
72: * arguments must not be null.
73: * @param incomingMessageNumbers a Map from agent MessageAddresses
74: * to Integers giving the number of the last message received. The
75: * arguments must not be null.
76: */
77: void setMessageNumbers(Map outgoingMessageNumbers,
78: Map incomingMessageNumbers);
79:
80: /**
81: * Specifies that, from this service instance point-of-view, the
82: * agent is quiescent. The message number maps are not altered.
83: */
84: void setQuiescentState();
85:
86: /**
87: * Specifies that this agent is no longer quiescent.
88: */
89: void clearQuiescentState();
90: }
|