JLHTTP - Java Lightweight HTTP Server (Web Server)

The Java Lightweight HTTP Server is an open-source implementation of an HTTP Server (a.k.a. web server). It is lightweight, i.e. small and efficient, yet provides various useful features commonly found in heavier HTTP servers. It can be used both as a standalone web server, and as an easily embedded server for integration into existing applications. This is commonly used to provide a convenient GUI (Graphical User Interface) which can be viewed across the network in a cross-platform manner from any computer with a web browser (just about all of them).

This server is conformant to RFC 9110 ("HTTP Semantics") and RFC 9112 ("HTTP/1.1") in the role of an "origin server", and also implements some of the optional functionality and additional features.

Feature highlights are:

RFC compliant - correctness is not sacrificed for the sake of size
Virtual hosts - multiple domains and subdomains per server
File serving - built-in handler to serve files and folders from disk
Mime type mappings - configurable via API or a standard mime.types file
Directory index generation - enables browsing folder contents
Welcome files - configurable default filename (e.g. index.html)
All HTTP methods supported - GET/HEAD/OPTIONS/TRACE/POST/PUT/DELETE/custom
Conditional statuses - ETags and If-* header support
Chunked transfer encoding - for serving dynamically-generated data streams
Gzip/deflate compression - reduces bandwidth and download time
HTTPS - secures all server communications
Partial content - download continuation (a.k.a. byte range serving)
File upload - multipart/form-data handling as stream or iterator
Multiple context handlers - different handler per URL path and HTTP method
@Context annotations - auto-detection of context handler methods
Parameter parsing - from query string or x-www-form-urlencoded body
Path parameters - extracted from the URL path itself
A single source file - super-easy to integrate into any application
Standalone - no dependencies other than the Java runtime
Small footprint - standard jar is ~60K, stripped jar is ~40K
Extensible design - easy to override, add or remove functionality
Reusable utility methods to simplify your custom code
Extensive documentation of API and implementation (>40% of source lines)

What can the Java Lightweight HTTP Server be used for?

Being a lightweight, standalone, easily embeddable and tiny-footprint server, it is well-suited for:

Resource-constrained environments such as embedded devices. For really extreme constraints, you can easily remove unneeded functionality to make it even smaller (also make sure to compile without debug info and strip the jar of unnecessary files)
Unit and integration tests - fast setup/teardown times, small overhead and simple context handler setup make it a great web server for testing client components under various server response conditions.
Embedding a web console into any headless application for administration, monitoring, or a full portable GUI.
A full-fledged standalone web server serving static files, dynamically-generated content, REST APIs, pseudo-streaming, etc.
A good reference for learning how HTTP works under the hood.

How do I use the Java Lightweight HTTP Server?

This server is intentionally written as a single source file, in order to make it as easy as possible to integrate into any existing project - by simply adding this single file to the project sources. It can also be used like any other library, by including the jar file in the application classpath.

It is also available on Maven Central at the artifact coordinates net.freeutils:jlhttp:3.2.

See the javadocs in the source file for the full API details. Examining the source code of the main method can be a good starting point for understanding how to embed the server in your application, as well.

The server can also be run as a standalone application from the command line using the command 'java -jar jlhttp-3.2.jar' to serve files under a specified directory with no need for additional configuration.

FAQ

Make sure to read the FAQ, which includes additional information and sample code.

What's New?

In version 3.2:

Made MultipartInputStream constructor public.
Fixed 408 timeout response sent before request is received.
Fixed missing Content-Length header on some empty error responses.
Limited graceful server shutdown to complete one last request/response per connection.
Fixed parsing of suffix range larger than resource.
Fixed zero suffix range edge case.
Fixed merging of multiple slashes in query parameters.
Improved javadocs and misc. minor refactorings.

In version 3.1:

Updated response status texts to RFC9110 phrasing.
Fixed parsing of long URI.
Changed status to 414 when URI is too long.

In version 3.0:

