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.
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
Modifier and TypeClassDescriptionstatic enum
Describes the log message output level produced by the server when processing exchanges. -
Method Summary
Modifier and TypeMethodDescriptionstatic 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.
-
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 ofcreateFileHandler(rootDirectory)
, and is associated to a context created as if by an invocation ofcreateContext("/")
. 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
. IfOutputLevel.NONE
is given, no log messages are printed.- Parameters:
addr
- the address to listen onrootDirectory
- the root directory to be served, must be an absolute pathoutputLevel
- 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 readableUncheckedIOException
- if an I/O error occursNullPointerException
- if any argument is nullSecurityException
- if a security manager is installed and a recursiveFilePermission
"read
" of the rootDirectory is denied
-
createFileHandler
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 pathp
on the associated file system to serve the response. If the pathp
is a directory, then the response contains a directory listing, formatted in HTML, as the response body. If the pathp
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-widemimeTable
, 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 readableNullPointerException
- if the argument is nullSecurityException
- if a security manager is installed and a recursiveFilePermission
"read
" of the rootDirectory is denied
-
createOutputFilter
Creates a post-processing Filter that prints log messages about exchanges. The log messages are printed to the givenOutputStream
inUTF-8
encoding.- API Note:
- To not output any log messages it is recommended to not use a filter.
- Parameters:
out
- the stream to print tooutputLevel
- the output level- Returns:
- a post-processing filter
- Throws:
IllegalArgumentException
- ifOutputLevel.NONE
is givenNullPointerException
- if any argument is null
-