01: /*
02: * GeoTools - OpenSource mapping toolkit
03: * http://geotools.org
04: * (C) 2002-2006, GeoTools Project Managment Committee (PMC)
05: *
06: * This library is free software; you can redistribute it and/or
07: * modify it under the terms of the GNU Lesser General Public
08: * License as published by the Free Software Foundation;
09: * version 2.1 of the License.
10: *
11: * This library is distributed in the hope that it will be useful,
12: * but WITHOUT ANY WARRANTY; without even the implied warranty of
13: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14: * Lesser General Public License for more details.
15: */
16: package org.geotools.data.collection;
17:
18: import java.util.Collection;
19: import java.util.Iterator;
20:
21: /**
22: * Collection supporting close( Iterator ), used to grok resources.
23: * <p>
24: * This implementation is a port of java.util.Collection with support for
25: * the use of close( Iterator ). This will allow subclasses that make use of
26: * resources during iterator() to be uses safely.
27: * </p>
28: * @author Jody Garnett, Refractions Research, Inc.
29: * @since GeoTools 2.2
30: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/api/src/main/java/org/geotools/data/collection/ResourceCollection.java $
31: */
32: public interface ResourceCollection extends Collection {
33: /**
34: * An iterator over this collection, which must be closeed after use.
35: * <p>
36: * Collection is not guarneteed to be ordered in any manner.
37: * </p>
38: * <p>
39: * The implementation of Collection must adhere to the rules of
40: * fail-fast concurrent modification. In addition (to allow for
41: * resource backed collections, the <code>close( Iterator )</code>
42: * method must be called.
43: * <p>
44: * </p>
45: * Example (safe) use:<pre><code>
46: * Iterator iterator = collection.iterator();
47: * try {
48: * while( iterator.hasNext();){
49: * Feature feature = (Feature) iterator.hasNext();
50: * System.out.println( feature.getID() );
51: * }
52: * }
53: * finally {
54: * collection.close( iterator );
55: * }
56: * </code></pre>
57: * </p>
58: * @return Iterator
59: */
60: public Iterator iterator();
61:
62: /**
63: * Clean up after any resources assocaited with this itterator in a manner similar to JDO collections.
64: * </p>
65: * Example (safe) use:<pre><code>
66: * Iterator iterator = collection.iterator();
67: * try {
68: * for( Iterator i=collection.iterator(); i.hasNext();){
69: * Feature feature = (Feature) i.hasNext();
70: * System.out.println( feature.getID() );
71: * }
72: * }
73: * finally {
74: * collection.close( iterator );
75: * }
76: * </code></pre>
77: * </p>
78: * @param close
79: */
80: public void close(Iterator close);
81:
82: /**
83: * Close any outstanding resources released by this resources.
84: * <p>
85: * This method should be used with great caution, it is however available
86: * to allow the use of the ResourceCollection with algorthims that are
87: * unaware of the need to close iterators after use.
88: * </p>
89: * <p>
90: * Example of using a normal Collections utility method:<pre><code>
91: * Collections.sort( collection );
92: * collection.purge();
93: * </code></pre>
94: */
95: public void purge();
96: }
|