// Decorator.java
package org.eclipse.stem.core.model;

/*******************************************************************************
 * Copyright (c) 2006, 2008 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.DynamicLabel;
import org.eclipse.stem.core.graph.Edge;
import org.eclipse.stem.core.graph.Graph;
import org.eclipse.stem.core.scenario.ScenarioInitializationException;

/**
 * A <code>Decorator</code> represents a computational component that can
 * modify or "decorate" a {@link org.eclipse.stem.core.graph.Graph}.
 * <p>
 * The method {@link #decorateGraph(org.eclipse.stem.core.graph.Graph)} is
 * called once for each <code>Decorator</code> instance during the creation of
 * the canonical {@link org.eclipse.stem.core.graph.Graph} (see
 * {@link Model#getCanonicalGraph(org.eclipse.emf.common.util.URI)}).
 * Typically, this method would add additional {@link DynamicLabel}s to the
 * {@link org.eclipse.stem.core.graph.Graph} under construction. For
 * example, a disease model would be implemented as a <code>Decorator</code>
 * and it would add {@link DynamicLabel}s to the
 * {@link org.eclipse.stem.core.graph.Node}s of the
 * {@link org.eclipse.stem.core.graph.Graph} that represent the state of the
 * disease at each {@link org.eclipse.stem.core.graph.Node}.
 * </p>
 * <p>
 * After the canonical {@link org.eclipse.stem.core.graph.Graph} is created,
 * the method
 * {@link #updateLabels(org.eclipse.stem.core.graph.Graph, STEMTime, long)}
 * will be called once every time the
 * {@link org.eclipse.stem.core.scenario.Scenario} is "stepped" (see
 * {@link org.eclipse.stem.core.scenario.Scenario#step()}). The
 * {@link DynamicLabel}s that it updates are those that were added to the
 * {@link org.eclipse.stem.core.graph.Graph} in the
 * {@link #decorateGraph(org.eclipse.stem.core.graph.Graph)} method call. A
 * reference to each of those {@link DynamicLabel}s is kept in a collection
 * (see {@link #getLabelsToUpdate()}) maintained by the <code>Decorator</code>.
 * The {@link #updateLabels(Graph, STEMTime, long)} method computes the "next"
 * value of all of the {@link DynamicLabel}s in that collection.
 * </p>
 * <p>
 * For maximum flexibility, the nature of that
 * {@link org.eclipse.stem.core.graph.LabelValue} and its computation are
 * not defined or restricted. For instance, the <code>Decorator</code> could
 * compute the {@link org.eclipse.stem.core.graph.LabelValue} from the
 * contents of the {@link org.eclipse.stem.core.graph.Graph}, read the
 * value from a file, obtain it from a real-time data source such as a weather
 * station or something accessible from a web site or a web service.
 * </p>
 * 
 * @model
 */
public interface Decorator extends Identifiable {

	/**
	 * A {@link Decorator} is enabled by default, but if it is the action of a
	 * {@link Trigger} then it will be disabled by the {@link Trigger} until the
	 * {@link Trigger}'s {@link Predicate} evaluates to <code>true</code>.
	 * <p>
	 * If the value is <code>false</code> then calls to {@link #decorateGraph()}
	 * and {@link #updateLabels(STEMTime, long)} will be ignored.
	 * 
	 * @return <code>true</code> if the {@link Decorator} is enabled.
	 * @model default="true"
	 */
	boolean isEnabled();
	
	/**
	 * Sets the value of the '{@link org.eclipse.stem.core.model.Decorator#isEnabled <em>Enabled</em>}' attribute.
	 * <!-- begin-user-doc -->
	 * <!-- end-user-doc -->
	 * @param value the new value of the '<em>Enabled</em>' attribute.
	 * @see #isEnabled()
	 * @generated
	 */
	void setEnabled(boolean value);


	/**
	 * @return <code>true</code> if {@link #decorateGraph()} has been called and
	 *         it has completed decorating the {@link Graph}, <code>false</code>
	 *         otherwise.
	 * @model default="false"
	 */
	boolean isGraphDecorated();
	
	/**
	 * Sets the value of the '{@link org.eclipse.stem.core.model.Decorator#isGraphDecorated <em>Graph Decorated</em>}' attribute.
	 * <!-- begin-user-doc -->
	 * <!-- end-user-doc -->
	 * @param value the new value of the '<em>Graph Decorated</em>' attribute.
	 * @see #isGraphDecorated()
	 * @generated
	 */
	void setGraphDecorated(boolean value);
	
	/**
	 * 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.model.ModelPackage#getDecorator_Progress()
	 * @model default="0.0" transient="true"
	 * @generated
	 */
	double getProgress();

	/**
	 * Sets the value of the '{@link org.eclipse.stem.core.model.Decorator#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);

	/**Augment the graph by adding components ({@link Edge}s,
	 * {@link org.eclipse.stem.core.graph.Node}s,
	 * {@link org.eclipse.stem.core.graph.Label}s). The added components,
	 * in particular {@link DynamicLabel}s, can be modified later during a call
	 * to {@link #updateLabels(Graph, STEMTime)}. A side effect of this call is
	 * that it adds the decorator to the collection maintained by the
	 * {@link Graph}.
	 * @param tiome
	 * @return boolean
	 * @generated
	 * @model volatile="true" transient="true" changeable="false"
	 */
	void decorateGraph(STEMTime time) throws ScenarioInitializationException;

	/**
	 * 
	 * @return the {@link Graph} that the <code>Decorator</code> decorates.
	 * @model opposite="decorators"
	 */
	Graph getGraph();
	
	/**
	 * Sets the value of the '{@link org.eclipse.stem.core.model.Decorator#getGraph <em>Graph</em>}' container reference.
	 * <!-- begin-user-doc --> 
	 * 
	 * Sets the value of the '{@link org.eclipse.stem.core.model.Decorator#getGraph <em>Graph</em>}'
	 * container reference.
	 * 
	 * @param value
	 *            the new value of the '<em>Graph</em>' container reference.
	 * @see #getGraph()
	 * 
	 * <!-- end-user-doc -->
	 * @param value the new value of the '<em>Graph</em>' container reference.
	 * @see #getGraph()
	 * @generated
	 */
	void setGraph(Graph value);

	/**
	 * @return the list of {@link DynamicLabel}s that this <code>Decorator</code>
	 * 	 is responsible for updating.
	 * @model type="DynamicLabel" containment="false" opposite="decorator"
	 */
	EList<DynamicLabel> getLabelsToUpdate();


	/**
	 * Process each of the {@link DynamicLabel}s that this
	 * <code>Decorator</code> is responsible for and determine their "next"
	 * value.
	 * 
	 * @param time
	 *            the time to be used when determining the changes to be made to
	 *            the Graph
	 * @param timePeriod
	 *            the number of milliseconds difference between the time and the
	 *            previous time value.
	 * @param cycle 
	 * 			  The next cycle number.
	 * @model volatile="true" transient="true" changeable="false"
	 */
	void updateLabels(final STEMTime time, final long timerPeriod, int cycle);

	/**
	 * Process each of the {@link DynamicLabels} that this
	 * <code>decorator</code> is responsible for and reset their "current"
	 * value to be the initial value assigned during the call to the method
	 * {@link #decorateGraph()}
	 * @throws ScenarioInitializationException 
	 * 
	 * @model volatile="true" transient="true" changeable="false"
	 */
	void resetLabels() throws ScenarioInitializationException;

	/**
	 * <!-- begin-user-doc -->
	 * <!-- end-user-doc -->
	 * @model
	 * @generated
	 */
	void prepare(Model model, STEMTime time);

} // Decorator