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 jakarta.annotation.Nullable;
034import jakarta.validation.Valid;
035import jakarta.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   * Inserts a metadata document, replacing any previously existing document of the same type.
110   * Updates dataset from metadata document, but only if metadata document does not exist already.
111   * The document type is discovered by the service and returned in the Metadata instance.
112   *
113   * @param datasetKey the dataset in question
114   * @param document metadata document to insert
115   * @param contentJson json string if the document is json
116   * @param type MetadataType (EML, DC, DWC_DP, COLDP)
117   * @throws IllegalArgumentException if document is not parsable
118   */
119  Metadata insertMetadata(UUID datasetKey, InputStream document, String contentJson, MetadataType type);
120
121  /**
122   * Retrieves a GBIF generated EML document overlaying GBIF information with any existing metadata
123   * document data.
124   */
125  InputStream getMetadataDocument(UUID datasetKey);
126
127  /** Gets the actual metadata document content by its key. */
128  InputStream getMetadataDocument(int metadataKey);
129
130  /** Provides access to deleted datasets. */
131  PagingResponse<Dataset> listDeleted(DatasetRequestSearchParams searchParams);
132
133  /**
134   * Provides access to datasets that are marked as a duplicate of another. When 2 datasets are
135   * considered duplicates, one is marked as a duplicate of the other. Only the marked dataset is
136   * returned in this call.
137   */
138  PagingResponse<Dataset> listDuplicates(@Nullable Pageable page);
139
140  /**
141   * Provides access to internal (e.g. not marked as external) datasets, that are not sub datasets
142   * that have no endpoint.
143   */
144  PagingResponse<Dataset> listDatasetsWithNoEndpoint(@Nullable Pageable page);
145
146  /**
147   * Get a Dataset list from a DOI. GBIF assigned DOIs and alternate identifiers are returned.
148   * Multiple dataset could share the same DOI since this is not enforced.
149   */
150  PagingResponse<Dataset> listByDOI(String doi, @Nullable Pageable page);
151
152  /**
153   * Get gridded datasets processing info
154   *
155   * @param datasetKey the dataset in question
156   * @return List of grids
157   */
158  List<Grid> listGrids(UUID datasetKey);
159
160  /**
161   * Provides paging service to list datasets that can be filtered by multiple parameters.
162   *
163   * @param searchParams {@link DatasetRequestSearchParams}
164   * @return list of datasets ordered by creation date with the latest coming first
165   */
166  PagingResponse<Dataset> list(DatasetRequestSearchParams searchParams);
167
168
169  /**
170   * Creates DwcA metadata to a target dataset.
171   *
172   * @param datasetKey   key of target dataset
173   * @param dwcA         dqwcA metadata
174   *
175   */
176  void createDwcaData(UUID datasetKey, @NotNull @Valid Dataset.DwcA dwcA);
177
178  /**
179   * Updates DwcA metadata to a target dataset.
180   *
181   * @param datasetKey   key of target dataset
182   * @param dwcA         dqwcA metadata
183   *
184   */
185  void updateDwcaData(UUID datasetKey, @NotNull @Valid Dataset.DwcA dwcA);
186}