001 //$Header: /deegreerepository/deegree/src/org/deegree/io/datastore/Datastore.java,v 1.28 2007/01/16 13:58:34 mschneider Exp $
002 /*---------------- FILE HEADER ------------------------------------------
003
004 This file is part of deegree.
005 Copyright (C) 2001-2008 by:
006 EXSE, Department of Geography, University of Bonn
007 http://www.giub.uni-bonn.de/deegree/
008 lat/lon GmbH
009 http://www.lat-lon.de
010
011 This library is free software; you can redistribute it and/or
012 modify it under the terms of the GNU Lesser General Public
013 License as published by the Free Software Foundation; either
014 version 2.1 of the License, or (at your option) any later version.
015
016 This library is distributed in the hope that it will be useful,
017 but WITHOUT ANY WARRANTY; without even the implied warranty of
018 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019 Lesser General Public License for more details.
020
021 You should have received a copy of the GNU Lesser General Public
022 License along with this library; if not, write to the Free Software
023 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
024
025 Contact:
026
027 Andreas Poth
028 lat/lon GmbH
029 Aennchenstraße 19
030 53177 Bonn
031 Germany
032 E-Mail: poth@lat-lon.de
033
034 Prof. Dr. Klaus Greve
035 Department of Geography
036 University of Bonn
037 Meckenheimer Allee 166
038 53115 Bonn
039 Germany
040 E-Mail: greve@giub.uni-bonn.de
041
042 ---------------------------------------------------------------------------*/
043 package org.deegree.io.datastore;
044
045 import java.util.ArrayList;
046 import java.util.Collection;
047 import java.util.List;
048 import java.util.Set;
049
050 import org.deegree.datatypes.QualifiedName;
051 import org.deegree.framework.log.ILogger;
052 import org.deegree.framework.log.LoggerFactory;
053 import org.deegree.framework.trigger.TriggerProvider;
054 import org.deegree.i18n.Messages;
055 import org.deegree.io.datastore.schema.MappedFeatureType;
056 import org.deegree.io.datastore.schema.MappedGMLSchema;
057 import org.deegree.io.datastore.schema.content.MappingGeometryField;
058 import org.deegree.model.crs.CoordinateSystem;
059 import org.deegree.model.crs.UnknownCRSException;
060 import org.deegree.model.feature.Feature;
061 import org.deegree.model.feature.FeatureCollection;
062 import org.deegree.model.filterencoding.Filter;
063 import org.deegree.ogcwebservices.wfs.WFService;
064 import org.deegree.ogcwebservices.wfs.operation.Lock;
065 import org.deegree.ogcwebservices.wfs.operation.LockFeature;
066 import org.deegree.ogcwebservices.wfs.operation.Query;
067
068 /**
069 * A datastore implementation must extend this class.
070 * <p>
071 * Describes the access to a datastore that encapsulates the access to a database or file. The
072 * accessible objects are {@link Feature} instances. Primarily, datastores are used as persistence
073 * layer by the {@link WFService} class.
074 *
075 * @author <a href="mailto:poth@lat-lon.de">Andreas Poth </a>
076 * @author <a href="mailto:tfr@users.sourceforge.net">Torsten Friebe </a>
077 * @author <a href="mailto:schneider@lat-lon.de">Markus Schneider </a>
078 * @author last edited by: $Author: apoth $
079 *
080 * @version $Revision: 9342 $, $Date: 2007-12-27 13:32:57 +0100 (Do, 27 Dez 2007) $
081 */
082 public abstract class Datastore {
083
084 private static final TriggerProvider TP = TriggerProvider.create( Datastore.class );
085
086 protected static final ILogger LOG = LoggerFactory.getLogger( Datastore.class );
087
088 private Collection<MappedGMLSchema> schemas = new ArrayList<MappedGMLSchema>( 10 );
089
090 private DatastoreConfiguration config;
091
092 /**
093 * Returns the datastore specific annotation parser.
094 *
095 * @return the datastore specific annotation parser
096 */
097 public abstract AnnotationDocument getAnnotationParser ();
098
099 /**
100 * Configures the datastore with the supplied configuration.
101 *
102 * @param config
103 * configuration
104 * @throws DatastoreException
105 */
106 @SuppressWarnings("unused")
107 public void configure( DatastoreConfiguration config )
108 throws DatastoreException {
109 this.config = config;
110 }
111
112 /**
113 * Returns the configuration parameters of the datastore.
114 *
115 * @return the configuration parameters of the datastore
116 */
117 public DatastoreConfiguration getConfiguration() {
118 return this.config;
119 }
120
121 /**
122 * Adds the given GML application schema to the set of schemas that are handled by this
123 * datastore instance.
124 * <p>
125 * Note that this method may be called several times for every GML schema that uses this
126 * datastore instance.
127 *
128 * @param schema
129 * GML application schema to bind
130 * @throws DatastoreException
131 */
132 @SuppressWarnings("unused")
133 public void bindSchema( MappedGMLSchema schema )
134 throws DatastoreException {
135 this.schemas.add( schema );
136 }
137
138 /**
139 * Returns the GML application schemas that are handled by this datastore.
140 *
141 * @return the GML application schemas that are handled by this datastore
142 */
143 public MappedGMLSchema[] getSchemas() {
144 return this.schemas.toArray( new MappedGMLSchema[this.schemas.size()] );
145 }
146
147 /**
148 * Returns the feature type with the given name.
149 *
150 * @param ftName
151 * name of the feature type
152 * @return the feature type with the given name, or null if the <code>Datastore</code> does
153 * not this feature type
154 */
155 public MappedFeatureType getFeatureType( QualifiedName ftName ) {
156 MappedFeatureType ft = null;
157 MappedGMLSchema[] schemas = getSchemas();
158 for ( int i = 0; i < schemas.length; i++ ) {
159 ft = schemas[i].getFeatureType( ftName );
160 if ( ft != null ) {
161 break;
162 }
163 }
164 return ft;
165 }
166
167 /**
168 * Closes the datastore so it can free dependent resources.
169 *
170 * @throws DatastoreException
171 */
172 public abstract void close()
173 throws DatastoreException;
174
175 /**
176 * Performs a query against the datastore.
177 *
178 * @param query
179 * query to be performed
180 * @param rootFts
181 * the root feature types that are queried, more than one type means that the types
182 * are joined
183 * @return requested feature instances
184 * @throws DatastoreException
185 * @throws UnknownCRSException
186 */
187 public abstract FeatureCollection performQuery( final Query query, final MappedFeatureType[] rootFts )
188 throws DatastoreException, UnknownCRSException;
189
190 /**
191 * Performs a query against the datastore (in the given transaction context).
192 *
193 * @param query
194 * query to be performed
195 * @param rootFts
196 * the root feature types that are queried, more than one type means that the types
197 * are joined
198 * @param context
199 * context (used to specify the JDBCConnection, for example)
200 * @return requested feature instances
201 * @throws DatastoreException
202 * @throws UnknownCRSException
203 */
204 public abstract FeatureCollection performQuery( final Query query, final MappedFeatureType[] rootFts,
205 final DatastoreTransaction context )
206 throws DatastoreException, UnknownCRSException;
207
208 /**
209 * Determines the ids of all features to be locked by the given parts of a {@link LockFeature}
210 * request, this includes all descendant and super features of the targeted features as well.
211 *
212 * @param requestParts
213 * the parts of a <code>LockFeature</code> request that this <code>Datastore</code>
214 * is responsible for
215 * @return the ids of all features that have to be locked
216 * @throws DatastoreException
217 */
218 public Set<FeatureId> determineFidsToLock( @SuppressWarnings("unused")
219 List<Lock> requestParts )
220 throws DatastoreException {
221 throw new DatastoreException( Messages.getMessage( "DATASTORE_METHOD_UNSUPPORTED", this.getClass().getName(),
222 "#determineFeaturesToLock( LockFeature )" ) );
223 }
224
225 /**
226 * Acquires transactional access to the datastore instance. There's only one active transaction
227 * per datastore allowed.
228 *
229 * @return transaction object that allows to perform transactions operations on the datastore
230 * @throws DatastoreException
231 */
232 public DatastoreTransaction acquireTransaction()
233 throws DatastoreException {
234 throw new DatastoreException( Messages.getMessage( "DATASTORE_METHOD_UNSUPPORTED", this.getClass().getName(),
235 "#acquireTransaction()" ) );
236 }
237
238 /**
239 * Returns the transaction to the datastore. This makes the transaction available to other
240 * clients again (via {@link #acquireTransaction()}). Underlying resources (such as
241 * JDBCConnections are freed).
242 * <p>
243 * The transaction should be terminated, i.e. {@link DatastoreTransaction#commit()} or
244 * {@link DatastoreTransaction#rollback()} must have been called before.
245 *
246 * @param ta
247 * the DatastoreTransaction to be returned
248 * @throws DatastoreException
249 */
250 public void releaseTransaction( @SuppressWarnings("unused")
251 DatastoreTransaction ta )
252 throws DatastoreException {
253 throw new DatastoreException( Messages.getMessage( "DATASTORE_METHOD_UNSUPPORTED", this.getClass().getName(),
254 "#releaseTransaction()" ) );
255 }
256
257 /**
258 * Transforms the incoming {@link Query} so that the {@link CoordinateSystem} of all spatial
259 * arguments (BBOX, etc.) in the {@link Filter} match the SRS of the targeted
260 * {@link MappingGeometryField}s.
261 * <p>
262 * NOTE: If this transformation can be performed by the backend (e.g. by Oracle Spatial), this
263 * method should be overwritten to return the original input {@link Query}.
264 *
265 * @param query
266 * query to be transformed
267 * @return query with spatial arguments transformed to target SRS
268 */
269 protected Query transformQuery( Query query ) {
270 LOG.logDebug( "Transforming query." );
271 Object[] result = TP.doPreTrigger( this, query );
272 query = (Query) result[0];
273 return query;
274 }
275
276 /**
277 * Transforms the {@link FeatureCollection} so that the geometries of all contained geometry
278 * properties use the requested SRS.
279 *
280 * @param fc
281 * feature collection to be transformed
282 * @param targetSRS
283 * requested SRS
284 * @return transformed FeatureCollection
285 */
286 protected FeatureCollection transformResult( FeatureCollection fc, String targetSRS ) {
287 LOG.logDebug( "Transforming result to SRS '" + targetSRS + "'." );
288 Object[] result = TP.doPostTrigger( this, fc, targetSRS );
289 fc = (FeatureCollection) result[0];
290 return fc;
291 }
292
293 /**
294 * Returns whether the datastore is capable of performing a native coordinate transformation
295 * (using an SQL function call for example) into the given SRS.
296 * <p>
297 * <code>Datastore</code> implementations capable of performing native coordinate
298 * transformations must override this class.
299 *
300 * @param targetSRS
301 * target spatial reference system (usually "EPSG:XYZ")
302 * @return true, if the datastore can perform the coordinate transformation, false otherwise
303 */
304 protected boolean canTransformTo( @SuppressWarnings("unused")
305 String targetSRS ) {
306 return false;
307 }
308 }