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.registry;
017
018import org.gbif.api.model.common.paging.Pageable;
019import org.gbif.api.model.common.paging.PagingResponse;
020import org.gbif.api.model.registry.Dataset;
021import org.gbif.api.model.registry.Grid;
022import org.gbif.api.model.registry.Metadata;
023import org.gbif.api.model.registry.Network;
024import org.gbif.api.model.registry.search.DatasetRequestSearchParams;
025import org.gbif.api.vocabulary.Country;
026import org.gbif.api.vocabulary.DatasetType;
027import org.gbif.api.vocabulary.MetadataType;
028
029import java.io.InputStream;
030import java.util.List;
031import java.util.UUID;
032
033import javax.annotation.Nullable;
034import javax.validation.Valid;
035import javax.validation.constraints.NotNull;
036
037@SuppressWarnings("unused")
038public interface DatasetService extends NetworkEntityService<Dataset> {
039
040  /**
041   * Pages through constituents of a dataset, i.e. returns datasets which have a parentDatasetKey
042   * equals to the one requested.
043   *
044   * @param datasetKey the parent datasets key
045   */
046  PagingResponse<Dataset> listConstituents(UUID datasetKey, @Nullable Pageable page);
047
048  /**
049   * Pages through all constituent datasets, i.e. returns datasets which have a non null
050   * parentDatasetKey.
051   */
052  PagingResponse<Dataset> listConstituents(@Nullable Pageable page);
053
054  /**
055   * Provides paging service to list datasets published, i.e. owned by organizations from a given
056   * country.
057   *
058   * @param country the hosting country
059   * @param type the optional dataset type filter
060   * @return list of datasets ordered by creation date with latest coming first
061   */
062  PagingResponse<Dataset> listByCountry(
063      Country country, @Nullable DatasetType type, @Nullable Pageable page);
064
065  /**
066   * Provides paging service to list datasets published filtered by a particular dataset type.
067   *
068   * @param type the dataset type filter
069   * @return list of datasets ordered by creation date with latest coming first
070   */
071  PagingResponse<Dataset> listByType(DatasetType type, @Nullable Pageable page);
072
073  /**
074   * Lists all metadata descriptions available for a dataset and optionally filters them by document
075   * type. The list is sorted by priority with the first result ranking highest. Highest priority in
076   * this sense means most relevant for augmenting/updating a dataset with EML being the most
077   * relevant cause informative type.
078   *
079   * @return the list of metadata entries sorted by priority
080   */
081  List<Metadata> listMetadata(UUID datasetKey, @Nullable MetadataType type);
082
083  /**
084   * Lists all networks that this dataset is a constituent of.
085   *
086   * @param datasetKey the dataset in question
087   * @return list of networks that have this dataset as a constituent
088   */
089  List<Network> listNetworks(UUID datasetKey);
090
091  /** Get a metadata description by its key. */
092  Metadata getMetadata(int metadataKey);
093
094  /** Removes a metadata entry and its document by its key. */
095  void deleteMetadata(int metadataKey);
096
097  /**
098   * Inserts a metadata document, replacing any previously existing document of the same type.
099   * Updates dataset from metadata document, but only if metadata document does not exist already.
100   * The document type is discovered by the service and returned in the Metadata instance.
101   *
102   * @param datasetKey the dataset in question
103   * @param document metadata document to insert
104   * @throws IllegalArgumentException if document is not parsable
105   */
106  Metadata insertMetadata(UUID datasetKey, InputStream document);
107
108  /**
109   * Retrieves a GBIF generated EML document overlaying GBIF information with any existing metadata
110   * document data.
111   */
112  InputStream getMetadataDocument(UUID datasetKey);
113
114  /** Gets the actual metadata document content by its key. */
115  InputStream getMetadataDocument(int metadataKey);
116
117  /** Provides access to deleted datasets. */
118  PagingResponse<Dataset> listDeleted(DatasetRequestSearchParams searchParams);
119
120  /**
121   * Provides access to datasets that are marked as a duplicate of another. When 2 datasets are
122   * considered duplicates, one is marked as a duplicate of the other. Only the marked dataset is
123   * returned in this call.
124   */
125  PagingResponse<Dataset> listDuplicates(@Nullable Pageable page);
126
127  /**
128   * Provides access to internal (e.g. not marked as external) datasets, that are not sub datasets
129   * that have no endpoint.
130   */
131  PagingResponse<Dataset> listDatasetsWithNoEndpoint(@Nullable Pageable page);
132
133  /**
134   * Get a Dataset list from a DOI. GBIF assigned DOIs and alternate identifiers are returned.
135   * Multiple dataset could share the same DOI since this is not enforced.
136   */
137  PagingResponse<Dataset> listByDOI(String doi, @Nullable Pageable page);
138
139  /**
140   * Get gridded datasets processing info
141   *
142   * @param datasetKey the dataset in question
143   * @return List of grids
144   */
145  List<Grid> listGrids(UUID datasetKey);
146
147  /**
148   * Provides paging service to list datasets that can be filtered by multiple parameters.
149   *
150   * @param searchParams {@link DatasetRequestSearchParams}
151   * @return list of datasets ordered by creation date with the latest coming first
152   */
153  PagingResponse<Dataset> list(DatasetRequestSearchParams searchParams);
154
155
156  /**
157   * Add a new Contact to a target entity.
158   *
159   * @param targetEntityKey key of target entity
160   * @param contact         Contact to add
161   *
162   * @return key of Contact added
163   */
164  void createDwcaData(UUID datasetKey, @NotNull @Valid Dataset.DwcA dwcA);
165
166  /**
167   * Add a new Contact to a target entity.
168   *
169   * @param targetEntityKey key of target entity
170   * @param contact         Contact to add
171   *
172   * @return key of Contact added
173   */
174  void updateDwcaData(UUID datasetKey, @NotNull @Valid Dataset.DwcA dwcA);
175}