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.

Nested and Inner Type Summary

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

Modifier and Type	Field and Description
private static final UnaryOperator<String>	MIME_TABLE

Access	Constructor and Description
private	SimpleFileServer()

Method Summary

Modifier and Type	Method and Description
public static HttpHandler	Returns: a file handler createFileHandler(Path the root directory to be served, must be an absolute path rootDirectory) Creates a file handler that serves files from a given directory path (and its subdirectories).
public static HttpServer	Returns: an HttpServer createFileServer(InetSocketAddress the address to listen on addr, Path the root directory to be served, must be an absolute path rootDirectory, SimpleFileServer.OutputLevel the log message output level outputLevel) Creates a file server that serves files from a given path.
public static Filter	Returns: a post-processing filter createOutputFilter(OutputStream the stream to print to out, SimpleFileServer.OutputLevel the output level outputLevel) Creates a post-processing Filter that prints log messages about exchanges.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

MIME_TABLE	back to summary
private static final UnaryOperator<String> MIME_TABLE

Constructor Detail

SimpleFileServer	back to summary
private SimpleFileServer()

Method Detail

createFileHandler back to summary

createFileHandler	back to summary
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:Path the root directory to be served, must be an absolute path Returns:HttpHandler a file handler Exceptions IllegalArgumentException: if rootDirectory does not exist, is not absolute, is not a directory, or is not readable NullPointerException: if the argument is null

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:Path: the root directory to be served, must be an absolute path

Returns:HttpHandler

a file handler

Exceptions

IllegalArgumentException:: if rootDirectory does not exist, is not absolute, is not a directory, or is not readable
NullPointerException:: if the argument is null

createFileServer back to summary

createFileServer	back to summary
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:InetSocketAddress the address to listen on rootDirectory:Path the root directory to be served, must be an absolute path outputLevel:SimpleFileServer.OutputLevel the log message output level Returns:HttpServer an HttpServer Exceptions 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

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:InetSocketAddress: the address to listen on
rootDirectory:Path: the root directory to be served, must be an absolute path
outputLevel:SimpleFileServer.OutputLevel: the log message output level

Returns:HttpServer

an HttpServer

Exceptions

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

createOutputFilter back to summary

createOutputFilter	back to summary
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:OutputStream the stream to print to outputLevel:SimpleFileServer.OutputLevel the output level Returns:Filter a post-processing filter Exceptions IllegalArgumentException: if `OutputLevel.NONE` is given NullPointerException: if any argument is null

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:OutputStream: the stream to print to
outputLevel:SimpleFileServer.OutputLevel: the output level

Returns:Filter

a post-processing filter

Exceptions

IllegalArgumentException:: if OutputLevel.NONE is given
NullPointerException:: if any argument is null

com.sun.net.httpserver back to summary

public final Enum SimpleFileServer.OutputLevel

Class Inheritance

extends Enum<SimpleFileServer.OutputLevel>

java.lang.Object
java.lang.Enum
com.sun.net.httpserver.SimpleFileServer.OutputLevel

Describes the log message output level produced by the server when processing exchanges.

Since: 18

Field Summary

Modifier and Type	Field and Description
public static final SimpleFileServer.OutputLevel	INFO Used to specify the informative log message output level.
public static final SimpleFileServer.OutputLevel	NONE Used to specify no log message output level.
public static final SimpleFileServer.OutputLevel	VERBOSE Used to specify the verbose log message output level.

Constructor Summary

Access	Constructor and Description
private	OutputLevel()

Method Summary

Modifier and Type	Method and Description
public static SimpleFileServer.OutputLevel	valueOf(String name)
public static SimpleFileServer.OutputLevel[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

INFO back to summary

INFO	back to summary
public static final SimpleFileServer.OutputLevel INFO Used to specify the informative log message output level. The log message format is based on the Common Logfile Format, that includes the following information about an `HttpExchange`: `remotehost rfc931 authuser [date] "request" status bytes` Example: `127.0.0.1 - - [22/Jun/2000:13:55:36 -0700] "GET /example.txt HTTP/1.1" 200 -` Implementation Note The fields `rfc931`, `authuser` and `bytes` are not captured in the implementation, so are always represented as `'-'`.

public static final SimpleFileServer.OutputLevel INFO

Used to specify the informative log message output level.

The log message format is based on the Common Logfile Format, that includes the following information about an HttpExchange:

remotehost rfc931 authuser [date] "request" status bytes

Example:

127.0.0.1 - - [22/Jun/2000:13:55:36 -0700] "GET /example.txt HTTP/1.1" 200 -

Implementation Note

The fields rfc931, authuser and bytes are not captured in the implementation, so are always represented as '-'.

NONE	back to summary
public static final SimpleFileServer.OutputLevel NONE Used to specify no log message output level.

VERBOSE back to summary

VERBOSE	back to summary
public static final SimpleFileServer.OutputLevel VERBOSE Used to specify the verbose log message output level. Additional to the information provided by the info level, the verbose level includes the request and response headers of the `HttpExchange` and the absolute path of the resource served up.

public static final SimpleFileServer.OutputLevel VERBOSE

Used to specify the verbose log message output level.

Additional to the information provided by the info level, the verbose level includes the request and response headers of the HttpExchange and the absolute path of the resource served up.

Constructor Detail

OutputLevel	back to summary
private OutputLevel()

Method Detail

valueOf	back to summary
public static SimpleFileServer.OutputLevel valueOf(String name)

values	back to summary
public static SimpleFileServer.OutputLevel[] values()

public final Class SimpleFileServer

Simple file server

File handler

Output filter

jwebserver Tool

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Enum SimpleFileServer.OutputLevel

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail