Statistics
| Revision:

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 / DataStore.java @ 44297

History | View | Annotate | Download (11 KB)

1
/**
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
package org.gvsig.fmap.dal;
25

    
26
import java.util.Collection;
27
import java.util.Iterator;
28
import java.util.List;
29

    
30
import org.gvsig.fmap.dal.exception.DataException;
31
import org.gvsig.fmap.dal.exception.ValidateDataParametersException;
32
import org.gvsig.metadata.Metadata;
33
import org.gvsig.timesupport.Interval;
34
import org.gvsig.timesupport.Time;
35
import org.gvsig.tools.dispose.Disposable;
36
import org.gvsig.tools.dynobject.DynObject;
37
import org.gvsig.tools.dynobject.DynObject_v2;
38
import org.gvsig.tools.exception.BaseException;
39
import org.gvsig.tools.observer.ComplexWeakReferencingObservable;
40
import org.gvsig.tools.observer.Observer;
41
import org.gvsig.tools.persistence.Persistent;
42
import org.gvsig.tools.resourcesstorage.ResourcesStorage;
43
import org.gvsig.tools.service.spi.Services;
44
import org.gvsig.tools.util.UnmodifiableBasicList;
45
import org.gvsig.tools.util.UnmodifiableBasicMap;
46
import org.gvsig.tools.visitor.Visitable;
47
import org.gvsig.tools.visitor.Visitor;
48

    
49
/**
50
 * <p>
51
 * This is the basic interface for all data stores. Depending on the context, it
52
 * can represent a geographic layer, an alphanumeric database table or any data
53
 * file. DataStore offers generic services like:
54
 * <ul>
55
 * <li>Open and close data stores</li>
56
 * <li>Access to data sets, with the possibility of loading data in background.</li>
57
 * <li>Use of selection and locks, as well as data sets</li>
58
 * <li>Editing</li>
59
 * <li>Register event observers through the Observable interface</li>
60
 * <li>Access to embedded data stores (like GML)</li>
61
 * <li>Information about the Spatial Reference Systems used by the data store</li>
62
 * </ul>
63
 * </p>
64
 * <br>
65
 *
66
 */
