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.Language;
017
018import java.util.Objects;
019import java.util.StringJoiner;
020
021import javax.annotation.Nullable;
022
023import io.swagger.v3.oas.annotations.media.Schema;
024
025/**
026 * Description Model Object represents a taxon description.
027 *
028 * @see <a href="http://rs.gbif.org/extension/gbif/1.0/description.xml">Description Definition</a>
029 */
030@SuppressWarnings("unused")
031public class Description implements NameUsageExtension {
032
033  private Integer key;
034  private Integer taxonKey;
035  private String type;
036  private Language language;
037  private String description;
038  private String source;
039  private Integer sourceTaxonKey;
040  private String creator;
041  private String contributor;
042  private String license;
043
044  /**
045   * A unique GBIF identifier for any description.
046   * This key is used in the table of contents to retrieve the detailed description.
047   */
048  @Schema(description = "A unique GBIF identifier for the description.\n\n" +
049    "This key is used in the table of contents to retrieve the detailed description.")
050  public Integer getKey() {
051    return key;
052  }
053
054  public void setKey(Integer key) {
055    this.key = key;
056  }
057
058  /**
059   * The name usage "taxon" key this description belongs to.
060   */
061  @Schema(description = "The name usage “taxon“ key to which this species profile belongs.")
062  @Override
063  public Integer getTaxonKey() {
064    return taxonKey;
065  }
066
067  @Override
068  public void setTaxonKey(Integer taxonKey) {
069    this.taxonKey = taxonKey;
070  }
071
072  /**
073   * An entity responsible for making contributions to the textual information provided for a description.
074   *
075   * @return the contributor
076   */
077  @Schema(description = "An entity responsible for making contributions to the textual information provided for a description.")
078  @Nullable
079  public String getContributor() {
080    return contributor;
081  }
082
083  /**
084   * @param contributor the contributor to set
085   */
086  public void setContributor(String contributor) {
087    this.contributor = contributor;
088  }
089
090  /**
091   * The author(s) of the textual information provided for a description.
092   *
093   * @return the creator
094   */
095  @Schema(description = "The author(s) of the textual information provided for a description.")
096  @Nullable
097  public String getCreator() {
098    return creator;
099  }
100
101  /**
102   * @param creator the creator to set.
103   */
104  public void setCreator(String creator) {
105    this.creator = creator;
106  }
107
108  /**
109   * Any descriptive free text matching the category given as dc:type. The text should be either plain text or
110   * formatted with basic HTML tags, i.e. h1-4,p,i,b,a,img,ul and li. All other tags should be removed.
111   *
112   * @return the description
113   */
114  @Schema(description = "Any descriptive, free text matching the category given as dc:type.\n\n" +
115    "The text should be either plain text or HTML.")
116  @Nullable
117  public String getDescription() {
118    return description;
119  }
120
121  /**
122   * @param description the description to set
123   */
124  public void setDescription(String description) {
125    this.description = description;
126  }
127
128  /**
129   * ISO 639-1 language code used for the description.
130   *
131   * @return the language
132   */
133  @Schema(description = "ISO 639-1 language code used for the description.")
134  @Nullable
135  public Language getLanguage() {
136    return language;
137  }
138
139  /**
140   * @param language the language to set
141   */
142  public void setLanguage(Language language) {
143    this.language = language;
144  }
145
146  /**
147   * Official permission to do something with the resource. Please use Creative Commons URIs if you can. <br/>
148   * <blockquote>
149   * <p>
150   * <i>Example:</i> CC-BY
151   * </p>
152   * </blockquote>
153   *
154   * @return the license.
155   */
156  @Schema(description = "Official permission to do something with the resource.")
157  @Nullable
158  public String getLicense() {
159    return license;
160  }
161
162  /**
163   * @param license the license to set
164   */
165  public void setLicense(String license) {
166    this.license = license;
167  }
168
169  /**
170   * Source reference of this description, a URL or full publication citation.
171   *
172   * @return the source
173   */
174  @Schema(description = "Bibliographic citation referencing a source for the description.")
175  @Nullable
176  @Override
177  public String getSource() {
178    return source;
179  }
180
181  /**
182   * @param source the source to set
183   */
184  @Override
185  public void setSource(String source) {
186    this.source = source;
187  }
188
189  @Schema(description = "The name usage key of the taxon in the checklist including this description.")
190  @Nullable
191  @Override
192  public Integer getSourceTaxonKey() {
193    return sourceTaxonKey;
194  }
195
196  @Override
197  public void setSourceTaxonKey(Integer sourceTaxonKey) {
198    this.sourceTaxonKey = sourceTaxonKey;
199  }
200
201  /**
202   * Returns the type used to categorize paragraphs of a taxon description.
203   * Given the list of types is so broad, an Enum is not used to maintain it. Rather it is kept as plain text.
204   *
205   * @return the type
206   *
207   * @see <a href="https://rs.gbif.org/vocabulary/gbif/descriptionType">Description type definition</a>
208   */
209  @Schema(description = "The type used to categorize paragraphs of a taxon description.\n\n" +
210    "See the [Description Type vocabulary](http://rs.gbif.org/vocabulary/gbif/descriptionType).")
211  @Nullable
212  public String getType() {
213    return type;
214  }
215
216  /**
217   * @param type the type to set
218   */
219  public void setType(String type) {
220    this.type = type;
221  }
222
223  @Override
224  public boolean equals(Object o) {
225    if (this == o) {
226      return true;
227    }
228    if (o == null || getClass() != o.getClass()) {
229      return false;
230    }
231    Description that = (Description) o;
232    return Objects.equals(key, that.key) &&
233      Objects.equals(taxonKey, that.taxonKey) &&
234      Objects.equals(type, that.type) &&
235      language == that.language &&
236      Objects.equals(description, that.description) &&
237      Objects.equals(source, that.source) &&
238      Objects.equals(sourceTaxonKey, that.sourceTaxonKey) &&
239      Objects.equals(creator, that.creator) &&
240      Objects.equals(contributor, that.contributor) &&
241      Objects.equals(license, that.license);
242  }
243
244  @Override
245  public int hashCode() {
246    return Objects.hash(key, taxonKey, type, language, description, source, sourceTaxonKey, creator,
247      contributor, license);
248  }
249
250  @Override
251  public String toString() {
252    return new StringJoiner(", ", Description.class.getSimpleName() + "[", "]")
253      .add("key=" + key)
254      .add("taxonKey=" + taxonKey)
255      .add("type='" + type + "'")
256      .add("language=" + language)
257      .add("description='" + description + "'")
258      .add("source='" + source + "'")
259      .add("sourceTaxonKey=" + sourceTaxonKey)
260      .add("creator='" + creator + "'")
261      .add("contributor='" + contributor + "'")
262      .add("license='" + license + "'")
263      .toString();
264  }
265}