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.Allocation;
030: import org.cougaar.planning.ldm.plan.PlanElement;
031: import org.cougaar.planning.ldm.plan.Task;
032:
033: /**
034: * Interface defining what to do when an allocation changes.
035: *
036: * Paired with UTILAllocationCallback.
037: *
038: * @see org.cougaar.lib.callback.UTILAllocationCallback
039: * @see org.cougaar.lib.callback.UTILExpansionListener
040: * @see org.cougaar.lib.callback.UTILAggregationListener
041: */
042:
043: public interface UTILAllocationListener extends
044: UTILFilterCallbackListener {
045: /**
046: * Filter for task notifications on allocations that are
047: * interesting.
048: *
049: * @param t task to check for notification
050: * @return boolean true if task is interesting
051: */
052: boolean interestingNotification(Task t);
053:
054: /**
055: * Defines conditions for rescinding tasks.
056: *
057: * When returns TRUE, handleRescindedAlloc is called.
058: *
059: * See comment on UTILAllocatorPluginAdapter.needToRescind.
060: *
061: * @param alloc allocation to check for
062: * @return boolean true if task needs to be rescinded
063: * @see #handleRescindedAlloc
064: * @see org.cougaar.lib.filter.UTILAllocatorPluginAdapter#needToRescind
065: */
066: boolean needToRescind(Allocation alloc);
067:
068: /**
069: * What to do with a rescinded allocation.
070: *
071: * See comment on UTILAllocatorPluginAdapter.needToRescind.
072: *
073: * Implementers need to take into consideration that
074: * the asset chosen last time is not available this time.
075: *
076: * @param alloc the allocation that has been rescinded
077: * @return true if handled
078: * @see #needToRescind
079: * @see org.cougaar.lib.filter.UTILAllocatorPluginAdapter#needToRescind
080: */
081: boolean handleRescindedAlloc(Allocation alloc);
082:
083: /**
084: * Called when an allocation is removed from the cluster.
085: * I.e. an upstream cluster removed an allocation, and this
086: * has resulted in this allocation being removed.
087: *
088: * If the plugin maintains some local state of the availability
089: * of assets, it should update them here.
090: */
091: void handleRemovedAlloc(Allocation alloc);
092:
093: /**
094: * Default implementation automatically moves the
095: * reported allocation result (AR) to the estimated AR on a
096: * plan element that was previously allocated.
097: *
098: * Called when needToRescind returns FALSE.
099: *
100: * (This is the COUGAAR notification mechanism.)
101: *
102: * @param cpe the PlanElement that needs to be updated.
103: * @see #needToRescind
104: */
105: void updateAllocationResult(PlanElement cpe);
106:
107: /**
108: * What to do with a successful allocation.
109: * For implementers who DON'T extend UTILPluginAdapter,
110: * this is equivalent to updateAllocationResult and therefore
111: * should be implemented with an empty body.
112: *
113: * Called after updateAllocationResult when needToRescind returns FALSE.
114: * Implementers need to take into consideration that
115: * the asset chosen last time is not available this time.
116: *
117: * @param alloc the returned successful allocation
118: * @see #needToRescind
119: * @see org.cougaar.lib.filter.UTILAllocatorPluginAdapter#needToRescind
120: */
121: void handleSuccessfulAlloc(Allocation alloc);
122:
123: /**
124: * Public version of publishRemove
125: *
126: * Called when needToRescind returns TRUE.
127: *
128: * @param alloc the allocation to remove...
129: */
130: void publishRemovalOfAllocation(Allocation alloc);
131: }
|