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.occurrence;
017
018import org.gbif.api.exception.ServiceUnavailableException;
019import org.gbif.api.model.occurrence.Occurrence;
020import org.gbif.api.model.occurrence.VerbatimOccurrence;
021
022import java.util.UUID;
023
024import javax.annotation.Nullable;
025
026public interface OccurrenceService {
027
028  /**
029   * Attempt to find an occurrence matching the passed key.
030   *
031   * @param key that identifies an occurrence (Long rather than long for use in methods/classes using generic types)
032   *
033   * @return a matching occurrence, or null if no occurrence can be found
034   *
035   * @throws ServiceUnavailableException if the underlying data connection fails
036   */
037  @Nullable
038  Occurrence get(Long key);
039
040  /**
041   * Attempt to find an occurrence matching the passed dataset key and occurrenceId.
042   *
043   * @param datasetKey datasey key that should contain the  occurrenceID
044   *
045   * @param occurrenceId that identifies an occurrence in a dataset
046   *
047   * @return a matching occurrence, or null if no occurrence can be found
048   *
049   * @throws ServiceUnavailableException if the underlying data connection fails
050   */
051  @Nullable
052  Occurrence get(UUID datasetKey, String occurrenceId);
053
054  /**
055   * Attempt to find the verbatim values for an occurrence matching the passed key.
056   *
057   * @param key that identifies the occurrence
058   *
059   * @return the verbatim occurrence, or null if no occurrence can be found
060   *
061   * @throws ServiceUnavailableException if the underlying data connection fails
062   */
063  @Nullable
064  VerbatimOccurrence getVerbatim(Long key);
065
066  /**
067   * Returns the "fragment" of raw data (either xml response fragment or json dwca fragment) for the passed in key.
068   * Returns null if no fragment exists.
069   *
070   * @param key that identifies an occurrence
071   *
072   * @return the raw data fragment as a String, or null if no fragment is found
073   *
074   * @throws ServiceUnavailableException if the underlying data connection fails
075   */
076  @Nullable
077  String getFragment(long key);
078}