/gs-uploading-files

Uploading Files :: Learn how to build a Spring application that accepts multi-part file uploads.

Primary LanguageJava

Table of Contents

This guide walks you through the process of creating a server application that can receive HTTP multi-part file uploads.

What you’ll build

You will create a Spring Boot web application that accepts file uploads. You will also build a simple HTML interface to upload a test file.

What you’ll need

Create an Application class

To start a Spring Boot MVC application, we first need a starter; here, spring-boot-starter-thymeleaf and spring-boot-starter-web are already added as dependencies. To upload files with Servlet containers, you need to register a MultipartConfigElement class (which would be <multipart-config> in web.xml). Thanks to Spring Boot, everything is auto-configured for you!

All you need to get started with this application is the following Application class.

src/main/java/hello/Application.java

link:initial/src/main/java/hello/Application.java[role=include]

As part of auto-configuring Spring MVC, Spring Boot will create a MultipartConfigElement bean and make itself ready for file uploads.

Create a file upload controller

The initial application already contains a few classes to deal with storing and loading the uploaded files on disk; they’re all located in the hello.storage package. We’ll use those in our new FileUploadController.

src/main/java/hello/FileUploadController.java

link:complete/src/main/java/hello/FileUploadController.java[role=include]

This class is annotated with @Controller so Spring MVC can pick it up and look for routes. Each method is tagged with @GetMapping or @PostMapping to tie the path and the HTTP action to a particular Controller action.

In this case:

  • GET / looks up the current list of uploaded files from the StorageService and loads it into a Thymeleaf template. It calculates a link to the actual resource using MvcUriComponentsBuilder

  • GET /files/{filename} loads the resource if it exists, and sends it to the browser to download using a "Content-Disposition" response header

  • POST / is geared to handle a multi-part message file and give it to the StorageService for saving

Note
 In a production scenario, you more likely would store the files in a temporary location, a database, or perhaps a NoSQL store like Mongo’s GridFS. It’s is best to NOT load up the file system of your application with content.

You will need to provide a StorageService for the controller to interact with a storage layer (e.g. a file system). The interface is like this:

src/main/java/hello/storage/StorageService.java

link:complete/src/main/java/hello//storage/StorageService.java[role=include]

There is an example implementation of the interface in the sample app. You could copy and paste it if you want to save time.

Creating a simple HTML template

To build something of interest, the following Thymeleaf template is a nice example of uploading files as well as showing what’s been uploaded.

src/main/resources/templates/uploadForm.html

link:complete/src/main/resources/templates/uploadForm.html[role=include]

This template has three parts:

  • An optional message at the top where Spring MVC writes a flash-scoped messages.

  • A form allowing the user to upload files

  • A list of files supplied from the backend

Tuning file upload limits

When configuring file uploads, it is often useful to set limits on the size of files. Imagine trying to handle a 5GB file upload! With Spring Boot, we can tune its auto-configured MultipartConfigElement with some property settings.

Add the following properties to your existing properties settings:

src/main/resources/application.properties

link:complete/src/main/resources/application.properties[role=include]

The multipart settings are constrained as follows:

  • spring.http.multipart.max-file-size is set to 128KB, meaning total file size cannot exceed 128KB.

  • spring.http.multipart.max-request-size is set to 128KB, meaning total request size for a multipart/form-data cannot exceed 128KB.

Make the application executable

Although it is possible to package this service as a traditional WAR file for deployment to an external application server, the simpler approach demonstrated below creates a standalone application. You package everything in a single, executable JAR file, driven by a good old Java main() method. And along the way, you use Spring’s support for embedding the Tomcat servlet container as the HTTP runtime, instead of deploying to an external instance.

You also want a target folder to upload files to, so let’s enhance the basic Application class and add a Boot CommandLineRunner which deletes and re-creates that folder at startup:

src/main/java/hello/Application.java

link:complete/src/main/java/hello/Application.java[role=include]

That runs the server-side piece that receives file uploads. Logging output is displayed. The service should be up and running within a few seconds.

With the server running, you need to open a browser and visit http://localhost:8080/ to see the upload form. Pick a (small) file and press "Upload" and you should see the success page from the controller. Choose a file that is too large and you will get an ugly error page.

You should then see something like this in your browser window:

You successfully uploaded <name of your file>!

Testing your application

There are multiple ways to test this particular feature in our application. Here’s one example that leverages MockMvc, so it does not require to start the Servlet container:

src/test/java/hello/FileUploadTests.java

link:complete/src/test/java/hello/FileUploadTests.java[role=include]

In those tests, we’re using various mocks to set up the interactions with our Controller and the StorageService but also with the Servlet container itself by using MockMultipartFile.

For an example of an integration test, please check out the FileUploadIntegrationTests class.

Summary

Congratulations! You have just written a web application that uses Spring to handle file uploads.

See Also

The following guides may also be helpful: