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