001/*
002 * Copyright 2014 Global Biodiversity Information Facility (GBIF)
003 * Licensed under the Apache License, Version 2.0 (the "License");
004 * you may not use this file except in compliance with the License.
005 * You may obtain a copy of the License at
006 * http://www.apache.org/licenses/LICENSE-2.0
007 * Unless required by applicable law or agreed to in writing, software
008 * distributed under the License is distributed on an "AS IS" BASIS,
009 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
010 * See the License for the specific language governing permissions and
011 * limitations under the License.
012 */
013package org.gbif.api.model.occurrence.search;
014
015
016import org.gbif.api.model.common.search.SearchParameter;
017import org.gbif.api.vocabulary.BasisOfRecord;
018import org.gbif.api.vocabulary.Continent;
019import org.gbif.api.vocabulary.Country;
020import org.gbif.api.vocabulary.EndpointType;
021import org.gbif.api.vocabulary.EstablishmentMeans;
022import org.gbif.api.vocabulary.License;
023import org.gbif.api.vocabulary.MediaType;
024import org.gbif.api.vocabulary.OccurrenceIssue;
025import org.gbif.api.vocabulary.TypeStatus;
026
027import java.util.Date;
028import java.util.UUID;
029
030/**
031 * Supported query parameters by the occurrence search and download service.
032 * For download predicates only the numerical types support comparisons other than equals.
033 */
034public enum OccurrenceSearchParameter implements SearchParameter {
035
036  /**
037   * The dataset key as a uuid.
038   */
039  DATASET_KEY(UUID.class),
040
041  /**
042   * The 4 digit year. A year of 98 will be 98 after christ, no 1998.
043   * This parameter accepts comma separated range values, e.g.:
044   * <dl>
045   * <dt>*,1810</dt>
046   * <dd>Found before or equal to 1810</dd>
047   * <dt>1848,1933</dt>
048   * <dd>Year between 1848 and 1933</dd>
049   * </dl>
050   */
051  YEAR(Integer.class),
052
053  /**
054   * The month of the year, starting with 1 for January.
055   * A month query can be used to retrieve seasonal records when used without a year or a year range.
056   * This parameter accepts comma separated range values, e.g.:
057   * <dl>
058   * <dt>4,8</dt>
059   * <dd>Month between April and August</dd>
060   * </dl>
061   */
062  MONTH(Integer.class),
063
064
065  /**
066   * Event date (date the occurrence was recorded) in ISO 8601 formats:yyyy, yyyy-MM, yyyy-MM-dd and MM-dd.
067   * This parameter accepts comma separated range values, examples of valid ranges are:
068   * <dl>
069   * <dt>2001-02-11,2010-01-10</dt>
070   * <dd>Dates between 2001-02-11 and 2010-01-10</dd>
071   * <dt>2001-02,2010-01</dt>
072   * <dd>Dates between first day of 2001-02 and last day of 2010-01</dd>
073   * <dt>2001,2010</dt>
074   * <dd>Dates between first day of 2001 and last day of 2010</dd>
075   * <dt>2001,2010-01</dt>
076   * <dd>Dates between first day of 2001 and last day of 2010-01</dd>
077   * <dt>2001-01-10,2010</dt>
078   * <dd>Dates between 2001-01-10 and last day of 2010</dd>
079   * <dt>2001-01-10,*</dt>
080   * <dd>Dates after 2001-01-10</dd>
081   * <dt>*,2001-01-10</dt>
082   * <dd>Dates before 2001-01-10</dd>
083   * <dt>*</dt>
084   * <dd>all dates</dd>
085   * </dl>
086   */
087  EVENT_DATE(Date.class),
088
089  /**
090   * Last interpreted date in ISO 8601 formats:yyyy, yyyy-MM, yyyy-MM-dd and MM-dd.
091   * This parameter accepts comma separated range values, examples of valid ranges are:
092   * <dl>
093   * <dt>2001-02-11,2010-01-10</dt>
094   * <dd>Dates between 2001-02-11 and 2010-01-10</dd>
095   * <dt>2001-02,2010-01</dt>
096   * <dd>Dates between first day of 2001-02 and last day of 2010-01</dd>
097   * <dt>2001,2010</dt>
098   * <dd>Dates between first day of 2001 and last day of 2010</dd>
099   * <dt>2001,2010-01</dt>
100   * <dd>Dates between first day of 2001 and last day of 2010-01</dd>
101   * <dt>2001-01-10,2010</dt>
102   * <dd>Dates between 2001-01-10 and last day of 2010</dd>
103   * <dt>2001-01-10,*</dt>
104   * <dd>Dates after 2001-01-10</dd>
105   * <dt>*,2001-01-10</dt>
106   * <dd>Dates before 2001-01-10</dd>
107   * <dt>*</dt>
108   * <dd>all dates</dd>
109   * </dl>
110   */
111  LAST_INTERPRETED(Date.class),
112
113  /**
114   * Latitude in decimals between -90 and 90 based on WGS 84.
115   */
116  DECIMAL_LATITUDE(Double.class),
117
118  /**
119   * Longitude in decimals between -180 and 180 based on WGS 84.
120   */
121  DECIMAL_LONGITUDE(Double.class),
122
123  /**
124   * Country the occurrence was recorded in.
125   */
126  COUNTRY(Country.class),
127
128  /**
129   * Continent the occurrence was recorded in.
130   */
131  CONTINENT(Continent.class),
132
133  /**
134   * The country of the organization that publishes the dataset the occurrence belongs to.
135   */
136  PUBLISHING_COUNTRY(Country.class),
137
138  /**
139   * Altitude/elevation in meters above sea level.
140   * This parameter accepts comma separated range values, e.g.:
141   * <dl>
142   * <dt>*,100</dt>
143   * <dd>Altitude below or equals 100m</dd>
144   * <dt>100,*</dt>
145   * <dd>Altitude above or equals 100m</dd>
146   * <dt>-2,8.8</dt>
147   * <dd>Altitude between or equals -2m and 8.8m</dd>
148   * </dl>
149   */
150  ELEVATION(Double.class),
151
152  /**
153   * Depth in meters relative to altitude. For example 10 meters below a lake surface with given altitude.
154   * This parameter accepts comma separated range values, e.g.:
155   * <dl>
156   * <dt>*,10</dt>
157   * <dd>Depth below or equals 10m</dd>
158   * <dt>100,*</dt>
159   * <dd>Depth above or equals 100m</dd>
160   * <dt>12.1,28.8</dt>
161   * <dd>Depth between or equals 12.1m and 28.8m</dd>
162   * </dl>
163   */
164  DEPTH(Double.class),
165
166  /**
167   * An identifier of any form assigned by the source to identify the institution
168   * the record belongs to. Not guaranteed to be unique.
169   */
170  INSTITUTION_CODE(String.class),
171
172  /**
173   * An identifier of any form assigned by the source to identify the physical collection or digital dataset
174   * uniquely within the context of an institution.
175   */
176  COLLECTION_CODE(String.class),
177
178  /**
179   * An identifier of any form assigned by the source within a physical collection or digital dataset for the record
180   * which may not be unique, but should be fairly unique in combination with the institution and collection code.
181   */
182  CATALOG_NUMBER(String.class),
183
184  /**
185   * The person who recorded the occurrence.
186   */
187  RECORDED_BY(String.class),
188
189  /**
190   * An identifier given to the Occurrence at the time it was recorded.
191   */
192  RECORD_NUMBER(String.class),
193
194  /**
195   * A basis of record enumeration value.
196   */
197  BASIS_OF_RECORD(BasisOfRecord.class),
198
199  /**
200   * A taxon key from the GBIF backbone. All included and synonym taxa are included in the search, so a search for
201   * aves with taxonKey=212 will match all birds, no matter which species.
202   */
203  TAXON_KEY(Integer.class),
204
205  /**
206   * A kingdom key from the GBIF backbone.
207   */
208  KINGDOM_KEY(Integer.class),
209
210  /**
211   * A phylum key from the GBIF backbone.
212   */
213  PHYLUM_KEY(Integer.class),
214
215  /**
216   * A class key from the GBIF backbone.
217   */
218  CLASS_KEY(Integer.class),
219
220  /**
221   * A order key from the GBIF backbone.
222   */
223  ORDER_KEY(Integer.class),
224
225  /**
226   * A family key from the GBIF backbone.
227   */
228  FAMILY_KEY(Integer.class),
229
230  /**
231   * A genus key from the GBIF backbone.
232   */
233  GENUS_KEY(Integer.class),
234
235  /**
236   * A subgenus key from the GBIF backbone.
237   */
238  SUBGENUS_KEY(Integer.class),
239
240  /**
241   * A species key from the GBIF backbone.
242   */
243  SPECIES_KEY(Integer.class),
244
245  /**
246   * Searches the interpreted, full scientific name of the occurrence.
247   */
248  SCIENTIFIC_NAME(String.class),
249
250  /**
251   * Searches for occurrence records which contain a value on its coordinate fields (latitude and longitude).
252   * HAS_COORDINATE=true searches for occurrence records with a coordinate value.
253   * HAS_COORDINATE=false searches for occurrence records without a coordinate value.
254   */
255  HAS_COORDINATE(Boolean.class),
256
257
258  /**
259   * Geometry in <a href="http://en.wikipedia.org/wiki/Well-known_text">Well Known Text</a> (WKT) format.
260   * E.g.: POLYGON ((30.0 10.0, 10.12 20.23, 20 40, 40 40, 30 10)).
261   * Multi geometries like MULTIPOLYGON are not supported and multiple parameters should be used instead.
262   * Valid geometries are:
263   * <ul>
264   * <li>POINT</li>
265   * <li>LINESTRING</li>
266   * <li>POLYGON</li>
267   * <li>LINEARRING</li>
268   * </ul>
269   */
270  GEOMETRY(String.class),
271
272
273  /**
274   * Includes/excludes occurrence records which contain geospatial issues for their coordinate.
275   * See {@link org.gbif.api.vocabulary.OccurrenceIssue#GEOSPATIAL_RULES}
276   * HAS_GEOSPATIAL_ISSUE=true include records with spatial issues.
277   * HAS_GEOSPATIAL_ISSUE=false exclude records with spatial issues.
278   * The absence of this parameter returns any record with or without spatial issues.
279   */
280  HAS_GEOSPATIAL_ISSUE(Boolean.class),
281
282  /**
283   * Searches occurrence for those that have a specific issue.
284   */
285  ISSUE(OccurrenceIssue.class),
286
287  /**
288   * Nomenclatural type (type status, typified scientific name, publication) applied to the subject.
289   */
290  TYPE_STATUS(TypeStatus.class),
291
292
293  /**
294   * The kind of media object.
295   * Recommended terms from the DCMI Type Vocabulary are StillImage, Sound or MovingImage for GBIF to index and show the
296   * media files.
297   */
298  MEDIA_TYPE(MediaType.class),
299
300  /**
301   *  An identifier for the Occurrence (as opposed to a particular digital record of the occurrence).
302   *  In the absence of a persistent global unique identifier, construct one from a combination of identifiers in the
303   *  record that will most closely make the occurrenceID globally unique.
304   */
305  OCCURRENCE_ID(String.class),
306
307  /**
308   * The process by which the biological individual(s) represented in the Occurrence became established at the location.
309   */
310  ESTABLISHMENT_MEANS(EstablishmentMeans.class),
311
312  /**
313   * Searches for records whose publishing country is different to the country where the record was recorded in.
314   */
315  REPATRIATED(Boolean.class),
316
317  /**
318   * An identifier for the Organism instance (as opposed to a particular digital record of the Organism).
319   * May be a globally unique identifier or an identifier specific to the data set.
320   */
321  ORGANISM_ID(String.class),
322
323  /**
324   * The name of the next smaller administrative region than country in which the Location occurs.
325   */
326  STATE_PROVINCE(String.class),
327
328  /**
329   * The name of the water body in which the Location occurs.
330   */
331  WATER_BODY(String.class),
332
333  /**
334   * The specific description of the place.
335   * It may contain information modified from the original to correct perceived errors or standardize the description.
336   */
337  LOCALITY(String.class),
338
339  /**
340   * Protocol used to provide the occurrence record.
341   */
342  PROTOCOL(EndpointType.class),
343
344  /**
345   * The license applied to the dataset.
346   */
347  LICENSE(License.class),
348
349  /**
350   * The owning organizations uuid key.
351   */
352  PUBLISHING_ORG(UUID.class),
353
354  /**
355   * Crawl attempt that harvested this record.
356   */
357  CRAWL_ID(UUID.class);
358
359  private final Class<?> type;
360
361  private OccurrenceSearchParameter(Class<?> type) {
362    this.type = type;
363  }
364
365  /**
366   * @return the data type expected for the value of the respective search parameter
367   */
368  public Class<?> type() {
369    return type;
370  }
371
372}