A simple file server is composed of three components: *
The {@link #createFileServer(InetSocketAddress,Path,OutputLevel) createFileServer} * static factory method returns an {@link HttpServer 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 * {@code System.out}, if any. * *
Example of a simple file server: *
{@code
* var addr = new InetSocketAddress(8080);
* var server = SimpleFileServer.createFileServer(addr, Path.of("/some/path"), OutputLevel.INFO);
* server.start();
* }
*
* The {@link #createFileHandler(Path) createFileHandler} static factory * method returns an {@code 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 * {@link HttpHandlers#handleOrElse(Predicate, HttpHandler, HttpHandler)}. * *
Example of composing a single handler: *
{@code
* var handler = HttpHandlers.handleOrElse(
* (req) -> req.getRequestMethod().equals("PUT"),
* (exchange) -> {
* // validate and handle PUT request
* },
* SimpleFileServer.createFileHandler(Path.of("/some/path")))
* );
* }
*
* The {@link #createOutputFilter(OutputStream, OutputLevel) createOutputFilter} * static factory method returns a * {@link Filter#afterHandler(String, Consumer) post-processing filter} that * prints log messages relating to the exchanges handled by the server. The * output format is specified by the {@link OutputLevel outputLevel}. * *
Example of an output filter: *
{@code
* var filter = SimpleFileServer.createOutputFilter(System.out, OutputLevel.VERBOSE);
* var server = HttpServer.create(new InetSocketAddress(8080), 10, "/some/path/", new SomeHandler(), filter);
* server.start();
* }
*
* A simple HTTP file server implementation is provided via the
* {@code jwebserver} tool.
*
* @toolGuide jwebserver
*
* @since 18
*/
public final class SimpleFileServer {
private static final UnaryOperator The log message format is based on the
* Common Logfile Format,
* that includes the following information about an {@code HttpExchange}:
*
* {@code remotehost rfc931 authuser [date] "request" status bytes}
*
* Example:
* Additional to the information provided by the
* {@linkplain OutputLevel#INFO info} level, the verbose level
* includes the request and response headers of the {@code HttpExchange}
* and the absolute path of the resource served up.
*/
VERBOSE
}
/**
* Creates a file server that serves files from a given path.
*
* The server is configured with an initial context that maps the
* URI {@code path} to a file handler. The file handler is
* created as if by an invocation of
* {@link #createFileHandler(Path) createFileHandler(rootDirectory)}, and is
* associated to a context created as if by an invocation of
* {@link HttpServer#createContext(String) 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
* {@code System.out}. If {@link OutputLevel#NONE OutputLevel.NONE} is
* given, no log messages are printed.
*
* @param addr the address to listen on
* @param rootDirectory the root directory to be served, must be an absolute path
* @param outputLevel the log message output level
* @return an HttpServer
* @throws IllegalArgumentException if root does not exist, is not absolute,
* is not a directory, or is not readable
* @throws UncheckedIOException if an I/O error occurs
* @throws NullPointerException if any argument is null
*/
public static HttpServer createFileServer(InetSocketAddress addr,
Path rootDirectory,
OutputLevel outputLevel) {
Objects.requireNonNull(addr);
Objects.requireNonNull(rootDirectory);
Objects.requireNonNull(outputLevel);
try {
var handler = FileServerHandler.create(rootDirectory, MIME_TABLE);
if (outputLevel.equals(OutputLevel.NONE))
return HttpServer.create(addr, 0, "/", handler);
else
return HttpServer.create(addr, 0, "/", handler, OutputFilter.create(System.out, outputLevel));
} catch (IOException ioe) {
throw new UncheckedIOException(ioe);
}
}
/**
* 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
* {@code rootDirectory} path to determine the path {@code p} on the
* associated file system to serve the response. If the path {@code p} is
* a directory, then the response contains a directory listing, formatted in
* HTML, as the response body. If the path {@code 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
* {@linkplain java.net.FileNameMap#getContentTypeFor(String) getContentTypeFor},
* on the system-wide {@link URLConnection#getFileNameMap() 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 {@code 405} response code for requests with
* any other method.
*
* @param rootDirectory the root directory to be served, must be an absolute path
* @return a file handler
* @throws IllegalArgumentException if rootDirectory does not exist,
* is not absolute, is not a directory, or is not readable
* @throws NullPointerException if the argument is null
*/
public static HttpHandler createFileHandler(Path rootDirectory) {
Objects.requireNonNull(rootDirectory);
return FileServerHandler.create(rootDirectory, MIME_TABLE);
}
/**
* Creates a {@linkplain Filter#afterHandler(String, Consumer)
* post-processing Filter} that prints log messages about
* {@linkplain HttpExchange exchanges}. The log messages are printed to
* the given {@code OutputStream} in {@code UTF-8} encoding.
*
* @apiNote
* To not output any log messages it is recommended to not use a filter.
*
* @param out the stream to print to
* @param outputLevel the output level
* @return a post-processing filter
* @throws IllegalArgumentException if {@link OutputLevel#NONE OutputLevel.NONE}
* is given
* @throws NullPointerException if any argument is null
*/
public static Filter createOutputFilter(OutputStream out,
OutputLevel outputLevel) {
Objects.requireNonNull(out);
Objects.requireNonNull(outputLevel);
return OutputFilter.create(out, outputLevel);
}
}
{@code
* 127.0.0.1 - - [22/Jun/2000:13:55:36 -0700] "GET /example.txt HTTP/1.1" 200 -
* }
*
* @implNote The fields {@code rfc931}, {@code authuser} and {@code bytes}
* are not captured in the implementation, so are always represented as
* {@code '-'}.
*/
INFO,
/**
* Used to specify the verbose log message output level.
*
*