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.OrganizationUsageSortField;
027import org.gbif.api.vocabulary.SortOrder;
028
029import java.time.LocalDateTime;
030import java.util.Date;
031import java.util.Map;
032import java.util.Set;
033import java.util.UUID;
034
035import javax.annotation.Nullable;
036import javax.validation.Valid;
037import javax.validation.constraints.NotNull;
038
039/** Interface to access and persist information about occurrence download events. */
040@SuppressWarnings("unused")
041public interface OccurrenceDownloadService {
042
043  /**
044   * Persists the occurrence download object. The object must contain a unique key, the persistence
045   * storage doesn't generate one for it.
046   */
047  void create(@NotNull @Valid Download download);
048
049  /** Retrieves a occurrence download by its unique key or DOI. */
050  Download get(@NotNull String keyOrDoi);
051
052  /**
053   * Retrieves a pageable result of all the downloads, optionally the downloads can be filtered by
054   * status and source.
055   */
056  PagingResponse<Download> list(
057      @Nullable Pageable page, @Nullable Set<Download.Status> status, @Nullable String source);
058
059  /** Counts downloads based on the given parameters. */
060  long count(@Nullable Set<Download.Status> status, @Nullable String source);
061
062  /** Retrieves a pageable result of the downloads created by a user in a given status. */
063  PagingResponse<Download> listByUser(
064      @NotNull String user,
065      @Nullable Pageable page,
066      @Nullable Set<Download.Status> status,
067      LocalDateTime from,
068      Boolean statistics);
069
070  /** Counts the downloads created by a user. */
071  long countByUser(
072      @NotNull String user,
073      @Nullable Set<Download.Status> status,
074      LocalDateTime from);
075
076  /**
077   * Retrieves a pageable result of the downloads created by a user in a given status.
078   *
079   * <p>Internal use only; behaviour may change without notice.
080   */
081  PagingResponse<Download> listByEraseAfter(
082      @Nullable Pageable page,
083      @Nullable String eraseAfter,
084      @Nullable Long size,
085      @Nullable String erasureNotification);
086
087  /** Update an existing occurrence download. */
088  void update(@NotNull @Valid Download download);
089
090  /**
091   * Retrieves a pageable result of the dataset usages in a occurrence download.
092   *
093   * <p>The Downloads in the DatasetOccurrenceDownloadUsages are null, to avoid redundant repetition
094   * of potentially large objects.
095   */
096  PagingResponse<DatasetOccurrenceDownloadUsage> listDatasetUsages(
097      @NotNull String keyOrDoi, @Nullable Pageable page);
098
099  PagingResponse<DatasetOccurrenceDownloadUsage> listDatasetUsages(
100      @NotNull String keyOrDoi,
101      @Nullable String datasetTitle,
102      @Nullable DatasetUsageSortField sortBy,
103      @Nullable SortOrder sortOrder,
104      @Nullable Pageable page);
105
106  PagingResponse<OrganizationOccurrenceDownloadUsage> listOrganizationUsages(
107      @NotNull String keyOrDoi,
108      @Nullable String organizationTitle,
109      @Nullable OrganizationUsageSortField sortBy,
110      @Nullable SortOrder sortOrder,
111      @Nullable Pageable page);
112
113  PagingResponse<CountryOccurrenceDownloadUsage> listCountryUsages(
114      @NotNull String keyOrDoi,
115      @Nullable CountryUsageSortField sortBy,
116      @Nullable SortOrder sortOrder,
117      @Nullable Pageable page);
118
119  /** Retrieve citation details of a download by its unique key or DOI. */
120  String getCitation(@NotNull String keyOrDoi);
121
122  /** Retrieves downloads monthly stats by country (user and publishing country) and dataset. */
123  Map<Integer, Map<Integer, Long>> getDownloadsByUserCountry(
124      @Nullable Date fromDate, @Nullable Date toDate, @Nullable Country userCountry);
125
126  /** Retrieves downloads monthly stats by source. */
127  Map<Integer, Map<Integer, Long>> getDownloadsBySource(
128      @Nullable Date fromDate, @Nullable Date toDate, @Nullable String source);
129
130  /**
131   * Retrieves downloaded records monthly stats by country (user and publishing country) and
132   * dataset.
133   */
134  Map<Integer, Map<Integer, Long>> getDownloadedRecordsByDataset(
135      @Nullable Date fromDate,
136      @Nullable Date toDate,
137      @Nullable Country publishingCountry,
138      @Nullable UUID datasetKey,
139      @Nullable UUID publishingOrgKey);
140
141  /** Retrieves downloads monthly stats by country (user and publishing country) and dataset. */
142  Map<Integer, Map<Integer, Long>> getDownloadsByDataset(
143      @Nullable Date fromDate,
144      @Nullable Date toDate,
145      @Nullable Country publishingCountry,
146      @Nullable UUID datasetKey,
147      @Nullable UUID publishingOrgKey);
148
149  /** Retrieves downloads monthly stats by country (user and publishing country) and dataset. */
150  PagingResponse<DownloadStatistics> getDownloadStatistics(
151      @Nullable Date fromDate,
152      @Nullable Date toDate,
153      @Nullable Country publishingCountry,
154      @Nullable UUID datasetKey,
155      @Nullable UUID publishingOrgKey,
156      @Nullable Pageable page);
157
158  /**
159   * Persists usages of datasets in an occurrence download.
160   *
161   * @param downloadKey downloadkey of the datasets' usage information.
162   * @param datasetCitations map of datasetkey as key and number of records as value.
163   */
164  void createUsages(@NotNull String downloadKey, @NotNull Map<UUID, Long> datasetCitations);
165}