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.Country;
019import org.gbif.api.vocabulary.Language;
020import org.gbif.api.vocabulary.LifeStage;
021import org.gbif.api.vocabulary.Sex;
022
023import javax.annotation.Nullable;
024import javax.validation.constraints.NotNull;
025
026import com.google.common.base.Objects;
027
028
029/**
030 * VernacularName Model Object represents a vernacular name for a scientific taxon.
031 *
032 * @see <a href="http://rs.gbif.org/extension/gbif/1.0/vernacularname.xml">Vernacular Name Definition</a>
033 */
034public class VernacularName implements NameUsageExtension {
035
036  private Integer taxonKey;
037  private String vernacularName;
038  private Language language;
039  private LifeStage lifeStage;
040  private Sex sex;
041  private Country country;
042  private String area;
043  private String source;
044  private Integer sourceTaxonKey;
045  private Boolean preferred;
046  private Boolean plural;
047
048  /**
049   * The name usage "taxon" key this description belongs to.
050   */
051  @Override
052  public Integer getTaxonKey() {
053    return taxonKey;
054  }
055
056  @Override
057  public void setTaxonKey(Integer taxonKey) {
058    this.taxonKey = taxonKey;
059  }
060
061  /**
062   * The area for the vernacular name.
063   *
064   * @return the area
065   */
066  @Nullable
067  public String getArea() {
068    return area;
069  }
070
071  /**
072   * @param area the area to set
073   */
074  public void setArea(String area) {
075    this.area = area;
076  }
077
078  /**
079   * The standard code for the country in which the vernacular name is used. Recommended best practice is to use the
080   * ISO 3166-1-alpha-2 country codes available as a vocabulary at http://rs.gbif.org/vocabulary/iso/3166-1_alpha2.xml.
081   * For multiple countries separate values with a comma ",".
082   * <blockquote>
083   * <p>
084   * <i>Example:</i> "AR" for Argentina, "SV" for El Salvador. "AR,CR,SV" for Argentina, Costa Rica, and El Salvador
085   * combined.
086   * </p>
087   * </blockquote>
088   *
089   * @return the country
090   */
091  @Nullable
092  public Country getCountry() {
093    return country;
094  }
095
096  /**
097   * @param country the country to set
098   */
099  public void setCountry(Country country) {
100    this.country = country;
101  }
102
103  /**
104   * ISO 639-1 language code used for the vernacular name value.
105   * <blockquote>
106   * <p>
107   * <i>Example:</i> es
108   * </p>
109   * </blockquote>
110   *
111   * @return the language
112   */
113  @Nullable
114  public Language getLanguage() {
115    return language;
116  }
117
118  /**
119   * @param language the language to set
120   */
121  public void setLanguage(Language language) {
122    this.language = language;
123  }
124
125  /**
126   * The age class or life stage of the species for which the vernacular name applies. Best practice is to utilise a
127   * controlled list of terms for this value.
128   * <blockquote>
129   * <p>
130   * <i>Example:</i> juvenile" is the life stage of the fish Pomatomus saltatrix for which the name "snapper blue"
131   * refers.
132   * </p>
133   * </blockquote>
134   *
135   * @return the lifeStage
136   *
137   * @see <a href="http://rs.gbif.org/vocabulary/gbif/life_stage.xml">Life Stage GBIF Vocabulary</a>
138   */
139  @Nullable
140  public LifeStage getLifeStage() {
141    return lifeStage;
142  }
143
144  /**
145   * @param lifeStage the lifeStage to set
146   */
147  public void setLifeStage(LifeStage lifeStage) {
148    this.lifeStage = lifeStage;
149  }
150
151  /**
152   * The sex (gender) of the taxon for which the vernacular name applies when the vernacular name is limited to a
153   * specific gender of a species. If not limited sex should be empty. For example the vernacular name "Buck" applies
154   * to the "Male" gender of the species, Odocoileus virginianus.
155   * <blockquote>
156   * <p>
157   * <i>Example:</i> male.
158   * </p>
159   * </blockquote>
160   *
161   * @return the sex
162   *
163   * @see <a href="http://rs.gbif.org/vocabulary/gbif/sex.xml">Sex GBIF Vocabulary</a>
164   */
165  @Nullable
166  public Sex getSex() {
167    return sex;
168  }
169
170  /**
171   * @param sex the sex to set
172   */
173  public void setSex(Sex sex) {
174    this.sex = sex;
175  }
176
177  /**
178   * Bibliographic citation referencing a source where the vernacular name refers to the cited species.
179   * <blockquote>
180   * <p>
181   * <i>Example:</i> Peterson Field Guide to the Eastern Seashore, Houghton Mifflin Co, 1961, p131.
182   * </p>
183   * </blockquote>
184   *
185   * @return the source
186   */
187  @Nullable
188  public String getSource() {
189    return source;
190  }
191
192  /**
193   * @param source the source to set
194   */
195  public void setSource(String source) {
196    this.source = source;
197  }
198
199  @Nullable
200  public Integer getSourceTaxonKey() {
201    return sourceTaxonKey;
202  }
203
204  public void setSourceTaxonKey(Integer sourceTaxonKey) {
205    this.sourceTaxonKey = sourceTaxonKey;
206  }
207
208  /**
209   * A common or vernacular name.
210   * <blockquote>
211   * <p>
212   * <i>Example:</i> Andean Condor", "Condor Andino", "American Eagle", "Gänsegeier".
213   * </p>
214   * </blockquote>
215   *
216   * @return the vernacularName
217   */
218  @NotNull
219  public String getVernacularName() {
220    return vernacularName;
221  }
222
223  /**
224   * @param vernacularName the vernacularName to set
225   */
226  public void setVernacularName(String vernacularName) {
227    this.vernacularName = vernacularName;
228  }
229
230  /**
231   * This value is true if the vernacular name it qualifies refers to a plural form of the name.
232   * <blockquote>
233   * <p>
234   * <i>Example:</i> The term "Schoolies" is the plural form of a name used along the coastal Northeastern U.S. for
235   * groups of juvenile fish of the species, Morone saxatilis.
236   * </p>
237   * </blockquote>
238   *
239   * @return the plural
240   *
241   * @see <a href="http://rs.gbif.org/vocabulary/basic/boolean.xml">Boolean Vocabulary</a>
242   */
243  @Nullable
244  public Boolean isPlural() {
245    return plural;
246  }
247
248  /**
249   * @param plural the plural to set
250   */
251  public void setPlural(Boolean plural) {
252    this.plural = plural;
253  }
254
255  /**
256   * This term is true if the source citing the use of this vernacular name indicates the usage has some preference or
257   * specific standing over other possible vernacular names used for the species.
258   * <blockquote>
259   * <p>
260   * <i>Example:</i> Some organisations have attempted to assign specific and unique vernacular names for particular
261   * taxon groups in a systematic attempt to bring order and consistency to the use of these names. For example, the
262   * American Ornithological Union assigns the name "Pearl Kite" for the taxon, Gampsonyx swainsonii. The value of
263   * isPreferredName for this record would be true.
264   * </p>
265   * </blockquote>
266   *
267   * @return the preferred
268   *
269   * @see <a href="http://rs.gbif.org/vocabulary/basic/boolean.xml">Boolean Vocabulary</a>
270   */
271  @Nullable
272  public Boolean isPreferred() {
273    return preferred;
274  }
275
276  /**
277   * @param preferred the preferred to set
278   */
279  public void setPreferred(Boolean preferred) {
280    this.preferred = preferred;
281  }
282
283  @Override
284  public boolean equals(Object object) {
285    if (this == object) {
286      return true;
287    }
288    if (!(object instanceof VernacularName)) {
289      return false;
290    }
291
292    VernacularName that = (VernacularName) object;
293    return Objects.equal(this.vernacularName, that.vernacularName)
294           && Objects.equal(this.language, that.language)
295           && Objects.equal(this.lifeStage, that.lifeStage)
296           && Objects.equal(this.sex, that.sex)
297           && Objects.equal(this.country, that.country)
298           && Objects.equal(this.area, that.area)
299           && Objects.equal(this.source, that.source)
300           && Objects.equal(this.sourceTaxonKey, that.sourceTaxonKey)
301           && Objects.equal(this.preferred, that.preferred)
302           && Objects.equal(this.plural, that.plural);
303  }
304
305  @Override
306  public int hashCode() {
307    return Objects.hashCode(vernacularName,
308                            language,
309                            lifeStage,
310                            sex,
311                            country,
312                            area,
313                            source,
314                            sourceTaxonKey,
315                            preferred,
316                            plural);
317  }
318
319  @Override
320  public String toString() {
321    return Objects.toStringHelper(this)
322      .add("vernacularName", vernacularName)
323      .add("language", language)
324      .add("lifeStage", lifeStage)
325      .add("sex", sex)
326      .add("country", country)
327      .add("area", area)
328      .add("source", source)
329      .add("sourceTaxonKey", sourceTaxonKey)
330      .add("preferred", preferred)
331      .add("plural", plural)
332      .toString();
333  }
334
335}