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.file; 033 034import java.io.IOException; 035import java.io.OutputStream; 036import java.io.Writer; 037 038import org.graphstream.graph.Graph; 039import org.graphstream.stream.Sink; 040 041/** 042 * Output a graph or graph events to a file. 043 * 044 * <p> 045 * File outputs can work in two modes: 046 * <ul> 047 * <li>In the "writeAll()" mode, the file output is done "all at once" writing a 048 * "snapshot" of the graph at this particular instant in time. This mode cannot 049 * convey the dynamics of the graph.</li> 050 * <li>In "begin()/end()" mode, the output is listener of an input (a graph or 051 * any other sort of graph events producer) and it write events as they come, 052 * conveying the dynamics of the graph correctly.</li> 053 * </ul> 054 * </p> 055 */ 056public interface FileSink extends Sink { 057 /** 058 * Write the current graph state in one big non-interruptible operation. 059 * This operation is a "snapshot" of the graph, it will never convey the 060 * dynamics of the graph. To ensure you store the graph 061 * "as it evolves in time" you must use the {@link #begin(OutputStream)} or 062 * {@link #begin(String)} as soon as the graph appears (or any source of 063 * graph event, any descendant of {@link Source} will do). 064 * 065 * @param graph 066 * The graph to send as events to the file. 067 * @param fileName 068 * Name of the file to write. 069 * @throws IOException 070 * if an I/O error occurs while writing. 071 */ 072 void writeAll(Graph graph, String fileName) throws IOException; 073 074 /** 075 * Write the current graph state in one big non-interruptible operation. 076 * This operation is a "snapshot" of the graph, it will never convey the 077 * dynamics of the graph. To ensure you store the graph 078 * "as it evolves in time" you must use the {@link #begin(Writer)} or 079 * {@link #begin(OutputStream)} or {@link #begin(String)} as soon as the 080 * graph appears (or any source of graph event, any descendant of 081 * {@link Source} will do). 082 * 083 * @param graph 084 * The graph to send as events to the file. 085 * @param stream 086 * The stream where the graph is sent. 087 * @throws IOException 088 * if an I/O error occurs while writing. 089 */ 090 void writeAll(Graph graph, OutputStream stream) throws IOException; 091 092 /** 093 * Write the current graph state in one big non-interruptible operation. 094 * This operation is a "snapshot" of the graph, it will never convey the 095 * dynamics of the graph. To ensure you store the graph 096 * "as it evolves in time" you must use the {@link #begin(Writer)} or 097 * {@link #begin(OutputStream)} or {@link #begin(String)} as soon as the 098 * graph appears (or any source of graph event, any descendant of 099 * {@link Source} will do). 100 * 101 * @param graph 102 * The graph to send as events to the file. 103 * @param writer 104 * The writer where the graph is sent. 105 * @throws IOException 106 * if an I/O error occurs while writing. 107 */ 108 void writeAll(Graph graph, Writer writer) throws IOException; 109 110 /** 111 * Begin the output of the given stream of graph events. The graph events 112 * can come from any input (implementation of {@link Source} or you can 113 * directly use the methods inherited from {@link Sink}. Once the writing is 114 * started using begin(), you must close it using {@link #end()} when done 115 * to ensure data is correctly stored in the file. 116 * 117 * @param fileName 118 * The name of the file where to output the graph events. 119 * @throws IOException 120 * If an I/O error occurs while writing. 121 */ 122 void begin(String fileName) throws IOException; 123 124 /** 125 * Begin the output of the given stream of graph events. The graph events 126 * can come from any input (implementation of {@link Source} or you can 127 * directly use the methods inherited from {@link Sink}. Once the writing is 128 * started using begin(), you must close it using {@link #end()} when done 129 * to ensure data is correctly stored in the file. 130 * 131 * @param stream 132 * The file stream where to output the graph events. 133 * @throws IOException 134 * If an I/O error occurs while writing. 135 */ 136 void begin(OutputStream stream) throws IOException; 137 138 /** 139 * Begin the output of the given stream of graph events. The graph events 140 * can come from any input (implementation of {@link Source} or you can 141 * directly use the methods inherited from {@link Sink}. Once the writing is 142 * started using begin(), you must close it using {@link #end()} when done 143 * to ensure data is correctly stored in the file. 144 * 145 * @param writer 146 * The writer where to output the graph events. 147 * @throws IOException 148 * If an I/O error occurs while writing. 149 */ 150 void begin(Writer writer) throws IOException; 151 152 /** 153 * Ensure all data sent to the output are correctly written. 154 * 155 * @throws IOException 156 * If an I/O error occurs during write. 157 */ 158 void flush() throws IOException; 159 160 /** 161 * End the writing process started with {@link #begin(OutputStream)} or 162 * {@link #begin(String)}. 163 * 164 * @throws IOException 165 */ 166 void end() throws IOException; 167}