// 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.logger.Logger;
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" transient="true"
	 * @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);

	/**
	 * Returns the value of the '<em><b>Loggers</b></em>' reference list.
	 * The list contents are of type {@link org.eclipse.stem.core.logger.Logger}.
	 * <!-- begin-user-doc -->
	 * <p>
	 * If the meaning of the '<em>Loggers</em>' reference list isn't clear,
	 * there really should be more of a description here...
	 * </p>
	 * <!-- end-user-doc -->
	 * @return the value of the '<em>Loggers</em>' reference list.
	 * @see org.eclipse.stem.core.scenario.ScenarioPackage#getScenario_Loggers()
	 * @model
	 * @generated
	 */
	EList<Logger> getLoggers();

	/**
	 * 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.
	 * @throws ScenarioInitializationException 
	 * 
	 * @model volatile="true" transient="true" changeable="false"
	 */
	void reset() throws ScenarioInitializationException;

	/**
	 * 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() throws ScenarioInitializationException;

	/**
	 * @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