001: /*
002: * <copyright>
003: *
004: * Copyright 2001-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 org.cougaar.core.component.Service;
031: import org.cougaar.core.mts.MessageAddress;
032:
033: /**
034: * This service tracks agent incarnation numbers, which are
035: * updated every time the agent restarts (excluding agent
036: * mobility).
037: * <p>
038: * This is used to detect restarted agents and reconcile
039: * with them.
040: */
041: public interface IncarnationService extends Service {
042:
043: /**
044: * @return the agent incarnation, or -1 if the agent or its
045: * incarnation is not known.
046: */
047: long getIncarnation(MessageAddress addr);
048:
049: /**
050: * Update an agent's incarnation.
051: * @return 0 if unchanged, -1 if the incarnation is old,
052: * or 1 if the incarnation is new (which will invoke the
053: * callbacks in the caller's thread)
054: */
055: int updateIncarnation(MessageAddress addr, long inc);
056:
057: /**
058: * Subscribe to incarnation change callbacks.
059: * Equivalent to <code>subscribe(addr, cb, 0)</code>.
060: * @return true if the callback was not already subscribed
061: */
062: boolean subscribe(MessageAddress addr, Callback cb);
063:
064: /**
065: * Subscribe to incarnation change callbacks with an initial
066: * minimal incarnation value filter.
067: * <p>
068: * The incarnation is used to restore a subscription after
069: * capturing it from {@link #getIncarnation(MessageAddress)},
070: * specifically for mobile agents.
071: *
072: * @return true if the callback was not already subscribed
073: */
074: boolean subscribe(MessageAddress addr, Callback cb, long inc);
075:
076: /**
077: * Unsubscribe from incarnation change callbacks.
078: * @return true if the callback was subscribed
079: */
080: boolean unsubscribe(MessageAddress addr, Callback cb);
081:
082: /**
083: * Get a map of our subscriptions (addrs to callbacks).
084: *
085: * @return Map>MessageAddress, Set>Callback<<
086: */
087: Map getSubscriptions();
088:
089: /**
090: * Subscription callback API.
091: * <p>
092: * Callback instances not implementing {@link Comparable} are
093: * invoked first, followed by the {@link Comparable} instances
094: * in sorted order.
095: */
096: interface Callback {
097: /**
098: * The incarnation for the specified agent has changed
099: * to the new <code>inc</code> value.
100: */
101: void incarnationChanged(MessageAddress addr, long inc);
102: }
103: }
|