Class SimpleFileServer

java.lang.Object
com.sun.net.httpserver.SimpleFileServer
public final class SimpleFileServer extends Object
A simple HTTP file server and its components (intended for testing, development and debugging purposes only).

A simple file server is composed of three components:

  • an HttpServer that is bound to a given address,
  • an HttpHandler that serves files from a given directory path, and
  • an optional Filter that prints log messages relating to the exchanges handled by the server.
The individual server components can be retrieved for reuse and extension via the static methods provided.

Simple file server

The createFileServer static factory method returns an HttpServer that is a simple out-of-the-box file server. The server comes with an initial handler that serves files from a given directory path (and its subdirectories). The output level determines what log messages are printed to System.out, if any.

Example of a simple file server: 

   var addr = new InetSocketAddress(8080);
   var server = SimpleFileServer.createFileServer(addr, Path.of("/some/path"), OutputLevel.INFO);
   server.start();

File handler

The createFileHandler static factory method returns an HttpHandler that serves files and directory listings. The handler supports only the HEAD and GET request methods; to handle other request methods, one can either add additional handlers to the server, or complement the file handler by composing a single handler via HttpHandlers.handleOrElse(Predicate, HttpHandler, HttpHandler).

Example of composing a single handler: 

   var handler = HttpHandlers.handleOrElse(
       (req) -> req.getRequestMethod().equals("PUT"),
       (exchange) -> {
           // validate and handle PUT request
       },
       SimpleFileServer.createFileHandler(Path.of("/some/path")))
   );

Output filter

The createOutputFilter static factory method returns a post-processing filter that prints log messages relating to the exchanges handled by the server. The output format is specified by the outputLevel.

Example of an output filter: 

   var filter = SimpleFileServer.createOutputFilter(System.out, OutputLevel.VERBOSE);
   var server = HttpServer.create(new InetSocketAddress(8080), 10, "/some/path/", new SomeHandler(), filter);
   server.start();

jwebserver Tool

A simple HTTP file server implementation is provided via the jwebserver tool.

Tool Guides:
jwebserver
Since:
18

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    SimpleFileServer.OutputLevel
    Describes the log message output level produced by the server when processing exchanges.

  • Method Summary

    Modifier and Type
    Method
    Description
    static HttpHandler
    createFileHandler(Path rootDirectory)
    Creates a file handler that serves files from a given directory path (and its subdirectories).
    static HttpServer
    createFileServer(InetSocketAddress addr, Path rootDirectory, SimpleFileServer.OutputLevel outputLevel)
    Creates a file server that serves files from a given path.
    static Filter
    createOutputFilter(OutputStream out, SimpleFileServer.OutputLevel outputLevel)
    Creates a post-processing Filter that prints log messages about exchanges.

    Methods declared in class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    Modifier and Type
    Method
    Description
    protected Object
    clone()
    Creates and returns a copy of this object.
    boolean
    equals(Object obj)
    Indicates whether some other object is "equal to" this one.
    protected void
    finalize()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Finalization is deprecated and subject to removal in a future release.
    final Class<?>
    getClass()
    Returns the runtime class of this Object.
    int
    hashCode()
    Returns a hash code value for this object.
    final void
    notify()
    Wakes up a single thread that is waiting on this object's monitor.
    final void
    notifyAll()
    Wakes up all threads that are waiting on this object's monitor.
    String
    toString()
    Returns a string representation of the object.
    final void
    wait()
    Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
    final void
    wait(long timeoutMillis)
    Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
    final void
    wait(long timeoutMillis, int nanos)
    Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

  • Method Details

    • createFileServer

      public static HttpServer createFileServer(InetSocketAddress addr, Path rootDirectory, SimpleFileServer.OutputLevel outputLevel)
      Creates a file server that serves files from a given path.

      The server is configured with an initial context that maps the URI path to a file handler. The file handler is created as if by an invocation of createFileHandler(rootDirectory), and is associated to a context created as if by an invocation of createContext("/"). The returned server is not started.

      An output level can be given to print log messages relating to the exchanges handled by the server. The log messages, if any, are printed to System.out. If OutputLevel.NONE is given, no log messages are printed.

      Parameters:
      addr - the address to listen on
      rootDirectory - the root directory to be served, must be an absolute path
      outputLevel - the log message output level
      Returns:
      an HttpServer
      Throws:
      IllegalArgumentException - if root does not exist, is not absolute, is not a directory, or is not readable
      UncheckedIOException - if an I/O error occurs
      NullPointerException - if any argument is null

    • createFileHandler

      public static HttpHandler createFileHandler(Path rootDirectory)
      Creates a file handler that serves files from a given directory path (and its subdirectories).

      The file handler resolves the request URI against the given rootDirectory path to determine the path p on the associated file system to serve the response. If the path p is a directory, then the response contains a directory listing, formatted in HTML, as the response body. If the path p is a file, then the response contains a "Content-Type" header based on the best-guess content type, as determined by an invocation of getContentTypeFor, on the system-wide mimeTable, as well as the contents of the file as the response body.

      The handler supports only requests with the HEAD or GET method, and will reply with a 405 response code for requests with any other method.

      Parameters:
      rootDirectory - the root directory to be served, must be an absolute path
      Returns:
      a file handler
      Throws:
      IllegalArgumentException - if rootDirectory does not exist, is not absolute, is not a directory, or is not readable
      NullPointerException - if the argument is null

    • createOutputFilter

      public static Filter createOutputFilter(OutputStream out, SimpleFileServer.OutputLevel outputLevel)
      Creates a post-processing Filter that prints log messages about exchanges. The log messages are printed to the given OutputStream in UTF-8 encoding.
      API Note:
      To not output any log messages it is recommended to not use a filter.
      Parameters:
      out - the stream to print to
      outputLevel - the output level
      Returns:
      a post-processing filter
      Throws:
      IllegalArgumentException - if OutputLevel.NONE is given
      NullPointerException - if any argument is null