01: package it.unimi.dsi.mg4j.document;
02:
03: /*
04: * MG4J: Managing Gigabytes for Java
05: *
06: * Copyright (C) 2005-2007 Paolo Boldi and Sebastiano Vigna
07: *
08: * This library is free software; you can redistribute it and/or modify it
09: * under the terms of the GNU Lesser General Public License as published by the Free
10: * Software Foundation; either version 2.1 of the License, or (at your option)
11: * any later version.
12: *
13: * This library is distributed in the hope that it will be useful, but
14: * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
15: * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
16: * for more details.
17: *
18: * You should have received a copy of the GNU Lesser General Public License
19: * along with this program; if not, write to the Free Software
20: * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
21: *
22: */
23:
24: import java.io.Closeable;
25: import java.io.IOException;
26:
27: /** An iterator over documents.
28: *
29: * <p>This interface provide a {@link #nextDocument()}
30: * method returning the next document, or <code>null</code> if
31: * no more documents are available. Usually
32: * you would need to {@link Document#close()} each document when you
33: * are finished with it, but in the present case it is
34: * guaranteed that each call to {@link DocumentIterator#nextDocument()}
35: * will close the previously returned document.
36: *
37: * <p>An additional {@link #close()} method releases all resources
38: * used by the iterator. Implementations are invited to be
39: * {@link it.unimi.dsi.io.SafelyCloseable safely closeable}.
40: */
41: public interface DocumentIterator extends Closeable {
42:
43: /** Returns the next document.
44: *
45: * @return the next document, or <code>null</code> if there are no other documents.
46: */
47: public Document nextDocument() throws IOException;
48:
49: /** Closes this document iterator, releasing all resources.
50: *
51: * <p>You should always call this method after having finished with this iterator.
52: * Implementations are invited to call this method in a finaliser as a safety net, but since there
53: * is no guarantee as to when finalisers are invoked, you should not depend on this behaviour.
54: */
55:
56: public void close() throws IOException;
57: }
|