Java Doc for UTILExpansionListener.java in  » Science » Cougaar12_4 » org » cougaar » lib » callback » Java Source Code / Java DocumentationJava Source Code and Java Documentation

 Listener intended to be used by all expanders.
 Being an expansion listener now means participating in a 4 step process.
 When an expansion changes, it can change in one of 4 ways, each of which the 
 the listener can play a role in.
 Note that below, when default behavior is mentioned, it is in ExpanderPluginAdapter.
 1) The expansion can fail.  (handleFailedExpansion)
 Some downstream allocation can fail, and if this happens, the listener will
 be called with the expansion and the list of failed sub tasks.  
 The listener can handle this in one of two ways :
 a) rescind the expansion and replan and reallocate OR
 b) give up and report the failed expansion to a superior.  An example of this
 approach is in UTILSimpleExpanderPlugin
 Since this is important, THERE IS NO DEFAULT BEHAVIOR for this option.
 2) The expansion's constraints may be violated.  (handleConstraintViolation)
 No allocation failed, but a workflow constraint was violated.  E.g. Task A is supposed
 to come before task B, but it wasn't allocated that way.  If this happens, the 
 listener will be called with the expansion and the list of failed constraints.  
 The listener can handle this in one of two ways :
 a) rescind the expansion and replan and reallocate OR
 b) give up and report the expansion to a superior.
 This doesn't happen very often, so the default behavior is to throw an exception.
 3) The expansion is not good enough, in some way.  (wantToChangeExpansion, 
 handleChangedExpansion, publishChangedExpansion)
 No allocation failed, no workflow constraint was violated, but perhaps the aggregate score
 of all the allocated subtasks was above some threshold.  First the listener is asked if
 it wants to change the expansion, and if so, handleChangedExpansion gets called.  Finally,
 publishChangeExpansion is called.
 The listener can handle this in the same way as case #1.
 Default behavior is not to want to change the expansion.
 4) The expansion is fine.  (reportChangedExpansion)
 Everything is fine with the expansion, and the listener is asked to report the results
 of the expansion to its superior.
 The listener can handle this by simply reporting the changed expansion by calling
 updateAllocationResult.
 Default behavior is to do this.  
 Allocators should use/be a GenericListener.