Introduction
To browse and select a file for upload you need a HTML <input type="file">
field in the form. As stated in the HTML specification you have to use the POST
method and the enctype
attribute of the form has to be set to "multipart/form-data"
.
<form action="upload" method="post" enctype="multipart/form-data">
<input type="text" name="description" />
<input type="file" name="file" />
<input type="submit" />
</form>
After submitting such a form, the binary multipart form data is available in the request body in a different format than when the enctype
isn't set.
Before Servlet 3.0, the Servlet API didn't natively support multipart/form-data
. It supports only the default form enctype of application/x-www-form-urlencoded
. The request.getParameter()
and consorts would all return null
when using multipart form data. This is where the well known Apache Commons FileUpload came into the picture.
Don't manually parse it!
You can in theory parse the request body yourself based on ServletRequest#getInputStream()
. However, this is a precise and tedious work which requires precise knowledge of RFC2388. You shouldn't try to do this on your own or copypaste some homegrown library-less code found elsewhere on the Internet. Many online sources have failed hard in this, such as roseindia.net. See also uploading of pdf file. You should rather use a real library which is used (and implicitly tested!) by millions of users for years. Such a library has proven its robustness.
When you're already on Servlet 3.0 or newer, use native API
If you're using at least Servlet 3.0 (Tomcat 7, Jetty 9, JBoss AS 6, GlassFish 3, etc), then you can just use standard API provided HttpServletRequest#getPart()
to collect the individual multipart form data items (most Servlet 3.0 implementations actually use Apache Commons FileUpload under the covers for this!). Also, normal form fields are available by getParameter()
the usual way.
First annotate your servlet with @MultipartConfig
in order to let it recognize and support multipart/form-data
requests and thus get getPart()
to work:
@WebServlet("/upload")
@MultipartConfig
public class UploadServlet extends HttpServlet {
// ...
}
Then, implement its doPost()
as follows:
protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
String description = request.getParameter("description"); // Retrieves <input type="text" name="description">
Part filePart = request.getPart("file"); // Retrieves <input type="file" name="file">
String fileName = Paths.get(filePart.getSubmittedFileName()).getFileName().toString(); // MSIE fix.
InputStream fileContent = filePart.getInputStream();
// ... (do your job here)
}
Note the Path#getFileName()
. This is a MSIE fix as to obtaining the file name. This browser incorrectly sends the full file path along the name instead of only the file name.
In case you want to upload multiple files via either multiple="true"
,
<input type="file" name="files" multiple="true" />
or the old-fashioned way with multiple inputs,
<input type="file" name="files" />
<input type="file" name="files" />
<input type="file" name="files" />
...
then you can collect them as below (unfortunately there is no such method as request.getParts("files")
):
protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
// ...
List<Part> fileParts = request.getParts().stream().filter(part -> "files".equals(part.getName()) && part.getSize() > 0).collect(Collectors.toList()); // Retrieves <input type="file" name="files" multiple="true">
for (Part filePart : fileParts) {
String fileName = Paths.get(filePart.getSubmittedFileName()).getFileName().toString(); // MSIE fix.
InputStream fileContent = filePart.getInputStream();
// ... (do your job here)
}
}
When you're not on Servlet 3.1 yet, manually get submitted file name
Note that Part#getSubmittedFileName()
was introduced in Servlet 3.1 (Tomcat 8, Jetty 9, WildFly 8, GlassFish 4, etc). If you're not on Servlet 3.1 yet, then you need an additional utility method to obtain the submitted file name.
private static String getSubmittedFileName(Part part) {
for (String cd : part.getHeader("content-disposition").split(";")) {
if (cd.trim().startsWith("filename")) {
String fileName = cd.substring(cd.indexOf('=') + 1).trim().replace("\"", "");
return fileName.substring(fileName.lastIndexOf('/') + 1).substring(fileName.lastIndexOf('\\') + 1); // MSIE fix.
}
}
return null;
}
String fileName = getSubmittedFileName(filePart);
Note the MSIE fix as to obtaining the file name. This browser incorrectly sends the full file path along the name instead of only the file name.
When you're not on Servlet 3.0 yet, use Apache Commons FileUpload
If you're not on Servlet 3.0 yet (isn't it about time to upgrade?), the common practice is to make use of Apache Commons FileUpload to parse the multpart form data requests. It has an excellent User Guide and FAQ (carefully go through both). There's also the O'Reilly ("cos") MultipartRequest
, but it has some (minor) bugs and isn't actively maintained anymore for years. I wouldn't recommend using it. Apache Commons FileUpload is still actively maintained and currently very mature.
In order to use Apache Commons FileUpload, you need to have at least the following files in your webapp's /WEB-INF/lib
:
Your initial attempt failed most likely because you forgot the commons IO.
Here's a kickoff example how the doPost()
of your UploadServlet
may look like when using Apache Commons FileUpload:
protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
try {
List<FileItem> items = new ServletFileUpload(new DiskFileItemFactory()).parseRequest(request);
for (FileItem item : items) {
if (item.isFormField()) {
// Process regular form field (input type="text|radio|checkbox|etc", select, etc).
String fieldName = item.getFieldName();
String fieldValue = item.getString();
// ... (do your job here)
} else {
// Process form file field (input type="file").
String fieldName = item.getFieldName();
String fileName = FilenameUtils.getName(item.getName());
InputStream fileContent = item.getInputStream();
// ... (do your job here)
}
}
} catch (FileUploadException e) {
throw new ServletException("Cannot parse multipart request.", e);
}
// ...
}
It's very important that you don't call getParameter()
, getParameterMap()
, getParameterValues()
, getInputStream()
, getReader()
, etc on the same request beforehand. Otherwise the servlet container will read and parse the request body and thus Apache Commons FileUpload will get an empty request body. See also a.o. ServletFileUpload#parseRequest(request) returns an empty list.
Note the FilenameUtils#getName()
. This is a MSIE fix as to obtaining the file name. This browser incorrectly sends the full file path along the name instead of only the file name.
Alternatively you can also wrap this all in a Filter
which parses it all automagically and put the stuff back in the parametermap of the request so that you can continue using request.getParameter()
the usual way and retrieve the uploaded file by request.getAttribute()
. You can find an example in this blog article.
Workaround for GlassFish3 bug of getParameter()
still returning null
Note that Glassfish versions older than 3.1.2 had a bug wherein the getParameter()
still returns null
. If you are targeting such a container and can't upgrade it, then you need to extract the value from getPart()
with help of this utility method:
private static String getValue(Part part) throws IOException {
BufferedReader reader = new BufferedReader(new InputStreamReader(part.getInputStream(), "UTF-8"));
StringBuilder value = new StringBuilder();
char[] buffer = new char[1024];
for (int length = 0; (length = reader.read(buffer)) > 0;) {
value.append(buffer, 0, length);
}
return value.toString();
}
String description = getValue(request.getPart("description")); // Retrieves <input type="text" name="description">
Saving uploaded file (don't use getRealPath()
nor part.write()
!)
Head to the following answers for detail on properly saving the obtained InputStream
(the fileContent
variable as shown in the above code snippets) to disk or database:
Serving uploaded file
Head to the following answers for detail on properly serving the saved file from disk or database back to the client:
Ajaxifying the form
Head to the following answers how to upload using Ajax (and jQuery). Do note that the servlet code to collect the form data does not need to be changed for this! Only the way how you respond may be changed, but this is rather trivial (i.e. instead of forwarding to JSP, just print some JSON or XML or even plain text depending on whatever the script responsible for the Ajax call is expecting).
Hope this all helps :)
ServletContext
When the servlet container (like Apache Tomcat) starts up, it will deploy and load all its web applications. When a web application is loaded, the servlet container creates the ServletContext
once and keeps it in the server's memory. The web app's web.xml
and all of included web-fragment.xml
files is parsed, and each <servlet>
, <filter>
and <listener>
found (or each class annotated with @WebServlet
, @WebFilter
and @WebListener
respectively) is instantiated once and kept in the server's memory as well. For each instantiated filter, its init()
method is invoked with a new FilterConfig
.
When a Servlet
has a <servlet><load-on-startup>
or @WebServlet(loadOnStartup)
value greater than 0
, then its init()
method is also invoked during startup with a new ServletConfig
. Those servlets are initialized in the same order specified by that value (1
is 1st, 2
is 2nd, etc). If the same value is specified for more than one servlet, then each of those servlets is loaded in the same order as they appear in the web.xml
, web-fragment.xml
, or @WebServlet
classloading. In the event the "load-on-startup" value is absent, the init()
method will be invoked whenever the HTTP request hits that servlet for the very first time.
When the servlet container is finished with all of the above described initialization steps, then the ServletContextListener#contextInitialized()
will be invoked.
When the servlet container shuts down, it unloads all web applications, invokes the destroy()
method of all its initialized servlets and filters, and all ServletContext
, Servlet
, Filter
and Listener
instances are trashed. Finally the ServletContextListener#contextDestroyed()
will be invoked.
HttpServletRequest
and HttpServletResponse
The servlet container is attached to a web server that listens for HTTP requests on a certain port number (port 8080 is usually used during development and port 80 in production). When a client (e.g. user with a web browser, or programmatically using URLConnection
) sends an HTTP request, the servlet container creates new HttpServletRequest
and HttpServletResponse
objects and passes them through any defined Filter
in the chain and, eventually, the Servlet
instance.
In the case of filters, the doFilter()
method is invoked. When the servlet container's code calls chain.doFilter(request, response)
, the request and response continue on to the next filter, or hit the servlet if there are no remaining filters.
In the case of servlets, the service()
method is invoked. By default, this method determines which one of the doXxx()
methods to invoke based off of request.getMethod()
. If the determined method is absent from the servlet, then an HTTP 405 error is returned in the response.
The request object provides access to all of the information about the HTTP request, such as its URL, headers, query string and body. The response object provides the ability to control and send the HTTP response the way you want by, for instance, allowing you to set the headers and the body (usually with generated HTML content from a JSP file). When the HTTP response is committed and finished, both the request and response objects are recycled and made available for reuse.
HttpSession
When a client visits the webapp for the first time and/or the HttpSession
is obtained for the first time via request.getSession()
, the servlet container creates a new HttpSession
object, generates a long and unique ID (which you can get by session.getId()
), and stores it in the server's memory. The servlet container also sets a Cookie
in the Set-Cookie
header of the HTTP response with JSESSIONID
as its name and the unique session ID as its value.
As per the HTTP cookie specification (a contract any decent web browser and web server must adhere to), the client (the web browser) is required to send this cookie back in subsequent requests in the Cookie
header for as long as the cookie is valid (i.e. the unique ID must refer to an unexpired session and the domain and path are correct). Using your browser's built-in HTTP traffic monitor, you can verify that the cookie is valid (press F12 in Chrome / Firefox 23+ / IE9+, and check the Net/Network tab). The servlet container will check the Cookie
header of every incoming HTTP request for the presence of the cookie with the name JSESSIONID
and use its value (the session ID) to get the associated HttpSession
from server's memory.
The HttpSession
stays alive until it has been idle (i.e. not used in a request) for more than the timeout value specified in <session-timeout>
, a setting in web.xml
. The timeout value defaults to 30 minutes. So, when the client doesn't visit the web app for longer than the time specified, the servlet container trashes the session. Every subsequent request, even with the cookie specified, will not have access to the same session anymore; the servlet container will create a new session.
On the client side, the session cookie stays alive for as long as the browser instance is running. So, if the client closes the browser instance (all tabs/windows), then the session is trashed on the client's side. In a new browser instance, the cookie associated with the session wouldn't exist, so it would no longer be sent. This causes an entirely new HttpSession
to be created, with an entirely new session cookie being used.
In a nutshell
- The
ServletContext
lives for as long as the web app lives. It is shared among all requests in all sessions.
- The
HttpSession
lives for as long as the client is interacting with the web app with the same browser instance, and the session hasn't timed out at the server side. It is shared among all requests in the same session.
- The
HttpServletRequest
and HttpServletResponse
live from the time the servlet receives an HTTP request from the client, until the complete response (the web page) has arrived. It is not shared elsewhere.
- All
Servlet
, Filter
and Listener
instances live as long as the web app lives. They are shared among all requests in all sessions.
- Any
attribute
that is defined in ServletContext
, HttpServletRequest
and HttpSession
will live as long as the object in question lives. The object itself represents the "scope" in bean management frameworks such as JSF, CDI, Spring, etc. Those frameworks store their scoped beans as an attribute
of its closest matching scope.
Thread Safety
That said, your major concern is possibly thread safety. You should now know that servlets and filters are shared among all requests. That's the nice thing about Java, it's multithreaded and different threads (read: HTTP requests) can make use of the same instance. It would otherwise be too expensive to recreate, init()
and destroy()
them for every single request.
You should also realize that you should never assign any request or session scoped data as an instance variable of a servlet or filter. It will be shared among all other requests in other sessions. That's not thread-safe! The below example illustrates this:
public class ExampleServlet extends HttpServlet {
private Object thisIsNOTThreadSafe;
protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
Object thisIsThreadSafe;
thisIsNOTThreadSafe = request.getParameter("foo"); // BAD!! Shared among all requests!
thisIsThreadSafe = request.getParameter("foo"); // OK, this is thread safe.
}
}
See also:
Best Answer
You can indeed not define the filter execution order using
@WebFilter
annotation. However, to minimize theweb.xml
usage, it's sufficient to annotate all filters with just afilterName
so that you don't need the<filter>
definition, but just a<filter-mapping>
definition in the desired order.For example,
with in
web.xml
just this:If you'd like to keep the URL pattern in
@WebFilter
, then you can just do like so,but you should still keep the
<url-pattern>
inweb.xml
, because it's required as per XSD, although it can be empty:Regardless of the approach, this all will fail in Tomcat until version 7.0.28 because it chokes on presence of
<filter-mapping>
without<filter>
. See also Using Tomcat, @WebFilter doesn't work with <filter-mapping> inside web.xml