001/*
002 * Licensed under the Apache License, Version 2.0 (the "License");
003 * you may not use this file except in compliance with the License.
004 * You may obtain a copy of the License at
005 *
006 *     http://www.apache.org/licenses/LICENSE-2.0
007 *
008 * Unless required by applicable law or agreed to in writing, software
009 * distributed under the License is distributed on an "AS IS" BASIS,
010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011 * See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014package org.gbif.api.service.registry;
015
016import org.gbif.api.model.common.paging.Pageable;
017import org.gbif.api.model.common.paging.PagingResponse;
018import org.gbif.api.model.occurrence.Download;
019import org.gbif.api.model.occurrence.DownloadStatistics;
020import org.gbif.api.model.registry.CountryOccurrenceDownloadUsage;
021import org.gbif.api.model.registry.DatasetOccurrenceDownloadUsage;
022import org.gbif.api.model.registry.OrganizationOccurrenceDownloadUsage;
023import org.gbif.api.vocabulary.Country;
024import org.gbif.api.vocabulary.CountryUsageSortField;
025import org.gbif.api.vocabulary.DatasetUsageSortField;
026import org.gbif.api.vocabulary.License;
027import org.gbif.api.vocabulary.OrganizationUsageSortField;
028import org.gbif.api.vocabulary.SortOrder;
029
030import java.time.LocalDateTime;
031import java.util.Date;
032import java.util.Map;
033import java.util.Set;
034import java.util.UUID;
035
036import jakarta.annotation.Nullable;
037import jakarta.validation.Valid;
038import jakarta.validation.constraints.NotNull;
039
040/** Interface to access and persist information about occurrence download events. */
041@SuppressWarnings("unused")
042public interface OccurrenceDownloadService {
043
044  /**
045   * Persists the occurrence download object. The object must contain a unique key, the persistence
046   * storage doesn't generate one for it.
047   */
048  void create(@NotNull @Valid Download download);
049
050  /** Retrieves a occurrence download by its unique key or DOI. */
051  Download get(@NotNull String keyOrDoi);
052
053  /**
054   * Retrieves a pageable result of all the downloads, optionally the downloads can be filtered by
055   * status and source.
056   */
057  PagingResponse<Download> list(
058      @Nullable Pageable page, @Nullable Set<Download.Status> status, @Nullable String source);
059
060  /** Counts downloads based on the given parameters. */
061  long count(@Nullable Set<Download.Status> status, @Nullable String source);
062
063  /** Retrieves a pageable result of the downloads created by a user in a given status. */
064  PagingResponse<Download> listByUser(
065      @NotNull String user,
066      @Nullable Pageable page,
067      @Nullable Set<Download.Status> status,
068      LocalDateTime from,
069      Boolean statistics);
070
071  /** Counts the downloads created by a user. */
072  long countByUser(
073      @NotNull String user,
074      @Nullable Set<Download.Status> status,
075      LocalDateTime from);
076
077  /**
078   * Retrieves a pageable result of the downloads created by a user in a given status.
079   *
080   * <p>Internal use only; behaviour may change without notice.
081   */
082  PagingResponse<Download> listByEraseAfter(
083      @Nullable Pageable page,
084      @Nullable String eraseAfter,
085      @Nullable Long size,
086      @Nullable String erasureNotification);
087
088  /** Update an existing occurrence download. */
089  Download update(@NotNull @Valid Download download);
090
091  /**
092   * Retrieves a pageable result of the dataset usages in a occurrence download.
093   *
094   * <p>The Downloads in the DatasetOccurrenceDownloadUsages are null, to avoid redundant repetition
095   * of potentially large objects.
096   */
097  PagingResponse<DatasetOccurrenceDownloadUsage> listDatasetUsages(
098      @NotNull String keyOrDoi, @Nullable Pageable page);
099
100  PagingResponse<DatasetOccurrenceDownloadUsage> listDatasetUsages(
101      @NotNull String keyOrDoi,
102      @Nullable String datasetTitle,
103      @Nullable DatasetUsageSortField sortBy,
104      @Nullable SortOrder sortOrder,
105      @Nullable Pageable page);
106
107  PagingResponse<OrganizationOccurrenceDownloadUsage> listOrganizationUsages(
108      @NotNull String keyOrDoi,
109      @Nullable String organizationTitle,
110      @Nullable OrganizationUsageSortField sortBy,
111      @Nullable SortOrder sortOrder,
112      @Nullable Pageable page);
113
114  PagingResponse<CountryOccurrenceDownloadUsage> listCountryUsages(
115      @NotNull String keyOrDoi,
116      @Nullable CountryUsageSortField sortBy,
117      @Nullable SortOrder sortOrder,
118      @Nullable Pageable page);
119
120  /** Retrieve citation details of a download by its unique key or DOI. */
121  String getCitation(@NotNull String keyOrDoi);
122
123  /** Retrieves downloads monthly stats by country (user and publishing country) and dataset. */
124  Map<Integer, Map<Integer, Long>> getDownloadsByUserCountry(
125      @Nullable Date fromDate, @Nullable Date toDate, @Nullable Country userCountry);
126
127  /** Retrieves downloads monthly stats by source. */
128  Map<Integer, Map<Integer, Long>> getDownloadsBySource(
129      @Nullable Date fromDate, @Nullable Date toDate, @Nullable String source);
130
131  /**
132   * Retrieves downloaded records monthly stats by country (user and publishing country) and
133   * dataset.
134   */
135  Map<Integer, Map<Integer, Long>> getDownloadedRecordsByDataset(
136      @Nullable Date fromDate,
137      @Nullable Date toDate,
138      @Nullable Country publishingCountry,
139      @Nullable UUID datasetKey,
140      @Nullable UUID publishingOrgKey);
141
142  /** Retrieves downloads monthly stats by country (user and publishing country) and dataset. */
143  Map<Integer, Map<Integer, Long>> getDownloadsByDataset(
144      @Nullable Date fromDate,
145      @Nullable Date toDate,
146      @Nullable Country publishingCountry,
147      @Nullable UUID datasetKey,
148      @Nullable UUID publishingOrgKey);
149
150  /** Retrieves downloads monthly stats by country (user and publishing country) and dataset. */
151  PagingResponse<DownloadStatistics> getDownloadStatistics(
152      @Nullable Date fromDate,
153      @Nullable Date toDate,
154      @Nullable Country publishingCountry,
155      @Nullable UUID datasetKey,
156      @Nullable UUID publishingOrgKey,
157      @Nullable Pageable page);
158
159  /**
160   * Persists usages of datasets in an occurrence download.
161   *
162   * @param downloadKey downloadkey of the datasets' usage information.
163   * @param datasetCitations map of datasetkey as key and number of records as value.
164   */
165  void createUsages(@NotNull String downloadKey, @NotNull Map<UUID, Long> datasetCitations);
166
167  void updateLicense(@NotNull String downloadKey, @NotNull License license);
168
169  void updateTotalRecords(@NotNull String downloadKey, @NotNull long totalRecords);
170
171  void updateLicenseAndTotalRecords(
172      @NotNull String downloadKey, @NotNull License license, @NotNull long totalRecords);
173}