Upgraded build to JDK 8.
Upgraded to conform to RFC9110 and RFC9112.
Changed context paths to be non-recursive by default.
Added wildcard path parameter to support recursive context paths explicitly.
Updated ETag matching to conform to RFC 7232.
Updated conditional request processing to conform to RFC 7232.
Updated request body processing to conform to RFC 7230.
Updated header parsing to reject whitespace surrounding header name.
Updated all RFC2616 references to their equivalent RFC9110 and RFC9112 references.
Added path parameters support.
Added full QValues support for Accept-Encoding header.
Added rejection of multiple Host headers.
Added several additional HTTP status code texts.
Changed Headers.getParams to lowercase header parameter names.
Changed directory index to recalculate context handler for updated path.
Changed chunk size/extension parsing to allow whitespace.
Changed virtual host matching to be case-insensitive.
Changed range units to be case-insensitive.
Changed request HTTP version to be an integer.
Separated request headers from trailers.
Re-implemented readRequestLine for performance and better error handling.
Fixed modification date comparisons to round to seconds.
Fixed unsatisfiable range response overriding failed conditional response.
Fixed error when suffix range is larger than content.
Fixed If-None-Match to use weak matching only for GET/HEAD requests.
Fixed support for absolute URI in request line.
Removed HTTP/0.9 support.
Removed removal of headers specified in Connection header of HTTP/1.0 requests.
Removed obsolete header line folding support.
Removed default "*" context (unnecessary for default OPTIONS handling).
Improved javadocs and misc. minor refactorings.

In version 2.6:

Replaced Response.encoders array with a single chained OutputStream reference.
Extracted ResponseOutputStream class to reduce binary size.
Added socket parameter to handleConnection method for setting socket options.
Added socket to Request for retrieving connection meta-data (e.g. remote address).

In version 2.5:

Removed VirtualHost.DEFAULT_HOST_NAME constant.
Changed addContentType parameter from File to InputStream.
Optimized readToken memory allocations.
Changed readToken with LF delimiter to also match CRLF and refactored readLine to reduce garbage.
Fixed missing query params when accessing a context ending with slash with directory index enabled.
Improved javadocs and misc. minor refactorings.

In version 2.4:

Added support for enabling SSL from command line.
Replaced HTTPServer.setSecure method with setServerSocketFactory fo easier SSL configuration.
Changed parseDate to be less lenient.
Fixed UnsupportedOperationException stack trace printed when closing SSL connection.
Fixed NullPointerException stack trace may be printed when stopping server.
Fixed Request context not updated by calling Request.setPath with path from different context.
Fixed possible NullPointerException when stopping the server immediately after starting it.
Reimplemented MultipartInputStream to reduce compiled size and object (garbage) creation.
Fixed several MultipartInputStream edge cases.
Improved MultipartInputStream error handling.
Improved MultipartInputStream preamble/epilogue handling.
Added limit parameter to split utility method.
Misc. tiny refactorings for consistency and reduced size.

In version 2.3:

Fixed missing welcome page when accessing non-root base context path without trailing slash.
Added context to Request.
Added path to ContextInfo.
Removed redundant context path from FileContextHandler (now taken from request).
Simplified and optimized VirtualHost.getContext method.
Optimized Request.getVirtualHost and Request.getContext lookups.

In version 2.2:

Fixed graceful socket closing error handling.
Changed ETag generated for string content to be weak.
Changed If-None-Match ETag handling to use weak matching algorithm.
Added Vary Accept-Encoding header to responses.
Added accessors for MultipartIterator.Part class fields.
Added setSocketTimeout setter.

In version 2.1:

Set setReuseAddress (SO_REUSEADDR) on server socket for quicker restarts.
Set setTcpNoDelay (TCP_NODELAY) on sockets for lower latency.
Added connection close header when responding to request that sent it.
Added connection close header when closing connection due to error.
Changed connection to close if response contains connection close header.
Removed error response when client disconnects between requests.
Fixed clearing existing headers when sending generic 500 error response.
Changed handleConnection to always close response, even on error after headers sent.
Added graceful socket closing (half-close and consume input before final close).
Added 408 Request Timeout support.
Optimized formatDate by reimplementing it without SimpleDateFormat.
Optimized bulk writes to response body stream.
Optimized ISO-8859-1/US-ASCII string encoding using getBytes utility method.
Optimized Request.getBaseURL reuse by caching parsed value.
Replaced Headers.iterator implementation to avoid extra 1.5K class file.
Changed transfer method to accept null OutputStream for discarding output.
Optimized transfer when discarding empty output.
Removed SocketHandlerThread constructor.
Removed Request.consumeBody method.
Improved javadocs and misc. minor refactorings.

In version 2.0:

