001/*
002 * Copyright 2014 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.occurrence;
014
015import org.gbif.api.model.occurrence.DownloadRequest;
016
017import java.io.InputStream;
018
019import javax.annotation.Nullable;
020import javax.validation.constraints.NotNull;
021
022/**
023 * Provides services to manage download requests and retrieve the download file. The services provided are:
024 * <ul>
025 * <li><strong>request</strong> inits a new download and assigns it a key</li> *
026 * <li><strong>cancel</strong> cancels an existing download</li>
027 * <li><strong>getResult</strong> retrieves the download file, if it is ready</li>
028 * </ul>
029 */
030public interface DownloadRequestService {
031
032  /**
033   * Cancels running download. If the download is not running throws an IllegalStateException.
034   */
035  void cancel(@NotNull String downloadKey);
036
037  /**
038   * Creates a download request. If the request is successfully created its key is returned.
039   */
040  String create(@NotNull DownloadRequest downloadRequest);
041
042  /**
043   * @param downloadKey of the corresponding download request
044   * @return the input stream of the zipped download result file or null if it's not existing or ready yet
045   */
046  @Nullable
047  InputStream getResult(String downloadKey);
048
049}