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 java.util.List;
030:
031: import org.cougaar.planning.ldm.plan.Expansion;
032: import org.cougaar.planning.ldm.plan.Task;
033:
034: /**
035: * <pre>
036: * Listener intended to be used by all expanders.
037: *
038: * Being an expansion listener now means participating in a 4 step process.
039: * When an expansion changes, it can change in one of 4 ways, each of which the
040: * the listener can play a role in.
041: *
042: * Note that below, when default behavior is mentioned, it is in ExpanderPluginAdapter.
043: *
044: * 1) The expansion can fail. (handleFailedExpansion)
045: * Some downstream allocation can fail, and if this happens, the listener will
046: * be called with the expansion and the list of failed sub tasks.
047: *
048: * The listener can handle this in one of two ways :
049: * a) rescind the expansion and replan and reallocate OR
050: * b) give up and report the failed expansion to a superior. An example of this
051: * approach is in UTILSimpleExpanderPlugin
052: *
053: * Since this is important, THERE IS NO DEFAULT BEHAVIOR for this option.
054: *
055: * 2) The expansion's constraints may be violated. (handleConstraintViolation)
056: * No allocation failed, but a workflow constraint was violated. E.g. Task A is supposed
057: * to come before task B, but it wasn't allocated that way. If this happens, the
058: * listener will be called with the expansion and the list of failed constraints.
059: *
060: * The listener can handle this in one of two ways :
061: * a) rescind the expansion and replan and reallocate OR
062: * b) give up and report the expansion to a superior.
063: *
064: * This doesn't happen very often, so the default behavior is to throw an exception.
065: *
066: * 3) The expansion is not good enough, in some way. (wantToChangeExpansion,
067: * handleChangedExpansion, publishChangedExpansion)
068: * No allocation failed, no workflow constraint was violated, but perhaps the aggregate score
069: * of all the allocated subtasks was above some threshold. First the listener is asked if
070: * it wants to change the expansion, and if so, handleChangedExpansion gets called. Finally,
071: * publishChangeExpansion is called.
072: *
073: * The listener can handle this in the same way as case #1.
074: *
075: * Default behavior is not to want to change the expansion.
076: *
077: * 4) The expansion is fine. (reportChangedExpansion)
078: * Everything is fine with the expansion, and the listener is asked to report the results
079: * of the expansion to its superior.
080: *
081: * The listener can handle this by simply reporting the changed expansion by calling
082: * updateAllocationResult.
083: *
084: * Default behavior is to do this.
085: *
086: * Allocators should use/be a GenericListener.
087: *
088: * </pre>
089: * @see org.cougaar.lib.callback.UTILExpansionCallback
090: * @see org.cougaar.lib.callback.UTILAggregationListener
091: * @see org.cougaar.lib.callback.UTILAllocationListener
092: */
093:
094: public interface UTILExpansionListener extends
095: UTILFilterCallbackListener {
096: /**
097: * Defines tasks you find interesting.
098: * @param t Task to check for interest
099: * @return boolean true if task is interesting
100: */
101: boolean interestingExpandedTask(Task t);
102:
103: /**
104: * An expansion has failed. It's up to the plugin how to deal with the
105: * failure.
106: *
107: * @param exp expansion that failed
108: * @param failedSubTasks List of SubTaskResult objects, all of which have newly failed.
109: * @see org.cougaar.planning.ldm.plan.SubTaskResult
110: */
111: void handleFailedExpansion(Expansion exp, List failedSubTasks);
112:
113: /**
114: * At least one constraint has been violated. It's up to the plugin how to deal
115: * with the violation(s).
116: *
117: * @param exp expansion that failed
118: * @param violatedConstraints list of Constraints that have been violated
119: */
120: void handleConstraintViolation(Expansion exp,
121: List violatedConstraints);
122:
123: /**
124: * Does the plugin want to change the expansion?
125: * For instance, although no individual preference may have been exceeded,
126: * the total score for the expansion may exceed some threshold, and so the
127: * plugin may want to alter the expansion.
128: *
129: * @see org.cougaar.lib.util.UTILAllocate#scoreAgainstPreferences
130: * @param exp expansion to check
131: * @return true if plugin wants to change expansion
132: */
133: boolean wantToChangeExpansion(Expansion exp);
134:
135: /**
136: * The plugin changes the expansion.
137: *
138: * @see #wantToChangeExpansion(Expansion)
139: * @param exp expansion to change
140: */
141: void changeExpansion(Expansion exp);
142:
143: /**
144: * publish the change
145: *
146: * @see #wantToChangeExpansion(Expansion)
147: * @param exp expansion to change
148: */
149: void publishChangedExpansion(Expansion exp);
150:
151: /**
152: * Updates and publishes allocation result of expansion.
153: *
154: * @param exp expansion to report
155: */
156: void reportChangedExpansion(Expansion exp);
157:
158: /**
159: * Updates and publishes allocation result of expansion.
160: *
161: * @param exp expansion to report
162: * @param successfulSubtasks list of successful subtasks
163: */
164: void handleSuccessfulExpansion(Expansion exp,
165: List successfulSubtasks);
166: }
|