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 * Interface to listen at changes in the graph structure.
036 * 
037 * <p>
038 * Graph elements listeners are called each time an element of the graph (node
039 * or edge) is added or removed. It is also called for special events like
040 * "steps" that introduce the notion of time in graphs.
041 * </p>
042 */
043public interface ElementSink {
044        /**
045         * A node was inserted in the given graph.
046         * 
047         * @param sourceId
048         *            Identifier of the graph where the node was added.
049         * @param nodeId
050         *            Identifier of the added node.
051         */
052        void nodeAdded(String sourceId, long timeId, String nodeId);
053
054        /**
055         * A node was removed from the graph.
056         * 
057         * @param sourceId
058         *            Identifier of the graph where the node will be removed.
059         * @param nodeId
060         *            Identifier of the removed node.
061         */
062        void nodeRemoved(String sourceId, long timeId, String nodeId);
063
064        /**
065         * An edge was inserted in graph.
066         * 
067         * @param sourceId
068         *            Identifier of the graph where the edge was added.
069         * @param edgeId
070         *            Identifier of the added edge.
071         * @param fromNodeId
072         *            Identifier of the first node of the edge.
073         * @param toNodeId
074         *            Identifier of the second node of the edge.
075         * @param directed
076         *            If true, the edge is directed.
077         */
078        void edgeAdded(String sourceId, long timeId, String edgeId,
079                        String fromNodeId, String toNodeId, boolean directed);
080
081        /**
082         * An edge of graph was removed.The nodes the edge connects may already have
083         * been removed from the graph.
084         * 
085         * @param sourceId
086         *            The graph where the edge will be removed.
087         * @param edgeId
088         *            The edge that will be removed.
089         */
090        void edgeRemoved(String sourceId, long timeId, String edgeId);
091
092        /**
093         * The whole graph was cleared. All the nodes, edges and attributes of the
094         * graph are removed.
095         * 
096         * @param sourceId
097         *            The graph cleared.
098         */
099        void graphCleared(String sourceId, long timeId);
100
101        /**
102         * <p>
103         * Since dynamic graphs are based on discrete event modifications, the
104         * notion of step is defined to simulate elapsed time between events. So a
105         * step is a event that occurs in the graph, it does not modify it but it
106         * gives a kind of timestamp that allow the tracking of the progress of the
107         * graph over the time.
108         * </p>
109         * 
110         * <p>
111         * This kind of event is useful for dynamic algorithms that listen to the
112         * dynamic graph and need to measure the time in the graph's evolution.
113         * </p>
114         * 
115         * @param sourceId
116         *            Identifier of the graph where the step starts.
117         * @param timeId
118         *            A numerical value that may give a timestamp to track the
119         *            evolution of the graph over the time.
120         */
121        void stepBegins(String sourceId, long timeId, double step);
122}