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}