Changed ChunkedOutputStream to write a chunk per standard write method invocation.
Added ChunkedOutputStream.close which writes trailing chunk if necessary.
Changed Response.sendHeaders to add chunked transfer encoding if length is unknown.
Changed Response.getBody to create encoding streams automatically according to headers.
Added Response.getOutputStream to get raw unencoded output stream.
Removed Response.getChunkedBody method.
Removed Response.isDiscardBody method.
Changed Response to implement Closeable for closing and flushing all streams.
Added gzip/deflate response compression support.
Added HTTPS support.
Fixed uncaught exception handling, error response and connection termination.
Removed persistent connections for HTTP/1.0 requests.
Changed connection persistence to work even if request/response body streams are closed.
Added isCompressible method to determine which content types can be compressed.
Added parameter to splitElements for converting elements to lowercase.
Changed lower-case conversions to ignore system locale.
Changed Response.sendHeaders to throw exception if headers were already sent.
Improved Transfer-Encoding header parsing.
Improved javadocs and misc. minor refactorings.

In version 1.3:

Added support for content type mapping via standard mime.types file.
Added full support for different HTTP method handlers per context.
Improved compliance of built-in HTTP method handling: OPTIONS *, Allow header, 405 status, etc.
Replaced parseParams utility method with parseParamsList for access to multi-valued parameters.
Fixed MultipartInputStream handling of several valid and invalid inputs.
Fixed MultipartInputStream.fill when reading form a very slow input stream.
Optimized MultipartInputStream buffer fill using partial boundary detection.
Optimized MultipartInputStream latency by returning data as soon as it is available.
Optimized MultipartInputStream performance by reducing in-memory copying.
Updated Server response header string and version number.
Fixed formatDate GMT time calculation.
Fixed serving non-directory files ending with a slash.
Changed Range header to be ignored if content is empty (return 200 instead of 416).
Changed files starting with dot to return 404 on all platforms.
Changed handleConnection method to accept input/output streams instead of socket.
Changed split method to support multiple delimiters.
Added Request.getParamsList method.
Added toMap and join utility methods.
Added sample dynamic context handler to main method.
Migrated to Maven build system, directory structure and artifact conventions.
Added OSGi headers to jar manifest.
Fixed javadoc errors when building with JDK 8.
Revamped HTTPServer class documentation with feature list, use cases and getting started sections.
Improved javadocs and misc. minor refactorings.

In version 1.2:

Split handleTransaction into preprocessTransaction and handleMethod, making it easier for subclasses to add filters.
Added MultipartIterator.Part.getString() convenience method to get a form input value as a string.
Added Response.getChunkedBody helper method to encourage proper use when body length is unknown.
Renamed utility method parseULong (parseLong) and changed it to treat sign characters as invalid.
Renamed utility methods trimLeft (ltrim), trimRight (rtrim), and toSizeApproxString (toSizeString).
Added @Override annotations.
Changed index and error pages HTML markup to use the HTML5 doctype.
Added explanation on how to support file uploads (via MultipartIterator).
Improved documentation and misc. minor refactorings.

In version 1.1:

Made jar file executable (added Main-Class attribute to manifest).
Fixed generated index date format on non-US locale (always use US).
Fixed Request.parseParams() preserving of parameter order.
Added no-arg constructor and setPort() method to allow post-construction port setting.
Fixed serveFile() appending of relative path to base directory.
Fixed double-slash when accessing root folder.
Added file upload support using the MultipartInputStream and MultipartIterator classes.
Added ltrim utility method.
Added parseParameters() method for easy header parameter handling.
Fixed sendError() default text for success statuses.
Changed default error text to include both status code and status description.
Improved documentation.

In version 1.0:

This is the first release of the Java Lightweight HTTP Server.

License

The JLHTTP Package is provided under the GNU General Public License agreement.
For non-GPL commercial licensing please contact the author.

Donate

If you like it, why not give something back?

Donate Bitcoin 13aWWmQqkiYnpkWT7QmE9khnpuuuG48U7o

Donate Bitcoin via mobile

Contact

You can contact the author via e-mail at:

support@freeutils.net

Please write in with any bugs, suggestions, fixes, contributions, or just to drop a good word and let me know you've found the JLHTTP Package useful and you'd like it to keep being maintained.

For updates and additional information, you can always visit the website at: