| /******************************************************************************** |
| * Copyright (c) 2015-2019 Contributors to the Eclipse Foundation |
| * |
| * See the NOTICE file(s) distributed with this work for additional |
| * information regarding copyright ownership. |
| * |
| * This program and the accompanying materials are made available under the |
| * terms of the Eclipse Public License v. 2.0 which is available at |
| * http://www.eclipse.org/legal/epl-2.0. |
| * |
| * SPDX-License-Identifier: EPL-2.0 |
| * |
| ********************************************************************************/ |
| |
| package org.eclipse.mdm.api.base.file; |
| |
| import java.io.IOException; |
| import java.io.InputStream; |
| import java.nio.file.Path; |
| import java.util.Collection; |
| |
| import org.eclipse.mdm.api.base.model.Entity; |
| import org.eclipse.mdm.api.base.model.FileLink; |
| |
| /** |
| * Provides stream and download operations to access externally linked files. |
| * |
| * @since 1.0.0 |
| * @author Viktor Stoehr, Gigatronik Ingolstadt GmbH |
| */ |
| public interface FileService { |
| |
| // ====================================================================== |
| // Public methods |
| // ====================================================================== |
| |
| /** |
| * Sequential download of given {@link FileLink}s into given target {@code |
| * Path}. Remote paths linked multiple times are downloaded only once. |
| * |
| * @param entity Used for security checks. |
| * @param target Must be a directory. |
| * @param fileLinks Collection of {@code FileLink}s to download. |
| * @throws IOException Thrown if unable to download files. |
| */ |
| default void downloadSequential(Entity entity, Path target, Collection<FileLink> fileLinks) throws IOException { |
| downloadSequential(entity, target, fileLinks, null); |
| } |
| |
| /** |
| * Sequential download of given {@link FileLink}s into given target {@code |
| * Path}. Remote paths linked multiple times are downloaded only once. The |
| * download progress may be traced with a progress listener. |
| * |
| * @param entity Used for security checks. |
| * @param target Must be a directory. |
| * @param fileLinks Collection of {@code FileLink}s to download. |
| * @param progressListener The progress listener. |
| * @throws IOException Thrown if unable to download files. |
| */ |
| void downloadSequential(Entity entity, Path target, Collection<FileLink> fileLinks, |
| ProgressListener progressListener) throws IOException; |
| |
| /** |
| * Parallel download of given {@link FileLink}s into given target {@code |
| * Path}. Remote paths linked multiple times are downloaded only once. |
| * |
| * @param entity Used for security checks. |
| * @param target Must be a directory. |
| * @param fileLinks Collection of {@code FileLink}s to download. |
| * @throws IOException Thrown if unable to download files. |
| */ |
| default void downloadParallel(Entity entity, Path target, Collection<FileLink> fileLinks) throws IOException { |
| downloadParallel(entity, target, fileLinks, null); |
| } |
| |
| /** |
| * Parallel download of given {@link FileLink}s into given target {@code |
| * Path}. Remote paths linked multiple times are downloaded only once. The |
| * download progress may be traced with a progress listener. |
| * |
| * @param entity Used for security checks. |
| * @param target Must be a directory. |
| * @param fileLinks Collection of {@code FileLink}s to download. |
| * @param progressListener The progress listener. |
| * @throws IOException Thrown if unable to download files. |
| */ |
| void downloadParallel(Entity entity, Path target, Collection<FileLink> fileLinks, ProgressListener progressListener) |
| throws IOException; |
| |
| /** |
| * Downloads given {@link FileLink} into given target {@code Path}. |
| * |
| * @param entity Used for security checks. |
| * @param target Must be a directory. |
| * @param fileLink The {@code FileLink} to download. |
| * @throws IOException Thrown if unable to download file. |
| */ |
| default void download(Entity entity, Path target, FileLink fileLink) throws IOException { |
| download(entity, target, fileLink, null); |
| } |
| |
| /** |
| * Downloads given {@link FileLink} into given target {@code Path}. The download |
| * progress may be traced with a progress listener. |
| * |
| * @param entity Used for security checks. |
| * @param target Must be a directory. |
| * @param fileLink The {@code FileLink} to download. |
| * @param progressListener The progress listener. |
| * @throws IOException Thrown if unable to download file. |
| */ |
| void download(Entity entity, Path target, FileLink fileLink, ProgressListener progressListener) throws IOException; |
| |
| /** |
| * Opens an {@code InputStream} for given {@link FileLink}. The returned stream |
| * should be consumed with a try-with-resources statement to ensure the stream |
| * is closed properly, e.g: |
| * |
| * <pre> |
| * try (InputStream is = openStream(entity, fileLink)) { |
| * // do something useful |
| * } |
| * </pre> |
| * |
| * @param entity Used for security checks. |
| * @param fileLink The {@code FileLink} to be provided as a stream. |
| * @return A consumable {@code InputStream} is returned. |
| * @throws IOException Thrown if unable to provide as stream. |
| */ |
| default InputStream openStream(Entity entity, FileLink fileLink) throws IOException { |
| return openStream(entity, fileLink, null); |
| } |
| |
| /** |
| * Opens an {@code InputStream} for given {@link FileLink}. The progress of the |
| * stream consumption may be traced with a progress listener. The returned |
| * stream should be consumed with a try-with-resources statement to ensure the |
| * stream is closed properly, e.g: |
| * |
| * <pre> |
| * try (InputStream is = openStream(entity, fileLink)) { |
| * // do something useful |
| * } |
| * </pre> |
| * |
| * @param entity Used for security checks. |
| * @param fileLink The {@code FileLink} to be provided as a stream. |
| * @param progressListener The progress listener. |
| * @return A consumable {@code InputStream} is returned. |
| * @throws IOException Thrown if unable to provide as stream. |
| */ |
| InputStream openStream(Entity entity, FileLink fileLink, ProgressListener progressListener) throws IOException; |
| |
| /** |
| * Loads the file size for given {@link FileLink}. The file size is stored in |
| * the given {@code FileLink}. |
| * |
| * @param entity Used for security checks. |
| * @param fileLink The {@code FileLink} whose file size is requested. |
| * @throws IOException Thrown if unable to load file size. |
| */ |
| void loadSize(Entity entity, FileLink fileLink) throws IOException; |
| |
| // ====================================================================== |
| // Inner classes |
| // ====================================================================== |
| |
| /** |
| * A {@link FileService} consumer may implement this interface to get notified |
| * about stream or download progress. |
| */ |
| @FunctionalInterface |
| interface ProgressListener { |
| |
| /** |
| * Progress notification. |
| * |
| * @param bytes Number of transferred bytes since last notification. |
| * @param percent The overall percentage, where percent p ∈ [0.0, 1.0]. |
| */ |
| void progress(int bytes, float percent); |
| |
| } |
| |
| } |