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;
017
018import java.util.Objects;
019import java.util.StringJoiner;
020
021import javax.annotation.Nullable;
022import javax.validation.constraints.Min;
023import javax.validation.constraints.NotNull;
024
025import io.swagger.v3.oas.annotations.media.Schema;
026
027/**
028 * Basic metrics for a single name usage. These metrics have been embedded in the NameUsage class before
029 * but are rarely being used. They are therefore split out into a separate class to be retrieved only when needed.
030 */
031@SuppressWarnings("unused")
032public class NameUsageMetrics {
033
034  private Integer key;
035  private int numPhylum;
036  private int numClass;
037  private int numOrder;
038  private int numFamily;
039  private int numGenus;
040  private int numSubgenus;
041  private int numSpecies;
042  private int numChildren;
043  private int numDescendants;
044  private int numSynonyms;
045
046  /**
047   * Return the key that uniquely identifies this name usage.
048   *
049   * @return the key
050   */
051  @Schema(description = "The name usage key that uniquely identifies this name usage.")
052  @NotNull
053  public Integer getKey() {
054    return key;
055  }
056
057  /**
058   * @param key the key to set
059   */
060  public void setKey(Integer key) {
061    this.key = key;
062  }
063
064  /**
065   * Returns the number of direct taxonomic elements under this usage. "Direct" means that children should have
066   * this usageKey as their parentKey.
067   *
068   * @return the numChildren
069   */
070  @Schema(description = "Returns the number of direct taxonomic elements under this usage. “Direct” means that " +
071    "children should have this usageKey as their parentKey.")
072  @Min(0)
073  public int getNumChildren() {
074    return numChildren;
075  }
076
077  /**
078   * @param numChildren the numChildren to set
079   */
080  public void setNumChildren(int numChildren) {
081    this.numChildren = numChildren;
082  }
083
084  /**
085   * Returns the number of classes that are below this taxon. Typically, this would mean
086   * this usage is of something above the "class" taxonomic level.
087   *
088   * @return the numClass
089   */
090  @Schema(description = "Returns the number of classes that are below this taxon. Typically, this would mean " +
091    "this usage is of something above the “class” taxonomic level.")
092  @Min(0)
093  public int getNumClass() {
094    return numClass;
095  }
096
097  /**
098   * @param numClass the numClass to set
099   */
100  public void setNumClass(int numClass) {
101    this.numClass = numClass;
102  }
103
104  /**
105   * The number of all accepted taxonomic elements under this usage.
106   *
107   * @return the number of descendants
108   */
109  @Schema(description = "The number of all accepted taxonomic elements under this usage.")
110  public int getNumDescendants() {
111    return numDescendants;
112  }
113
114  /**
115   * @param numDescendants the n umber of descendants to set
116   */
117  public void setNumDescendants(int numDescendants) {
118    this.numDescendants = numDescendants;
119  }
120
121  /**
122   * Returns the number of families that are below this taxon. Typically, this would mean
123   * this usage is of something above the "family" taxonomic level.
124   *
125   * @return the numFamily
126   */
127  @Schema(description = "Returns the number of families that are below this taxon. Typically, this would mean " +
128    "this usage is of something above the “family” taxonomic level.")
129  @Min(0)
130  public int getNumFamily() {
131    return numFamily;
132  }
133
134  /**
135   * @param numFamily the numFamily to set
136   */
137  public void setNumFamily(int numFamily) {
138    this.numFamily = numFamily;
139  }
140
141  /**
142   * Returns the number of genus that are below this taxon. Typically, this would mean
143   * this usage is of something above the "genus" taxonomic level.
144   *
145   * @return the numGenus
146   */
147  @Schema(description = "Returns the number of genus that are below this taxon. Typically, this would mean " +
148    "this usage is of something above the “genus” taxonomic level.")
149  @Min(0)
150  public int getNumGenus() {
151    return numGenus;
152  }
153
154  /**
155   * @param numGenus the numGenus to set
156   */
157  public void setNumGenus(int numGenus) {
158    this.numGenus = numGenus;
159  }
160
161  /**
162   * Returns the number of orders that are below this taxon. Typically, this would mean
163   * this usage is of something above the "order" taxonomic level.
164   *
165   * @return the numOrder
166   */
167  @Schema(description = "Returns the number of orders that are below this taxon. Typically, this would mean " +
168    "this usage is of something above the “order” taxonomic level.")
169  @Min(0)
170  public int getNumOrder() {
171    return numOrder;
172  }
173
174  /**
175   * @param numOrder the numOrder to set
176   */
177  public void setNumOrder(int numOrder) {
178    this.numOrder = numOrder;
179  }
180
181  /**
182   * Returns the number of phyla that are below this taxon. Typically, this would mean
183   * this usage is of something above the "phylum" taxonomic level.
184   *
185   * @return the numPhylum
186   */
187  @Schema(description = "Returns the number of phyla that are below this taxon. Typically, this would mean " +
188    "this usage is of something above the “phylum” taxonomic level.")
189  @Min(0)
190  public int getNumPhylum() {
191    return numPhylum;
192  }
193
194  /**
195   * @param numPhylum the numPhylum to set
196   */
197  public void setNumPhylum(int numPhylum) {
198    this.numPhylum = numPhylum;
199  }
200
201  /**
202   * Returns the number of species that are below this taxon. Typically, this would mean
203   * this usage is of something above the "species" taxonomic level.
204   *
205   * @return the numSpecies.
206   */
207  @Schema(description = "Returns the number of species that are below this taxon. Typically, this would mean " +
208    "this usage is of something above the “species” taxonomic level.")
209  @Min(0)
210  public int getNumSpecies() {
211    return numSpecies;
212  }
213
214  /**
215   * @param numSpecies the numSpecies to set
216   */
217  public void setNumSpecies(int numSpecies) {
218    this.numSpecies = numSpecies;
219  }
220
221  /**
222   * Returns the number of distinct subgenera that are below this taxon. Typically, this would mean
223   * this usage is of something above the "subgenus" taxonomic level.
224   *
225   * @return the numSubgenus
226   */
227  @Schema(description = "Returns the number of distinct subgenera that are below this taxon. Typically, this would mean " +
228    "this usage is of something above the “subgenus” taxonomic level.")
229  @Min(0)
230  public int getNumSubgenus() {
231    return numSubgenus;
232  }
233
234  /**
235   * @param numSubgenus the number of distinct subgenera
236   */
237  public void setNumSubgenus(int numSubgenus) {
238    this.numSubgenus = numSubgenus;
239  }
240
241  /**
242   * Returns the number of related synonyms this usage possses.
243   *
244   * @return the numSynonyms.
245   */
246  @Schema(description = "Returns the number of related synonyms this usage possses.")
247  @Min(0)
248  public int getNumSynonyms() {
249    return numSynonyms;
250  }
251
252  /**
253   * @param numSynonyms the numSynonyms to set
254   */
255  public void setNumSynonyms(int numSynonyms) {
256    this.numSynonyms = numSynonyms;
257  }
258
259  /**
260   * Gets the count of usages by a rank.
261   * Only Linnean ranks are supported.
262   *
263   * @param rank the linnean rank to retrieve counts for
264   *
265   * @return the count or null if rank doesn't exist
266   */
267  @Nullable
268  public Integer getNumByRank(Rank rank) {
269    if (rank == Rank.PHYLUM) {
270      return numPhylum;
271    }
272    if (rank == Rank.CLASS) {
273      return numClass;
274    }
275    if (rank == Rank.ORDER) {
276      return numOrder;
277    }
278    if (rank == Rank.FAMILY) {
279      return numFamily;
280    }
281    if (rank == Rank.GENUS) {
282      return numGenus;
283    }
284    if (rank == Rank.SUBGENUS) {
285      return numSubgenus;
286    }
287    if (rank == Rank.SPECIES) {
288      return numSpecies;
289    }
290    return null;
291  }
292
293
294  @Override
295  public boolean equals(Object o) {
296    if (this == o) {
297      return true;
298    }
299    if (o == null || getClass() != o.getClass()) {
300      return false;
301    }
302    NameUsageMetrics that = (NameUsageMetrics) o;
303    return numPhylum == that.numPhylum &&
304      numClass == that.numClass &&
305      numOrder == that.numOrder &&
306      numFamily == that.numFamily &&
307      numGenus == that.numGenus &&
308      numSubgenus == that.numSubgenus &&
309      numSpecies == that.numSpecies &&
310      numChildren == that.numChildren &&
311      numDescendants == that.numDescendants &&
312      numSynonyms == that.numSynonyms &&
313      Objects.equals(key, that.key);
314  }
315
316  @Override
317  public int hashCode() {
318    return Objects
319      .hash(key, numPhylum, numClass, numOrder, numFamily, numGenus, numSubgenus, numSpecies,
320        numChildren, numDescendants, numSynonyms);
321  }
322
323  @Override
324  public String toString() {
325    return new StringJoiner(", ", NameUsageMetrics.class.getSimpleName() + "[", "]")
326      .add("key=" + key)
327      .add("numPhylum=" + numPhylum)
328      .add("numClass=" + numClass)
329      .add("numOrder=" + numOrder)
330      .add("numFamily=" + numFamily)
331      .add("numGenus=" + numGenus)
332      .add("numSubgenus=" + numSubgenus)
333      .add("numSpecies=" + numSpecies)
334      .add("numChildren=" + numChildren)
335      .add("numDescendants=" + numDescendants)
336      .add("numSynonyms=" + numSynonyms)
337      .toString();
338  }
339}