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}