001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2002-2006, GeoTools Project Managment Committee (PMC)
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation;
009: * version 2.1 of the License.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: */
016: package org.geotools.data;
017:
018: import java.io.IOException;
019: import org.geotools.feature.Feature;
020: import org.geotools.feature.FeatureType;
021:
022: /**
023: * Provides the ability to write Features information.
024: *
025: * <p>
026: * Capabilities:
027: * </p>
028: *
029: * <ul>
030: * <li>
031: * Similar API to FeatureReader
032: * </li>
033: * <li>
034: * After aquiring a feature using next() you may call remove() or after
035: * modification write(). If you do not call one of these two methods before
036: * calling hasNext(), or next() for that matter, the feature will be left
037: * unmodified.
038: * </li>
039: * <li>
040: * This API allows modification, and Filter based modification to be written.
041: * Please see AbstractDataStore for examples of implementing common
042: * opperations using this API.
043: * </li>
044: * <li>
045: * In order to add new Features, FeatureWriters capable of accepting new
046: * content allow next() to be called when hasNext() is <code>false</code> to
047: * allow new feature creation. These changes
048: * </li>
049: * </ul>
050: *
051: * <p>
052: * One thing that is really nice about the approach to adding content is that
053: * the generation of FID is not left in the users control.
054: * </p>
055: *
056: * @author Ian Schneider
057: * @author Jody Garnett, Refractions Research
058: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/api/src/main/java/org/geotools/data/FeatureWriter.java $
059: * @version $Id: FeatureWriter.java 22294 2006-10-20 00:55:40Z desruisseaux $
060: */
061: public interface FeatureWriter {
062: /**
063: * FeatureType this reader has been configured to create.
064: *
065: * @return FeatureType this writer has been configured to create.
066: */
067: FeatureType getFeatureType();
068:
069: /**
070: * Reads a Feature from the underlying AttributeReader.
071: *
072: * <p>
073: * This method may return a Feature even though hasNext() returns
074: * <code>false</code>, this allows FeatureWriters to provide an ability to
075: * append content.
076: * </p>
077: *
078: * @return Feature from Query, or newly appended Feature
079: *
080: * @throws IOException DOCUMENT ME!
081: */
082: Feature next() throws IOException;
083:
084: /**
085: * Removes current Feature, must be called before hasNext.
086: *
087: * <p>
088: * FeatureWriters will need to allow all FeatureSources of the same
089: * typeName to issue a FeatureEvent event of type
090: * <code>FeatureEvent.FEATURES_REMOVED</code> when this method is called.
091: * </p>
092: *
093: * <p>
094: * If this FeatureWriter is opperating against a Transaction
095: * FEATURES_REMOVED events should only be sent to FeatureSources operating
096: * on the same Transaction. When Transaction commit() is called other
097: * FeatureSources will be informed of the modifications.
098: * </p>
099: *
100: * <p>
101: * When the current Feature has been provided as new content, this method
102: * "cancels" the add opperation (and notification needed).
103: * </p>
104: *
105: * @throws IOException DOCUMENT ME!
106: */
107: void remove() throws IOException;
108:
109: /**
110: * Wrties the current Feature, must be called before hasNext.
111: *
112: * <p>
113: * FeautreWriters will need to allow FeatureSources of the same typeName to
114: * issue a FeatureEvent:
115: * </p>
116: *
117: * <ul>
118: * <li>
119: * FeatureEvent.FEATURES_ADDED: when next() has been called with hasNext()
120: * equal to <code>false</code>.
121: * </li>
122: * <li>
123: * FeatureEvent.FEATURES_MODIFIED: when next has been called with hasNext()
124: * equal to <code>true</code> and the resulting Feature has indeed been
125: * modified.
126: * </li>
127: * </ul>
128: *
129: * <p>
130: * If this FeatureWriter is opperating against a Transaction the
131: * FEATURES_MODIFIED or FEATURES_ADDED events should only be sent to
132: * FeatureSources opperating on the same Transaction. When Transaction
133: * commit() is called other FeatureSources will be informed of the
134: * modifications.
135: * </p>
136: *
137: * <p>
138: * If you have not called write() when you call hasNext() or next(), no
139: * modification will occur().
140: * </p>
141: *
142: * @throws IOException
143: */
144: void write() throws IOException;
145:
146: /**
147: * Query whether this FeatureWriter has another Feature.
148: *
149: * <p>
150: * Please note: it is more efficient to construct your FeatureWriter with a
151: * Filer (to skip entries you do not want), than to force the creation of
152: * entire Features only to skip over them.
153: * </p>
154: *
155: * <p>
156: * FeatureWriters that support append opperations will allow calls to next,
157: * even when haveNext() returns <code>false</code>.
158: * </p>
159: *
160: * @return <code>true</code> if an additional <code>Feature</code> is
161: * available.
162: *
163: * @throws IOException DOCUMENT ME!
164: */
165: boolean hasNext() throws IOException;
166:
167: /**
168: * Release the underlying resources.
169: *
170: * @throws IOException if there there are problems releasing underlying resources, or
171: * possibly if close has been called (up to the implementation).
172: */
173: void close() throws IOException;
174: }
|