svn-gvsig-desktop / trunk / org.gvsig.desktop / org.gvsig.desktop.compat.cdc / org.gvsig.fmap.dal / org.gvsig.fmap.dal.api / src / main / java / org / gvsig / fmap / dal / feature / FeatureSet.java @ 44149
History | View | Annotate | Download (12.4 KB)
1 | 40559 | jjdelcerro | /**
|
---|---|---|---|
2 | * gvSIG. Desktop Geographic Information System.
|
||
3 | *
|
||
4 | * Copyright (C) 2007-2013 gvSIG Association.
|
||
5 | *
|
||
6 | * This program is free software; you can redistribute it and/or
|
||
7 | * modify it under the terms of the GNU General Public License
|
||
8 | * as published by the Free Software Foundation; either version 3
|
||
9 | * of the License, or (at your option) any later version.
|
||
10 | *
|
||
11 | * This program 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
|
||
14 | * GNU General Public License for more details.
|
||
15 | *
|
||
16 | * You should have received a copy of the GNU General Public License
|
||
17 | * along with this program; if not, write to the Free Software
|
||
18 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
|
||
19 | * MA 02110-1301, USA.
|
||
20 | *
|
||
21 | * For any additional information, do not hesitate to contact us
|
||
22 | * at info AT gvsig.com, or visit our website www.gvsig.com.
|
||
23 | */
|
||
24 | 40435 | jjdelcerro | package org.gvsig.fmap.dal.feature; |
25 | |||
26 | import java.util.List; |
||
27 | |||
28 | import org.gvsig.fmap.dal.DataSet; |
||
29 | import org.gvsig.fmap.dal.exception.DataException; |
||
30 | import org.gvsig.tools.dispose.DisposableIterator; |
||
31 | import org.gvsig.tools.dynobject.DynObject; |
||
32 | import org.gvsig.tools.dynobject.DynObjectSet; |
||
33 | import org.gvsig.tools.exception.BaseException; |
||
34 | import org.gvsig.tools.visitor.IndexedVisitable; |
||
35 | import org.gvsig.tools.visitor.Visitor; |
||
36 | |||
37 | /**
|
||
38 | * A FeatureSet represents a set of {@link Feature}(s). These sets of features
|
||
39 | * are typically obtained directly from a {@link FeatureStore}, or through a
|
||
40 | * {@link FeatureQuery}.
|
||
41 | *
|
||
42 | * A FeatureSet may contain subsets of {@link Feature}(s) of different
|
||
43 | * {@link FeatureType}(s). It allows iterating and editing the features.
|
||
44 | *
|
||
45 | * FIXME: Actualizar javadoc
|
||
46 | *
|
||
47 | * Si el store en el que esta basado el featureset es modificado, se realiza un
|
||
48 | * update, insert, delete o se modifican los featuretype de este, el FeatureSet
|
||
49 | * quedara invalidado, y cualquier acceso a el provocara que se lance una
|
||
50 | * excepcion de tiempo de ejecucion ConcurrentModificationException.
|
||
51 | *
|
||
52 | * Habria que indicar que invocar al metodo accept del interface visitor
|
||
53 | * provocara la excepcion ConcurrentModificationException si el store a sido
|
||
54 | * modificado desde otro punto.
|
||
55 | *
|
||
56 | * Indicar que los metodos insert/delete/update ademas de actuar sobre el set,
|
||
57 | * actuan sobre el store en el que este esta basado, pero que no invalidan el
|
||
58 | * set sobre el que se ejecutan. No se si esto deberia hacerse mencion en esos
|
||
59 | * metodos o en la doc general del featureset.
|
||
60 | *
|
||
61 | */
|
||
62 | 43987 | jjdelcerro | public interface FeatureSet extends DataSet, IndexedVisitable, Iterable<Feature> { |
63 | 40435 | jjdelcerro | |
64 | /**
|
||
65 | * Returns the default {@link FeatureType} of this FeatureSet.
|
||
66 | *
|
||
67 | * @return default {@link FeatureType} in this FeatureSet.
|
||
68 | */
|
||
69 | public FeatureType getDefaultFeatureType();
|
||
70 | |||
71 | /**
|
||
72 | * Returns a list of the {@link FeatureType}(s) in this FeatureSet.
|
||
73 | *
|
||
74 | * @return list of the {@link FeatureType}(s) in this FeatureSet.
|
||
75 | */
|
||
76 | public List getFeatureTypes(); |
||
77 | |||
78 | /**
|
||
79 | * Returns the number of {@link Feature}(s) contained in this FeatureSet.
|
||
80 | *
|
||
81 | * The value returned by this method won't be accurate when
|
||
82 | * the FeatureStore is being edited and this set's features
|
||
83 | * are modified, added or deleted.
|
||
84 | *
|
||
85 | * @return number of {@link Feature}(s) contained in this FeatureSet.
|
||
86 | *
|
||
87 | * @throws DataException
|
||
88 | */
|
||
89 | public long getSize() throws DataException; |
||
90 | |||
91 | /**
|
||
92 | * Returns an iterator over the elements in this collection, in the order
|
||
93 | * (if any) defined when the collection was obtained.
|
||
94 | *
|
||
95 | * The iterator starts at the specified position in this collection. The
|
||
96 | * specified index indicates the first element that would be returned by an
|
||
97 | * initial call to the <tt>next</tt> method. An initial call to the
|
||
98 | * <tt>previous</tt> method would return the element with the specified
|
||
99 | * index minus one.
|
||
100 | *
|
||
101 | * <p>
|
||
102 | * <em>
|
||
103 | * <strong>NOTE:</strong> if you use this method to get the iterator, you
|
||
104 | * must get sure the iterator is disposed (@see
|
||
105 | * {@link DisposableIterator#dispose()}) in any case, even if an error occurs
|
||
106 | * while getting the data. It is recommended to use the <code>accept</code>
|
||
107 | * methods instead, which handle everything for you.
|
||
108 | * Take into account the accept methods may use a fast iterator to
|
||
109 | * get the features.
|
||
110 | * </em>
|
||
111 | * </p>
|
||
112 | *
|
||
113 | * @see #accept(org.gvsig.tools.visitor.Visitor)
|
||
114 | * @see #accept(org.gvsig.tools.visitor.Visitor, long)
|
||
115 | * @see #fastIterator()
|
||
116 | * @see #fastIterator(long)
|
||
117 | *
|
||
118 | * @param index
|
||
119 | * index of first element to be returned from the iterator (by a
|
||
120 | * call to the <tt>next</tt> method).
|
||
121 | * @return an iterator of the elements in this collection (in proper
|
||
122 | * sequence), starting at the specified position in the collection.
|
||
123 | * @throws DataException
|
||
124 | * if the index is out of range (index < 0 || index >
|
||
125 | * size()).
|
||
126 | * @deprecated use {@link #fastIterator(long)} instead
|
||
127 | */
|
||
128 | DisposableIterator iterator(long index) throws DataException; |
||
129 | |||
130 | 43358 | jjdelcerro | DisposableIterator iterator(long index, long elements) throws DataException; |
131 | |||
132 | 40435 | jjdelcerro | /**
|
133 | * Returns an iterator over the elements in this collection, in the order
|
||
134 | * (if any) defined when the collection was obtained.
|
||
135 | *
|
||
136 | * @see #accept(org.gvsig.tools.visitor.Visitor)
|
||
137 | * @see #accept(org.gvsig.tools.visitor.Visitor, long)
|
||
138 | * @see #fastIterator()
|
||
139 | * @see #fastIterator(long)
|
||
140 | *
|
||
141 | * @return an iterator of the elements in this collection (in proper
|
||
142 | * sequence).
|
||
143 | *
|
||
144 | 42535 | jjdelcerro | * @deprecated use fastiterator. In next versions the signature of this
|
145 | 43358 | jjdelcerro | * method will be changed to "Iterator<Feature> iterator()".
|
146 | 40435 | jjdelcerro | */
|
147 | 42535 | jjdelcerro | DisposableIterator iterator(); |
148 | 40435 | jjdelcerro | |
149 | /**
|
||
150 | * Returns a fast iterator over this set.
|
||
151 | * <p>
|
||
152 | * Fast in this case means that each of the elements returned may be a
|
||
153 | * reused or pooled object instance, so don't use it to be stored in any
|
||
154 | * way.
|
||
155 | * </p>
|
||
156 | * <p>
|
||
157 | * If you need to store one of the {@link Feature} of the iterator, use the
|
||
158 | * {@link Feature#getCopy()} to create a clone of the object.
|
||
159 | * </p>
|
||
160 | *
|
||
161 | * <p>
|
||
162 | * <em>
|
||
163 | * <strong>NOTE:</strong> if you use this method to get the iterator, you
|
||
164 | * must get sure the iterator is disposed (@see
|
||
165 | * {@link DisposableIterator#dispose()}) in any case, even if an error occurs
|
||
166 | * while getting the data. It is recommended to use the <code>accept</code>
|
||
167 | * methods instead, which handle everything for you.
|
||
168 | * Take into account the accept methods may use a fast iterator to
|
||
169 | * get the features.
|
||
170 | * </em>
|
||
171 | * </p>
|
||
172 | *
|
||
173 | * @see #accept(org.gvsig.tools.visitor.Visitor)
|
||
174 | * @see #accept(org.gvsig.tools.visitor.Visitor, long)
|
||
175 | *
|
||
176 | * @return an iterator over this set.
|
||
177 | *
|
||
178 | * @throws DataException
|
||
179 | */
|
||
180 | public DisposableIterator fastIterator() throws DataException; |
||
181 | |||
182 | /**
|
||
183 | * Returns a fast iterator over this set, starting from the given index.
|
||
184 | * <p>
|
||
185 | * Fast in this case means that each of the elements returned may be a
|
||
186 | * reused or pooled object instance, so don't use it to be stored in any
|
||
187 | * way.
|
||
188 | * </p>
|
||
189 | * <p>
|
||
190 | * If you need to store one of the {@link Feature} of the iterator, use the
|
||
191 | * {@link Feature#getCopy()} to create a clone of the object.
|
||
192 | * </p>
|
||
193 | *
|
||
194 | * <p>
|
||
195 | * <em>
|
||
196 | * <strong>NOTE:</strong> if you use this method to get the iterator, you
|
||
197 | * must get sure the iterator is disposed (@see
|
||
198 | * {@link DisposableIterator#dispose()}) in any case, even if an error occurs
|
||
199 | * while getting the data. It is recommended to use the <code>accept</code>
|
||
200 | * methods instead, which handle everything for you.
|
||
201 | * Take into account the accept methods may use a fast iterator to
|
||
202 | * get the features.
|
||
203 | * </em>
|
||
204 | * </p>
|
||
205 | *
|
||
206 | * @see #accept(org.gvsig.tools.visitor.Visitor)
|
||
207 | * @see #accept(org.gvsig.tools.visitor.Visitor, long)
|
||
208 | *
|
||
209 | * @param index
|
||
210 | * position in which the iterator is initially located.
|
||
211 | *
|
||
212 | * @return an iterator initially located at the position indicated by the
|
||
213 | * given index
|
||
214 | *
|
||
215 | * @throws DataException
|
||
216 | */
|
||
217 | 43987 | jjdelcerro | public DisposableIterator fastIterator(long index) throws DataException; |
218 | 40435 | jjdelcerro | |
219 | 43358 | jjdelcerro | public DisposableIterator fastIterator(long index, long elemets) throws DataException; |
220 | |||
221 | 40435 | jjdelcerro | /**
|
222 | * Indicates whether this FeatureSet contains zero features.
|
||
223 | *
|
||
224 | * The value returned by this method won't be accurate when
|
||
225 | * the FeatureStore is being edited and this set's features
|
||
226 | * are modified, added or deleted.
|
||
227 | *
|
||
228 | * @return true if this FeatureSet is empty, false otherwise.
|
||
229 | *
|
||
230 | * @throws DataException
|
||
231 | */
|
||
232 | boolean isEmpty() throws DataException; |
||
233 | |||
234 | 43088 | jjdelcerro | /**
|
235 | * Return the first feature of the set.
|
||
236 | * If the set is empty return null.
|
||
237 | *
|
||
238 | * This not is a good method to determine if the set is empty.
|
||
239 | * Use isEmpty instead.
|
||
240 | *
|
||
241 | * This is a utility method that call iterator and retrieve the
|
||
242 | * first feature of the iterator.
|
||
243 | *
|
||
244 | * @return the first fearure of the set or null.
|
||
245 | */
|
||
246 | public Feature first();
|
||
247 | |||
248 | 40435 | jjdelcerro | /**
|
249 | * Updates a {@link Feature} with the given {@link EditableFeature}.<br>
|
||
250 | *
|
||
251 | * Any {@link DisposableIterator} from this store that was still in use can will not
|
||
252 | * reflect this change.
|
||
253 | *
|
||
254 | * @param feature
|
||
255 | * an instance of {@link EditableFeature} with which to update
|
||
256 | * the associated {@link Feature}.
|
||
257 | *
|
||
258 | * @throws DataException
|
||
259 | */
|
||
260 | public void update(EditableFeature feature) throws DataException; |
||
261 | 44097 | omartinez | |
262 | public void commitChanges() throws DataException; |
||
263 | |||
264 | /**
|
||
265 | 40435 | jjdelcerro | * Deletes a {@link Feature} from this FeatureSet.<br>
|
266 | *
|
||
267 | * Any {@link DisposableIterator} from this store that was still in use will be
|
||
268 | * <i>unsafe</i>. Use {@link DisposableIterator#remove()} instead.
|
||
269 | *
|
||
270 | * @param feature
|
||
271 | * the {@link Feature} to delete.
|
||
272 | *
|
||
273 | * @throws DataException
|
||
274 | */
|
||
275 | public void delete(Feature feature) throws DataException; |
||
276 | |||
277 | /**
|
||
278 | * Inserts a new feature in this set. It needs to be an instance of
|
||
279 | * {@link EditableFeature} as it has not been stored yet.<br>
|
||
280 | *
|
||
281 | * Any {@link DisposableIterator} from this store that was still in use can will not
|
||
282 | * reflect this change.
|
||
283 | *
|
||
284 | * @param feature
|
||
285 | * the {@link EditableFeature} to insert.
|
||
286 | *
|
||
287 | * @throws DataException
|
||
288 | */
|
||
289 | public void insert(EditableFeature feature) throws DataException; |
||
290 | |||
291 | /**
|
||
292 | * Returns a {@link DynObjectSet} of the contents of this set.
|
||
293 | * Defaults to fast iteration.
|
||
294 | *
|
||
295 | * @return a {@link DynObjectSet}
|
||
296 | */
|
||
297 | public DynObjectSet getDynObjectSet();
|
||
298 | |||
299 | /**
|
||
300 | * Returns a {@link DynObjectSet} of the contents of this set.
|
||
301 | *
|
||
302 | * @param fast
|
||
303 | * if the set will be able to be iterated in a fast way, by
|
||
304 | * reusing the {@link DynObject} instance for each
|
||
305 | * {@link Feature} instance.
|
||
306 | * @return a {@link DynObjectSet}
|
||
307 | */
|
||
308 | public DynObjectSet getDynObjectSet(boolean fast); |
||
309 | |||
310 | /**
|
||
311 | * Provides each value of this Store to the provided {@link Visitor},
|
||
312 | * beginning from the provided index position.
|
||
313 | * The values received through the {@link Visitor#visit(Object)} method
|
||
314 | * may be transient, reused or externally modifiable, so they can't
|
||
315 | * be used to be stored in any external form out of the visit method.
|
||
316 | *
|
||
317 | * If you need to store any of the values out of the
|
||
318 | * {@link Visitor#visit(Object)} method execution, create a copy or clone
|
||
319 | * the received value in order to be stored.
|
||
320 | *
|
||
321 | * @param visitor
|
||
322 | * the visitor to apply to each value.
|
||
323 | * @param firstValueIndex
|
||
324 | * index of first element to be visited by the {@link Visitor}
|
||
325 | * @exception BaseException
|
||
326 | * if there is an error while performing the visit
|
||
327 | */
|
||
328 | 43358 | jjdelcerro | @Override
|
329 | 40435 | jjdelcerro | void accept(Visitor visitor, long firstValueIndex) throws BaseException; |
330 | 43358 | jjdelcerro | |
331 | void accept(Visitor visitor, long firstValueIndex, long elements) throws BaseException; |
||
332 | 44092 | omartinez | |
333 | public FeatureStore getFeatureStore();
|
||
334 | 40435 | jjdelcerro | } |