001/*
002 * Copyright 2014 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.api.model.checklistbank;
017
018import org.gbif.api.vocabulary.CitesAppendix;
019import org.gbif.api.vocabulary.Country;
020import org.gbif.api.vocabulary.EstablishmentMeans;
021import org.gbif.api.vocabulary.LifeStage;
022import org.gbif.api.vocabulary.OccurrenceStatus;
023import org.gbif.api.vocabulary.ThreatStatus;
024
025import javax.annotation.Nullable;
026import javax.validation.constraints.Max;
027import javax.validation.constraints.Min;
028
029import com.google.common.base.Objects;
030
031/**
032 * Distribution Model Object represents a species distribution.
033 *
034 * @see <a href="http://rs.gbif.org/extension/gbif/1.0/distribution.xml">Distribution Definition</a>
035 */
036public class Distribution implements NameUsageExtension {
037
038  private Integer taxonKey;
039  private String locationId;
040  private String locality;
041  private Country country;
042  private OccurrenceStatus status;
043  private LifeStage lifeStage;
044  private String temporal;
045  private ThreatStatus threatStatus;
046  private EstablishmentMeans establishmentMeans;
047  private CitesAppendix appendixCites;
048  private String source;
049  private Integer sourceTaxonKey;
050  private Integer startDayOfYear;
051  private Integer endDayOfYear;
052  private String remarks;
053
054  /**
055   * The name usage "taxon" key this description belongs to.
056   */
057  @Override
058  public Integer getTaxonKey() {
059    return taxonKey;
060  }
061
062  @Override
063  public void setTaxonKey(Integer taxonKey) {
064    this.taxonKey = taxonKey;
065  }
066
067  /**
068   * The CITES (Convention on International Trade in Endangered Species of Wild Fauna and Flora) Appendix number the
069   * taxa is listed. It is possible to have different appendix numbers for different areas, but "global" as an area is
070   * also valid if its the same worldwide see also http://www.cites.org/eng/app/index.shtml
071   * <blockquote>
072   * <p>
073   * <i>Example:</i> II
074   * </p>
075   * </blockquote>
076   *
077   * @return the appendixCites.
078   */
079  @Nullable
080  public CitesAppendix getAppendixCites() {
081    return appendixCites;
082  }
083
084  /**
085   * @param appendixCites the appendixCites to set
086   */
087  public void setAppendixCites(CitesAppendix appendixCites) {
088    this.appendixCites = appendixCites;
089  }
090
091  /**
092   * @return the country
093   */
094  @Nullable
095  public Country getCountry() {
096    return country;
097  }
098
099  /**
100   * @param country the country to set
101   */
102  public void setCountry(Country country) {
103    this.country = country;
104  }
105
106  /**
107   * Seasonal temporal subcontext within the eventDate context. The latest ordinal day of the year on which the
108   * distribution record is valid.
109   * <blockquote>
110   * <p>
111   * <i>Example:</i> 120
112   * </p>
113   * </blockquote>
114   *
115   * @return the endDayOfYear.
116   */
117  @Nullable
118  @Min(1)
119  @Max(366)
120  public Integer getEndDayOfYear() {
121    return endDayOfYear;
122  }
123
124  /**
125   * @param endDayOfYear the endDayOfYear to set
126   */
127  public void setEndDayOfYear(Integer endDayOfYear) {
128    this.endDayOfYear = endDayOfYear;
129  }
130
131  /**
132   * Term describing whether the organism occurs natively, is introduced or cultivated.
133   * <blockquote>
134   * <p>
135   * <i>Example:</i> introduced
136   * </p>
137   * </blockquote>
138   *
139   * @return the establishmentMeans
140   */
141  @Nullable
142  public EstablishmentMeans getEstablishmentMeans() {
143    return establishmentMeans;
144  }
145
146  /**
147   * @param establishmentMeans the establishmentMeans to set
148   */
149  public void setEstablishmentMeans(EstablishmentMeans establishmentMeans) {
150    this.establishmentMeans = establishmentMeans;
151  }
152
153  /**
154   * The distribution information pertains solely to a specific life stage of the taxon.
155   * <blockquote>
156   * <p>
157   * <i>Example:</i> adult
158   * </p>
159   * </blockquote>
160   *
161   * @return the lifeStage
162   *
163   * @see <a href="http://rs.gbif.org/vocabulary/gbif/life_stage.xml">life stage vocabulary for recommended values</a>
164   */
165  @Nullable
166  public LifeStage getLifeStage() {
167    return lifeStage;
168  }
169
170  /**
171   * @param lifeStage the lifeStage to set
172   */
173  public void setLifeStage(LifeStage lifeStage) {
174    this.lifeStage = lifeStage;
175  }
176
177  /**
178   * The verbatim name of the area this distribution record is about.
179   * <blockquote>
180   * <p>
181   * <i>Example:</i> Patagonia
182   * </p>
183   * </blockquote>
184   *
185   * @return the locality
186   */
187  @Nullable
188  public String getLocality() {
189    return locality;
190  }
191
192  /**
193   * @param locality the locality to set
194   */
195  public void setLocality(String locality) {
196    this.locality = locality;
197  }
198
199  /**
200   * A code for the named area this distributon record is about.
201   * See http://en.wikipedia.org/wiki/ISO_3166-2 for state codes within a country,
202   * otherwise use a prefix for each code to indicate the source of the code.
203   * <p/>
204   * <blockqoute>
205   * <p>
206   * <i>Example:</i> TDWG:AGS-TF <i>Example:</i> ISO3166:AR <i>Example:</i> WOEID:564721
207   * </p>
208   * </blockquote>
209   *
210   * @return the location id
211   */
212  public String getLocationId() {
213    return locationId;
214  }
215
216  /**
217   * @param locationId the locationId to set
218   */
219  public void setLocationId(String locationId) {
220    this.locationId = locationId;
221  }
222
223  /**
224   * Additional notes on the distribution.
225   *
226   * @return the notes
227   */
228  @Nullable
229  public String getRemarks() {
230    return remarks;
231  }
232
233  public void setRemarks(String remarks) {
234    this.remarks = remarks;
235  }
236
237  /**
238   * Source reference for this distribution record. Can be proper publication citation, a webpage URL, etc.
239   * <blockquote>
240   * <p>
241   * <i>Example:</i> "Euro+Med Plantbase - the information resource for Euro-Mediterranean plant diversity (2006-).
242   * Published on the Internet http://ww2.bgbm.org/EuroPlusMed/ July, 2009"
243   * </p>
244   * </blockquote>
245   *
246   * @return the source
247   */
248  @Nullable
249  public String getSource() {
250    return source;
251  }
252
253  /**
254   * @param source the source to set
255   */
256  public void setSource(String source) {
257    this.source = source;
258  }
259
260  @Nullable
261  public Integer getSourceTaxonKey() {
262    return sourceTaxonKey;
263  }
264
265  public void setSourceTaxonKey(Integer sourceTaxonKey) {
266    this.sourceTaxonKey = sourceTaxonKey;
267  }
268
269  /**
270   * Seasonal temporal subcontext within the eventDate context. Useful for migratory species. The earliest ordinal day
271   * of the year on which the distribution record is valid. Numbering starts with 1 for January 1 and ends with 365 for
272   * December 31.
273   * <blockquote>
274   * <p>
275   * <i>Example:</i> 90
276   * </p>
277   * </blockquote>
278   *
279   * @return the startDayOfYear.
280   */
281  @Nullable
282  @Min(1)
283  @Max(366)
284  public Integer getStartDayOfYear() {
285    return startDayOfYear;
286  }
287
288  /**
289   * @param startDayOfYear the startDayOfYear to set
290   */
291  public void setStartDayOfYear(Integer startDayOfYear) {
292    this.startDayOfYear = startDayOfYear;
293  }
294
295  /**
296   * Term describing the occurrence status of the organism in the given area based on how frequent the species occurs.
297   * <blockquote>
298   * <p>
299   * <i>Example:</i> absent
300   * </p>
301   * </blockquote>
302   *
303   * @return the status.
304   *
305   * @see <a href="http://rs.gbif.org/vocabulary/gbif/occurrence_status.xml">occurrence status vocabulary for
306   *      recommended
307   *      values</a>
308   */
309  @Nullable
310  public OccurrenceStatus getStatus() {
311    return status;
312  }
313
314  /**
315   * @param status the status to set
316   */
317  public void setStatus(OccurrenceStatus status) {
318    this.status = status;
319  }
320
321  /**
322   * @return the temporal
323   */
324  @Nullable
325  public String getTemporal() {
326    return temporal;
327  }
328
329  /**
330   * @param temporal the temporal to set
331   */
332  public void setTemporal(String temporal) {
333    this.temporal = temporal;
334  }
335
336  /**
337   * Threat status of a species as defined by IUCN
338   * (http://www.iucnredlist.org/static/categories_criteria_3_1#categories).
339   * <blockquote>
340   * <p>
341   * <i>Examples:</i> "EX" - "EW" - "CR"
342   * </p>
343   * </blockquote>
344   *
345   * @return the threatStatus.
346   *
347   * @see <a href="http://rs.gbif.org/vocabulary/iucn/threat_status.xml">threat status vocabulary for recommended
348   *      values</a>
349   */
350  @Nullable
351  public ThreatStatus getThreatStatus() {
352    return threatStatus;
353  }
354
355  /**
356   * @param threatStatus the threatStatus to set
357   */
358  public void setThreatStatus(ThreatStatus threatStatus) {
359    this.threatStatus = threatStatus;
360  }
361
362  @Override
363  public boolean equals(Object object) {
364    if (this == object) {
365      return true;
366    }
367    if (!(object instanceof Distribution)) {
368      return false;
369    }
370
371    Distribution that = (Distribution) object;
372    return Objects.equal(this.locality, that.locality)
373           && Objects.equal(this.country, that.country)
374           && Objects.equal(this.status, that.status)
375           && Objects.equal(this.lifeStage, that.lifeStage)
376           && Objects.equal(this.temporal, that.temporal)
377           && Objects.equal(this.threatStatus, that.threatStatus)
378           && Objects.equal(this.establishmentMeans, that.establishmentMeans)
379           && Objects.equal(this.appendixCites, that.appendixCites)
380           && Objects.equal(this.source, that.source)
381           && Objects.equal(this.sourceTaxonKey, that.sourceTaxonKey)
382           && Objects.equal(this.startDayOfYear, that.startDayOfYear)
383           && Objects.equal(this.endDayOfYear, that.endDayOfYear);
384  }
385
386  @Override
387  public int hashCode() {
388    return Objects.hashCode(locality,
389                            country,
390                            status,
391                            lifeStage,
392                            temporal,
393                            threatStatus,
394                            establishmentMeans,
395                            appendixCites,
396                            source,
397                            startDayOfYear,
398                            endDayOfYear);
399  }
400
401  @Override
402  public String toString() {
403    return Objects.toStringHelper(this)
404      .add("locality", locality)
405      .add("country", country)
406      .add("status", status)
407      .add("lifeStage", lifeStage)
408      .add("temporal", temporal)
409      .add("threatStatus", threatStatus)
410      .add("establishmentMeans", establishmentMeans)
411      .add("appendixCites", appendixCites)
412      .add("source", source)
413      .add("sourceTaxonKey", sourceTaxonKey)
414      .add("startDayOfYear", startDayOfYear)
415      .add("endDayOfYear", endDayOfYear)
416      .add("locationId", locationId)
417      .add("remarks", remarks)
418      .toString();
419  }
420
421}