001/*
002 * Copyright 2021 Global Biodiversity Information Facility (GBIF)
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.gbif.dwc.terms;
017
018import java.io.Serializable;
019import java.net.URI;
020import java.util.ArrayList;
021import java.util.List;
022
023public enum GbifTerm implements Term, AlternativeNames, Serializable {
024  // row types
025
026  /**
027   * The <a href="http://rs.gbif.org/terms/1.0/Description">GBIF Taxon Description</a>
028   * extension row type.
029   */
030  Description(GbifTerm.GROUP_ROW_TYPE),
031
032  /**
033   * The <a href="http://rs.gbif.org/terms/1.0/Distribution">GBIF Species Distribution</a>
034   * extension row type.
035   */
036  Distribution(GbifTerm.GROUP_ROW_TYPE),
037
038  /**
039   * The <a href="http://rs.gbif.org/terms/1.0/Identifier">GBIF Alternative Identifiers</a>
040   * extension row type.
041   */
042  Identifier(GbifTerm.GROUP_ROW_TYPE),
043
044  /**
045   * The deprecated <a href="http://rs.gbif.org/terms/1.0/Image">GBIF Simple Images</a>
046   * extension row type.
047   */
048  Image(GbifTerm.GROUP_ROW_TYPE, "Images"),
049
050  /**
051   * The <a href="http://rs.gbif.org/terms/1.0/References">GBIF Literature References</a>
052   * extension row type.
053   */
054  Reference(GbifTerm.GROUP_ROW_TYPE, "References"),
055
056  /**
057   * The <a href="http://rs.gbif.org/terms/1.0/SpeciesProfile">GBIF Species Profile</a>
058   * extension row type.
059   */
060  SpeciesProfile(GbifTerm.GROUP_ROW_TYPE, "SpeciesMiniProfile", "SpeciesInfo", "SpeciesData", "SpeciesFactsheet"),
061
062  /**
063   * The <a href="http://rs.gbif.org/terms/1.0/TypesAndSpecimen">GBIF Types and Specimen</a>
064   * extension row type.
065   */
066  TypesAndSpecimen(GbifTerm.GROUP_ROW_TYPE, "Specimen", "Types", "TypeDesignation"),
067
068  /**
069   * The <a href="http://rs.gbif.org/terms/1.0/VernacularNames">GBIF Vernacular Names</a>
070   * extension row type.
071   */
072  VernacularName(GbifTerm.GROUP_ROW_TYPE, "VernacularNames", "Vernacular", "Vernaculars"),
073
074  /**
075   * The <a href="http://rs.gbif.org/terms/1.0/Multimedia">GBIF Simple Multimedia</a>
076   * extension row type.
077   */
078  Multimedia(GbifTerm.GROUP_ROW_TYPE),
079
080  /**
081   * The <a href="http://rs.gbif.org/terms/1.0/DNADerivedData">DNA Derived Data</a>
082   * extension row type.
083   */
084  DNADerivedData(GbifTerm.GROUP_ROW_TYPE),
085
086  /**
087   * The UUID key for the dataset registered in GBIF.
088   */
089  datasetKey(GbifTerm.GROUP_DATASET),
090
091  /**
092   * The ISO 3166 2-letter code of the country of the organization that publishes the dataset to which the occurrence belongs.
093   */
094  publishingCountry(GbifTerm.GROUP_DATASET),
095
096  /**
097   * Numerical, stable identifier assigned by GBIF to an Occurrence record.
098   */
099  gbifID(DwcTerm.GROUP_OCCURRENCE),
100
101  /**
102   * Timestamp of the last time the record was (re)interpreted by GBIF.
103   */
104  lastInterpreted(DwcTerm.GROUP_OCCURRENCE),
105
106  /**
107   * The uncertainty radius for the latitude and longitude in decimal degrees.
108   */
109  @Deprecated
110  coordinateAccuracy(DwcTerm.GROUP_OCCURRENCE),
111
112  /**
113   * Elevation in metres above sea level (altitude).
114   * <p>
115   * The elevation is the absolute vertical position of the observed location (z-coordinate).
116   * If depth is given or not will not impact the 3-dimensional position.
117   * For example a location 100m below the surface of a lake in 2000m altitude has a depth of 100 and
118   * an elevation of 1900.
119   * </p>
120   * <p>
121   * If minimum and maximum values are given the elevation is calculated using the equation:
122   * <code>(minimumElevationInMeters + maximumElevationInMeters) / 2</code>.
123   * For consistency and ease of use GBIF decided to always use a value in metres plus its accuracy instead of
124   * min/max values which are sometimes used in Darwin Core. See also depth & distanceAboveSurface.
125   * </p>
126   */
127  elevation(DwcTerm.GROUP_LOCATION),
128
129  /**
130   * Elevation accuracy is the uncertainty for the elevation in metres.
131   * <p>
132   * The elevation accuracy is calculated using the equation: <code>(maximumElevationInMeters - minimumElevationInMeters) / 2</code>
133   * in case a minimum and maximum verbatim value is given.
134   * </p>
135   */
136  elevationAccuracy(DwcTerm.GROUP_LOCATION),
137
138  /**
139   * Depth in metres below the surface.
140   * <p>
141   * Complimentary and relative to elevation, depth indicates the distance to the earth surface, whether that is water
142   * or ground.
143   * For example a location 100m below the surface of a lake in 2000m altitude has a depth of 100 and
144   * an elevation of 1900.
145   * </p>
146   * <p>
147   * The depth is calculated using the equation: <code>(minimumDepthInMeters + maximumDepthInMeters) / 2</code>.
148   * For consistency and ease of use GBIF decided to always use a value in meters plus it's accuracy instead of
149   * min/max values which are sometimes used in Darwin Core. See also elevation & distanceAboveSurface.
150   * </p>
151   */
152  depth(DwcTerm.GROUP_LOCATION),
153
154  /**
155   * Depth accuracy is the uncertainty for the depth in metres.
156   * <p>
157   * The depth accuracy is calculated using the equation: <code>(maximumDepthInMeters - minimumDepthInMeters) / 2</code>
158   * in case a minimum and maximum verbatim value is given.
159   * </p>
160   */
161  depthAccuracy(DwcTerm.GROUP_LOCATION),
162
163  /**
164   * Replaced by Darwin Core terms <a href="http://rs.tdwg.org/dwc/terms/minimumDistanceAboveSurfaceInMeters">dwc:minimumDistanceAboveSurfaceInMeters</a>
165   * and <a href="http://rs.tdwg.org/dwc/terms/maximumDistanceAboveSurfaceInMeters">dwc:maximumDistanceAboveSurfaceInMeters</a>.
166   */
167  @Deprecated
168  distanceAboveSurface(DwcTerm.GROUP_LOCATION),
169
170  /**
171   * Replaced by Darwin Core terms <a href="http://rs.tdwg.org/dwc/terms/minimumDistanceAboveSurfaceInMeters">dwc:minimumDistanceAboveSurfaceInMeters</a>
172   * and <a href="http://rs.tdwg.org/dwc/terms/maximumDistanceAboveSurfaceInMeters">dwc:maximumDistanceAboveSurfaceInMeters</a>.
173   */
174  @Deprecated
175  distanceAboveSurfaceAccuracy(DwcTerm.GROUP_LOCATION),
176
177  /**
178   * The distance in metres from a known centroid, e.g. a country centroid.
179   */
180  distanceFromCentroidInMeters(DwcTerm.GROUP_LOCATION),
181
182  /**
183   * Any issue found during processing and interpretation or the record.
184   * See <a href="https://gbif.github.io/gbif-api/apidocs/org/gbif/api/vocabulary/OccurrenceIssue.html">OccurrenceIssue enumeration</a> for possible values.
185   */
186  issue(DwcTerm.GROUP_OCCURRENCE),
187
188  /**
189   * Issue found during processing and interpretation or the record related to a specific checklist.
190   * See <a href="https://gbif.github.io/gbif-api/apidocs/org/gbif/api/vocabulary/OccurrenceIssue.html">OccurrenceIssue enumeration</a> for possible values.
191   */
192  taxonomicIssue(DwcTerm.GROUP_OCCURRENCE),
193
194  /**
195   * Issue found during processing and interpretation or the record that are non-taxonomic.
196   */
197  nonTaxonomicIssue(DwcTerm.GROUP_OCCURRENCE),
198
199  /**
200   * The environments the interpreted taxon is known to live in according to the checklist used,
201   * e.g. MARINE, BRACKISH, FRESHWATER or TERRESTRIAL. A property of the taxon, not of the occurrence.
202   */
203  environments(DwcTerm.GROUP_TAXON),
204
205  /**
206   * The media type given as Dublin Core type values, in particular StillImage, MovingImage or Sound.
207   */
208  mediaType(DwcTerm.GROUP_OCCURRENCE),
209
210  // experimental Occurrence properties
211  infraspecificMarker(DwcTerm.GROUP_OCCURRENCE),
212
213  // Types and Specimen checklist extension
214  typeDesignatedBy(DwcTerm.GROUP_OCCURRENCE),
215  typeDesignationType(DwcTerm.GROUP_OCCURRENCE),
216
217  /**
218   * Boolean indicating that a valid latitude and longitude exists.
219   * Even if existing it might still have issues, see hasGeospatialIssues and issue.
220   */
221  hasCoordinate(DwcTerm.GROUP_OCCURRENCE),
222
223  /**
224   * Boolean indicating that some spatial validation rule has not passed.
225   * Primarily used to indicate that the record should not be displayed on a map.
226   */
227  hasGeospatialIssues(DwcTerm.GROUP_OCCURRENCE),
228
229
230  /**
231   * The checklist key.
232   * <p>
233   * The taxonomic checklist to use when search using a taxonKey, a higher taxonKey e.g. phylumKey
234   * or when searching with a scientific name
235   * </p>
236   */
237  checklistKey(DwcTerm.GROUP_TAXON),
238
239  /**
240   * The GBIF backbone key.
241   * <p>
242   * The best matching, accepted GBIF backbone name usage representing this occurrence.
243   * In case the verbatim scientific name and its classification can only be matched to a higher rank this will
244   * represent the lowest matching rank. In the worst case this could just be for example Animalia.
245   * </p>
246   * <p>
247   * In contrast dwc:taxonID is only used for the source ids similar to occurrenceID
248   * </p>
249   */
250  taxonKey(DwcTerm.GROUP_TAXON),
251
252
253  /**
254   * The GBIF backbone key of the accepted taxon key.
255   */
256  acceptedTaxonKey(DwcTerm.GROUP_TAXON),
257
258  /**
259   * The key to the accepted kingdom in the taxonomy.
260   */
261  kingdomKey(DwcTerm.GROUP_TAXON),
262
263  /**
264   * The key to the accepted phylum in the taxonomy.
265   */
266  phylumKey(DwcTerm.GROUP_TAXON),
267
268  /**
269   * The key to the accepted class in the taxonomy.
270   */
271  classKey(DwcTerm.GROUP_TAXON),
272
273  /**
274   * The key to the accepted order in the taxonomy.
275   */
276  orderKey(DwcTerm.GROUP_TAXON),
277
278  /**
279   * The key to the accepted superfamily in the taxonomy.
280   */
281  superfamilyKey(DwcTerm.GROUP_TAXON),
282
283  /**
284   * The key to the accepted family in the taxonomy.
285   */
286  familyKey(DwcTerm.GROUP_TAXON),
287
288  /**
289   * The key to the accepted subfamily in the taxonomy.
290   */
291  subfamilyKey(DwcTerm.GROUP_TAXON),
292
293  /**
294   * The key to the accepted tribe in the taxonomy.
295   */
296  tribeKey(DwcTerm.GROUP_TAXON),
297
298  /**
299   * The key to the accepted subtribe in the taxonomy.
300   */
301  subtribeKey(DwcTerm.GROUP_TAXON),
302
303    /**
304   * The key to the accepted genus in the taxonomy.
305   */
306  genusKey(DwcTerm.GROUP_TAXON),
307
308  /**
309   * The key to the accepted subgenus in the taxonomy.
310   */
311  subgenusKey(DwcTerm.GROUP_TAXON),
312
313  /**
314   * The backbone key to the accepted species.
315   * In case the taxonKey is of a higher rank than species (e.g. genus) speciesKey is null.
316   * In case taxonKey represents an infraspecific taxon the speciesKey points to the species
317   * the infraspecies is classified as. In case of taxonKey being a species the speciesKey is the same.
318   */
319  speciesKey(DwcTerm.GROUP_TAXON),
320
321  /**
322   * The canonical name without authorship of the accepted species.
323   */
324  species(DwcTerm.GROUP_TAXON),
325
326  // experimental Taxon properties
327  canonicalName(DwcTerm.GROUP_TAXON),
328  nameType(DwcTerm.GROUP_TAXON),
329
330  /**
331   * The scientific name the type associated acceptedNubKey.
332   */
333  acceptedScientificName(DwcTerm.GROUP_TAXON),
334
335  /**
336   * Scientific name as provided by the source.
337   */
338  verbatimScientificName(DwcTerm.GROUP_TAXON),
339
340  /**
341   * The scientific name the type status of this specimen applies to.
342   * Term proposed in Darwin Core, but not yet ratified.
343   */
344  typifiedName(DwcTerm.GROUP_IDENTIFICATION),
345
346  /**
347   * The kind of protocol used when the record was last crawled by GBIF.
348   * See <a href="http://gbif.github.io/gbif-api/apidocs/org/gbif/api/vocabulary/EndpointType.html">EndpointType enumeration</a> for possible values.
349   */
350  protocol(GbifTerm.GROUP_CRAWLING),
351
352  /**
353   * The date this record was last parsed from raw xml/json into a verbatim GBIF record.
354   */
355  lastParsed(GbifTerm.GROUP_CRAWLING),
356
357  /**
358   * The date this record was last crawled/harvested by GBIF from the endpoint.
359   */
360  lastCrawled(GbifTerm.GROUP_CRAWLING),
361
362  // Species Profile checklist extension
363  isMarine(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION),
364  isFreshwater(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION),
365  isTerrestrial(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION),
366  isInvasive(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION),
367  isHybrid(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION),
368  isExtinct(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION),
369  livingPeriod(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION, "timePeriod"),
370  ageInDays(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION),
371  sizeInMillimeters(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION, "sizeInMillimeter"),
372  massInGrams(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION, "massInGram", "weightInGram"),
373  lifeForm(GbifTerm.GROUP_SPECIES_PROFILE_EXTENSION),
374
375  // Vernacular Name checklist extension
376  organismPart(GbifTerm.GROUP_VERNACULAR_NAME_EXTENSION),
377  isPlural(GbifTerm.GROUP_VERNACULAR_NAME_EXTENSION),
378  isPreferredName(GbifTerm.GROUP_VERNACULAR_NAME_EXTENSION),
379
380  // Distribution checklist extension
381  appendixCITES(GbifTerm.GROUP_SPECIES_DISTRIBUTION_EXTENSION),
382  numberOfOccurrences(GbifTerm.GROUP_SPECIES_DISTRIBUTION_EXTENSION),
383
384  /** Boolean indicating if the publishing country is different to the location country. */
385  repatriated(DwcTerm.GROUP_OCCURRENCE),
386
387  /** Calculated relative organism quantity, based on organism and sample measure types */
388  relativeOrganismQuantity(DwcTerm.GROUP_MATERIAL_SAMPLE),
389
390  /** Flag occurrence when associatedSequences/extension exists */
391  isSequenced(DwcTerm.GROUP_OCCURRENCE),
392
393  /** GBIF region based on country code */
394  gbifRegion(DwcTerm.GROUP_LOCATION),
395
396  /** GBIF region based on publishing country code */
397  publishedByGbifRegion(DwcTerm.GROUP_LOCATION),
398  geologicalTime(DwcTerm.GROUP_OCCURRENCE),
399  lithostratigraphy(DwcTerm.GROUP_OCCURRENCE),
400  biostratigraphy(DwcTerm.GROUP_OCCURRENCE),
401  dnaSequenceID(GbifTerm.GROUP_DNA_DERIVED_DATA),
402
403  /**
404   * The <a href="http://rs.tdwg.org/eco/terms/Event">Humboldt</a> extension row type.
405   */
406  Humboldt(GbifTerm.GROUP_ROW_TYPE);
407
408  private static final String PREFIX = "gbif";
409  private static final String NS = "http://rs.gbif.org/terms/1.0/";
410  private static final URI NS_URI = URI.create(NS);
411
412  public static final String GROUP_CRAWLING = "Crawling";
413  public static final String GROUP_DATASET = "Dataset";
414  public static final String GROUP_ROW_TYPE = "RowType";
415  public static final String GROUP_SPECIES_DISTRIBUTION_EXTENSION = "SpeciesDistribution";
416  public static final String GROUP_SPECIES_PROFILE_EXTENSION = "SpeciesProfile";
417  public static final String GROUP_VERNACULAR_NAME_EXTENSION = "VernacularName";
418  public static final String GROUP_DNA_DERIVED_DATA = "DnaDerivedData";
419  public static final String GROUP_HUMBOLDT = "Humboldt";
420
421  /**
422   * Lists all GBIF term groups.
423   */
424  public static final String[] GROUPS = {GROUP_CRAWLING, GROUP_DATASET, DwcTerm.GROUP_OCCURRENCE, GROUP_ROW_TYPE,
425    GROUP_SPECIES_DISTRIBUTION_EXTENSION, GROUP_SPECIES_PROFILE_EXTENSION, DwcTerm.GROUP_TAXON,
426    GROUP_VERNACULAR_NAME_EXTENSION, DwcTerm.GROUP_LOCATION};
427
428  /**
429   * Lists all GBIF terms in taxon group.
430   */
431  public static final GbifTerm[] TAXONOMIC_TERMS =
432  {GbifTerm.checklistKey, GbifTerm.taxonKey, GbifTerm.acceptedTaxonKey, GbifTerm.kingdomKey, GbifTerm.phylumKey,
433   GbifTerm.classKey, GbifTerm.orderKey, GbifTerm.superfamilyKey, GbifTerm.familyKey, GbifTerm.subfamilyKey,
434   GbifTerm.tribeKey, GbifTerm.subtribeKey, GbifTerm.genusKey, GbifTerm.subgenusKey, GbifTerm.speciesKey,
435   GbifTerm.species, GbifTerm.canonicalName, GbifTerm.nameType, GbifTerm.acceptedScientificName,
436   GbifTerm.verbatimScientificName, GbifTerm.environments};
437
438  private final String groupName;
439  private final boolean isDeprecated;
440  public final String[] normAlts;
441
442  GbifTerm(String groupName, String... alternatives) {
443    this.groupName = groupName;
444    this.normAlts = alternatives;
445    boolean deprecatedAnnotationPresent = false;
446    try {
447      deprecatedAnnotationPresent = GbifTerm.class.getField(this.name()).isAnnotationPresent(Deprecated.class);
448    } catch (NoSuchFieldException ignore) { }
449    this.isDeprecated = deprecatedAnnotationPresent;
450  }
451
452  /**
453   * The simple term name without a namespace.
454   * For example taxonKey.
455   *
456   * @return simple term name
457   */
458  @Override
459  public String simpleName() {
460    return name();
461  }
462
463  /**
464   * Array of alternative simple names in use for the term.
465   *
466   * @return simple term name
467   */
468  @Override
469  public String[] alternativeNames() {
470    return normAlts;
471  }
472
473  /**
474   * The optional group the term is grouped in.
475   * For example Occurrence, Taxon, etc.
476   */
477  public String getGroup() {
478    return groupName;
479  }
480
481
482  /**
483   * List all terms that belong to a given group.
484   *
485   * @param group the group to list terms for
486   * @return the list of GBIF terms in the given group
487   */
488  public static List<GbifTerm> listByGroup(String group) {
489    List<GbifTerm> terms = new ArrayList<GbifTerm>();
490    for (GbifTerm t : GbifTerm.values()) {
491      if (t.getGroup().equalsIgnoreCase(group)) {
492        terms.add(t);
493      }
494    }
495    return terms;
496  }
497
498  @Override
499  public String toString() {
500    return prefixedName();
501  }
502
503  @Override
504  public boolean isClass() {
505    return Character.isUpperCase(simpleName().charAt(0));
506  }
507
508  @Override
509  public String prefix() {
510    return PREFIX;
511  }
512
513  @Override
514  public URI namespace() {
515    return NS_URI;
516  }
517
518  /**
519   *
520   * @return true if the Term is annotated with @Deprecated.
521   */
522  public boolean isDeprecated(){
523    return isDeprecated;
524  }
525
526}