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.planning.ldm.plan;
028:
029: import java.util.Collection;
030: import java.util.Date;
031: import java.util.Enumeration;
032: import java.util.List;
033:
034: import org.cougaar.core.mts.MessageAddress;
035: import org.cougaar.core.util.UID;
036: import org.cougaar.planning.ldm.asset.Asset;
037: import org.cougaar.planning.ldm.policy.Policy;
038: import org.cougaar.util.TimeSpan;
039:
040: /**
041: * Top-level Factory for Cluster Objects which can be created by Plugins
042: * of various sorts.
043: * While we do not subset these interfaces at this time, one should
044: * keep in mind that a given component may choose to both
045: * restrict access to (by throwing exceptions) these accessors and to
046: * choose how these objects actually get realized.
047: *
048: * The majority of the factory methods are of the form <em> NewFoo newFoo() </em>
049: * where <em> Foo </em> is the basic type to be constructed. The
050: * Return value is always an Interface type which extends the basic
051: * type with set-methods and other methods useful for constructing
052: * objects of this basic type.
053: *
054: * There a few factory methods that return a completed or built object.
055: * These methods usually take arguments that are used to build the object.
056: * The Interface return type are usually not the extending interfaces which
057: * contain set-methods (since the object has already been built).
058: *
059: */
060: public interface ClusterObjectFactory {
061:
062: NewAlert newAlert();
063:
064: NewAlertParameter newAlertParameter();
065:
066: NewAssetAssignment newAssetAssignment();
067:
068: NewComposition newComposition();
069:
070: NewConstraint newConstraint();
071:
072: NewAssignedRelationshipElement newAssignedRelationshipElement();
073:
074: NewAssignedRelationshipElement newAssignedRelationshipElement(
075: Asset assetA, Role roleA, Asset assetB, long startTime,
076: long endTime);
077:
078: NewAssignedRelationshipElement newAssignedRelationshipElement(
079: Relationship relationship);
080:
081: NewAssignedAvailabilityElement newAssignedAvailabilityElement();
082:
083: NewAssignedAvailabilityElement newAssignedAvailabilityElement(
084: Asset assignee, long startTime, long endTime);
085:
086: NewItineraryElement newItineraryElement();
087:
088: NewLocationRangeScheduleElement newLocationRangeScheduleElement();
089:
090: NewLocationScheduleElement newLocationScheduleElement();
091:
092: NewMPTask newMPTask();
093:
094: NewNotification newNotification();
095:
096: NewDeletion newDeletion();
097:
098: NewAssetVerification newAssetVerification();
099:
100: NewAssetVerification newAssetVerification(Asset asset,
101: Asset assignee, Schedule schedule);
102:
103: Policy newPolicy(String policyType);
104:
105: /** construct a skeleton PrepositionalPhrase **/
106: NewPrepositionalPhrase newPrepositionalPhrase();
107:
108: /** construct a complete PrepositionalPhrase **/
109: PrepositionalPhrase newPrepositionalPhrase(String preposition,
110: Object indirectObject);
111:
112: NewReport newReport();
113:
114: NewScheduleElement newScheduleElement(Date start, Date end);
115:
116: NewTask newTask();
117:
118: NewTask newTask(UID uid);
119:
120: NewTransferableAssignment newTransferableAssignment();
121:
122: NewTransferableTransfer newTransferableTransfer();
123:
124: NewTransferableRescind newTransferableRescind();
125:
126: NewTransferableVerification newTransferableVerification(
127: Transferable t);
128:
129: NewWorkflow newWorkflow();
130:
131: /** Low-level task duplication. Tasks created by this method are
132: * not suitable for use as blackboard Objects. This method should
133: * only be called by networking infrastructure.
134: **/
135: NewTask shadowTask(Task t);
136:
137: //
138: // Methods that return built or complete objects
139: //
140:
141: /** Build a new TransferableTransfer
142: * @param aTransferable
143: * @param anAsset - should be of type Organization
144: * @return TranserableTransfer
145: */
146: TransferableTransfer createTransferableTransfer(
147: Transferable aTransferable, Asset anAsset);
148:
149: /** Build a new AssetTransfer (planelement)
150: * @param aPlan The Plan this PlanElement is against
151: * @param aTask The Task being disposed
152: * @param anAsset The Asset that is being transferred
153: * @param aSchedule The Schedule that represents the time window the Asset will be transferred
154: * for
155: * @param toAsset The Asset to which the transferred Asset is being
156: * transferred. Must have a ClusterPG
157: * @param estimatedresult - allowed to be null
158: * @param aRole The Role of the Asset while transferred
159: * @return AssetTransfer
160: **/
161: AssetTransfer createAssetTransfer(Plan aPlan, Task aTask,
162: org.cougaar.planning.ldm.asset.Asset anAsset,
163: Schedule aSchedule,
164: org.cougaar.planning.ldm.asset.Asset toAsset,
165: AllocationResult estimatedresult, Role aRole);
166:
167: /** Build a new Allocation (planelement)
168: * @param aPlan - The Plan this PlanElement is against
169: * @param aTask - The Task being disposed
170: * @param anAsset - The Asset that the task is being assigned to.
171: * @param estimatedresult - allowed to be null
172: * @param aRole - The role of the Asset while performing this Task.
173: * @see org.cougaar.planning.ldm.asset.Asset
174: * @see org.cougaar.planning.ldm.plan.AllocationResult
175: **/
176: Allocation createAllocation(Plan aPlan, Task aTask,
177: org.cougaar.planning.ldm.asset.Asset anAsset,
178: AllocationResult estimatedresult, Role aRole);
179:
180: /** Build a new Expansion (planelement)
181: * @param aPlan
182: * @param aTask
183: * @param aWorkflow
184: * @param estimatedresult -allowed to be null
185: * @return Expansion
186: * @see org.cougaar.planning.ldm.plan.Workflow
187: * @see org.cougaar.planning.ldm.plan.AllocationResult
188: */
189: Expansion createExpansion(Plan aPlan, Task aTask,
190: Workflow aWorkflow, AllocationResult estimatedresult);
191:
192: /** Build a new Aggregation (planelement)
193: * @param aPlan
194: * @param aTask
195: * @param aComposition
196: * @param estimatedresult -allowed to be null
197: * @return Aggregation
198: * @see org.cougaar.planning.ldm.plan.Composition
199: * @see org.cougaar.planning.ldm.plan.AllocationResult
200: */
201:
202: Aggregation createAggregation(Plan aPlan, Task aTask,
203: Composition aComposition, AllocationResult estimatedresult);
204:
205: /** Build a new FailedDisposition (planelement)
206: * @param aPlan
207: * @param aTask
208: * @param failure
209: * @return a Failed Disposition
210: * @see org.cougaar.planning.ldm.plan.AllocationResult
211: */
212:
213: Disposition createFailedDisposition(Plan aPlan, Task aTask,
214: AllocationResult failure);
215:
216: /** Build a new Disposition
217: * @return a Disposition
218: * @see org.cougaar.planning.ldm.plan.AllocationResult
219: */
220: Disposition createDisposition(Plan aPlan, Task aTask,
221: AllocationResult result);
222:
223: /** Build a new simple schedule that contains only one start and end
224: * date.
225: * @param start - The start Date of the schedule
226: * @param end - the end or finish Date of the schedule
227: * @return Schedule - a schedule object containing one scheduleelement
228: * @see java.util.Date
229: **/
230: NewSchedule newSimpleSchedule(Date start, Date end);
231:
232: /** Build a new simple schedule that contains only one start and end
233: * date.
234: * @param startTime - The start time of the schedule
235: * @param endTime - the end or finish time of the schedule
236: * @return Schedule - a schedule object containing one scheduleelement
237: * @see java.util.Date
238: **/
239: NewSchedule newSimpleSchedule(long startTime, long endTime);
240:
241: /** Create an assigned relationship schedule. This schedule is a container
242: * of AssignedRelationshipElements. Should only be used by logic providers
243: * in handling new/modified/removed AssetTransfers.
244: * @param elements Enumeration{AssignedRelationshipElement}
245: * @see org.cougaar.planning.ldm.plan.AssignedRelationshipElement
246: **/
247: NewSchedule newAssignedRelationshipSchedule(Enumeration elements);
248:
249: /** Create an empty assigned relationship schedule. Schedule elements added
250: * later must be AssignedRelationshipElements. Should only be used by logic
251: * providers in handling new/modified/removed AssetTransfers.
252: * @see org.cougaar.planning.ldm.plan.AssignedRelationshipElement
253: **/
254: NewSchedule newAssignedRelationshipSchedule();
255:
256: /** Build an asset transfer availabity schedule.
257: * @param availElements Enumeration{AssignedAvailabilityElement}
258: * @see org.cougaar.planning.ldm.plan.AssignedAvailabilityElement
259: **/
260: NewSchedule newAssignedAvailabilitySchedule(
261: Enumeration availElements);
262:
263: /** Build a an asset transfer availabity schedule
264: * @see org.cougaar.planning.ldm.plan.AssignedAvailabilityElement
265: **/
266: NewSchedule newAssignedAvailabilitySchedule();
267:
268: /** Create a location schedule. This schedule is a container of
269: * LocationScheduleElements.
270: * @param locationElements Enumeration{LocationScheduleElement}
271: * @see org.cougaar.planning.ldm.plan.LocationScheduleElement
272: **/
273: NewSchedule newLocationSchedule(Enumeration locationElements);
274:
275: /** Create a location range schedule. This schedule is a container
276: * of LocationRangeScheduleElements.
277: * @param locationRangeElements Enumeration{LocationRangeScheduleElement}
278: * @see org.cougaar.planning.ldm.plan.LocationRangeScheduleElement
279: **/
280: NewSchedule newLocationRangeSchedule(
281: Enumeration locationRangeElements);
282:
283: /** Create a schedule that contains different types of scheduleelements.
284: * Note that ScheduleElement has multiple subclasses which are excepted.
285: * @param scheduleElements Enumeration{ScheduleElement}
286: * @see org.cougaar.planning.ldm.plan.ScheduleElement
287: **/
288: NewSchedule newSchedule(Enumeration scheduleElements);
289:
290: /**
291: * newRelationship - returns a Relationship
292: *
293: * @param role1 Role for object1
294: * @param object1 HasRelationships which has role1
295: * @param object2 HasRelationships which is the other half of the
296: * relationship, role set at role1.getConverse()
297: * @param timeSpan TimeSpan for which the relationship is valid
298: */
299: Relationship newRelationship(Role role1, HasRelationships object1,
300: HasRelationships object2, TimeSpan timeSpan);
301:
302: /**
303: * newRelationship - returns a Relationship
304: *
305: * @param role1 Role for object1
306: * @param object1 HasRelationships which has role1
307: * @param object2 HasRelationships which is the other half of the
308: * relationship, role set at role1.getConverse()
309: * @param startTime long which specifies the start of the relationship
310: * @param endTime long which specifies the end of the relationship.
311: * @see org.cougaar.util.TimeSpan
312: */
313: Relationship newRelationship(Role role1, HasRelationships object1,
314: HasRelationships object2, long startTime, long endTime);
315:
316: /**
317: * newRelationship - returns a Relationship based on the specified
318: * AssignedRelationshipElement. Specified assets must match the
319: * item identifications in the AssignedRelationshipElement
320: *
321: * @param assignedRelationship AssignedRelationshipElement
322: * @param asset1 Asset to be used in converting the
323: * AssignedRelationshipElement
324: * @param asset2 Asset other asset to be used in converting the
325: * AssignedRelationshipElement
326: */
327: Relationship newRelationship(
328: AssignedRelationshipElement assignedRelationship,
329: Asset asset1, Asset asset2);
330:
331: /** Build an empty relationship schedule for the specified HasRelationships.
332: * @param hasRelationships HasRelationships to which the relationship
333: * schedule will apply
334: **/
335: NewRelationshipSchedule newRelationshipSchedule(
336: HasRelationships hasRelationships);
337:
338: /** Build a new relationship schedule for the specified HasRelationships.
339: * @param hasRelationships HasRelationships to which the relationship
340: * schedule applies. N.B. hasRelationships must be included in all the
341: * Relationships on the schedule.
342: * @param relationships Collection of Relationships for the specified
343: * HasRelationships.
344: **/
345: NewRelationshipSchedule newRelationshipSchedule(
346: HasRelationships hasRelationships, Collection relationships);
347:
348: /**@param v - Pass a valid string representation of the Verb
349: * @return Verb
350: * @see org.cougaar.planning.ldm.plan.Verb for a list of valid values
351: * @deprecated use Verb constructor.
352: **/
353: Verb getVerb(String v);
354:
355: /** Build a TaskRescind Message. This message is only sent by
356: * CCRescind - NOT PLUGINS!!!.
357: * The deleted status is taken from the task
358: * @param task - The Task to be rescinded
359: * @param destination - The Cluster to send the TaskRescind Message to.
360: * @return TaskRescind
361: **/
362: TaskRescind newTaskRescind(Task task, MessageAddress destination);
363:
364: /** Build a TaskRescind Message. This message is only sent by
365: * CCRescind - NOT PLUGINS!!!.
366: * The deleted status is assumed to be false
367: * @param taskUID - The UID of the Task to be rescinded
368: * @param destination - The Cluster to send the TaskRescind Message to.
369: * @return TaskRescind
370: **/
371: TaskRescind newTaskRescind(UID taskUID, MessageAddress destination);
372:
373: /** Build a TaskRescind Message. This message is only sent by
374: * CCRescind - NOT PLUGINS!!!.
375: * The deleted status is explicitly specifed by the deleted parameter
376: * @param taskUID - The UID of the Task to be rescinded
377: * @param destination - The Cluster to send the TaskRescind Message to.
378: * @param deleted - Mark the TaskRescind as referring to a deleted task.
379: * @return TaskRescind
380: **/
381: TaskRescind newTaskRescind(UID taskUID, MessageAddress destination,
382: boolean deleted);
383:
384: /** Build an AssetRescind Message. This message is only sent by
385: * CCRescind - NOT PLUGINS!!!.
386: * @param asset - The Asset to be rescinded
387: * @param rescindeeAsset - Asset from which asset will be rescinded
388: * @param rescindSchedule - Schedule for which the asset is rescinded
389: * @return AssetRescind
390: **/
391: AssetRescind newAssetRescind(
392: org.cougaar.planning.ldm.asset.Asset asset,
393: org.cougaar.planning.ldm.asset.Asset rescindeeAsset,
394: Schedule rescindSchedule);
395:
396: /** Create a new NON-PHASE AllocationResult
397: * @param rating The confidence rating of this result.
398: * @param success Whether the allocationresult violated any preferences.
399: * @param aspecttypes The AspectTypes (and order) of the results.
400: * @param result The value for each aspect.
401: * @return AllocationResult A new AllocationResult
402: * @deprecated Use #newAllocationResult(double,boolean,AspectValue[]);
403: */
404: AllocationResult newAllocationResult(double rating,
405: boolean success, int[] aspecttypes, double[] result);
406:
407: /** Create a new NON-PHASE AllocationResult
408: * @param rating The confidence rating of this result.
409: * @param success Whether the allocationresult violated any preferences.
410: * @param avrs The AspectValues of the result.
411: * @return AllocationResult A new AllocationResult
412: */
413: AllocationResult newAllocationResult(double rating,
414: boolean success, AspectValue[] avrs);
415:
416: /** Create a new PHASED AllocationResult instance.
417: * @param rating The confidence rating of this result.
418: * @param success Whether the allocationresult violated any preferences.
419: * @param aspecttypes The AspectTypes (and order) of the results.
420: * @param rollup The summary values for each aspect.
421: * @param allresults An Enumeration of Vectors representing
422: * each phased collection of results.
423: * For Example a phased answer may look like
424: * [ [10, 100.00, c0], [5, 50.00, c3], [5, 50.00, c6] ]
425: * @return AllocationResult
426: * @deprecated use #newPhasedAllocationResult(double,boolean,AspectValue[],Collection)
427: */
428: AllocationResult newPhasedAllocationResult(double rating,
429: boolean success, int[] aspecttypes, double[] rollup,
430: Enumeration allresults);
431:
432: /** Create a new PHASED AllocationResult instance.
433: * @param rating The confidence rating of this result.
434: * @param success Whether the allocationresult violated any preferences.
435: * @param rollup The summary values for each aspect as AspectValues.
436: * @param allresults An Enumeration of Vectors representing
437: * each phased collection of results.
438: * For Example a phased answer may look like
439: * [ [10, 100.00, c0], [5, 50.00, c3], [5, 50.00, c6] ]
440: * @return AllocationResult
441: */
442: AllocationResult newPhasedAllocationResult(double rating,
443: boolean success, AspectValue[] rollup,
444: Enumeration allresults);
445:
446: /** Create a new AllocationResult that takes a PHASED result in the form of AspectValues.
447: * Subclasses of AspectValue, such as TypedQuantityAspectValue are allowed.
448: * @param rating The confidence rating of this result.
449: * @param success Whether the allocationresult violated any preferences.
450: * @param rollupavs The Summary (or rolled up) AspectValues that represent the results.
451: * @param phasedresults A Collection of the phased results. The Collection
452: * must contain one Collection or Array of AspectValues for each phase of the results.
453: * @return AllocationResult
454: */
455: AllocationResult newPhasedAllocationResult(double rating,
456: boolean success, AspectValue[] rollupavs,
457: Collection phasedresults);
458:
459: /**
460: * @deprecated use #newPhasedAllocationResult(double,boolean,AspectValue[],Collection)
461: */
462: AllocationResult newAVPhasedAllocationResult(double rating,
463: boolean success, AspectValue[] rollupavs,
464: Collection phasedresults);
465:
466: /** @deprecated use #newAllocationResult(double,boolean,AspectValue[]);
467: */
468: AllocationResult newAVAllocationResult(double rating,
469: boolean success, AspectValue[] aspectvalues);
470:
471: /** Create a new Preference.
472: * @param aspecttype The AspectType this preference is about.
473: * @param scorefunction The function that defines the scoring curve
474: * @see org.cougaar.planning.ldm.plan.AspectType
475: * @see org.cougaar.planning.ldm.plan.ScoringFunction
476: * @return Preference
477: */
478: Preference newPreference(int aspecttype,
479: ScoringFunction scorefunction);
480:
481: /** Create a new Preference with a weight.
482: * @param aspecttype The AspectType this preference is about.
483: * @param scorefunction The function that defines the scoring curve
484: * @param aweight The weight of the preference - must be between 0.0 - 1.0
485: * @see org.cougaar.planning.ldm.plan.AspectType
486: * @see org.cougaar.planning.ldm.plan.ScoringFunction
487: * @return Preference
488: */
489: Preference newPreference(int aspecttype,
490: ScoringFunction scorefunction, double aweight);
491:
492: /** Create a new BulkEstimate
493: * @param atask The Task to test allocations against preference sets
494: * @param prefsets A List containing Preference[] represening the preference sets.
495: * @param conf The confidence rating the allocation results should reach before returning final results
496: * @return BulkEstimate
497: */
498: BulkEstimate newBulkEstimate(Task atask, List prefsets, double conf);
499:
500: //
501: // Special constructors
502: //
503:
504: /** Return a reference to the the plan object which represents
505: * "reality" in this cluster.
506: **/
507: Plan getRealityPlan();
508:
509: MessageAddress getMessageAddress();
510:
511: }
|