67
public interface DataStore extends ComplexWeakReferencingObservable,
68
                Persistent, Metadata, Disposable, Visitable, DataFactoryUnit, Services, DynObject_v2 {
69

    
70
        public static final String METADATA_DEFINITION_NAME = "DataProvider";
71

    
72
        public static final String FEATURE_METADATA_DEFINITION_NAME = "FeatureProvider";
73

    
74
        public static final String SPATIAL_METADATA_DEFINITION_NAME = "SpatialProvider";
75

    
76
        /**
77
         * Metadata property name for the provider name provided by the data provider.
78
         *
79
         * This metadata is provided by all data providers.
80
         */
81
        public static final String METADATA_PROVIDER = "ProviderName";
82

    
83
        /**
84
         * Metadata property name for Container name provided by the data provider.
85
         * By explample, in a dbf file, this is the name of dbf.
86
         *
87
         * This metadata is provided by all data providers.
88
         */
89
        public static final String METADATA_CONTAINERNAME = "ContainerName";
90

    
91
        /**
92
         * Metadata property name for the feature type provided by the data provider.
93
         *
94
         * This metadata is provided by all tabular data providers.
95
         */
96
        public static final String METADATA_FEATURETYPE = "FeatureType";
97

    
98
        /**
99
         * Metadata property name for CRS provided by the data provider.
100
         *
101
         * This metadata is only provided by data provider with spatial
102
         * information.
103
         */
104
        public static final String METADATA_CRS = "CRS";
105

    
106
        /**
107
         * Metadata property name for Envelope provided by the data provider
108
         *
109
         * This metadata is only provided by data provider with spatial
110
         * information.
111
         */
112
        public static final String METADATA_ENVELOPE = "Envelope";
113

    
114
        /**
115
         * Returns the name associated to the store.
116
         * This name is provided for informational purposes only.
117
         * Explamples:
118
         *
119
         * In a dbf the filename without the path
120
         *
121
         * In a DDBB table the name of the table
122
         *
123
         * In a WFS layer the name of the layer.
124
         *
125
         * @return String containing this store's name.
126
         */
127
        public String getName();
128

    
129
        /**
130
         * Returns a more descriptive name for the store that getName.
131
         * This name is provided for informational purposes only.
132
         * Explamples:
133
         *
134
         * In a file based store may return the full name of the filename, path and filename.
135
         *
136
         * In a data base based store may return "server:dbname:tablename"
137
         *
138
         * In a WFS layer based store may return "server:layername"
139
         *
140
         * @return String Containing the full name of the store
141
         */
142
        public String getFullName();
143

    
144
        /**
145
         * Return the of parameters of this store
146
         *
147
         * @return parameters of this store
148
         */
149
        public DataStoreParameters getParameters();
150

    
151
        /**
152
         * Return the provider name that use this store.
153
         *
154
         * @return provider name of this store
155
         */
156
        public String getProviderName();
157

    
158
        /**
159
         * Refreshes this store state.
160
         *
161
         * @throws DataException
162
         */
163
        public void refresh() throws DataException;
164

    
165
        /**
166
         * Returns all available data.
167
         *
168
         * @return a set of data
169
         * @throws DataException
170
         *             if there is any error while loading the data
171
         */
172
        DataSet getDataSet() throws DataException;
173

    
174
        /**
175
         * Returns a subset of data taking into account the properties and
176
         * restrictions of the DataQuery.
177
         *
178
         * @param dataQuery
179
         *            defines the properties of the requested data
180
         * @return a set of data
181
         * @throws DataException
182
         *             if there is any error while loading the data
183
         */
184
        DataSet getDataSet(DataQuery dataQuery) throws DataException;
185

    
186
    /**
187
     * Provides each value of this Store to the provided {@link Visitor}.
188
     * The values received through the {@link Visitor#visit(Object)} method
189
     * may be transient, reused or externally modifiable, so they can't
190
     * be used to be stored in any external form out of the visit method.
191
     *
192
     * If you need to store any of the values out of the
193
     * {@link Visitor#visit(Object)} method execution, create a copy or clone
194
     * the received value in order to be stored.
195
     *
196
     * @param visitor
197
     *            the visitor to apply to each value.
198
     * @exception BaseException
199
     *                if there is an error while performing the visit
200
     */
201
    public void accept(Visitor visitor) throws BaseException;
202

    
203
        /**
204
     * Provides each value of this Store to the provided {@link Visitor}.
205
     * The values received through the {@link Visitor#visit(Object)} method
206
     * may be transient, reused or externally modifiable, so they can't
207
     * be used to be stored in any external form out of the visit method.
208
     *
209
     * If you need to store any of the values out of the
210
     * {@link Visitor#visit(Object)} method execution, create a copy or clone
211
     * the received value in order to be stored.
212
     *
213
     * @param visitor
214
     *            the visitor to apply to each value.
215
     * @param dataQuery
216
     *            defines the properties of the data to visit
217
     * @exception BaseException
218
     *                if there is an error while performing the visit
219
     */
220
        public void accept(Visitor visitor, DataQuery dataQuery)
221
                        throws BaseException;
222

    
223
        /**
224
         * Loads all available data and notifies the observer for each loaded block of data.
225
         *
226
         * @param observer
227
         *            to be notified for each block of data loaded
228
         * @throws DataException
229
         *             if there is any error while loading the data
230
         */
231
        void getDataSet(Observer observer) throws DataException;
232

    
233
        /**
234
         * Loads a subset of data taking into account the properties and
235
         * restrictions of the DataQuery. Data loading is performed by calling the
236
         * Observer, once each data block is loaded.
237
         *
238
         * @param dataQuery
239
         *            defines the properties of the requested data
240
         * @param observer
241
         *            to be notified for each block of data loaded
242
         * @throws DataException
243
         *             if there is any error while loading the data
244
         */
245
        void getDataSet(DataQuery dataQuery, Observer observer) throws DataException;
246

    
247
        /**
248
         * Returns the selected set of data
249
         *
250
         * @return DataSet
251
         */
252

    
253
        public DataSet getSelection() throws DataException;
254

    
255
        /**
256
         * Sets the current data selection with the given data set.
257
         *
258
         * @param DataSet
259
         *            selection
260
         * @throws DataException
261
         */
262
        public void setSelection(DataSet selection) throws DataException;
263

    
264
        /**
265
         * Creates a new selection.
266
         *
267
         * @return DataSet that contains the selection
268
         *
269
         * @throws DataException
270
         */
271
        public DataSet createSelection() throws DataException;
272

    
273
        /**
274
         * Returns an UnmodifiableBasicMap with this store children.
275
         * If do not have children, return an empty map.
276
         * Never returns null.
277
         *
278
         * @return an UnmodifiableBasicMap with this DataStore children
279
         */
280
        public UnmodifiableBasicMap<String,DataStore> getChildren();
281
        
282

    
283
        /**
284
         * Returns the DataServerExplorer to which this DataStore belongs, if there
285
         * is any.
286
         *
287
         * @return DataServerExplorer to which this DataStore belongs, or
288
         *         <code>null</code> if this was not accessed through any
289
         *         DataServerExplorer.
290
         *
291
         * @throws DataException
292
         * @throws ValidateDataParametersException
293
         */
294
        public DataServerExplorer getExplorer() throws DataException,
295
                        ValidateDataParametersException;
296

    
297

    
298
        /**
299
         * Returns a new instance of a {@link DataQuery}.
300
         *
301
         * @return new {@link DataQuery} instance.
302
         *
303
         * @throws DataException
304
         */
305
        public DataQuery createQuery();
306

    
307
        /**
308
         * Gets the {@link Interval} of the store, that means the temporal
309
         * interval where the store has valid data.
310
         * @return
311
         *         a time interval or null if there is not time support
312
         */
313
        public Interval getInterval();
314

    
315
        /**
316
         * Gets all the possible values of time for which the store has data.
317
         * @return
318
         *         a collection of {@link Time} objects.
319
         */
320
        public Collection getTimes();
321

    
322
        /**
323
         * Gets all the possible values of time for which the store has data
324
         * and intersects with an interval.
325
         * @param interval
326
         *         the interval of time
327
         * @return
328
         *         a collection of {@link Time} objects.
329
         */
330
        public Collection getTimes(Interval interval);
331

    
332
        /**
333
         * @param providerName
334
         * @param parameters
335
         * @throws DataException
336
         */
337
        public void useCache(String providerName, DynObject parameters) throws DataException;
338

    
339
        public DataStoreProviderFactory getProviderFactory();
340

    
341
    /**
342
     * @return
343
     */
344
    public DataCache getCache();
345

    
346
    public ResourcesStorage getResourcesStorage();
347
    
348
    public StoresRepository getStoresRepository();
349

    
350
}
351