io.reactivex.netty.protocol.http.server

Class HttpServerInterceptorChain<I,O,II,OO>

java.lang.Object

io.reactivex.netty.protocol.http.server.HttpServerInterceptorChain<I,O,II,OO>

Type Parameters:

I - The type of objects received as content from a request to this server.

O - The type of objects written as content from a response from this server.

II - The type of objects received as content from a request to this server after applying these interceptors.

OO - The type of objects written as content from a response from this server after applying these interceptors.

@Beta
public final class HttpServerInterceptorChain<I,O,II,OO>
extends java.lang.Object

A utility to create an interceptor chain to be used with a HttpServer to modify behavior of requests processed by that server.

What are interceptors?

Interceptors can be used to achieve use-cases that involve instrumentation related to any behavior of the requests, they can even be used to short-circuit the rest of the chain or to provide canned responses. In order to achieve such widely different use-cases, an interceptor is modelled as a simple function that takes one RequestHandler and returns another RequestHandler instance. With this low level abstraction, any use-case pertaining to connection instrumentation can be achieved.

Interceptor chain anatomy

        -------        -------        -------        -------        -------
       |       |      |       |      |       |      |       |      |       |
       |       | ---> |       | ---> |       | ---> |       | ---> |       |
       |       |      |       |      |       |      |       |      |       |
        -------        -------        -------        -------        -------
      Interceptor    Interceptor    Interceptor    Interceptor      Request
           1              2              3              4           Handler
 

An interceptor chain always starts with an interceptor and ends with a RequestHandler and any number of other interceptors can exist between the start and end.

A chain can be created by using the various start*() methods available in this class, eg: start(), startRaw().

After starting a chain, any number of other interceptors can be added by using the various next*() methods available in this class, eg: next(Interceptor), nextWithTransform(TransformingInterceptor), nextWithRequestTransform(TransformingInterceptor) and nextWithResponseTransform(TransformingInterceptor)

After adding the required interceptors, by providing a RequestHandler via the end(RequestHandler) method, the chain can be ended and the returned RequestHandler can be used with any HttpServer

So, a typical interaction with this class would look like:

HttpServer.newServer().start(HttpServerInterceptorChain.start(first).next(second).next(third).end(handler))

Simple Interceptor

For interceptors that do not change the types of objects read or written to the underlying request/response, the interface HttpServerInterceptorChain.Interceptor defines the interceptor contract.

Modifying the type of data read/written to the request/response

Sometimes, it is required to change the type of objects read from a request or written to a response handled by a HttpServer. For such cases, the interface HttpServerInterceptorChain.TransformingInterceptor defines the interceptor contract. Since, this included 4 generic arguments to the interceptor, this is not the base type for all interceptors and should be used only when the types of the request/response are actually to be changed.

Execution order

      -------        -------         -------        -------        -------        -------        -------
     |       |      |       |       |       |      |       |      |       |      |       |      |       |
     |       | ---> |       | --->  |       | ---> |       | ---> |       | ---> |       | ---> |       |
     |       |      |       |       |       |      |       |      |       |      |       |      |       |
      -------        -------         -------        -------        -------        -------        -------
       Http          Request      Interceptor    Interceptor    Interceptor    Interceptor        Request
      Server         Handler           1              2              3              4             Handler
                   (Internal)                                                                     (User)
 

The above diagram depicts the execution order of interceptors. The first request handler (internal) is created by this class and as is returned by end(RequestHandler) method by providing a RequestHandler that does the actual processing of the connection. HttpServer with which this interceptor chain is used, will invoke the internal request handler provided by this class.

The interceptors are invoked in the order that they are added to this chain.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	HttpServerInterceptorChain.Interceptor<I,O> An interceptor that preserves the type of content of request and response.
static interface	HttpServerInterceptorChain.TransformingInterceptor<I,O,II,OO> An interceptor that changes the type of content of request and response.

Method Summary

Modifier and Type	Method and Description
RequestHandler<I,O>	end(RequestHandler<II,OO> handler) Terminates this chain with the passed RequestHandler and returns a RequestHandler to be used by a HttpServer
HttpServerInterceptorChain<I,O,II,OO>	next(HttpServerInterceptorChain.Interceptor<II,OO> next) Add the next interceptor to this chain.
<III> HttpServerInterceptorChain<I,O,III,OO>	nextWithRequestTransform(HttpServerInterceptorChain.TransformingInterceptor<II,OO,III,OO> next) Add the next interceptor to this chain, which changes the type of objects read from the request accepted by the associated HttpServer.
<OOO> HttpServerInterceptorChain<I,O,II,OOO>	nextWithResponseTransform(HttpServerInterceptorChain.TransformingInterceptor<II,OO,II,OOO> next) Add the next interceptor to this chain, which changes the type of objects written to the response sent by the associated HttpServer.
<RRR,WWW> HttpServerInterceptorChain<I,O,RRR,WWW>	nextWithTransform(HttpServerInterceptorChain.TransformingInterceptor<II,OO,RRR,WWW> next) Add the next interceptor to this chain, which changes the type of objects read read from the request and written to the response sent by the associated HttpServer.
static <R,W> HttpServerInterceptorChain<R,W,R,W>	start() Starts a new interceptor chain.
static HttpServerInterceptorChain<io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf>	startRaw() Starts a new interceptor chain with ByteBuf read and written from request and to responses.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

next

public HttpServerInterceptorChain<I,O,II,OO> next(HttpServerInterceptorChain.Interceptor<II,OO> next)

Add the next interceptor to this chain.

Parameters:

next - Next interceptor to add.

Returns:

A new interceptor chain with the interceptors currently existing and the passed interceptor added to the end.

nextWithRequestTransform

public <III> HttpServerInterceptorChain<I,O,III,OO> nextWithRequestTransform(HttpServerInterceptorChain.TransformingInterceptor<II,OO,III,OO> next)

Add the next interceptor to this chain, which changes the type of objects read from the request accepted by the associated HttpServer.

Parameters:

next - Next interceptor to add.

Returns:

A new interceptor chain with the interceptors currently existing and the passed interceptor added to the end.

nextWithResponseTransform

public <OOO> HttpServerInterceptorChain<I,O,II,OOO> nextWithResponseTransform(HttpServerInterceptorChain.TransformingInterceptor<II,OO,II,OOO> next)

Add the next interceptor to this chain, which changes the type of objects written to the response sent by the associated HttpServer.

Parameters:

next - Next interceptor to add.

Returns:

A new interceptor chain with the interceptors current existing and the passed interceptor added to the end.

nextWithTransform

public <RRR,WWW> HttpServerInterceptorChain<I,O,RRR,WWW> nextWithTransform(HttpServerInterceptorChain.TransformingInterceptor<II,OO,RRR,WWW> next)

Add the next interceptor to this chain, which changes the type of objects read read from the request and written to the response sent by the associated HttpServer.

Parameters:

next - Next interceptor to add.

Returns:

A new interceptor chain with the interceptors current existing and the passed interceptor added to the end.

end

public RequestHandler<I,O> end(RequestHandler<II,OO> handler)

Terminates this chain with the passed RequestHandler and returns a RequestHandler to be used by a HttpServer

Parameters:

handler - Request handler to use.

Returns:

A request handler that wires the interceptor chain, to be used with HttpServer instead of directly using the passed handler

start

public static <R,W> HttpServerInterceptorChain<R,W,R,W> start()

Starts a new interceptor chain.

Returns:

A new interceptor chain.

startRaw

public static HttpServerInterceptorChain<io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf> startRaw()

Starts a new interceptor chain with ByteBuf read and written from request and to responses.

Returns:

A new interceptor chain.