Module SimpleHttpServer
Package dev.katsute.simplehttpserver

Class SimpleHttpServer

java.lang.Object
com.sun.net.httpserver.HttpServer
dev.katsute.simplehttpserver.SimpleHttpServer
public abstract class SimpleHttpServer extends com.sun.net.httpserver.HttpServer
A HttpServer with additional extensions to simplify usage.

Creating a SimpleHttpServer

A SimpleHttpServer is created in the same way was a standard HttpServer, by using one of the create methods.

Binding to a Port

A SimpleHttpServer requires a port to become accessible, the port can be defined in the create or bind methods. The backlog parameter in each of these determines the maximum amount of simultaneous connections at any given time.

Starting the Server

The server can be started by using the HttpServer.start() method.

Stopping the Server

The server can be stopped by using stop() or HttpServer.stop(int) methods.
The delay parameter determines how long the server should wait before forcefully closing the connection, by default this is 0.

Adding Pages

Pages (referred to as a context) are added by using any of the createContext methods.
  • HttpServer.createContext(String)
  • HttpServer.createContext(String, HttpHandler)
Content for each context is determined by using a HttpHandler. SimpleHttpServer offers some simplified handlers to handle some complex operations, documentation for those can be found in SimpleHttpHandler.
Contexts in a server are case sensitive and will resolve to the most specific context available.

Example:
If a user goes to /this/web/page and there are only handlers for /this and /this/web, then the handler for /this/web would be used because its the most specific context that exists on the server.

This behavior consequentially means that any handler added to the root / context would handle any requests that don't have a handler, since it's the most specific one available. A RootHandler can be used to mediate this issue.

Accessing the Server

Accessing on Host Machine

When a server is started it is immediately available at whatever port was set.
Example: localhost:8000, 127.0.0.1:80

Accessing on Local Network

If permitted, the server should also be accessible to all computers on your immediate internet network at your local IP.

Accessing Globally

For clients not connected to your network, they must use your public IP address.
People outside your network can not connect unless you port forward the port the server is using. This process varies depending on your ISP and can often leave your network vulnerable to attackers. It is not suggested to this unless you know what you are doing.
You can learn to port forward here (at your own risk).

Multi-threaded Server

By default the server runs on a single thread. This means that only one clients exchange can be processed at a time and can lead to long queues.
For a server to be multi-threaded the executor must be changed to one that process threads in parallel. The executor can be changed using the HttpServer.setExecutor(Executor) method on the server.
To process a fixed amount of threads you can use Executors.newFixedThreadPool(int).
To process an unlimited amount of threads you can use Executors.newCachedThreadPool().

Requests are still not being processed in parallel

Requests to the same context may not run in parallel for a user that is accessing the same page more than once. This issue is caused by the browser, where it will not send duplicate requests to the server at the same time.
This issue is better explained here.
If you still need to test multithreading then you must use an older browser like Internet Explorer or Microsoft Edge.
Since:
5.0.0
Version:
5.0.0
Author:
Katsute
See Also:
  • HttpServer

  • Method Details

    • create

      public static SimpleHttpServer create() throws IOException
      Creates an unbounded http server.
      Returns:
      http server
      Throws:
      IOException - IO exception
      Since:
      5.0.0
      See Also:

    • create

      public static SimpleHttpServer create(int port) throws IOException
      Creates an http server bounded to a port.
      Parameters:
      port - to bind to
      Returns:
      http server
      Throws:
      IOException - IO exception
      BindException - if server could not be bounded
      Since:
      5.0.0
      See Also:

    • create

      public static SimpleHttpServer create(int port, int backlog) throws IOException
      Creates an http server bounded to a port.
      Parameters:
      port - to bind to
      backlog - maximum amount of inbound connections at any given time
      Returns:
      http server
      Throws:
      IOException - IO exception
      BindException - if server could not be bounded
      Since:
      5.0.0
      See Also:

    • getHttpServer

      public abstract com.sun.net.httpserver.HttpServer getHttpServer()
      Returns the underlying http server.
      Returns:
      http server
      Since:
      5.0.0
      See Also:
      • HttpServer

    • bind

      InetSocketAddress bind(int port) throws IOException
      Binds the server to a port.
      Parameters:
      port - port to bind to
      Returns:
      server address
      Throws:
      IOException - internal error
      BindException - if server could not be bounded
      Since:
      5.0.0
      See Also:

    • bind

      InetSocketAddress bind(int port, int backlog) throws IOException
      Binds the server to a port.
      Parameters:
      port - port to bind to
      backlog - maximum amount of inbound connections at any given time
      Returns:
      server address
      Throws:
      IOException - internal error
      BindException - if server could not be bounded
      Since:
      5.0.0
      See Also:

    • setSessionHandler

      void setSessionHandler(HttpSessionHandler sessionHandler)
      Sets as session handler to use for the server.
      Parameters:
      sessionHandler - session handler
      Since:
      5.0.0
      See Also:

    • getSessionHandler

      HttpSessionHandler getSessionHandler()

    • getSession

      HttpSession getSession(com.sun.net.httpserver.HttpExchange exchange)
      Returns the session for a given exchange.
      Parameters:
      exchange - http exchange
      Returns:
      session associated with an exchange
      Since:
      5.0.0
      See Also:

    • getContextHandler

      com.sun.net.httpserver.HttpHandler getContextHandler(String context)
      Returns the handler for a given context.
      Parameters:
      context - context
      Returns:
      handler for context
      Since:
      5.0.0
      See Also:

    • getContextHandler

      com.sun.net.httpserver.HttpHandler getContextHandler(com.sun.net.httpserver.HttpContext context)
      Returns the handler for a given context.
      Parameters:
      context - http context
      Returns:
      handler for context
      Since:
      5.0.0
      See Also:

    • getContexts

      Map<com.sun.net.httpserver.HttpContext,com.sun.net.httpserver.HttpHandler> getContexts()
      Returns a map of all the contexts registered to the server.
      Returns:
      map of contexts
      Since:
      5.0.0
      See Also:

    • getRandomContext

      String getRandomContext()
      Returns a random context that doesn't yet exist on the server.
      Returns:
      random unused context
      Since:
      5.0.0
      See Also:

    • getRandomContext

      String getRandomContext(String context)
      Returns a random context prefixed by a set context.
      Parameters:
      context - context to prefix
      Returns:
      random unused context with prefix
      Since:
      5.0.0
      See Also:

    • stop

      void stop()
      Stops the server immediately without waiting.
      Since:
      5.0.0
      See Also:
      • HttpServer.stop(int)