| // Scenario.java |
| package org.eclipse.stem.core.scenario; |
| |
| /******************************************************************************* |
| * Copyright (c) 2006 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| |
| import org.eclipse.emf.common.util.EList; |
| import org.eclipse.stem.core.common.Identifiable; |
| import org.eclipse.stem.core.graph.Graph; |
| import org.eclipse.stem.core.model.Decorator; |
| import org.eclipse.stem.core.model.Model; |
| import org.eclipse.stem.core.sequencer.Sequencer; |
| import org.eclipse.stem.core.solver.Solver; |
| |
| /** |
| * A <code>Scenario</code> combines all of the components required to create |
| * and execute a simulation. These are a {@link Model}, a {@link Sequencer}, |
| * and a set of <code>Scenario</code> specific {@link Decorator}'s. |
| * <p> |
| * The {@link Model} contains the details of how to construct the |
| * <em>canonical graph</em> (see {@link Graph}. This graph is what the |
| * <code>Scenario</code> uses to represent the state of a simulation. |
| * <p> |
| * The {@link Sequencer} is used by the <code>Scenario</code> to determine the |
| * sequence of points in time through which the <code>Scenario</code> will |
| * {@link #step()} as it computes successive simulation states. |
| * <p> |
| * The "scenario decorators" implement that part of the simulation computation |
| * that is specific to the <code>Scenario</code>. |
| * <p> |
| * A <code>Scenario</code> implements all of the logic necessary to sequence |
| * through each step of a simulation and can be executed outside of the Eclipse |
| * workbench. |
| * </p> |
| * <p> |
| * This interface definition is also an "Annotated Java Interface" that defines |
| * one class in a <a href="http://www.uml.org/">UML</a> "model". The UML class |
| * diagram for the model is in the <code>documentation</code> folder of the |
| * project. This file and the other interfaces in this Java package are |
| * processed by the Eclipse Modeling Framework (aka EMF <a |
| * href="http://org.eclipse/emf">http://org.eclipse/emf</a>). to automatically |
| * generate an implementation of the model. EMF is documented in the book <a |
| * href="http://www.awprofessional.com/bookstore/product.asp?isbn=0131425420&rl=1">Eclipse |
| * Modeling Framework </a> by Budinsky, et al. |
| * </p> |
| * |
| * @see Model |
| * @see Graph |
| * |
| * @model |
| */ |
| public interface Scenario extends Identifiable { |
| |
| /** |
| * This is the segment of the type URI that prefixes all other segments in a |
| * scenario URI. |
| */ |
| String URI_TYPE_SCENARIO_SEGMENT = "scenario"; |
| |
| /** |
| * The {@link Model} contains all of the details required to construct the |
| * canonical graph that the scenario will use to represent the state of a |
| * simulation. |
| * |
| * @return the Scenario's {@link Model}. |
| * @model containment="false" |
| */ |
| Model getModel(); |
| |
| /** |
| * Sets the value of the '{@link org.eclipse.stem.core.scenario.Scenario#getModel <em>Model</em>}' reference. |
| * <!-- begin-user-doc --> <!-- end-user-doc --> |
| * @param value the new value of the '<em>Model</em>' reference. |
| * @see #getModel() |
| * @generated |
| */ |
| void setModel(Model value); |
| |
| /** |
| * The {@link Sequencer} is the component that determines the time of the |
| * simulation. It generates {@link org.eclipse.stem.core.model.STEMTime} |
| * values that are then used by the {@link Decorator}'s to update the |
| * {@link org.eclipse.stem.core.graph.Label}'s in the canonical graph. |
| * |
| * @model containment="false" |
| */ |
| Sequencer getSequencer(); |
| |
| /** |
| * Sets the value of the '{@link org.eclipse.stem.core.scenario.Scenario#getSequencer <em>Sequencer</em>}' reference. |
| * <!-- begin-user-doc --> <!-- end-user-doc --> |
| * @param value the new value of the '<em>Sequencer</em>' reference. |
| * @see #getSequencer() |
| * @generated |
| */ |
| void setSequencer(Sequencer value); |
| |
| /** |
| * The "scenario decorators" are the {@link Decorator}'s that can |
| * "decorate" (i.e., modify) the canonical {@link Graph} after it has been |
| * generated by the {@link Model}. Typically, these decorators are used to |
| * provide scenario specific initialization of a simulation independent of |
| * the more general initialization provided by the decorators in the |
| * {@link Model}. |
| * <p> |
| * For instance, in the case of a disease simulation, the model decorators |
| * would include one that implements a disease model. That decorator would |
| * have added labels to appropriate nodes to represent the state of the |
| * disease at specific geographic locations (likely most of the |
| * {@link Nodes} in the {@link Graph}). However, none of the disease states |
| * would (likely) include infected population members. The job of |
| * introducing the infected population members would be left up to a |
| * decorator contained in the scenario. Thus, one could reuse the same |
| * underlying {@link Model} in different {@link Scenario}'s. Each |
| * {@link Scenario}, in turn, would contain a {@link Decorator} configured |
| * for a different infection starting point. |
| * <p> |
| * |
| * @see #initialize() |
| * @see #getCanonicalGraph() |
| * |
| * @return the Scenario Decorators |
| * @model type="org.eclipse.stem.core.model.Decorator" |
| * containment="false" |
| */ |
| EList<Decorator> getScenarioDecorators(); |
| |
| /** |
| * The canonical {@link Graph} is created by the scenario's {@link Model} |
| * when the method {@link #initialize()} is invoked. This occurs either by a |
| * direct call or more typically in the {@link #step()} method. |
| * |
| * @return the canonical graph, or null if the Scenario hasn't been |
| * initialized. |
| * |
| * @model resolveProxies="false" changeable="false" |
| */ |
| Graph getCanonicalGraph(); |
| |
| /** |
| * Returns the value of the '<em><b>Progress</b></em>' attribute. |
| * The default value is <code>"0.0"</code>. |
| * <!-- begin-user-doc --> |
| * <p> |
| * If the meaning of the '<em>Progress</em>' attribute isn't clear, |
| * there really should be more of a description here... |
| * </p> |
| * <!-- end-user-doc --> |
| * @return the value of the '<em>Progress</em>' attribute. |
| * @see #setProgress(double) |
| * @see org.eclipse.stem.core.scenario.ScenarioPackage#getScenario_Progress() |
| * @model default="0.0" |
| * @generated |
| */ |
| double getProgress(); |
| |
| /** |
| * Sets the value of the '{@link org.eclipse.stem.core.scenario.Scenario#getProgress <em>Progress</em>}' attribute. |
| * <!-- begin-user-doc --> |
| * <!-- end-user-doc --> |
| * @param value the new value of the '<em>Progress</em>' attribute. |
| * @see #getProgress() |
| * @generated |
| */ |
| void setProgress(double value); |
| |
| /** |
| * Returns the value of the '<em><b>Solver</b></em>' containment reference. |
| * <!-- begin-user-doc --> |
| * <p> |
| * If the meaning of the '<em>Solver</em>' reference isn't clear, |
| * there really should be more of a description here... |
| * </p> |
| * <!-- end-user-doc --> |
| * @return the value of the '<em>Solver</em>' containment reference. |
| * @see #setSolver(Solver) |
| * @see org.eclipse.stem.core.scenario.ScenarioPackage#getScenario_Solver() |
| * @model containment="true" |
| * @generated |
| */ |
| Solver getSolver(); |
| |
| /** |
| * Sets the value of the '{@link org.eclipse.stem.core.scenario.Scenario#getSolver <em>Solver</em>}' containment reference. |
| * <!-- begin-user-doc --> |
| * <!-- end-user-doc --> |
| * @param value the new value of the '<em>Solver</em>' containment reference. |
| * @see #getSolver() |
| * @generated |
| */ |
| void setSolver(Solver value); |
| |
| /** |
| * Sequence the model by one simulation step. This performs any |
| * initialization required to create the canonical {@link Graph}, if |
| * necessary. |
| * |
| * @param l Listener that needs to be notified of progress of decorators |
| * @see #initialize() |
| * @return <code>true</code> if the sequence can continue, |
| * <code>false</code> if the sequence has completed. |
| * |
| * @model volatile="true" transient="true" changeable="false" |
| */ |
| boolean step(); |
| |
| /** |
| * Reset the state of the canonical {@link Graph} to its initial state. This |
| * does not delete and recreate the canonical graph. |
| * |
| * @model volatile="true" transient="true" changeable="false" |
| */ |
| void reset(); |
| |
| /** |
| * Create the canonical {@link Graph} and perform initialization steps |
| * required to sequence the scenario. This method is called by |
| * {@link #step()} when it needs to create the canonical {@link Graph}. It |
| * can be called before a call to {@link #step()} to create the |
| * {@link Graph}. |
| * |
| * @see #getCanonicalGraph() |
| * |
| * @model volatile="true" transient="true" changeable="false" |
| */ |
| void initialize(); |
| |
| /** |
| * @return the title of the scenario as specified by its |
| * {@link org.eclipse.stem.core.common.DublinCore}, or, if no |
| * title is defined, return the empty string. |
| * |
| * @see Identifiable#getDublinCore() |
| * |
| * @model volatile="true" transient="true" changeable="false" |
| */ |
| String produceTitle(); |
| } // Scenario |