Module org.omnifaces
Package org.omnifaces.servlet

Class FileServlet

java.lang.Object
jakarta.servlet.GenericServlet
jakarta.servlet.http.HttpServlet
org.omnifaces.servlet.FileServlet
All Implemented Interfaces:
Servlet, ServletConfig, Serializable
public abstract class FileServlet extends HttpServlet

The well known "BalusC FileServlet", as an abstract template, slightly refactored, rewritten and modernized with a.o. fast NIO stuff instead of legacy RandomAccessFile. GZIP support is stripped off as that can be done application wide via CompressedResponseFilter.

This servlet properly deals with ETag, If-None-Match and If-Modified-Since caching requests, hereby improving browser caching. This servlet also properly deals with Range and If-Range ranging requests (RFC 7233), which is required by most media players for proper audio/video streaming, and by webbrowsers and for a proper resume of an paused download, and by download accelerators to be able to request smaller parts simultaneously. This servlet is ideal when you have large files like media files placed outside the web application and you can't use the default servlet.

Usage

Just extend this class and override the getFile(HttpServletRequest) method to return the desired file. If you want to trigger a HTTP 400 "Bad Request" error, simply throw IllegalArgumentException. If you want to trigger a HTTP 404 "Not Found" error, simply return null, or a non-existent file.

Here's a concrete example which serves it via an URL like /media/foo.ext: 

 @WebServlet("/media/*")
 public class MediaFileServlet extends FileServlet {

     private File folder;

     @Override
     public void init() throws ServletException {
         folder = new File("/var/webapp/media");
     }

     @Override
     protected File getFile(HttpServletRequest request) {
         String pathInfo = request.getPathInfo();

         if (pathInfo == null || pathInfo.isEmpty() || "/".equals(pathInfo)) {
             throw new IllegalArgumentException();
         }

         return new File(folder, pathInfo);
     }

 }

You can embed it in e.g. HTML5 video tag as below: 

 <video src="#{request.contextPath}/media/video.mp4" controls="controls" />

Customizing FileServlet

If more fine grained control is desired for handling "file not found" error, determining the cache expire time, the content type, whether the file should be supplied as an attachment and the attachment's file name, then the developer can opt to override one or more of the following protected methods:

See also:

Since:
2.2
Author:
Bauke Scholtz
See Also:

  • Constructor Details

    • FileServlet

      public FileServlet()

  • Method Details

    • doHead

      protected void doHead(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException
      Overrides:
      doHead in class HttpServlet
      Throws:
      ServletException
      IOException

    • doGet

      protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException
      Overrides:
      doGet in class HttpServlet
      Throws:
      ServletException
      IOException

    • getFile

      protected abstract File getFile(HttpServletRequest request)
      Returns the file associated with the given HTTP servlet request. If this method throws IllegalArgumentException, then the servlet will return a HTTP 400 error. If this method returns null, or if File.isFile() returns false, then the servlet will invoke handleFileNotFound(HttpServletRequest, HttpServletResponse).
      Parameters:
      request - The involved HTTP servlet request.
      Returns:
      The file associated with the given HTTP servlet request.
      Throws:
      IllegalArgumentException - When the request is mangled in such way that it's not recognizable as a valid file request. The servlet will then return a HTTP 400 error.

    • handleFileNotFound

      protected void handleFileNotFound(HttpServletRequest request, HttpServletResponse response) throws IOException
      Handles the case when the file is not found.

      The default implementation sends a HTTP 404 error.

      Parameters:
      request - The involved HTTP servlet request.
      response - The involved HTTP servlet response.
      Throws:
      IOException - When something fails at I/O level.
      Since:
      2.3

    • getExpireTime

      protected long getExpireTime(HttpServletRequest request, File file)
      Returns how long the resource may be cached by the client before it expires, in seconds.

      The default implementation returns 30 days in seconds.

      Parameters:
      request - The involved HTTP servlet request.
      file - The involved file.
      Returns:
      The client cache expire time in seconds (not milliseconds!).

    • getContentType

      protected String getContentType(HttpServletRequest request, File file)
      Returns the content type associated with the given HTTP servlet request and file.

      The default implementation delegates File.getName() to ServletContext.getMimeType(String) with a fallback default value of application/octet-stream.

      Parameters:
      request - The involved HTTP servlet request.
      file - The involved file.
      Returns:
      The content type associated with the given HTTP servlet request and file.

    • isAttachment

      protected boolean isAttachment(HttpServletRequest request, String contentType)
      Returns true if we must force a "Save As" dialog based on the given HTTP servlet request and content type as obtained from getContentType(HttpServletRequest, File).

      The default implementation will return true if the content type does not start with text or image, and the Accept request header is either null or does not match the given content type.

      Parameters:
      request - The involved HTTP servlet request.
      contentType - The content type of the involved file.
      Returns:
      true if we must force a "Save As" dialog based on the given HTTP servlet request and content type.

    • getAttachmentName

      protected String getAttachmentName(HttpServletRequest request, File file)
      Returns the file name to be used in Content-Disposition header. This does not need to be URL-encoded as this will be taken care of.

      The default implementation returns File.getName().

      Parameters:
      request - The involved HTTP servlet request.
      file - The involved file.
      Returns:
      The file name to be used in Content-Disposition header.
      Since:
      2.3