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.stream;
033
034/**
035 * Defines sources that can be replayed. This is usefull when you are connecting
036 * a sink to a source but you need to get informations about the current state
037 * of the dynamic graph.
038 * 
039 * <pre>
040 * Replayable source = ... ;
041 * Replayable.Controller replay = source.getReplayController();
042 * ...
043 * // source is building a graph
044 * ...
045 * Graph g = ... ;
046 * //
047 * // Replay the source to get the current state of the graph
048 * //
049 * replay.addSink(g);
050 * replay.replay();
051 * </pre>
052 */
053public interface Replayable {
054        /**
055         * Get a controller to replay the graph.
056         * 
057         * @return a new replay controller
058         */
059        Controller getReplayController();
060
061        /**
062         * A controller used to replay a source. Controller should be used as a
063         * source by adding sinks on it. When sinks are set, a call to
064         * {@link #replay()} send events describing the current state of the
065         * original source to sinks.
066         */
067        public static interface Controller extends Source {
068                /**
069                 * Replay events describing the current state of the object being built
070                 * by the source.
071                 */
072                void replay();
073
074                /**
075                 * Same as {@link #replay(Sink)} but you can set the id of the source
076                 * sent in events.
077                 * 
078                 * @param sourceId
079                 *            id of the event source
080                 */
081                void replay(String sourceId);
082        }
083}