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.InputStream; 036import java.io.Reader; 037import java.net.URL; 038 039import org.graphstream.stream.Source; 040 041/** 042 * Source of graph events coming from a file. 043 * 044 * <p> 045 * The file input interface is an input with specific methods that deals with 046 * files. File inputs are designed to handle graphs stored under the form of a 047 * textual or binary file either under the form of a file name or a Java input 048 * stream. If the file comes from an URL, convert the URL to an input stream. 049 * </p> 050 * 051 * <p> 052 * The file package is designed under the idea that it provides graph inputs 053 * from files that store the graph under a given file format and encoding. The 054 * package provides decoders for all these formats. 055 * </p> 056 * 057 * <p> 058 * Do not confuse the file package with the net package that can also read from 059 * URLs, but build graph not from encoded description of a graph, but from web 060 * services like Flickr or Amazon, or simply networks of web pages tied by web 061 * links. The graph construction task is entirely different. 062 * </p> 063 * 064 * <p> 065 * Although not all graph format handle dynamic graphs, all file inputs must 066 * provide both the readAll() and begin()/nextEvents()/end() methods. The later 067 * must read one graph modification at a time. 068 * </p> 069 */ 070public interface FileSource extends Source { 071 /** 072 * Read the whole file in one big non-interruptible operation. 073 * 074 * @param fileName 075 * Name of the file to read. 076 * @throws IOException 077 * If an I/O error occurs while reading. 078 */ 079 void readAll(String fileName) throws IOException; 080 081 /** 082 * Read the whole file in one big non-interruptible operation. 083 * 084 * @param url 085 * The URL of the file to read. 086 * @throws IOException 087 * If an I/O error occurs while reading. 088 */ 089 void readAll(URL url) throws IOException; 090 091 /** 092 * Read the whole file in one big non-interruptible operation. 093 * 094 * @param stream 095 * The input stream to use for reading. 096 * @throws IOException 097 * If an I/O error occurs while reading. 098 */ 099 void readAll(InputStream stream) throws IOException; 100 101 /** 102 * Read the whole file in one big non-interruptible operation. 103 * 104 * @param reader 105 * The reader to use. 106 * @throws IOException 107 * If an I/O error occurs while reading. 108 */ 109 void readAll(Reader reader) throws IOException; 110 111 /** 112 * Begin reading the file stopping as soon as possible. Next graph events 113 * stored in the file will be sent by calling {@link #nextEvents()} or 114 * {@link #nextStep()}. Once begin() has been called, you must finish the 115 * reading process using {@link #end()}. You cannot call begin() twice 116 * without having called {@link #end()} in between. 117 * 118 * @param fileName 119 * Name of the file to read. 120 * @throws IOException 121 * If an I/O error occurs while reading. 122 */ 123 void begin(String fileName) throws IOException; 124 125 /** 126 * Begin reading the file stopping as soon as possible. Next graph events 127 * stored in the file will be sent by calling {@link #nextEvents()} or 128 * {@link #nextStep()}. Once begin() has been called, you must finish the 129 * reading process using {@link #end()}. You cannot call begin() twice 130 * without having called {@link #end()} in between. 131 * 132 * @param url 133 * The URL of the file to read. 134 * @throws IOException 135 * If an I/O error occurs while reading. 136 */ 137 void begin(URL url) throws IOException; 138 139 /** 140 * Begin reading the file stopping as soon as possible. Next graph events 141 * stored in the file will be sent by calling {@link #nextEvents()} or 142 * {@link #nextStep()}. Once begin() has been called, you must finish the 143 * reading process using {@link #end()}. You cannot call begin() twice 144 * without having called {@link #end()} in between. 145 * 146 * @param stream 147 * The input stream to use for reading. 148 * @throws IOException 149 * If an I/O error occurs while reading. 150 */ 151 void begin(InputStream stream) throws IOException; 152 153 /** 154 * Begin reading the file stopping as soon as possible. Next graph events 155 * stored in the file will be sent by calling {@link #nextEvents()} or 156 * {@link #nextStep()}. Once begin() has been called, you must finish the 157 * reading process using {@link #end()}. You cannot call begin() twice 158 * without having called {@link #end()} in between. 159 * 160 * @param reader 161 * The file reader to use. 162 * @throws IOException 163 * If an I/O error occurs while reading. 164 */ 165 void begin(Reader reader) throws IOException; 166 167 /** 168 * Try to process one graph event, or as few as possible, if more must be 169 * read at once. For this method to work, you must have called 170 * {@link #begin(InputStream)} or {@link #begin(String)} before. This method 171 * return true while there are still events to read. 172 * 173 * @return true if there are still events to read, false as soon as the file 174 * is finished. 175 * @throws IOException 176 * If an I/O error occurs while reading. 177 */ 178 boolean nextEvents() throws IOException; 179 180 /** 181 * Try to process all the events occurring during one time step. In 182 * GraphStream, a time step is a group of events that are considered 183 * occurring at the same time. Most file formats do not have this notion of 184 * step. The DGS format designed for GraphStream handles steps. This method 185 * return true while there are still events to read. 186 * 187 * @return true if there are still events to read, false as soon as the file 188 * is finished. 189 * @throws IOException 190 * If an I/O error occurs while reading. 191 */ 192 boolean nextStep() throws IOException; 193 194 /** 195 * Finish the reading process (even if {@link #nextEvents()} or 196 * {@link #nextStep()} did not returned false). You must call this method 197 * after reading. 198 * 199 * @throws IOException 200 * If an I/O error occurs while closing the file. 201 */ 202 void end() throws IOException; 203}