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.lib.callback;
028:
029: import org.cougaar.planning.ldm.plan.Aggregation;
030: import org.cougaar.planning.ldm.plan.Task;
031:
032: /**
033: * <pre>
034: * Listener intended to be used by all aggregators.
035: *
036: * Being an aggregation listener now means participating in a 2 step process.
037: * When an aggregation changes, it can change in one of two ways, each of which the
038: * the listener can play a role in.
039: *
040: * Note that below, when default behavior is mentioned, it is in ???PluginAdapter.
041: *
042: * 1) The aggregation can fail. (handleFailedAggregation)
043: * Some downstream allocation can fail, and if this happens, the listener will
044: * be called with the aggregation.
045: *
046: * The listener can handle this in one of two ways :
047: * a) rescind the aggregation and replan and reallocate OR
048: * b) give up and report the failed aggregation to a superior. An example of this
049: * approach is in UTILXXXPlugin
050: *
051: * Since this is important, THERE IS NO DEFAULT BEHAVIOR for this option.
052: *
053: * 2) The aggregation is fine. (reportChangedAggregation)
054: * Everything is fine with the aggregation, and the listener is asked to report the results
055: * of the aggregation to its superior.
056: *
057: * The listener can handle this by simply reporting the changed aggregation by calling
058: * updateAllocationResult.
059: *
060: * ???Default behavior is to do this.
061: *
062: * </pre>
063: * @see org.cougaar.lib.callback.UTILAggregationCallback
064: * @see org.cougaar.lib.callback.UTILExpansionListener
065: * @see org.cougaar.lib.callback.UTILAllocationListener
066: */
067:
068: public interface UTILAggregationListener extends
069: UTILFilterCallbackListener {
070: /**
071: * Defines tasks you find interesting.
072: * @param t Task to check for interest
073: * @return boolean true if task is interesting
074: */
075: boolean interestingParentTask(Task t);
076:
077: /**
078: * Defines conditions for rescinding tasks.
079: *
080: * When returns TRUE, handleRescindedAggregation is called.
081: *
082: * See comment on UTILAggregatorPluginAdapter.needToRescind.
083: *
084: * @param agg Aggregation to check for
085: * @return boolean true if task needs to be rescinded
086: * @see #handleRescindedAggregation
087: * @see org.cougaar.lib.filter.UTILAggregatorPluginAdapter#needToRescind
088: */
089: boolean needToRescind(Aggregation agg);
090:
091: /**
092: * An aggregation has failed. It's up to the plugin how to deal with the
093: * failure.
094: *
095: * See comment on UTILAggregatorPluginAdapter.needToRescind.
096: *
097: * @param agg aggregation that failed/has been rescinded by listener
098: * @return true if handled
099: * @see #needToRescind
100: * @see org.cougaar.lib.filter.UTILAggregatorPluginAdapter#needToRescind
101: */
102: boolean handleRescindedAggregation(Aggregation agg);
103:
104: /**
105: * Updates and publishes allocation result of aggregation.
106: *
107: * @param agg aggregation to report
108: */
109: void reportChangedAggregation(Aggregation agg);
110:
111: /**
112: * What to do with a successful aggregation.
113: * For implementers who DON'T extend UTILPluginAdapter,
114: * this should be implemented with an empty body.
115: *
116: * Called after reportChangedAggregation when needToRescind returns FALSE.
117: *
118: * @param agg the returned successful aggregation
119: * @see #needToRescind
120: * @see org.cougaar.lib.filter.UTILAggregatorPluginAdapter#needToRescind
121: */
122: void handleSuccessfulAggregation(Aggregation agg);
123:
124: /**
125: * Called when an aggregation is removed from the cluster.
126: * I.e. an upstream cluster removed an allocation, and this
127: * has resulted in this aggregation being removed.
128: *
129: * If the plugin maintains some local state of the availability
130: * of assets, it should update them here.
131: */
132: void handleRemovedAggregation(Aggregation agg);
133:
134: /**
135: * Public version of publishRemove
136: *
137: * Called when needToRescind returns TRUE.
138: *
139: * @param agg aggregation to remove
140: */
141: void publishRemovalOfAggregation(Aggregation agg);
142: }
|