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