001: /*
002: * <copyright>
003: *
004: * Copyright 2003-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: package org.cougaar.tools.csmart.experiment;
027:
028: import org.cougaar.tools.csmart.core.cdata.ComponentData;
029: import org.cougaar.tools.csmart.core.property.ModifiableComponent;
030: import org.cougaar.tools.csmart.core.db.DBConflictHandler;
031: import org.cougaar.tools.csmart.recipe.RecipeComponent;
032: import org.cougaar.tools.csmart.society.AgentComponent;
033: import org.cougaar.tools.csmart.society.SocietyComponent;
034:
035: import java.io.File;
036: import java.io.OutputStream;
037: import java.net.URL;
038: import java.util.List;
039: import java.util.Properties;
040: import java.awt.*;
041:
042: /**
043: * An Experiment, is a complete Host, Node, Agent, Component mapping
044: * containing all required runtime variables and components.
045: * A completed Experiment can be handed off to a COUGAAR node and
046: * run, with no additional parameters required.
047: *
048: */
049: public interface Experiment extends ModifiableComponent {
050: String EXPERIMENT_ID = "org.cougaar.experiment.id";
051: String PERSISTENCE_ENABLE = "org.cougaar.core.persistence.enable";
052: String PERSIST_CLEAR = "org.cougaar.core.persistence.clear";
053: String TIMEZONE = "user.timezone";
054: String AGENT_STARTTIME = "org.cougaar.core.agent.startTime";
055: String COMPLAININGLP_LEVEL = "org.cougaar.planning.ldm.lps.ComplainingLP.level";
056: // Used by AppServer
057: String CONTROL_PORT = "org.cougaar.control.port";
058:
059: String ENV_DISPLAY = "env.DISPLAY";
060: String BOOTSTRAP_CLASS = "java.class.name";
061: String NAME_SERVER = "org.cougaar.name.server";
062: String NODE_NAME = "org.cougaar.node.name";
063: /** When true, if CSMART dies, the society does not die **/
064: String AS_SWALLOW_ERRORS = "org.cougaar.tools.server.swallowOutputConnectionException";
065: /** Which initialization method should we use. DB means the CSMART DB **/
066: String INITIALIZER_PROP = "org.cougaar.core.node.InitializationComponent";
067:
068: // Default values:
069: String PERSISTENCE_DFLT = "false";
070: String PERSIST_CLEAR_DFLT = "true";
071: String TIMEZONE_DFLT = "GMT";
072: String AGENT_STARTTIME_DFLT = "08/10/2005";
073: String COMPLAININGLP_LEVEL_DFLT = "0";
074:
075: /** org.cougaar.control.port; port for contacting applications server **/
076: int APP_SERVER_DEFAULT_PORT = 8484;
077: String NAME_SERVER_PORTS = "8888:5555";
078: String DEFAULT_BOOTSTRAP_CLASS = "org.cougaar.bootstrap.Bootstrapper";
079: String DEFAULT_NODE_CLASS = "org.cougaar.core.node.Node";
080: String AS_SWALLOW_ERRORS_DFLT = "true";
081: String PROP_PREFIX = "PROP$";
082:
083: /**
084: * Adds a society, as a <code>SocietyComponent</code> to the experiment. A society contains
085: * a complete Node/Agent/Component mapping.
086: * Each experiment can only contain one Society. If a society already exists, an exception is
087: * thrown.
088: * @param sc The new society
089: * @throws IllegalArgumentException Exception is thrown if the experiment already contains a society.
090: */
091: void addSocietyComponent(SocietyComponent sc)
092: throws IllegalArgumentException;
093:
094: /**
095: * Removes the society component from the experiment.
096: */
097: void removeSocietyComponent();
098:
099: /**
100: * Returns a count of all societies in the experiment. Currently, the
101: * experiment can only have 1 society.
102: * @return count of societies within the experiment.
103: */
104: int getSocietyComponentCount();
105:
106: /**
107: * Gets the society component as a <code>SocietyCompoent</code> for this experiment.
108: * @return society component from this experiment. Or null, if one does not exist.
109: */
110: SocietyComponent getSocietyComponent();
111:
112: /**
113: * Sets the recipe components for this experiment.
114: * @param newRecipes array of <code>RecipeComponents</code> to apply to this experiment.
115: */
116: void setRecipeComponents(RecipeComponent[] newRecipes);
117:
118: /**
119: * Adds a specific recipe component to this experiment. If the recipe already exists in
120: * the experiment, an exception is thrown
121: * @param recipe New recipe component to add to the experiment.
122: * @throws IllegalArgumentException Exception is thrown if the experiment already contains this recipe.
123: */
124: void addRecipeComponent(RecipeComponent recipe)
125: throws IllegalArgumentException;
126:
127: /**
128: * Removed a specific recipe from the experiment.
129: * @param recipe The recipe to remove from the experiment.
130: */
131: void removeRecipeComponent(RecipeComponent recipe);
132:
133: /**
134: * Returns a count of the number of recipe components within this experiment.
135: * @return count of all recipe components.
136: */
137: int getRecipeComponentCount();
138:
139: /**
140: * Gets a specific <code>RecipeComponent</code> specified by the index it was stored.
141: * @param i - index of the recipe to retrieve.
142: * @return A <code>RecipeComponent</code> of the recipe found at the specified index.
143: * @throws IndexOutOfBoundsException Exception thrown if index out of bounds occurs.
144: */
145: RecipeComponent getRecipeComponent(int i)
146: throws IndexOutOfBoundsException;
147:
148: /**
149: * Gets an array of all <code>RecipeComponents</code> in this experiment.
150: * @return array of all recipe components.
151: */
152: RecipeComponent[] getRecipeComponents();
153:
154: /**
155: * Adds a component to the experiment. If the component is a society, and
156: * the experiment already contains a society, an exception is thrown. If the
157: * component is not a <code>SocietyComponent</code> or a <code>RecipeComponent</code>
158: * an exception is thrown.
159: * @param comp Component to add to the experiment.
160: * @throws IllegalArgumentException Expception if component known, or already exists.
161: */
162: void addComponent(ModifiableComponent comp)
163: throws IllegalArgumentException;
164:
165: /**
166: * Removes a specific component, specified as a <code>ModifiableComponent</code>.
167: * An exception is thrown if the Component to be removed is not a <code>SocietyComponent</code>
168: * or a <code>RecipeComponent</code>
169: * @param comp Component to remove from the experiment.
170: * @throws IllegalArgumentException Exception if the component is of unknown type.
171: */
172: void removeComponent(ModifiableComponent comp)
173: throws IllegalArgumentException;
174:
175: /**
176: * Returns a count of all components in the experiment.
177: * @return count of all components.
178: */
179: int getComponentCount();
180:
181: /**
182: * Returns all components on the experiment as a <code>ModifiableComponent</code> array.
183: * @return array of all components.
184: */
185: ModifiableComponent[] getComponentsAsArray();
186:
187: /**
188: * Returns a <code>List</code> of all components in the experiment.
189: * @return All components
190: */
191: List getComponents();
192:
193: /**
194: * Set the experiment running flag to true.
195: * @param newRunInProgress true if experiment is currently running, else false
196: */
197: void setRunInProgress(boolean newRunInProgress);
198:
199: /**
200: * Indicates if the current experiment is running.
201: * @return true if the current experiment is running, else false.
202: */
203: boolean isRunInProgress();
204:
205: /**
206: * Indicates that this experiment contains everything it needs to run.
207: * @return true if the experiment is ready to run, else false
208: */
209: boolean isRunnable();
210:
211: /**
212: * Set the experiment currently being edited flag.
213: * @param newEditInProgress true if the experiment is currently being edited, else false
214: */
215: void setEditInProgress(boolean newEditInProgress);
216:
217: /**
218: * Indicates if the experiment is currently being edited.
219: * @return true if the experiment is being edited, else false
220: */
221: boolean isEditInProgress();
222:
223: /**
224: * Stops the currently running experiment.
225: */
226: void stop();
227:
228: /**
229: * Stops the currently running experiment.
230: */
231: void experimentStopped();
232:
233: /**
234: * Gets all default node arguments.
235: * @return <code>Properties of all default node arguments.</code>
236: */
237: Properties getDefaultNodeArguments();
238:
239: /**
240: * Returns the results directory used by this experiment to store all collected results.
241: * @return <code>File</code> location to store results.
242: */
243: File getResultDirectory();
244:
245: /**
246: * Sets the directory to store all experiment results.
247: * @param resultDirectory <code>File</code> location to store results.
248: */
249: void setResultDirectory(File resultDirectory);
250:
251: /**
252: * Gets the current experiment name.
253: * @return Experiment name as a <code>String</code>
254: */
255: String getExperimentName();
256:
257: String toString();
258:
259: /**
260: * Copies this component, and returns a copy with the name specified.
261: * @param uniqueName name of the new Component.
262: * @return new <code>ModifiableComponent</code> copy of this component.
263: */
264: ModifiableComponent copy(String uniqueName);
265:
266: /**
267: * Gets the <code>URL</code> location of the description of this component.
268: * @return <code>URL</code> of description file.
269: */
270: URL getDescription();
271:
272: /**
273: * Initializes the properties of this component.
274: */
275: void initProperties();
276:
277: /**
278: * Gets the complete society component data specified as a <code>ComponentData</code> object.
279: * @return <code>ComponentData</code> of the complete society.
280: */
281: ComponentData getSocietyComponentData();
282:
283: /**
284: * Adds a new host to this experiment. An exception is thrown
285: * if the experiment already contains a host of the same name.
286: * @param name Name of the new host.
287: * @return <code>HostComponent</code> of the new host.
288: * @throws IllegalArgumentException Exception if the host is already defined in the experiment.
289: */
290: HostComponent addHost(String name) throws IllegalArgumentException;
291:
292: /**
293: * Returns an array of <code>HostComponent</code>s that are part of this experiment.
294: * @return Array of all hosts.
295: */
296: HostComponent[] getHostComponents();
297:
298: HostComponent[] getHostComponentsNoReconcile();
299:
300: /**
301: * Removes the specified host from the experiment.
302: * @param hostComponent Host to remove from the experiment.
303: */
304: void removeHost(HostComponent hostComponent);
305:
306: void renameHost(HostComponent hostComponent, String name)
307: throws IllegalArgumentException;
308:
309: void updateNameServerHostName();
310:
311: /**
312: * Adds a node to the experiment. If the experiment already contains a node
313: * of the same name, an exception is thrown.
314: * @param name Name of the new node.
315: * @return <code>NodeComponent</code> for the new node.
316: * @throws IllegalArgumentException Exception if the experiment already contains the node.
317: */
318: NodeComponent addNode(String name) throws IllegalArgumentException;
319:
320: /**
321: * Removes the specified node from the experiment.
322: * @param nc Node to remove from the experiment.
323: */
324: void removeNode(NodeComponent nc);
325:
326: /**
327: * Renames a node, in the <code>NodeComponent</code> to the new given name
328: * @param nc <code>NodeComponent</code> to be renamed.
329: * @param name New name of the node.
330: * @throws IllegalArgumentException
331: */
332: void renameNode(NodeComponent nc, String name)
333: throws IllegalArgumentException;
334:
335: /**
336: * Gets an <code>NodeComponent</code> array of all nodes in this experiment.
337: * @return An array of all nodes in the experiment.
338: */
339: NodeComponent[] getNodeComponents();
340:
341: /**
342: * Determines if the given agent name is unique within this experiment.
343: * @param name Name of agent to check for uniqueness
344: * @return true if the agent is unique, else false.
345: */
346: boolean agentNameUnique(String name);
347:
348: /**
349: * Returns a <code>List</code> of all the agents in this experiment.
350: * @return a <code>List</code> of all agents
351: */
352: List getAgentsList();
353:
354: /**
355: * Gets an <code>AgentComponent</code> array of all agents in this experiment.
356: * @return An array of all agents in the experiment.
357: */
358: AgentComponent[] getAgents();
359:
360: /**
361: * Dumps INI files for the current experiment.
362: */
363: void dumpINIFiles();
364:
365: /**
366: * Dumps an HNA mapping.
367: */
368: void dumpHNA();
369:
370: boolean hasConfiguration();
371:
372: void createDefaultConfiguration();
373:
374: /**
375: * Indicates if the current experiment has been modified.
376: * @return true if the current experiment has been modified, else false
377: */
378: boolean isModified();
379:
380: /**
381: * Resets the modified flag.
382: */
383: void resetModified();
384:
385: /**
386: * Gets the trial id for this experiment, if one exists.
387: *
388: * @return current trial Id, or null if one doesn't exist.
389: */
390: public String getTrialID();
391:
392: /**
393: * get the local variable idea of the community assembly for this
394: * experiment, possibly null
395: *
396: * @return assembly ID for community data, possibly null
397: */
398: public String getCommAsbID();
399:
400: /**
401: * (Re) set the local variables idea of the community assembly for
402: * this experiment, possibly to null
403: */
404: public void setCommAsbID(String id);
405:
406: /**
407: * Sets the name of this Experiment.
408: * @param name Name of this experiment
409: */
410: void setName(String name);
411:
412: /**
413: * Sets the Experiment Id for this experiment.
414: *
415: * @param expID current experiment id
416: */
417: public void setExperimentID(String expID);
418:
419: /**
420: * Experiment ID is used by database societies only.
421: *
422: * @return The ExperimentID, if one exists, else null.
423: */
424: public String getExperimentID();
425:
426: /**
427: * Imports an HNA mapping into the experiment. This
428: * method is only relevant for database experiments. Experiments
429: * from XML already contain their own HNA mapping.
430: *
431: * @param parent Component containing the HNA mapping.
432: */
433: public void importHNA(Component parent);
434:
435: /**
436: * Saves the current Experiment. If the Experiment Instance is
437: * a database instance <code>DBExperiment</code>. The experiment is
438: * saved to the database.
439: * Currently, Saving of an XMLExperiment is not implemented.
440: * @param handler Database conflict handler. This handler is only
441: * used for <code>DBExperiment</code> instances. All others
442: * ignore it.
443: */
444: public void save(DBConflictHandler handler);
445:
446: }
|