Upload Files in Java with Servlet API 3.1

This example demonstrates how to handle file uploads in Java web application with Servlet API 3.1.


  • Java 1.7+;
  • Servlet container with Servlet API 3.1 support, e.g. Jetty 9.2+, Tomcat 8.0+, etc.

Download and play

You can download sources and play with this example in your preferred IDE.

  • Download and unpack the latest project bundle.
  • Open Maven project in the folder examples/servlet-api-example
  • Start com.ursaj.hfs.example.servlet.Main class from the tests scope.
  • Try the example http://localhost:8080 in the browser.

Basic example how to upload files in Java with Servlet API 3.1

Application structure

This example consist of the following files:

Web application deployment descriptor.
Servlet to handle file uploads and UI requests.
Simple POJO to keep uploaded file information.
Upload form template.
Application UI template.

Deployment descriptor

/WEB-INF/web.xml deployment descriptor is optional as this example is configured via annotations. You can omit it or provide an empty stub.

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"

Keep in mind the main concern against this approach – to modify any single parameter you have to:

  • change the code and re-build your application or
  • provide complete servlet configuration in the deployment descriptor (servlet definition, initialization parameters, multipart-configuration, URI mapping, etc).

Servlet declaration

@WebServlet annotation provides a binding between your servlet code and web application URI.

@WebServlet(urlPatterns = { "/upload" }, ... )
public class UploadServlet extends HttpServlet {
    protected void doGet ...
    protected void doPost ...

Multipart requests support

@MultipartConfig annotation enables your servlet to handle 'multipart/form-data' POST requests.

@WebServlet ...
    fileSizeThreshold = 16768,
    maxRequestSize = 10L * 1024 * 1024,
    maxFileSize = 10L * 1024 * 1024
public class UploadServlet extends HttpServlet {
    protected void doGet ...
    protected void doPost ...

Handle upload request

Parts API is the essential part of Servlet API 3.1 to handle file uploads. It implements RFC-2047 and allows to work with 'multipart/form-data' request entities.

protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
    Deque<FileInfo> files = new LinkedList<>();
    for (Part part : req.getParts()) {
        long fileSize = part.getSize();
        String fileName = part.getSubmittedFileName();
        if (fileSize == 0 && (fileName == null || fileName.isEmpty())) {
            continue; // Ignore part, if not a file.
        FileInfo info = new FileInfo(UUID.randomUUID(), fileSize, fileName, part.getContentType());

        Files.copy(part.getInputStream(), new File(uploads, info.getId().toString()).toPath());

    req.getSession().setAttribute("uploadedFiles", files);
    resp.sendRedirect(applicationUrl + "/upload");

Note! It is the best practice rule to finish POST request handling with the redirect response.

Handle UI request

GET requests are handled with the same servlet class. However your are free to split user tracks between different handlers and redirect your users wherever you want.

protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
    @SuppressWarnings("unchecked") List<FileInfo> uploadedFiles =
        (List<FileInfo>) req.getSession().getAttribute("uploadedFiles");

    if (uploadedFiles == null)
        uploadedFiles = Collections.emptyList();

    req.setAttribute("applicationUrl", applicationUrl);
    req.setAttribute("uploadedFiles", uploadedFiles);
    req.setAttribute("uploadUri", req.getContextPath() + "/upload");
    getServletContext().getRequestDispatcher("/WEB-INF/pages/upload.jsp").forward(req, resp);

Render upload form

Template /WEB-INF/pages/upload.jsp renders both upload files form and uploaded files report.

<%@page contentType="text/html" pageEncoding="UTF-8" %>
<%@taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@taglib prefix="t" tagdir="/WEB-INF/tags" %>
<jsp:useBean id="uploadedFiles" scope="request" type="java.util.Collection<com.ursaj.hfs.example.servlet.FileInfo>"/>
<jsp:useBean id="uploadUri" scope="request" type="java.lang.String"/>

<t:page title="Basic example how to upload files with Servlet API 3.1">
    <form action="${uploadUri}"
          enctype="multipart/form-data" method="post">
        <input type="file" name="file" multiple="multiple"/>
        <input type="submit" value="Upload"/>

    <h3>Uploaded files information</h3>
            <th>Content type</th>
        <c:forEach var="fileInfo" varStatus="status" items="${uploadedFiles}">
            <c:when test="${empty uploadedFiles}">
                    <td colspan="5">
                        <p>No information about uploaded files.</p>

Uniform application UI

Page template /WEB-INF/tags/page.tag keeps your application uniform across multiple pages.

<%@tag description="Page Template" pageEncoding="UTF-8" trimDirectiveWhitespaces="true" %>
<%@attribute name="title" type="java.lang.String" required="true" rtexprvalue="true" %>
<%@attribute name="head" fragment="true" required="false" %>
<jsp:useBean id="applicationUrl" scope="request" type="java.lang.String"/>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <link href="${applicationUrl}/css/style.css" rel="stylesheet" type="text/css"/>
    <jsp:invoke fragment="head"/>




Pros and cons

While it seems a trivial task to handle file uploads with Servlet API 3.1, you should consider all aspects of its usage in the real applications.


  • Simple, Servlet API is ease to use and maintain.
  • Standard, it works in most of modern application containers.
  • Sufficient, it solves the main task – allows to handle file uploads.


  • Inefficient, upload traffic goes through application server.
  • Incomplete, Servlet API does not cover uploaded files management and publishing.

Read more