6.21 File Uploads - Route Arguments - 《Micronaut v3.0.0 Documentation》

Route Arguments
- Chunk Data Types
- Whole Data Types

Route Arguments

Method argument types determine how files are received. Data can be received a chunk at a time or when an upload is completed.

If the route argument name cannot or should not match the name of the part in the request, add the @Part annotation to the argument and specify the expected name in the request.

Chunk Data Types

PartData represents a chunk of data received in a multipart request. PartData interface methods convert the data to a byte[], InputStream, or a ByteBuffer.

Data can only be retrieved from a PartData once. The underlying buffer is released, causing further attempts to fail.

Route arguments of type Publisher<PartData> are treated as intended to receive a single file, and each chunk of the received file will be sent downstream. If the generic type is other than PartData, conversion will be attempted using Micronaut’s conversion service. Conversions to String and byte[] are supported by default.

If you need knowledge about the metadata of an uploaded file, the StreamingFileUpload class is a Publisher<PartData> that also has file information such as the content type and file name.

Streaming file upload

import io.micronaut.http.HttpResponse;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.multipart.StreamingFileUpload;
import org.reactivestreams.Publisher;
import reactor.core.publisher.Mono;
import io.micronaut.core.async.annotation.SingleResult;
import java.io.File;
import java.io.IOException;
import static io.micronaut.http.HttpStatus.CONFLICT;
import static io.micronaut.http.MediaType.MULTIPART_FORM_DATA;
import static io.micronaut.http.MediaType.TEXT_PLAIN;
@Controller("/upload")
public class UploadController {
    @Post(value = "/", consumes = MULTIPART_FORM_DATA, produces = TEXT_PLAIN) (1)
    @SingleResult
    public Publisher<HttpResponse<String>> upload(StreamingFileUpload file) { (2)
        File tempFile;
        try {
            tempFile = File.createTempFile(file.getFilename(), "temp");
        } catch (IOException e) {
            return Mono.error(e);
        }
        Publisher<Boolean> uploadPublisher = file.transferTo(tempFile); (3)
        return Mono.from(uploadPublisher)  (4)
            .map(success -> {
                if (success) {
                    return HttpResponse.ok("Uploaded");
                } else {
                    return HttpResponse.<String>status(CONFLICT)
                                       .body("Upload Failed");
                }
            });
    }
}

Streaming file upload

import io.micronaut.http.HttpResponse
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.micronaut.http.multipart.StreamingFileUpload
import org.reactivestreams.Publisher
import reactor.core.publisher.Mono
import static io.micronaut.http.HttpStatus.CONFLICT
import static io.micronaut.http.MediaType.MULTIPART_FORM_DATA
import static io.micronaut.http.MediaType.TEXT_PLAIN
@Controller("/upload")
class UploadController {
    @Post(value = "/", consumes = MULTIPART_FORM_DATA, produces = TEXT_PLAIN) (1)
    Mono<HttpResponse<String>> upload(StreamingFileUpload file) { (2)
        File tempFile = File.createTempFile(file.filename, "temp")
        Publisher<Boolean> uploadPublisher = file.transferTo(tempFile) (3)
        Mono.from(uploadPublisher)  (4)
            .map({ success ->
                if (success) {
                    HttpResponse.ok("Uploaded")
                } else {
                    HttpResponse.<String>status(CONFLICT)
                            .body("Upload Failed")
                }
            })
    }
}

Streaming file upload

import io.micronaut.http.HttpResponse
import io.micronaut.http.HttpStatus.CONFLICT
import io.micronaut.http.MediaType.MULTIPART_FORM_DATA
import io.micronaut.http.MediaType.TEXT_PLAIN
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.micronaut.http.multipart.StreamingFileUpload
import reactor.core.publisher.Mono
import java.io.File
@Controller("/upload")
class UploadController {
    @Post(value = "/", consumes = [MULTIPART_FORM_DATA], produces = [TEXT_PLAIN]) (1)
    fun upload(file: StreamingFileUpload): Mono<HttpResponse<String>> { (2)
        val tempFile = File.createTempFile(file.filename, "temp")
        val uploadPublisher = file.transferTo(tempFile) (3)
        return Mono.from(uploadPublisher)  (4)
            .map { success ->
                if (success) {
                    HttpResponse.ok("Uploaded")
                } else {
                    HttpResponse.status<String>(CONFLICT)
                        .body("Upload Failed")
                }
            }
    }
}

1	The method consumes MULTIPART_FORM_DATA
2	The method parameters match form attribute names. In this case `file` will match for example an `<input type=”file” name=”file”>`
3	The StreamingFileUpload.transferTo(java.lang.String) method transfers the file to the server. The method returns a Publisher
4	The returned reactor:Mono[] subscribes to the Publisher and outputs a response once the upload is complete, without blocking.

Whole Data Types

Route arguments that are not publishers cause route execution to be delayed until the upload has finished. The received data will attempt to be converted to the requested type. Conversions to a String or byte[] are supported by default. In addition, the file can be converted to a POJO if a media type codec is registered that supports the media type of the file. A media type codec is included by default that allows conversion of JSON files to POJOs.

Receiving a byte array

import io.micronaut.http.HttpResponse;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;
import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import static io.micronaut.http.MediaType.MULTIPART_FORM_DATA;
import static io.micronaut.http.MediaType.TEXT_PLAIN;
@Controller("/upload")
public class BytesUploadController {
    @Post(value = "/bytes", consumes = MULTIPART_FORM_DATA, produces = TEXT_PLAIN) (1)
    public HttpResponse<String> uploadBytes(byte[] file, String fileName) { (2)
        try {
            File tempFile = File.createTempFile(fileName, "temp");
            Path path = Paths.get(tempFile.getAbsolutePath());
            Files.write(path, file); (3)
            return HttpResponse.ok("Uploaded");
        } catch (IOException e) {
            return HttpResponse.badRequest("Upload Failed");
        }
    }
}

Receiving a byte array

import io.micronaut.http.HttpResponse
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import java.nio.file.Files
import java.nio.file.Path
import java.nio.file.Paths
import static io.micronaut.http.MediaType.MULTIPART_FORM_DATA
import static io.micronaut.http.MediaType.TEXT_PLAIN
@Controller("/upload")
class BytesUploadController {
    @Post(value = "/bytes", consumes = MULTIPART_FORM_DATA, produces = TEXT_PLAIN) (1)
    HttpResponse<String> uploadBytes(byte[] file, String fileName) { (2)
        try {
            File tempFile = File.createTempFile(fileName, "temp")
            Path path = Paths.get(tempFile.absolutePath)
            Files.write(path, file) (3)
            HttpResponse.ok("Uploaded")
        } catch (IOException e) {
            HttpResponse.badRequest("Upload Failed")
        }
    }
}

Receiving a byte array

import io.micronaut.http.HttpResponse
import io.micronaut.http.MediaType
import io.micronaut.http.MediaType.MULTIPART_FORM_DATA
import io.micronaut.http.MediaType.TEXT_PLAIN
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import java.io.File
import java.io.IOException
import java.nio.file.Files
import java.nio.file.Paths
@Controller("/upload")
class BytesUploadController {
    @Post(value = "/bytes", consumes = [MULTIPART_FORM_DATA], produces = [TEXT_PLAIN]) (1)
    fun uploadBytes(file: ByteArray, fileName: String): HttpResponse<String> { (2)
        return try {
            val tempFile = File.createTempFile(fileName, "temp")
            val path = Paths.get(tempFile.absolutePath)
            Files.write(path, file) (3)
            HttpResponse.ok("Uploaded")
        } catch (e: IOException) {
            HttpResponse.badRequest("Upload Failed")
        }
    }
}

If you need knowledge about the metadata of an uploaded file, the CompletedFileUpload class has methods to retrieve the data of the file, and also file information such as the content type and file name.

File upload with metadata

import io.micronaut.http.HttpResponse;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.multipart.CompletedFileUpload;
import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import static io.micronaut.http.MediaType.MULTIPART_FORM_DATA;
import static io.micronaut.http.MediaType.TEXT_PLAIN;
@Controller("/upload")
public class CompletedUploadController {
    @Post(value = "/completed", consumes = MULTIPART_FORM_DATA, produces = TEXT_PLAIN) (1)
    public HttpResponse<String> uploadCompleted(CompletedFileUpload file) { (2)
        try {
            File tempFile = File.createTempFile(file.getFilename(), "temp"); (3)
            Path path = Paths.get(tempFile.getAbsolutePath());
            Files.write(path, file.getBytes()); (3)
            return HttpResponse.ok("Uploaded");
        } catch (IOException e) {
            return HttpResponse.badRequest("Upload Failed");
        }
    }
}

File upload with metadata

import io.micronaut.http.HttpResponse
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.micronaut.http.multipart.CompletedFileUpload
import java.nio.file.Files
import java.nio.file.Path
import java.nio.file.Paths
import static io.micronaut.http.MediaType.MULTIPART_FORM_DATA
import static io.micronaut.http.MediaType.TEXT_PLAIN
@Controller("/upload")
class CompletedUploadController {
    @Post(value = "/completed", consumes = MULTIPART_FORM_DATA, produces = TEXT_PLAIN) (1)
    HttpResponse<String> uploadCompleted(CompletedFileUpload file) { (2)
        try {
            File tempFile = File.createTempFile(file.filename, "temp") (3)
            Path path = Paths.get(tempFile.absolutePath)
            Files.write(path, file.bytes) (3)
            HttpResponse.ok("Uploaded")
        } catch (IOException e) {
            HttpResponse.badRequest("Upload Failed")
        }
    }
}

File upload with metadata

import io.micronaut.http.HttpResponse
import io.micronaut.http.MediaType.MULTIPART_FORM_DATA
import io.micronaut.http.MediaType.TEXT_PLAIN
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.micronaut.http.multipart.CompletedFileUpload
import java.io.File
import java.io.IOException
import java.nio.file.Files
import java.nio.file.Paths
@Controller("/upload")
class CompletedUploadController {
    @Post(value = "/completed", consumes = [MULTIPART_FORM_DATA], produces = [TEXT_PLAIN]) (1)
    fun uploadCompleted(file: CompletedFileUpload): HttpResponse<String> { (2)
        return try {
            val tempFile = File.createTempFile(file.filename, "temp") (3)
            val path = Paths.get(tempFile.absolutePath)
            Files.write(path, file.bytes) (3)
            HttpResponse.ok("Uploaded")
        } catch (e: IOException) {
            HttpResponse.badRequest("Upload Failed")
        }
    }
}

1	The method consumes MULTIPART_FORM_DATA
2	The method parameters match form attribute names. In this case the `file` will match for example an `<input type=”file” name=”file”>`
3	The `CompletedFileUpload` instance gives access to metadata about the upload as well as access to the file contents.

If a file will not be read, the discard method on the file object must be called to prevent memory leaks.