001/*
002 * Copyright 2020 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.service.checklistbank;
017
018import org.gbif.api.model.checklistbank.NameUsageMatch;
019import org.gbif.api.model.common.LinneanClassification;
020import org.gbif.api.vocabulary.Rank;
021
022import javax.annotation.Nullable;
023
024/**
025 * A lookup service that fuzzy matches classified scientific names against a body of names.
026 * In GBIF this is in particular used for a Nub Lookup service that binds occurrence names and other external records
027 * with a scientific name to the nub.
028 * <p/>
029 * Several match signatures for essentially the same matching are provided.
030 */
031public interface NameUsageMatchingService {
032
033  /**
034   * Tries to match a scientific name with an optional classification given as individual parameters.
035   *
036   * @param scientificName  the name to match against
037   * @param rank            of the name to match
038   * @param classification  optional classification of the name to match
039   * @param strict          if true only tries to match the scientific name, if false (the default) the matching
040   *                        service tries also to match the lowest possible taxon from the given classification
041   * @param verbose         if true adds verbose matching information, i.e. list of alternative matches
042   *
043   * @return a match which is never null, but might have a usageKey=null if nothing could be matched
044   */
045  NameUsageMatch match(String scientificName, @Nullable Rank rank, @Nullable LinneanClassification classification,
046    boolean strict, boolean verbose);
047
048}