Web server : Hoka 7.x

Guides
1

Hello everyone,

Hoka 7.1.1 is now available on the central repository. It includes a bunch of changes :

  • The REST-server library is now merged with Hoka and APIs are aligned
  • A set of utility classes to enable authentication on the server
  • A debug mode that send exceptions stacktraces to clients
  • A better endpoint URI matching for REST
  • The request processing chain is now customizable
  • A better API for parsing requests bodies
  • Optimizations

You can find the sources of this library and examples on our GitHub :

Best regards,

2

Also, for those that are already using this library, here is a guide to migrate from Hoka/REST-server 5.x to Hoka 7.1.1.

Repackaging

Added

  • ej.hoka.auth : authentication API
  • ej.hoka.auth.session : ready-to-use utility classes to setup authentication using cookie-based sessions

Changed

  • ej.hoka.http.encoding : extract encoding stuff in this package.
  • ej.hoka.http.requesthandler : equivalent to legacy ej.hoka.http.HTTPSession.
  • ej.hoka.tcp : now the TCP server has more responsabilities, it maintains the list of opened connections. It was originally handled by the HTTP server.
  • ej.hoka.http : now the HTTP server is only responsible for maintaining jobs that process requests from the opened connections of the TCP server.

REST-server merge

What used to be an extension of the HTTP server (REST server) is now an architecture that the HTTP server can use directly.
Now, the HTTP server can serve a filesystem view, REST endpoints and other services from different architectures at the same time.

An example with two different REST interface (one public and one private) is available here : AccessControlExampleServer.java.

Request processing

A customizable processing chain

The request processing chain has been completely reworked to be customizable. For example, the authentication and the REST packages uses a custom chain of request handlers to achieve their goals.

Before this update, the processing was static : managed by an HTTPSession defined by the user.
Now, one can define a hierarchy of request handlers (See ej.hoka.http.requesthandler.RequestHandlerComposite) that will be browsed depending on the request.

An example that uses a RequestHandlerComposite is available here : RestServer.java.

Parse Request Body

As before, the body of the request is lazily parsed by the request handlers.
What changed is that handlers can now directly use the type of parser they need for a specific request.

Four implementations are available in ej.hoka.http.body :

  • StringBodyParser : read the whole body into a string
  • MultipartStringsParser : parse a multipart/* body, each part read into a string
  • MultiPartBodyParser : parse a multipart/* body, and parse each part as header fields and a body.
  • ParameterParser : parse a application/x-www-form-urlencoded body.

An example that uses the StringBodyParser is available here : DumpRequestHandler.java.

Endpoints URI matching (REST)

The request URI matching with available endpoints has been changed to use the endpoint the most specific to the request.
If there are two endpoints, /my and /my/endpoint, the second is used for requests to the same URI.
Also, the first endpoint must be declared as a global endpoint (with /my/*) to be used to handle the request to “sub-endpoints” like /my/other/endpoint.

An example is available here : AccessControlExampleServer.java. It uses a single global endpoint for the private part.

Authentication

This new version includes an authentication API (see ej.hoka.auth).
The library currently provides an implementation that uses a database of active sessions, it is possible to implement other authentication protocols.
Linked to this, the package ej.hoka.auth.session is a couple of ready-to-use components to enable such authentication, by default, it uses an in-memory database for active sessions and stores session tokens in cookies.

An example, using the ej.hoka.auth.session components, is available here : AccessControlExampleServer.java.

Debug mode

The application developer can now enable the server to dump the stack trace when an exception is thrown during the processing of a request. The mode is enabled with : HTTPServer#sendStackTraceOnException(true).
This is useful when debugging a web application : the exceptions are directly dumped into the client browser.