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 javax.annotation.Nullable;
019import javax.validation.constraints.NotNull;
020
021import com.google.common.base.Objects;
022
023
024/**
025 * Reference Model Object represents a literature reference stating a bibliography for a taxon.
026 *
027 * Since the initial release of the GBIF API version 1.0 ChecklistBank has been modified to only store the entire citation string of a reference and
028 * none of the atomised fields which are now deprecated.
029 *
030 * @see <a href="http://rs.gbif.org/extension/gbif/1.0/references.xml">Reference Definition</a>
031 */
032public class Reference implements NameUsageExtension {
033
034  private Integer taxonKey;
035  private String citation;
036  private String link;
037  private String doi;
038  private String type;
039  private String remarks;
040  private String source;
041  private Integer sourceTaxonKey;
042
043  @Deprecated
044  private String title;
045  @Deprecated
046  private String author;
047  @Deprecated
048  private String date;
049
050  /**
051   * The name usage "taxon" key this description belongs to.
052   */
053  @Override
054  public Integer getTaxonKey() {
055    return taxonKey;
056  }
057
058  @Override
059  public void setTaxonKey(Integer taxonKey) {
060    this.taxonKey = taxonKey;
061  }
062
063  /**
064   * The author or authors of the referenced work.
065   * <blockquote>
066   * <p>
067   * <i>Example:</i> Patricia Hartge.
068   * </p>
069   * </blockquote>
070   *
071   * @return the author
072   */
073  @Nullable
074  @Deprecated
075  public String getAuthor() {
076    return author;
077  }
078
079  /**
080   * @param author the author to set
081   */
082  @Deprecated
083  public void setAuthor(String author) {
084    this.author = author;
085  }
086
087  /**
088   * A text string referring to an un-parsed bibliographic citation.
089   * The full citation given here should include all the details potentially found in the other atomised fields,
090   * i.e. includes authorship, title, etc.
091   * <p/>
092   * <blockquote>
093   * <p>
094   * <i>Example:</i> Hartge, P., Genetics of reproductive lifespan. Nature Genetics 41, 637 - 638 (2009).
095   * </p>
096   * </blockquote>
097   *
098   * @return the citation
099   */
100  @NotNull
101  public String getCitation() {
102    return citation;
103  }
104
105  /**
106   * @param citation the citation to set
107   */
108  public void setCitation(String citation) {
109    this.citation = citation;
110  }
111
112  /**
113   * Date of publication, recommended ISO format YYYY or YYYY-MM-DD.
114   *
115   * @return the publication date
116   */
117  @Nullable
118  @Deprecated
119  public String getDate() {
120    return date;
121  }
122
123  @Deprecated
124  public void setDate(String date) {
125    this.date = date;
126  }
127
128  /**
129   * The pure DOI for the publication without potential http resolver or URI prefix.
130   * For example {@code 10.1038/ng0609-637} instead of {@code doi:10.1038/ng0609-637} or {@code
131   * http://dx.doi.org/10.1038/ng0609-637}. A valid DOI always starts with {@code 10.}.
132   *
133   * @return the doi
134   *
135   * @see <a href="http://www.crossref.org/01company/15doi_info.html">Crossref DOI Info</a>
136   * @see <a href="http://www.doi.org/hb.html">DOI Handbook</a>
137   * @see <a href="http://de.wikipedia.org/wiki/Digital_Object_Identifier">Wikipedia</a>
138   */
139  @Nullable
140  public String getDoi() {
141    return doi;
142  }
143
144  public void setDoi(String doi) {
145    this.doi = doi;
146  }
147
148  /**
149   * Link.
150   *
151   * @return the link
152   */
153  @Nullable
154  public String getLink() {
155    return link;
156  }
157
158  /**
159   * @param link the link to set
160   */
161  public void setLink(String link) {
162    this.link = link;
163  }
164
165  /**
166   * Annotation of taxon-specific information related to the referenced publication.
167   * <p/>
168   * <blockquote>
169   * <p>
170   * <i>Examples:</i> "transferred H. nigritarsus to Acanolonia"; "Type specimen is a skeleton"
171   * </p>
172   * </blockquote>
173   *
174   * @return the taxonomic remarks
175   */
176  @Nullable
177  public String getRemarks() {
178    return remarks;
179  }
180
181  public void setRemarks(String remarks) {
182    this.remarks = remarks;
183  }
184
185  /**
186   * Title of book or article.
187   * <blockquote>
188   * <p>
189   * <i>Example:</i> "Genetics of reproductive lifespan", "Field Guide to Moths of Eastern North America".
190   * </p>
191   * </blockquote>
192   *
193   * @return the title
194   */
195  @Nullable
196  @Deprecated
197  public String getTitle() {
198    return title;
199  }
200
201  /**
202   * @param title the title to set
203   */
204  @Deprecated
205  public void setTitle(String title) {
206    this.title = title;
207  }
208
209  /**
210   * Used to assign a bibliographic reference to list of taxonomic or nomenclatural categories. Best practice is to use
211   * a controlled vocabulary.
212   * <blockquote>
213   * <p>
214   * <i>Examples:</i> Original publication of new combination (comb nov.)
215   * </p>
216   * </blockquote>
217   *
218   * @return the publication type
219   */
220  @Nullable
221  public String getType() {
222    return type;
223  }
224
225  public void setType(String type) {
226    this.type = type;
227  }
228
229  @Nullable
230  @Override
231  public String getSource() {
232    return source;
233  }
234
235  @Override
236  public void setSource(String source) {
237    this.source = source;
238  }
239
240  @Nullable
241  @Override
242  public Integer getSourceTaxonKey() {
243    return sourceTaxonKey;
244  }
245
246  @Override
247  public void setSourceTaxonKey(Integer sourceTaxonKey) {
248    this.sourceTaxonKey = sourceTaxonKey;
249  }
250
251  @Override
252  public boolean equals(Object object) {
253    if (this == object) {
254      return true;
255    }
256    if (!(object instanceof Reference)) {
257      return false;
258    }
259
260    Reference that = (Reference) object;
261    return Objects.equal(this.citation, that.citation)
262           && Objects.equal(this.link, that.link)
263           && Objects.equal(this.type, that.type)
264           && Objects.equal(this.remarks, that.remarks)
265           && Objects.equal(this.doi, that.doi)
266           && Objects.equal(this.source, that.source)
267           && Objects.equal(this.sourceTaxonKey, that.sourceTaxonKey)
268           && Objects.equal(this.title, that.title)
269           && Objects.equal(this.author, that.author)
270           && Objects.equal(this.date, that.date);
271  }
272
273  @Override
274  public int hashCode() {
275    return Objects.hashCode(citation, link, doi, type, remarks, source, sourceTaxonKey, title, author, date);
276  }
277
278  @Override
279  public String toString() {
280    return Objects.toStringHelper(this)
281      .add("citation", citation)
282      .add("link", link)
283      .add("type", type)
284      .add("remarks", remarks)
285      .add("doi", doi)
286      .add("source", source)
287      .add("sourceTaxonKey", sourceTaxonKey)
288      .toString();
289  }
290
291}