001: //$HeadURL: https://svn.wald.intevation.org/svn/deegree/base/trunk/src/org/deegree/ogcwebservices/wfs/operation/Query.java $
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.ogcwebservices.wfs.operation;
044:
045: import org.deegree.datatypes.QualifiedName;
046: import org.deegree.framework.xml.XMLParsingException;
047: import org.deegree.model.filterencoding.Filter;
048: import org.deegree.model.filterencoding.Function;
049: import org.deegree.ogcbase.PropertyPath;
050: import org.deegree.ogcbase.SortProperty;
051: import org.deegree.ogcwebservices.wfs.operation.GetFeature.RESULT_TYPE;
052: import org.w3c.dom.Element;
053:
054: /**
055: * Represents a <code>Query</code> operation as a part of a {@link GetFeature} request.
056: *
057: * Each individual query packaged in a {@link GetFeature} request is defined using the query value.
058: * The query value defines which feature type to query, what properties to retrieve and what
059: * constraints (spatial and non-spatial) to apply to those properties.
060: * <p>
061: * The mandatory <code>typeName</code> attribute is used to indicate the name of one or more
062: * feature type instances or class instances to be queried. Its value is a list of
063: * namespace-qualified names (XML Schema type QName, e.g. myns:School) whose value must match one of
064: * the feature types advertised in the Capabilities document of the WFS. Specifying more than one
065: * typename indicates that a join operation is being performed. All the names in the typeName list
066: * must be valid types that belong to this query's feature content as defined by the GML Application
067: * Schema. Optionally, individual feature type names in the typeName list may be aliased using the
068: * format QName=Alias. The following is an example typeName value that indicates that a join
069: * operation is to be performed and includes aliases: <BR>
070: * <code>typeName="ns1:InwaterA_1m=A,ns1:InwaterA_1m=B,ns2:CoastL_1M=C"</code><BR>
071: * This example encodes a join between three feature types aliased as A, B and C. The join between
072: * feature type A and B is a self-join.
073: * </p>
074: *
075: * @author <a href="mailto:poth@lat-lon.de">Andreas Poth </a>
076: * @author <a href="mailto:schneider@lat-lon.de">Markus Schneider </a>
077: * @author last edited by: $Author: apoth $
078: *
079: * @version $Revision: 9345 $, $Date: 2007-12-27 08:22:25 -0800 (Thu, 27 Dec 2007) $
080: */
081: public class Query {
082:
083: private String handle;
084:
085: private QualifiedName[] typeNames;
086:
087: private String[] aliases;
088:
089: private String featureVersion;
090:
091: private String srsName;
092:
093: private PropertyPath[] propertyNames;
094:
095: private Function[] functions;
096:
097: private Filter filter;
098:
099: private SortProperty[] sortProperties;
100:
101: // deegree specific extension ("inherited" from GetFeature container)
102: private RESULT_TYPE resultType;
103:
104: // deegree specific extension ("inherited" from GetFeature container)
105: private int maxFeatures = -1;
106:
107: // deegree specific extension ("inherited" from GetFeature container)
108: private int startPosition = 1;
109:
110: /**
111: * Creates a new <code>Query</code> instance.
112: *
113: * @param propertyNames
114: * names of the requested properties, may be null or empty
115: * @param functions
116: * names of the requested functions, may be null or empty
117: * @param sortProperties
118: * sort criteria, may be null or empty
119: * @param handle
120: * client-generated identifier for the query, may be null
121: * @param featureVersion
122: * version of the feature instances to fetched, may be null
123: * @param typeNames
124: * list of requested feature types
125: * @param aliases
126: * list of aliases for the feature types, must either be null or have the same length
127: * as the typeNames array
128: * @param srsName
129: * name of the spatial reference system
130: * @param filter
131: * spatial and none-spatial constraints
132: * @param resultType
133: * deegree specific extension ("inherited" from GetFeature container)
134: * @param maxFeatures
135: * deegree specific extension ("inherited" from GetFeature container)
136: * @param startPosition
137: * deegree specific extension ("inherited" from GetFeature container)
138: */
139: Query(PropertyPath[] propertyNames, Function[] functions,
140: SortProperty[] sortProperties, String handle,
141: String featureVersion, QualifiedName[] typeNames,
142: String[] aliases, String srsName, Filter filter,
143: RESULT_TYPE resultType, int maxFeatures, int startPosition) {
144: if (propertyNames == null) {
145: this .propertyNames = new PropertyPath[0];
146: // this.propertyNames[0] = new PropertyPath( typeNames[0] );
147: } else {
148: this .propertyNames = propertyNames;
149: }
150: this .functions = functions;
151: this .sortProperties = sortProperties;
152: this .handle = handle;
153: this .featureVersion = featureVersion;
154: this .typeNames = typeNames;
155: this .aliases = aliases;
156: assert aliases == null || aliases.length == typeNames.length;
157: this .srsName = srsName;
158: this .filter = filter;
159: this .resultType = resultType;
160: this .maxFeatures = maxFeatures;
161: this .startPosition = startPosition;
162: }
163:
164: /**
165: * Creates a new <code>Query</code> instance.
166: *
167: * @param propertyNames
168: * names of the requested properties, may be null or empty
169: * @param functions
170: * names of the requested functions, may be null or empty
171: * @param sortProperties
172: * sort criteria, may be null or empty
173: * @param handle
174: * client-generated identifier for the query, may be null
175: * @param featureVersion
176: * version of the feature instances to fetched, may be null
177: * @param typeNames
178: * list of requested feature types. if more than one feature types is set a JOIN will
179: * be created (not yet supported)
180: * @param srsName
181: * name of the spatial reference system
182: * @param filter
183: * spatial and none-spatial constraints
184: * @param resultType
185: * deegree specific extension ("inherited" from GetFeature container)
186: * @param maxFeatures
187: * deegree specific extension ("inherited" from GetFeature container)
188: * @param startPosition
189: * deegree specific extension ("inherited" from GetFeature container)
190: * @return new <code>Query</code> instance
191: * @deprecated use
192: * {@link #create(PropertyPath[], Function[], SortProperty[], String, String, QualifiedName[], String, Filter, int, int, RESULT_TYPE)}
193: * instead
194: */
195: @Deprecated
196: public static Query create(PropertyPath[] propertyNames,
197: Function[] functions, SortProperty[] sortProperties,
198: String handle, String featureVersion,
199: QualifiedName[] typeNames, String srsName, Filter filter,
200: int maxFeatures, int startPosition, RESULT_TYPE resultType) {
201: return new Query(propertyNames, functions, sortProperties,
202: handle, featureVersion, typeNames, null, srsName,
203: filter, resultType, maxFeatures, startPosition);
204: }
205:
206: /**
207: * Creates a new <code>Query</code> instance.
208: *
209: * @param propertyNames
210: * names of the requested properties, may be null or empty
211: * @param functions
212: * names of the requested functions, may be null or empty
213: * @param sortProperties
214: * sort criteria, may be null or empty
215: * @param handle
216: * client-generated identifier for the query, may be null
217: * @param featureVersion
218: * version of the feature instances to fetched, may be null
219: * @param typeNames
220: * list of requested feature types. if more than one feature types is set a JOIN will
221: * be created (not yet supported)
222: * @param aliases
223: * list of aliases for the feature types, must either be null or have the same length
224: * as the typeNames array
225: * @param srsName
226: * name of the spatial reference system
227: * @param filter
228: * spatial and none-spatial constraints
229: * @param resultType
230: * deegree specific extension ("inherited" from GetFeature container)
231: * @param maxFeatures
232: * deegree specific extension ("inherited" from GetFeature container)
233: * @param startPosition
234: * deegree specific extension ("inherited" from GetFeature container)
235: * @return new <code>Query</code> instance
236: */
237: public static Query create(PropertyPath[] propertyNames,
238: Function[] functions, SortProperty[] sortProperties,
239: String handle, String featureVersion,
240: QualifiedName[] typeNames, String[] aliases,
241: String srsName, Filter filter, int maxFeatures,
242: int startPosition, RESULT_TYPE resultType) {
243: return new Query(propertyNames, functions, sortProperties,
244: handle, featureVersion, typeNames, aliases, srsName,
245: filter, resultType, maxFeatures, startPosition);
246: }
247:
248: /**
249: * Creates a new simple <code>Query</code> instance that selects the whole feature type.
250: *
251: * @param typeName
252: * name of the feature to be queried
253: * @return new <code>Query</code> instance
254: */
255: public static Query create(QualifiedName typeName) {
256: return new Query(null, null, null, null, null,
257: new QualifiedName[] { typeName }, null, null, null,
258: RESULT_TYPE.RESULTS, -1, 0);
259: }
260:
261: /**
262: * Creates a new simple <code>Query</code> instance that selects the whole feature type.
263: *
264: * @param typeName
265: * name of the feature to be queried
266: * @param filter
267: * spatial and none-spatial constraints
268: * @return new <code>Query</code> instance
269: */
270: public static Query create(QualifiedName typeName, Filter filter) {
271: return new Query(null, null, null, null, null,
272: new QualifiedName[] { typeName }, null, null, filter,
273: RESULT_TYPE.RESULTS, -1, 0);
274: }
275:
276: /**
277: * Creates a <code>Query</code> instance from a document that contains the DOM representation
278: * of the request, using the 1.1.0 filter encoding.
279: * <p>
280: * Note that the following attributes from the surrounding element are also considered (if it
281: * present):
282: * <ul>
283: * <li>resultType</li>
284: * <li>maxFeatures</li>
285: * <li>startPosition</li>
286: * </ul>
287: *
288: * @param element
289: * @return corresponding <code>Query</code> instance
290: * @throws XMLParsingException
291: */
292: public static Query create(Element element)
293: throws XMLParsingException {
294: return create(element, false);
295: }
296:
297: /**
298: * Creates a <code>Query</code> instance from a document that contains the DOM representation
299: * of the request.
300: * <p>
301: * Note that the following attributes from the surrounding element are also considered (if it
302: * present):
303: * <ul>
304: * <li>resultType</li>
305: * <li>maxFeatures</li>
306: * <li>startPosition</li>
307: * </ul>
308: *
309: * @param element
310: * @param useVersion_1_0_0 if the filterencoding 1.0.0 rules should be applied.
311: * @return corresponding <code>Query</code> instance
312: * @throws XMLParsingException
313: */
314: public static Query create(Element element, boolean useVersion_1_0_0)
315: throws XMLParsingException {
316:
317: GetFeatureDocument doc = new GetFeatureDocument();
318: Query query = doc.parseQuery(element, useVersion_1_0_0);
319: return query;
320: }
321:
322: /**
323: * Returns the handle attribute.
324: * <p>
325: * The handle attribute is included to allow a client to associate a mnemonic name to the query.
326: * The purpose of the handle attribute is to provide an error handling mechanism for locating a
327: * statement that might fail.
328: *
329: * @return the handle attribute
330: */
331: public String getHandle() {
332: return this .handle;
333: }
334:
335: /**
336: * Returns the names of the requested feature types.
337: *
338: * @return the names of the requested feature types
339: */
340: public QualifiedName[] getTypeNames() {
341: return this .typeNames;
342: }
343:
344: /**
345: * Returns the aliases for the requested feature types.
346: * <p>
347: * The returned array is either null or has the same length as the array returned by
348: * {@link #getTypeNames()}.
349: *
350: * @see #getTypeNames()
351: * @return the aliases for the requested feature types, or null if no aliases are used
352: */
353: public String[] getAliases() {
354: return this .aliases;
355: }
356:
357: /**
358: * Returns the srsName attribute.
359: *
360: * @return the srsName attribute
361: */
362: public String getSrsName() {
363: return this .srsName;
364: }
365:
366: /**
367: * Sets the srsName attribute to given value.
368: *
369: * @param srsName
370: * name of the requested SRS
371: */
372: public void setSrsName(String srsName) {
373: this .srsName = srsName;
374: }
375:
376: /**
377: * Returns the featureVersion attribute.
378: *
379: * The version attribute is included in order to accommodate systems that support feature
380: * versioning. A value of ALL indicates that all versions of a feature should be fetched.
381: * Otherwise an integer can be specified to return the n th version of a feature. The version
382: * numbers start at '1' which is the oldest version. If a version value larger than the largest
383: * version is specified then the latest version is return. The default action shall be for the
384: * query to return the latest version. Systems that do not support versioning can ignore the
385: * parameter and return the only version that they have.
386: *
387: * @return the featureVersion attribute
388: */
389: public String getFeatureVersion() {
390: return this .featureVersion;
391: }
392:
393: /**
394: * Returns all requested properties.
395: *
396: * @return all requested properties
397: *
398: * @see #getFunctions()
399: */
400: public PropertyPath[] getPropertyNames() {
401: return this .propertyNames;
402: }
403:
404: /**
405: * Beside property names a query may contains 0 to n functions modifying the values of one or
406: * more original properties. E.g. instead of area and population the density of a country can be
407: * requested by using a function instead:
408: *
409: * <pre>
410: * <ogc:Div>
411: * <ogc:PropertyName>population</ogc:PropertyName>
412: * <ogc:PropertyName>area</ogc:PropertyName>
413: * </ogc:Div>
414: * </pre>
415: *
416: * <p>
417: * If no functions and no property names are specified all properties should be fetched.
418: * </p>
419: *
420: * @return requested functions
421: *
422: * @see #getPropertyNames()
423: */
424: public Function[] getFunctions() {
425: return this .functions;
426: }
427:
428: /**
429: * Returns the filter that limits the query.
430: *
431: * @return the filter that limits the query
432: */
433: public Filter getFilter() {
434: return this .filter;
435: }
436:
437: /**
438: * Returns the sort criteria for the result.
439: *
440: * @return the sort criteria for the result
441: */
442: public SortProperty[] getSortProperties() {
443: return this .sortProperties;
444: }
445:
446: /**
447: * Returns the value of the resultType attribute ("inherited" from the GetFeature container).
448: *
449: * @return the value of the resultType attribute
450: */
451: public RESULT_TYPE getResultType() {
452: return this .resultType;
453: }
454:
455: /**
456: * Returns the value of the maxFeatures attribute ("inherited" from the GetFeature container).
457: *
458: * The optional maxFeatures attribute can be used to limit the number of features that a
459: * GetFeature request retrieves. Once the maxFeatures limit is reached, the result set is
460: * truncated at that point. If not limit is set -1 will be returned
461: *
462: * @return the value of the maxFeatures attribute
463: */
464: public int getMaxFeatures() {
465: return this .maxFeatures;
466: }
467:
468: /**
469: * @param maxFeatures
470: */
471: public void setMaxFeatures(int maxFeatures) {
472: this .maxFeatures = maxFeatures;
473: }
474:
475: /**
476: * Returns the value of the startPosition attribute ("inherited" from the GetFeature container).
477: * <p>
478: * The startPosition parameter identifies the first result set entry to be returned. If no
479: * startPosition is set explicitly, 1 will be returned.
480: *
481: * @return the value of the startPosition attribute, 1 if undefined
482: */
483: public int getStartPosition() {
484: return this .startPosition;
485: }
486:
487: /**
488: * @see #getStartPosition()
489: * @param startPosition
490: */
491: public void setStartPosition(int startPosition) {
492: this .startPosition = startPosition;
493: }
494:
495: /**
496: * Returns a string representation of the object.
497: *
498: * @return a string representation of the object
499: */
500: @Override
501: public String toString() {
502: String ret = null;
503: ret = "propertyNames = " + propertyNames + "\n";
504: ret += ("handle = " + handle + "\n");
505: ret += ("version = " + featureVersion + "\n");
506: ret += ("typeName = " + typeNames + "\n");
507: ret += ("filter = " + filter + "\n");
508: return ret;
509: }
510: }
|