001/*
002 * Copyright 2006 - 2013
003 *     Stefan Balev     <stefan.balev@graphstream-project.org>
004 *     Julien Baudry    <julien.baudry@graphstream-project.org>
005 *     Antoine Dutot    <antoine.dutot@graphstream-project.org>
006 *     Yoann Pigné      <yoann.pigne@graphstream-project.org>
007 *     Guilhelm Savin   <guilhelm.savin@graphstream-project.org>
008 * 
009 * This file is part of GraphStream <http://graphstream-project.org>.
010 * 
011 * GraphStream is a library whose purpose is to handle static or dynamic
012 * graph, create them from scratch, file or any source and display them.
013 * 
014 * This program is free software distributed under the terms of two licenses, the
015 * CeCILL-C license that fits European law, and the GNU Lesser General Public
016 * License. You can  use, modify and/ or redistribute the software under the terms
017 * of the CeCILL-C license as circulated by CEA, CNRS and INRIA at the following
018 * URL <http://www.cecill.info> or under the terms of the GNU LGPL as published by
019 * the Free Software Foundation, either version 3 of the License, or (at your
020 * option) any later version.
021 * 
022 * This program is distributed in the hope that it will be useful, but WITHOUT ANY
023 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
024 * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
025 * 
026 * You should have received a copy of the GNU Lesser General Public License
027 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
028 * 
029 * The fact that you are presently reading this means that you have had
030 * knowledge of the CeCILL-C and LGPL licenses and that you accept their terms.
031 */
032package org.graphstream.algorithm;
033
034/**
035 * Defines algorithms able to handle dynamics of a graph. This is an extension
036 * of the {@link org.graphstream.algorithm.Algorithm} so dynamic algorithms are
037 * composed of an initialization step followed by several computation steps. A
038 * last step, specific to dynamic algorithms, marks the termination of the
039 * algorithm and has to be used to close the computation.
040 * 
041 * The following example computes the amount of apparitions of each node and the
042 * average value of apparitions for nodes :
043 * 
044 * <pre>
045 * public class ApparitionAlgorithm extends SinkAdapter implements
046 *              DynamicAlgorithm {
047 * 
048 *      Graph theGraph;
049 *      HashMap&lt;String, Integer&gt; apparitions;
050 *      double avg;
051 * 
052 *      public void init(Graph graph) {
053 *              theGraph = graph;
054 *              avg = 0;
055 *              graph.addSink(this);
056 *      }
057 * 
058 *      public void compute() {
059 *              avg = 0;
060 * 
061 *              for (int a : apparitions.values())
062 *                      avg += a;
063 * 
064 *              avg /= apparitions.size();
065 *      }
066 * 
067 *      public void terminate() {
068 *              graph.removeSink(this);
069 *      }
070 * 
071 *      public double getAverageApparitions() {
072 *              return avg;
073 *      }
074 * 
075 *      public int getApparitions(String nodeId) {
076 *              return apparitions.get(nodeId);
077 *      }
078 * 
079 *      public void nodeAdded(String sourceId, long timeId, String nodeId) {
080 *              int a = 0;
081 * 
082 *              if (apparitions.containsKey(nodeId))
083 *                      a = apparitions.get(nodeId);
084 * 
085 *              apparitions.put(nodeId, a + 1);
086 *      }
087 * 
088 *      public void stepBegins(String sourceId, long timeId, double step) {
089 *              compute();
090 *      }
091 * }
092 * </pre>
093 * 
094 * Note that in the example, the #terminate() method is used to remove the link
095 * between graph and the algorithm. The computation here is done at every step
096 * but can be done anywhere else, according to the algorithm requirements.
097 */
098public interface DynamicAlgorithm extends Algorithm {
099        /**
100         * Terminate the dynamic algorithm.
101         * 
102         * @see #init(org.graphstream.graph.Graph)
103         */
104        void terminate();
105}