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.occurrence.Download;
018import org.gbif.api.model.registry.DatasetOccurrenceDownloadUsage;
019
020import java.util.Set;
021import javax.annotation.Nullable;
022import javax.validation.constraints.NotNull;
023
024/**
025 * Interface to access and persists information about occurrence download events.
026 */
027public interface OccurrenceDownloadService {
028
029
030  /**
031   * Persists the occurrence download object. The object must contain a unique key, the persistence storage doesn't
032   * generate one for it.
033   */
034  void create(@NotNull Download download);
035
036  /**
037   * Retrieves a occurrence download by its unique key.
038   */
039  Download get(@NotNull String key);
040
041
042  /**
043   * Retrieves a pageable result of all the downloads, optionally the downloads can be filtered by status.
044   */
045  PagingResponse<Download> list(@Nullable Pageable page,@Nullable Set<Download.Status> status);
046
047  /**
048   * Retrieves a pageable result of the downloads created by a user in a given status.
049   */
050  PagingResponse<Download> listByUser(@NotNull String user,  @Nullable Pageable page, @Nullable Set<Download.Status> status);
051
052  /**
053   * Update an existing occurrence download.
054   */
055  void update(@NotNull Download download);
056
057
058  /**
059   * Retrieves a pageable result of the dataset usages in a occurrence download.
060   */
061  PagingResponse<DatasetOccurrenceDownloadUsage> listDatasetUsages(@NotNull String downloadKey,
062                                                                @Nullable Pageable page);
063}