001/*
002 * Licensed under the Apache License, Version 2.0 (the "License");
003 * you may not use this file except in compliance with the License.
004 * You may obtain a copy of the License at
005 *
006 *     http://www.apache.org/licenses/LICENSE-2.0
007 *
008 * Unless required by applicable law or agreed to in writing, software
009 * distributed under the License is distributed on an "AS IS" BASIS,
010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011 * See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014package org.gbif.api.model.checklistbank;
015
016import org.gbif.api.vocabulary.Rank;
017import org.gbif.api.vocabulary.TypeDesignationType;
018import org.gbif.api.vocabulary.TypeStatus;
019
020import java.util.Objects;
021import java.util.StringJoiner;
022
023import javax.annotation.Nullable;
024
025import io.swagger.v3.oas.annotations.media.Schema;
026
027/**
028 * TypeSpecimen Model originally designed for both specimens and types, including type specimens, type species and type genera and simple
029 * specimens unrelated to types.
030 *
031 * Since the initial release of the GBIF API version 1.0 ChecklistBank has been modified to only store type species or type genera.
032 * All specimens including types are stored in the Occurrence store, hence the majority of properties in this class are now deprecated!
033 *
034 * @see <a href="http://rs.gbif.org/extension/gbif/1.0/typesandspecimen.xml">Types And Specimen Definition</a>
035 */
036@SuppressWarnings("unused")
037public class TypeSpecimen implements NameUsageExtension {
038
039  private Integer taxonKey;
040  private String source;
041  private Integer sourceTaxonKey;
042  private TypeDesignationType typeDesignationType;
043  private String typeDesignatedBy;
044  private String scientificName;
045  private Rank taxonRank;
046
047  @Deprecated
048  private TypeStatus typeStatus;
049  @Deprecated
050  private String citation;
051  @Deprecated
052  private String verbatimLabel;
053  @Deprecated
054  private String locality;
055  @Deprecated
056  private String recordedBy;
057  @Deprecated
058  private String verbatimEventDate;
059  @Deprecated
060  private String verbatimLongitude;
061  @Deprecated
062  private String verbatimLatitude;
063  @Deprecated
064  private String occurrenceId;
065  @Deprecated
066  private String institutionCode;
067  @Deprecated
068  private String collectionCode;
069  @Deprecated
070  private String catalogNumber;
071
072  /**
073   * The name usage "taxon" key this description belongs to.
074   */
075  @Schema(description = "The name usage “taxon“ to which this type specimen belongs.")
076  @Override
077  public Integer getTaxonKey() {
078    return taxonKey;
079  }
080
081  @Override
082  public void setTaxonKey(Integer taxonKey) {
083    this.taxonKey = taxonKey;
084  }
085
086  /**
087   * An identifier (preferably unique) for the record within the data set or collection.
088   * <blockquote>
089   * <p>
090   * <i>Examples:</i> "2008.1334", "145732a", "145732".
091   * </p>
092   * </blockquote>
093   *
094   * @return the catalogNumber
095   */
096  @Schema(description = "An identifier, preferable unique, for the record within the dataset or collection.")
097  @Nullable
098  @Deprecated
099  public String getCatalogNumber() {
100    return catalogNumber;
101  }
102
103  /**
104   * @param catalogNumber the catalogNumber to set.
105   */
106  @Deprecated
107  public void setCatalogNumber(String catalogNumber) {
108    this.catalogNumber = catalogNumber;
109  }
110
111  /**
112   * A text string citing the described specimen. Often found in taxonomic treatments and frequently based on
113   * institution code and catalog number.
114   * <blockquote>
115   * <p>
116   * <i>Examples:</i> Iraq: Mosul: Jabal Khantur prope Sharanish N. Zakho, in fissures rupium calc., 1200 m, Rech.
117   * 12083. (W!).
118   * </p>
119   * </blockquote>
120   *
121   * @return the citation
122   */
123  @Schema(description = "A text string citing the described speciemn.")
124  @Nullable
125  @Deprecated
126  public String getCitation() {
127    return citation;
128  }
129
130  /**
131   * @param citation the citation to set
132   */
133  @Deprecated
134  public void setCitation(String citation) {
135    this.citation = citation;
136  }
137
138  /**
139   * The name, acronym, coden, or initialism identifying the collection or data set from which the record was derived.
140   * <blockquote>
141   * <p>
142   * <i>Examples:</i> "Mammals", "Hildebrandt", "eBird".
143   * </p>
144   * </blockquote>
145   *
146   * @return the collectionCode
147   */
148  @Schema(description = "The name, acronym, code or initialism identifying the collection or dataset from which the " +
149    "record was derived.")
150  @Nullable
151  @Deprecated
152  public String getCollectionCode() {
153    return collectionCode;
154  }
155
156  /**
157   * @param collectionCode the collectionCode to set
158   */
159  @Deprecated
160  public void setCollectionCode(String collectionCode) {
161    this.collectionCode = collectionCode;
162  }
163
164  /**
165   * The name (or acronym) in use by the institution having custody of the object(s) or information referred to in the
166   * record.
167   * <blockquote>
168   * <p>
169   * <i>Examples:</i> "MVZ", "FMNH", "AKN-CLO", "University of California Museum of Paleontology (UCMP)".
170   * </p>
171   * </blockquote>
172   *
173   * @return the institutionCode
174   */
175  @Schema(description = "The name or acronym in use by the institution having custody of the type specimen or " +
176    "information referred to in the record.")
177  @Nullable
178  @Deprecated
179  public String getInstitutionCode() {
180    return institutionCode;
181  }
182
183  /**
184   * @param institutionCode the institutionCode to set
185   */
186  @Deprecated
187  public void setInstitutionCode(String institutionCode) {
188    this.institutionCode = institutionCode;
189  }
190
191  /**
192   * The location where the specimen was collected. In case of type specimens the type locality.
193   * <blockquote>
194   * <p>
195   * <i>Examples:</i> Iraq: Mosul: Jabal Khantur prope Sharanish N. Zakho, in fissures rupium calc., 1200 m.
196   * </p>
197   * </blockquote>
198   *
199   * @return the locality
200   */
201  @Schema(description = "The locality where the type specimen was collected, the type locality.")
202  @Nullable
203  @Deprecated
204  public String getLocality() {
205    return locality;
206  }
207
208  /**
209   * @param locality the locality to set
210   */
211  @Deprecated
212  public void setLocality(String locality) {
213    this.locality = locality;
214  }
215
216  /**
217   * An identifier for the specimen, preferably a resolvable globally unique identifier.
218   *
219   * @return the occurrenceId
220   */
221  @Schema(description = "An identifier for the specimen, preferable a resolvable, globally-unique identifier.")
222  @Nullable
223  @Deprecated
224  public String getOccurrenceId() {
225    return occurrenceId;
226  }
227
228  /**
229   * @param occurrenceId the occurrenceId to set
230   */
231  @Deprecated
232  public void setOccurrenceId(String occurrenceId) {
233    this.occurrenceId = occurrenceId;
234  }
235
236  /**
237   * The primary collector or observer, especially one who applies a personal identifier (recordNumber), should be
238   * listed first.
239   * <blockquote>
240   * <p>
241   * <i>Examples:</i> KH Rechinger.
242   * </p>
243   * </blockquote>
244   *
245   * @return the recordedBy
246   */
247  @Schema(description = "The primary collector or observer, especially one who applied a personal identifier " +
248    "(recordNumber), should be listed first.")
249  @Nullable
250  @Deprecated
251  public String getRecordedBy() {
252    return recordedBy;
253  }
254
255  /**
256   * @param recordedBy the recordedBy to set
257   */
258  @Deprecated
259  public void setRecordedBy(String recordedBy) {
260    this.recordedBy = recordedBy;
261  }
262
263  /**
264   * The scientific name originally used for the specimen, species or genus. Not necessarily the same as the currently
265   * recognized name. For type species this is the species name.
266   * <blockquote>
267   * <p>
268   * <i>Examples:</i> "Ctenomys sociabilis" - "Roptrocerus typographi (Györfi, 1952)".
269   * </p>
270   * </blockquote>
271   *
272   * @return the scientificName
273   */
274  @Schema(description = "The scientific name originally used for the specimen, species or genus.\n\n" +
275    "Not necessarily the same as the currently recognized name.  For type species this is the species name.")
276  @Nullable
277  public String getScientificName() {
278    return scientificName;
279  }
280
281  /**
282   * @param scientificName the scientificName to set
283   */
284  public void setScientificName(String scientificName) {
285    this.scientificName = scientificName;
286  }
287
288  /**
289   * The source.
290   *
291   * @return the source
292   */
293  @Schema(description = "Bibliographic citation referencing a source for the type specimen.")
294  @Nullable
295  @Override
296  public String getSource() {
297    return source;
298  }
299
300  /**
301   * @param source the source to set
302   */
303  @Override
304  public void setSource(String source) {
305    this.source = source;
306  }
307
308  @Schema(description = "The name usage key of the taxon in the checklist including this type specimen.")
309  @Nullable
310  @Override
311  public Integer getSourceTaxonKey() {
312    return sourceTaxonKey;
313  }
314
315  @Override
316  public void setSourceTaxonKey(Integer sourceTaxonKey) {
317    this.sourceTaxonKey = sourceTaxonKey;
318  }
319
320  /**
321   * The rank of the taxon bearing the scientific name.
322   *
323   * @return the taxonRank
324   */
325  @Schema(description = "The rank of the taxon bearing the scientific name.")
326  public Rank getTaxonRank() {
327    return taxonRank;
328  }
329
330  /**
331   * @param taxonRank the taxonRank to set
332   */
333  public void setTaxonRank(Rank taxonRank) {
334    this.taxonRank = taxonRank;
335  }
336
337  /**
338   * The citation of the publication where the type designation is found.
339   * <blockquote>
340   * <p>
341   * <i>Examples:</i> Vachal, J. (1897) Éclaircissements sur de genre Scrapter et description d’une espéce nouvelle de
342   * Dufourea. Bulletin de la Société Entomologique de France, 1897, 61–64.
343   * </p>
344   * </blockquote>
345   *
346   * @return the typeDesignatedBy
347   */
348  @Schema(description = "The citation of the publication where the type designation is found.")
349  @Nullable
350  public String getTypeDesignatedBy() {
351    return typeDesignatedBy;
352  }
353
354  /**
355   * @param typeDesignatedBy the typeDesignatedBy to set
356   */
357  public void setTypeDesignatedBy(String typeDesignatedBy) {
358    this.typeDesignatedBy = typeDesignatedBy;
359  }
360
361  /**
362   * The reason why this specimen or name is designated as a type.
363   * <blockquote>
364   * <p>
365   * <i>Examples:</i> monotypy, original designation, tautonomy.
366   * </p>
367   * </blockquote>
368   *
369   * @return the typeDesignationType
370   */
371  @Schema(description = "The reason why this specimen is designated as a type.")
372  @Nullable
373  public TypeDesignationType getTypeDesignationType() {
374    return typeDesignationType;
375  }
376
377  /**
378   * @param typeDesignationType the typeDesignationType to set
379   */
380  public void setTypeDesignationType(TypeDesignationType typeDesignationType) {
381    this.typeDesignationType = typeDesignationType;
382  }
383
384  /**
385   * The type status of the specimen, not used for type species or type genus.
386   * <blockquote>
387   * <p>
388   * <i>Examples:</i> holotype, syntype, lectotype, type species.
389   * </p>
390   * </blockquote>
391   *
392   * @return the typeStatus
393   */
394  @Schema(description = "The type status of the specimen, not used for type species or type genera.")
395  @Nullable
396  @Deprecated
397  public TypeStatus getTypeStatus() {
398    return typeStatus;
399  }
400
401  /**
402   * @param typeStatus the typeStatus to set
403   */
404  @Deprecated
405  public void setTypeStatus(TypeStatus typeStatus) {
406    this.typeStatus = typeStatus;
407  }
408
409  /**
410   * The date when the specimen was collected.
411   * <blockquote>
412   * <p>
413   * <i>Examples:</i> "spring 1910", "Marzo 2002", "1999-03-XX", "17IV1934".
414   * </p>
415   * </blockquote>
416   *
417   * @return the verbatimEventDate
418   */
419  @Schema(description = "The date when the specimen was collected.")
420  @Nullable
421  @Deprecated
422  public String getVerbatimEventDate() {
423    return verbatimEventDate;
424  }
425
426  /**
427   * @param verbatimEventDate the verbatimEventDate to set
428   */
429  @Deprecated
430  public void setVerbatimEventDate(String verbatimEventDate) {
431    this.verbatimEventDate = verbatimEventDate;
432  }
433
434  /**
435   * The full, verbatim text from the specimen label.
436   *
437   * @return the verbatimLabel
438   */
439  @Schema(description = "The full, verbatim text from the specimen label.")
440  @Nullable
441  @Deprecated
442  public String getVerbatimLabel() {
443    return verbatimLabel;
444  }
445
446  /**
447   * @param verbatimLabel the verbatimLabel to set
448   */
449  @Deprecated
450  public void setVerbatimLabel(String verbatimLabel) {
451    this.verbatimLabel = verbatimLabel;
452  }
453
454  /**
455   * The geographic latitude.
456   * <blockquote>
457   * <p>
458   * <i>Examples:</i> 41 05 54.03 S.
459   * </p>
460   * </blockquote>
461   *
462   * @return the verbatimLatitude
463   */
464  @Schema(description = "The geographic latitude.")
465  @Nullable
466  @Deprecated
467  public String getVerbatimLatitude() {
468    return verbatimLatitude;
469  }
470
471  /**
472   * @param verbatimLatitude the verbatimLatitude to set
473   */
474  @Deprecated
475  public void setVerbatimLatitude(String verbatimLatitude) {
476    this.verbatimLatitude = verbatimLatitude;
477  }
478
479  /**
480   * The geographic longitude.
481   * <blockquote>
482   * <p>
483   * <i>Examples:</i> 121d 10' 34 W.
484   * </p>
485   * </blockquote>
486   *
487   * @return the verbatimLongitude
488   */
489  @Schema(description = "The geographic longitude.")
490  @Nullable
491  @Deprecated
492  public String getVerbatimLongitude() {
493    return verbatimLongitude;
494  }
495
496  /**
497   * @param verbatimLongitude the verbatimLongitude to set
498   */
499  @Deprecated
500  public void setVerbatimLongitude(String verbatimLongitude) {
501    this.verbatimLongitude = verbatimLongitude;
502  }
503
504  @Override
505  public boolean equals(Object o) {
506    if (this == o) {
507      return true;
508    }
509    if (o == null || getClass() != o.getClass()) {
510      return false;
511    }
512    TypeSpecimen that = (TypeSpecimen) o;
513    return Objects.equals(source, that.source) &&
514      Objects.equals(sourceTaxonKey, that.sourceTaxonKey) &&
515      typeDesignationType == that.typeDesignationType &&
516      Objects.equals(typeDesignatedBy, that.typeDesignatedBy) &&
517      Objects.equals(scientificName, that.scientificName) &&
518      taxonRank == that.taxonRank &&
519      typeStatus == that.typeStatus &&
520      Objects.equals(citation, that.citation) &&
521      Objects.equals(verbatimLabel, that.verbatimLabel) &&
522      Objects.equals(locality, that.locality) &&
523      Objects.equals(recordedBy, that.recordedBy) &&
524      Objects.equals(verbatimEventDate, that.verbatimEventDate) &&
525      Objects.equals(verbatimLongitude, that.verbatimLongitude) &&
526      Objects.equals(verbatimLatitude, that.verbatimLatitude) &&
527      Objects.equals(occurrenceId, that.occurrenceId) &&
528      Objects.equals(institutionCode, that.institutionCode) &&
529      Objects.equals(collectionCode, that.collectionCode) &&
530      Objects.equals(catalogNumber, that.catalogNumber);
531  }
532
533  @Override
534  public int hashCode() {
535    return Objects
536      .hash(source, sourceTaxonKey, typeDesignationType, typeDesignatedBy, scientificName,
537        taxonRank, typeStatus, citation, verbatimLabel, locality, recordedBy, verbatimEventDate,
538        verbatimLongitude, verbatimLatitude, occurrenceId, institutionCode, collectionCode,
539        catalogNumber);
540  }
541
542  @Override
543  public String toString() {
544    return new StringJoiner(", ", TypeSpecimen.class.getSimpleName() + "[", "]")
545      .add("source='" + source + "'")
546      .add("sourceTaxonKey=" + sourceTaxonKey)
547      .add("typeDesignationType=" + typeDesignationType)
548      .add("typeDesignatedBy='" + typeDesignatedBy + "'")
549      .add("scientificName='" + scientificName + "'")
550      .add("taxonRank=" + taxonRank)
551      .toString();
552  }
553}