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.generator;
033
034import org.graphstream.stream.Source;
035
036/**
037 * Graph generator.
038 * 
039 * <p>
040 * A graph generator is an object that can send graph events to create a
041 * new graph from an internal description. Some generators will create a
042 * static predefined graph, others will be able to continuously evolve
043 * Indeed some generators define an end to the generation process, others
044 * may continue endlessly.
045 * </p>
046 * 
047 * <p>
048 * Each generator, in addition of being a source of events, provide only
049 * three methods:
050 * <ul>
051 *              <li>One to start the generation process {@link #begin()}.
052 *              For static generators this often generate a whole graph, for dynamic
053 *              generators this only initialise a base graph.</li>
054 *              <li>One to generate more dynamic events {@link #nextEvents()}.
055 *              This method will, as its name suggests, generate more dynamic
056 *              events making the graph evolve. You can call it (repeatedly) only
057 *              between a call to {@link #begin()} and to {@link #end()}. This
058 *              method returns a boolean that may indicate that no more events
059 *              can be generated.</li>
060 *              <li>One to end the generation process {@link #end()}. This method
061 *              must ALWAYS be called when finished with the generator.</li>
062 * </ul>
063 * </p>
064 */
065public interface Generator extends Source {
066        /**
067         * Begin the graph generation. This usually is the place for initialization
068         * of the generator. After calling this method, call the
069         * {@link #nextEvents()} method to add elements to the graph.
070         */
071        void begin();
072
073        /**
074         * Perform the next step in generating the graph. While this method returns
075         * true, there are still more elements to add to the graph to generate it.
076         * Be careful that some generators never return false here, since they can
077         * generate graphs of arbitrary size. For such generators, simply stop
078         * calling this method when enough elements have been generated.
079         * 
080         * A call to this method can produce an undetermined number of nodes and
081         * edges. Checking nodes count is advisable when generating the graph to
082         * avoid an unwanted big graph.
083         * 
084         * @return true while there are elements to add to the graph.
085         */
086        boolean nextEvents();
087
088        /**
089         * End the graph generation by finalizing it. Once the {@link #nextEvents()}
090         * method returned false (or even if you stop before), this method must be
091         * called to finish the graph.
092         */
093        void end();
094}