io.micronaut.http.multipart.StreamingFileUpload Maven / Gradle / Ivy
/*
* Copyright 2017-2020 original authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.micronaut.http.multipart;
import io.micronaut.core.annotation.NonNull;
import org.reactivestreams.Publisher;
import java.io.File;
import java.io.InputStream;
import java.io.OutputStream;
/**
* Represents a part of a {@link io.micronaut.http.MediaType#MULTIPART_FORM_DATA} request.
*
* The {@code StreamingFileUpload} may be incomplete when first received, in which case the consumer can subscribe
* to the file upload to process the data a chunk at a time.
*
* The {@link #transferTo(String)} method can be used whether the upload is complete or not. If it is not complete
* the framework will automatically subscribe to the upload and transfer the data chunk by chunk in a non-blocking
* manner
*
* All I/O operation return a {@link Publisher} that runs on the the configured I/O
* {@link java.util.concurrent.ExecutorService}
*
* @author Graeme Rocher
* @since 1.0
*/
public interface StreamingFileUpload extends FileUpload, Publisher {
/**
* A convenience method to write this uploaded item to disk.
*
* This method will return a no-op {@link Publisher} if called multiple times for the same location
*
* @param location the name of the file to which the stream will be written. The file is created relative to
* the location as specified in the {@code MultipartConfiguration}
* @return A {@link Publisher} that outputs whether the transfer was successful
* @deprecated Use {@link #transferTo(File)} or {@link #transferTo(OutputStream)} instead.
*/
@Deprecated
Publisher transferTo(String location);
/**
* A convenience method to write this uploaded item to disk.
*
* This method will return a no-op {@link Publisher} if called multiple times for the same location
*
* @param destination the destination of the file to which the stream will be written.
* @return A {@link Publisher} that outputs whether the transfer was successful
*/
Publisher transferTo(File destination);
/**
* A convenience method to write this uploaded item the provided output stream.
*
* @param outputStream the destination to which the stream will be written.
* @return A {@link Publisher} that outputs whether the transfer was successful
* @since 3.1.0
*/
default Publisher transferTo(OutputStream outputStream) {
throw new UnsupportedOperationException("StreamingFileUpload doesn't support transferTo OutputStream");
}
/**
* Deletes the underlying storage for a file item, including deleting any associated temporary disk file.
*
* @return A {@link Publisher} that outputs whether to delete was successful
*/
Publisher delete();
/**
* Create an {@link InputStream} that reads this file. The returned stream must be closed after
* use. The stream may block when data isn't yet available.
*
* @return An {@link InputStream} that reads this file's contents
* @since 4.2.0
*/
@NonNull
default InputStream asInputStream() {
throw new UnsupportedOperationException("StreamingFileUpload doesn't support asInputStream");
}
}