001/*
002 * Copyright 2013 Global Biodiversity Information Facility (GBIF)
003 * Licensed under the Apache License, Version 2.0 (the "License");
004 * you may not use this file except in compliance with the License.
005 * You may obtain a copy of the License at
006 * http://www.apache.org/licenses/LICENSE-2.0
007 * Unless required by applicable law or agreed to in writing, software
008 * distributed under the License is distributed on an "AS IS" BASIS,
009 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
010 * See the License for the specific language governing permissions and
011 * limitations under the License.
012 */
013package org.gbif.api.service.registry;
014
015import org.gbif.api.model.common.paging.Pageable;
016import org.gbif.api.model.common.paging.PagingResponse;
017import org.gbif.api.model.registry.Dataset;
018import org.gbif.api.model.registry.Metadata;
019import org.gbif.api.model.registry.Network;
020import org.gbif.api.vocabulary.Country;
021import org.gbif.api.vocabulary.DatasetType;
022import org.gbif.api.vocabulary.MetadataType;
023
024import java.io.InputStream;
025import java.util.List;
026import java.util.UUID;
027import javax.annotation.Nullable;
028
029public interface DatasetService
030  extends NetworkEntityService<Dataset> {
031
032  /**
033   * Pages through constituents of a dataset, i.e. returns datasets which have a parentDatasetKey
034   * equals to the one requested.
035   *
036   * @param datasetKey the parent datasets key
037   */
038  PagingResponse<Dataset> listConstituents(UUID datasetKey, @Nullable Pageable page);
039
040  /**
041   * Pages through all constituent datasets, i.e. returns datasets which have a non null parentDatasetKey.
042   */
043  PagingResponse<Dataset> listConstituents(@Nullable Pageable page);
044
045  /**
046   * Provides paging service to list datasets published, i.e. owned by organizations from a given country.
047   *
048   * @param country the hosting country
049   * @param type the optional dataset type filter
050   * @return list of datasets ordered by creation date with latest coming first
051   */
052  PagingResponse<Dataset> listByCountry(Country country, @Nullable DatasetType type, @Nullable Pageable page);
053
054  /**
055   * Provides paging service to list datasets published filtered by a particular dataset type.
056   *
057   * @param type the dataset type filter
058   * @return list of datasets ordered by creation date with latest coming first
059   */
060  PagingResponse<Dataset> listByType(DatasetType type, @Nullable Pageable page);
061
062  /**
063   * Lists all metadata descriptions available for a dataset and optionally filters them by document type.
064   * The list is sorted by priority with the first result ranking highest.
065   * Highest priority in this sense means most relevant for augmenting/updating a dataset with EML being the most
066   * relevant cause informative type.
067   *
068   * @return the list of metadata entries sorted by priority
069   */
070  List<Metadata> listMetadata(UUID datasetKey, @Nullable MetadataType type);
071
072  /**
073   * Lists all networks that this dataset is a constituent of.
074   * @param datasetKey the dataset in question
075   * @return list of networks that have this dataset as a constituent
076   */
077  List<Network> listNetworks(UUID datasetKey);
078
079  /**
080   * Get a metadata description by its key.
081   */
082  Metadata getMetadata(int metadataKey);
083
084  /**
085   * Removes a metadata entry and its document by its key.
086   */
087  void deleteMetadata(int metadataKey);
088
089  /**
090   * Inserts a metadata document, replacing any previously existing document of the same type.
091   * Updates dataset from metadata document, but only if metadata document does not exist already.
092   * The document type is discovered by the service and returned in the Metadata instance.
093   *
094   * @param datasetKey the dataset in question
095   * @param document   metadata document to insert
096   *
097   * @throws IllegalArgumentException if document is not parsable
098   */
099  Metadata insertMetadata(UUID datasetKey, InputStream document);
100
101  /**
102   * Retrieves a GBIF generated EML document overlaying GBIF information with any existing metadata document data.
103   */
104  InputStream getMetadataDocument(UUID datasetKey);
105
106  /**
107   * Gets the actual metadata document content by its key.
108   */
109  InputStream getMetadataDocument(int metadataKey);
110
111  /**
112   * Provides access to deleted datasets.
113   */
114  PagingResponse<Dataset> listDeleted(@Nullable Pageable page);
115
116  /**
117   * Provides access to datasets that are marked as a duplicate of another. When 2 datasets are considered duplicates,
118   * one is marked as a duplicate of the other. Only the marked dataset is returned in this call.
119   */
120  PagingResponse<Dataset> listDuplicates(@Nullable Pageable page);
121
122  /**
123   * Provides access to internal (e.g. not marked as external) datasets, that are not sub datasets that have no
124   * endpoint.
125   */
126  PagingResponse<Dataset> listDatasetsWithNoEndpoint(@Nullable Pageable page);
127
128  /**
129   * Get a Dataset list from a DOI.
130   * GBIF assigned DOIs and alternate identifiers are returned.
131   * Multiple dataset could share the same DOI since this is not enforced.
132   */
133  PagingResponse<Dataset> listByDOI(String doi, @Nullable Pageable page);
134}