| 1 | package desmoj.core.simulator; |
| 2 | |
| 3 | import java.util.List; |
| 4 | |
| 5 | import desmoj.core.report.DebugNote; |
| 6 | import desmoj.core.report.ErrorMessage; |
| 7 | import desmoj.core.report.Message; |
| 8 | import desmoj.core.report.TraceNote; |
| 9 | |
| 10 | /** |
| 11 | * Encapsulates all information relevant to each component of a model. Its basic |
| 12 | * intention is to connect each modelcomponent to a single Model object as the |
| 13 | * owner of this modelcomponent. Through this connection all relevant |
| 14 | * information about that Model can be retrieved. It is part of the composite |
| 15 | * design pattern as described in [Gamm97] page 163 in which it represents the |
| 16 | * component class. |
| 17 | * |
| 18 | * @version DESMO-J, Ver. 2.3.3 copyright (c) 2011 |
| 19 | * @author Tim Lechler |
| 20 | * |
| 21 | * Licensed under the Apache License, Version 2.0 (the "License"); you |
| 22 | * may not use this file except in compliance with the License. You may |
| 23 | * obtain a copy of the License at |
| 24 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 25 | * |
| 26 | * Unless required by applicable law or agreed to in writing, software |
| 27 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 28 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or |
| 29 | * implied. See the License for the specific language governing |
| 30 | * permissions and limitations under the License. |
| 31 | * |
| 32 | */ |
| 33 | public class ModelComponent extends NamedObject { |
| 34 | |
| 35 | /** |
| 36 | * The reference to the model that this modelcomponent belongs to. |
| 37 | */ |
| 38 | private Model _owner; |
| 39 | |
| 40 | /** |
| 41 | * Flag indicating if this modelcomponent should be listed in the trace |
| 42 | * output file. |
| 43 | */ |
| 44 | private boolean _traceMode; |
| 45 | |
| 46 | /** |
| 47 | * Flag indicating if this modelcomponent should be listed in the debug |
| 48 | * output file. |
| 49 | */ |
| 50 | private boolean _debugMode; |
| 51 | |
| 52 | /** |
| 53 | * Constructs a modelcomponent with the given String as name and the given |
| 54 | * model as the associated owner of this component. Components can only be |
| 55 | * created after the corresponding model object has been instantiated. The |
| 56 | * default preset for the showInTrace option is <code>false</code>. |
| 57 | * |
| 58 | * @param name |
| 59 | * java.lang.String : The name of the component |
| 60 | * @param ownerModel |
| 61 | * Model : The model this component is associated to. |
| 62 | */ |
| 63 | public ModelComponent(Model ownerModel, String name) { |
| 64 | |
| 65 | // create a ModelComponent with the given name and no trace output |
| 66 | this(ownerModel, name, false); |
| 67 | } |
| 68 | |
| 69 | /** |
| 70 | * Constructs a modelcomponent with the given String as name and the given |
| 71 | * model as the associated owner of this component. Components can thus only |
| 72 | * be created after the corresponding model object has been instantiated. |
| 73 | * |
| 74 | * @param name |
| 75 | * java.lang.String : The name of the component |
| 76 | * @param ownerModel |
| 77 | * Model : The model this component is associated to |
| 78 | * @param showInTrace |
| 79 | * boolean : Flag for showing component in trace-files. Set it to |
| 80 | * <code>true</code> if component should show up in trace. Set it |
| 81 | * to <code>false</code> if component should not be shown in |
| 82 | * trace. |
| 83 | */ |
| 84 | public ModelComponent(Model ownerModel, String name, boolean showInTrace) { |
| 85 | |
| 86 | super(name); // create the namedObject with given name |
| 87 | _owner = ownerModel; // set the owner of this component |
| 88 | _traceMode = showInTrace; // set the tracemode for this component |
| 89 | |
| 90 | } |
| 91 | |
| 92 | /** |
| 93 | * Returns the currently active Schedulable object that is handled by the |
| 94 | * scheduler. |
| 95 | * |
| 96 | * @return Schedulable : The current Schedulable object. |
| 97 | */ |
| 98 | public Schedulable current() { |
| 99 | |
| 100 | return _owner.getExperiment().getScheduler().getCurrentSchedulable(); |
| 101 | |
| 102 | } |
| 103 | |
| 104 | /** |
| 105 | * Returns the currently active Entity. Returns <code>null</code> if the current |
| 106 | * Schedulable happens to be an external event or a sim-process. |
| 107 | * Note that in case the current Event refers to more than one entity |
| 108 | * (<code>EventTwoEntitties</code>, <code>EventThreeEntitties</code>), |
| 109 | * only the first entity is returned; to obtain all such entities, |
| 110 | * use <code>getAllCurrentEntities()</code> instead. |
| 111 | * |
| 112 | * @return Entity : The currently active Entity or |
| 113 | * <code>null</code> in case of an external event or a sim-process |
| 114 | * being the currently active Schedulable |
| 115 | */ |
| 116 | public Entity currentEntity() { |
| 117 | |
| 118 | return _owner.getExperiment().getScheduler().getCurrentEntity(); |
| 119 | |
| 120 | } |
| 121 | |
| 122 | /** |
| 123 | * Returns the currently active entities. Returns an empty list |
| 124 | * if the current Schedulable happens to be an external event or a sim-process. |
| 125 | * |
| 126 | * @return List<Entity> : A list containing the currently active entities |
| 127 | */ |
| 128 | public List<Entity> currentEntityAll() { |
| 129 | |
| 130 | return _owner.getExperiment().getScheduler().getAllCurrentEntities(); |
| 131 | |
| 132 | } |
| 133 | |
| 134 | /** |
| 135 | * Returns the currently active Event that is handled by the scheduler. It |
| 136 | * returns <code>null</code> if a process Event is the current active |
| 137 | * Schedulable, thus no Event is active. |
| 138 | * |
| 139 | * @return Event : The current active Event or <code>null</code> if the |
| 140 | * current active Schedulable is a process |
| 141 | * |
| 142 | */ |
| 143 | public EventAbstract currentEvent() { |
| 144 | |
| 145 | return _owner.getExperiment().getScheduler().getCurrentEvent(); |
| 146 | |
| 147 | } |
| 148 | |
| 149 | /** |
| 150 | * Returns the model that the currently active Event or Entity handled by |
| 151 | * the scheduler belongs to or the main model connected to the experiment, |
| 152 | * if no model can be returned by the scheduler. |
| 153 | * |
| 154 | * @return Model : The current active or the main model connected to the |
| 155 | * experiment, if no model can be returned by the scheduler |
| 156 | */ |
| 157 | public Model currentModel() { |
| 158 | |
| 159 | Model mBuff = _owner.getExperiment().getScheduler().getCurrentModel(); |
| 160 | |
| 161 | if (mBuff != null) |
| 162 | return mBuff; |
| 163 | else |
| 164 | return _owner.getExperiment().getModel(); |
| 165 | |
| 166 | } |
| 167 | |
| 168 | /** |
| 169 | * Returns the currently active SimProcess that is handled by the scheduler. |
| 170 | * |
| 171 | * @return SimProcess : The current active SimProcess. |
| 172 | */ |
| 173 | public SimProcess currentSimProcess() { |
| 174 | |
| 175 | return _owner.getExperiment().getScheduler().getCurrentSimProcess(); |
| 176 | |
| 177 | } |
| 178 | |
| 179 | /** |
| 180 | * @deprecated Replaced by presentTime(). Returns the current simulation |
| 181 | * time as displayed by the simulation clock responsible for |
| 182 | * this modelcomponent. |
| 183 | * |
| 184 | * @return SimTime : The current simulation time |
| 185 | */ |
| 186 | @Deprecated |
| 187 | public SimTime currentTime() { |
| 188 | return SimTime.toSimTime(_owner.getExperiment().getSimClock() |
| 189 | .getTime()); |
| 190 | } |
| 191 | |
| 192 | /** |
| 193 | * Returns the current simulation time as displayed by the simulation clock |
| 194 | * responsible for this modelcomponent. |
| 195 | * |
| 196 | * @return TimeInstant : The current point of simulation time |
| 197 | */ |
| 198 | public TimeInstant presentTime() { |
| 199 | return _owner.getExperiment().getSimClock().getTime(); |
| 200 | } |
| 201 | |
| 202 | /** |
| 203 | * Shows if this modelcomponent currently produces debug output. |
| 204 | * |
| 205 | * @return boolean : true, if modelcomponent shows in debug, false if not |
| 206 | */ |
| 207 | public boolean debugIsOn() { |
| 208 | |
| 209 | return _debugMode; // has anybody ever returned from a debugMode... |
| 210 | |
| 211 | } |
| 212 | |
| 213 | /** |
| 214 | * Switches off debug output for this modelcomponent. Does nothing if trace |
| 215 | * is already switched off. |
| 216 | */ |
| 217 | public void debugOff() { |
| 218 | |
| 219 | _debugMode = false; // yep, that's it! |
| 220 | |
| 221 | } |
| 222 | |
| 223 | /** |
| 224 | * Switches on debug output for this modelcomponent. Does nothing if debug |
| 225 | * is already switched on. |
| 226 | */ |
| 227 | public void debugOn() { |
| 228 | |
| 229 | _debugMode = true; // yep, that's true! |
| 230 | |
| 231 | } |
| 232 | |
| 233 | /** |
| 234 | * @deprecated Use TimeOperations.getEpsilon(). |
| 235 | * Returns the minimum distinguishable span of simulation time for this |
| 236 | * experiment. |
| 237 | * |
| 238 | * @return SimTime : The minimum ditinguishable span of simulation time |
| 239 | */ |
| 240 | public SimTime epsilon() { |
| 241 | |
| 242 | return SimTime.toSimTime(new TimeSpan(1L, TimeOperations.getEpsilon())); |
| 243 | |
| 244 | } |
| 245 | |
| 246 | /** |
| 247 | * Returns the model that owns this component. |
| 248 | * |
| 249 | * @return Model : The model that this component is associated to |
| 250 | */ |
| 251 | public Model getModel() { |
| 252 | |
| 253 | return _owner; // "Make all things as simple as possible : but not |
| 254 | // simpler!" |
| 255 | // Albert Einstein |
| 256 | |
| 257 | } |
| 258 | |
| 259 | /** |
| 260 | * Tests if the modelcomponent given as parameter is a component of the same |
| 261 | * experiment as this modelcomponent. |
| 262 | * |
| 263 | * @return boolean : true, if this modelcomponent belongs to the same |
| 264 | * experiment as this modelcomponent, false otherwise |
| 265 | * @param other |
| 266 | * ModelComponent : the other modelcomponent to check |
| 267 | * compatibility with |
| 268 | */ |
| 269 | public boolean isExperimentCompatible(ModelComponent other) { |
| 270 | |
| 271 | // Checks if this modelcomponent has same experiment as other |
| 272 | // modelcomponent |
| 273 | return (_owner.getExperiment() == other.getModel().getExperiment()); |
| 274 | |
| 275 | } |
| 276 | |
| 277 | /** |
| 278 | * Tests if the modelcomponent given as parameter is a component of the same |
| 279 | * model as this modelcomponent. |
| 280 | * |
| 281 | * @return boolean :<code>true</code>, if this modelcomponent belongs to the |
| 282 | * same model as the given modelcomponent, <code>false</code> |
| 283 | * otherwise |
| 284 | * @param other |
| 285 | * ModelComponent : the other modelcomponent to check |
| 286 | * compatibility with |
| 287 | */ |
| 288 | public boolean isModelCompatible(ModelComponent other) { |
| 289 | |
| 290 | // since checking for compatibility is the models's responsibility, |
| 291 | // we just pass checking on to our owner. |
| 292 | return _owner.checkCompatibility(other); |
| 293 | |
| 294 | } |
| 295 | |
| 296 | /** |
| 297 | * Creates and sends a debugnote to the experiment's messagedistributor. |
| 298 | * Debugnotes express the internal state of a modelcomponent to visualize |
| 299 | * the changes of state to help find bugs. Classes <code>Scheduler</code> |
| 300 | * and <code>Queue</code> both produce debugnotes if set to do so |
| 301 | * representing the data stored inside them. The information about the |
| 302 | * simulation time is extracted from the experiment and must not be given as |
| 303 | * a parameter. |
| 304 | * |
| 305 | * @param description |
| 306 | * java.lang.String : The description of a modelcomponent's |
| 307 | * internal state to be passed with this debugnote |
| 308 | */ |
| 309 | public void sendDebugNote(String description) { |
| 310 | // send debug message only if debug mode of this model component |
| 311 | // and debug output is activated |
| 312 | // This bugfix was contributed by Heine Kolltveit |
| 313 | if (currentlySendDebugNotes()) { |
| 314 | sendMessage(new DebugNote(getModel(), presentTime(), getName(), |
| 315 | description)); |
| 316 | } |
| 317 | } |
| 318 | |
| 319 | /** |
| 320 | * returns true if this model component should currently send debug notes |
| 321 | * (i.e. experiment and the component are both in debug mode). |
| 322 | * |
| 323 | * @return |
| 324 | */ |
| 325 | protected boolean currentlySendDebugNotes() { |
| 326 | return debugIsOn() && getModel().getExperiment().debugIsOn(); |
| 327 | } |
| 328 | |
| 329 | /** |
| 330 | * Sends a message to the messagedistributor handled by the experiment. This |
| 331 | * modelcomponent must already be connected to an experiment in order to |
| 332 | * have a messagedistributor available to send this message to and an |
| 333 | * appropriate messagereceiver must already be registered at the |
| 334 | * messagedistributor to receive that type of message passed on to it. If no |
| 335 | * messaging subsystem is available to this modelcomponent, then the mesage |
| 336 | * is printed to the standard <code>out</code> printstream as configured in |
| 337 | * the local Java runtime environment of the computer this simulation is |
| 338 | * running on. Note that there are shorthands for sending the standard |
| 339 | * DESMO-J messages. These methods create and send the appropriate Message |
| 340 | * on-the-fly: |
| 341 | * <ul> |
| 342 | * <li><code>sendTraceNote()</clode> to send a tracenote</li> |
| 343 | * <li><code>sendDebugNote()</code> to send the data needed to debug models</li> |
| 344 | * <li><code>sendWarning()</code> to send an errormessage that does not stop |
| 345 | * the experiment</li> |
| 346 | * </ul> |
| 347 | * |
| 348 | * @param m |
| 349 | * Message : The message to be transmitted |
| 350 | * @see ModelComponent#sendTraceNote |
| 351 | * @see ModelComponent#sendDebugNote |
| 352 | * @see ModelComponent#sendWarning |
| 353 | */ |
| 354 | public void sendMessage(Message m) { |
| 355 | |
| 356 | if (m == null) { |
| 357 | sendWarning("Can't send Message!", "ModelComponent : " + getName() |
| 358 | + " Method: SendMessage(Message m)", |
| 359 | "The Message given as parameter is a null reference.", |
| 360 | "Be sure to have a valid Message reference."); |
| 361 | return; // no proper parameter |
| 362 | } |
| 363 | |
| 364 | if (_owner != null) { // is modelcomponent connected to model? |
| 365 | |
| 366 | if (_owner.getExperiment() != null) { // is model connected to |
| 367 | // Experiment? |
| 368 | |
| 369 | getModel().getExperiment().getMessageManager().receive(m); |
| 370 | return; |
| 371 | } |
| 372 | } |
| 373 | |
| 374 | // if not connected to messaging system, write to standard out |
| 375 | System.out.println(m); |
| 376 | |
| 377 | } |
| 378 | |
| 379 | /** |
| 380 | * Creates and sends a tracenote to the experiment's messagedistributor. The |
| 381 | * information about the simulation time, model and component producing this |
| 382 | * tracenote is extracted from the experiment and must not be given as |
| 383 | * parameters. |
| 384 | * |
| 385 | * @param description |
| 386 | * java.lang.String : The description of the tracenote |
| 387 | */ |
| 388 | public void sendTraceNote(String description) { |
| 389 | // send trace message only if trace mode of this model component |
| 390 | // and trace output is activated |
| 391 | // This bugfix was contributed by Heine Kolltveit |
| 392 | if (currentlySendTraceNotes()) { |
| 393 | sendMessage(new TraceNote(currentModel(), description, |
| 394 | presentTime(), currentEntityAll(), currentEvent())); |
| 395 | } |
| 396 | } |
| 397 | |
| 398 | /** |
| 399 | * returns true if this model component should currently send trace notes |
| 400 | * (i.e. experiment and the component are both in trace mode). |
| 401 | * |
| 402 | * @return |
| 403 | */ |
| 404 | protected boolean currentlySendTraceNotes() { |
| 405 | return traceIsOn() && getModel().getExperiment().traceIsOn(); |
| 406 | } |
| 407 | |
| 408 | /** |
| 409 | * Creates and sends an error message to warn about a erroneous condition in |
| 410 | * the DESMO-J framework to the experiment's messagedistributor. Be sure to |
| 411 | * have a correct location, since the object and method that the error |
| 412 | * becomes apparent is not necessary the location it was produced in. The |
| 413 | * information about the simulation time is extracted from the Experiment |
| 414 | * and must not be given as a parameter. |
| 415 | * |
| 416 | * @param description |
| 417 | * java.lang.String : The description of the error that occured |
| 418 | * @param location |
| 419 | * java.lang.String : The class and method the error occured in |
| 420 | * @param reason |
| 421 | * java.lang.String : The reason most probably responsible for |
| 422 | * the error to occur |
| 423 | * @param prevention |
| 424 | * java.lang.String : The measures a user should take to prevent |
| 425 | * this warning to be issued again |
| 426 | */ |
| 427 | public void sendWarning(String description, String location, String reason, |
| 428 | String prevention) { |
| 429 | |
| 430 | // comnpose the ErrorMessage and send it in one command |
| 431 | sendMessage(new ErrorMessage(getModel(), description, location, reason, |
| 432 | prevention, presentTime())); |
| 433 | |
| 434 | } |
| 435 | |
| 436 | /** |
| 437 | * Sets the owner of a modelcomponent to the given reference. This is |
| 438 | * exclusively needed to build a self-reference for the main model of an |
| 439 | * experiment. Has to be delegated to class <code>modelcomponent</code> |
| 440 | * since the owner attribute is encapsulated in this class. |
| 441 | * |
| 442 | * @param newOwner |
| 443 | * desmoj.Model : The modelcomponent's new owner |
| 444 | */ |
| 445 | void setOwner(Model newOwner) { |
| 446 | |
| 447 | _owner = newOwner; |
| 448 | |
| 449 | } |
| 450 | |
| 451 | /** |
| 452 | * Skips the next tracenote. The next tracenote produced by any object in |
| 453 | * the DESMO-J framework will not be distributed by the experiment's |
| 454 | * messagemanager. This is necessary for some operations to hide the |
| 455 | * framework's actions and thus not confuse the modeller. |
| 456 | */ |
| 457 | public void skipTraceNote() { |
| 458 | |
| 459 | skipTraceNote(1); |
| 460 | |
| 461 | } |
| 462 | |
| 463 | /** |
| 464 | * Skips the next number of tracenotes. The next -numSkipped - number of |
| 465 | * tracenotes produced by any object in the DESMO-J framework will not be |
| 466 | * distributed by the experiment's messagemanager. This is necessary for |
| 467 | * some operations to hide the framework's actions and thus not confuse the |
| 468 | * modeller. |
| 469 | * |
| 470 | * @param numSkipped |
| 471 | * int : The number of future tracenotes to be skipped |
| 472 | */ |
| 473 | public void skipTraceNote(int numSkipped) { |
| 474 | |
| 475 | if (numSkipped < 1) |
| 476 | return; // nothing to do or negative (illegal) param. |
| 477 | |
| 478 | try { |
| 479 | getModel().getExperiment().getMessageManager().skip( |
| 480 | Class.forName("desmoj.core.report.TraceNote"), numSkipped); |
| 481 | } catch (ClassNotFoundException cnfx) { |
| 482 | throw new desmoj.core.exception.SimAbortedException( |
| 483 | new ErrorMessage( |
| 484 | getModel(), |
| 485 | "Can not skip tracenotes! Simulation aborted.", |
| 486 | "ModelComponent : " + getName() |
| 487 | + " Method : skipTraceNote()", |
| 488 | "The file for class desmoj.report.TraceNote can not be found by " |
| 489 | + "the Java runtime. Following exception was caught : " |
| 490 | + cnfx.toString(), |
| 491 | "Check that all pathnames for DESMOJ are set in your environment.", |
| 492 | presentTime())); |
| 493 | |
| 494 | } |
| 495 | |
| 496 | } |
| 497 | |
| 498 | /** |
| 499 | * Shows if this modelcomponent currently produces trace output. |
| 500 | * |
| 501 | * @return boolean : true, if modelcomponent shows in trace, false if not |
| 502 | */ |
| 503 | public boolean traceIsOn() { |
| 504 | |
| 505 | return _traceMode; |
| 506 | |
| 507 | } |
| 508 | |
| 509 | /** |
| 510 | * Switches off trace output for this modelcomponent. Does nothing if trace |
| 511 | * is already switched off. |
| 512 | */ |
| 513 | public void traceOff() { |
| 514 | |
| 515 | _traceMode = false; // yep, that's it! |
| 516 | |
| 517 | } |
| 518 | |
| 519 | /** |
| 520 | * Switches on trace output for this modelcomponent. Does nothing if trace |
| 521 | * is already switched on. |
| 522 | */ |
| 523 | public void traceOn() { |
| 524 | |
| 525 | _traceMode = true; // yep, that's it! |
| 526 | |
| 527 | } |
| 528 | } |