io.reactivex.netty.protocol.tcp.server

Class TcpServerInterceptorChain<R,W,RR,WW>

java.lang.Object

io.reactivex.netty.protocol.tcp.server.TcpServerInterceptorChain<R,W,RR,WW>

Type Parameters:

R - The type of objects read from a connection to TcpServer with which this interceptor chain will be used.

W - The type of objects written to a connection to TcpServer with which this interceptor chain will be used.

RR - The type of objects read from a connection to TcpServer after applying this interceptor chain.

WW - The type of objects written to a connection to TcpServer after applying this interceptor chain.

@Beta
public final class TcpServerInterceptorChain<R,W,RR,WW>
extends java.lang.Object

A utility to create an interceptor chain to be used with a TcpServer to modify behavior of connections accepted by that server.

What are interceptors?

Interceptors can be used to achieve use-cases that involve instrumentation related to any behavior of the connection, 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 ConnectionHandler and returns another ConnectionHandler instance. With this low level abstraction, any use-case pertaining to connection instrumentation can be achieved.

Interceptor chain anatomy

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

An interceptor chain always starts with an interceptor and ends with a ConnectionHandler 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(Interceptor), startRaw(Interceptor).

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), nextWithReadTransform(TransformingInterceptor) and nextWithWriteTransform(TransformingInterceptor)

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

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

TcpServer.newServer().start(TcpServerInterceptorChain.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 connection, the interface TcpServerInterceptorChain.Interceptor defines the interceptor contract.

Modifying the type of data read/written to the Connection

Sometimes, it is required to change the type of objects read or written to a Connection instance handled by a TcpServer. For such cases, the interface TcpServerInterceptorChain.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 Connection are actually to be changed.

Execution order

      -------        -------         -------        -------        -------        -------        -------
     |       |      |       |       |       |      |       |      |       |      |       |      |       |
     |       | ---> |       | --->  |       | ---> |       | ---> |       | ---> |       | ---> |       |
     |       |      |       |       |       |      |       |      |       |      |       |      |       |
      -------        -------         -------        -------        -------        -------        -------
       Tcp         Connection      Interceptor    Interceptor    Interceptor    Interceptor     Connection
      Server         Handler           1              2              3              4             Handler
                   (Internal)                                                                     (User)
 

The above diagram depicts the execution order of interceptors. The first connection handler (internal) is created by this class and as is returned by end(ConnectionHandler) method by providing a ConnectionHandler that does the actual processing of the connection. TcpServer with which this interceptor chain is used, will invoke the internal connection 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	TcpServerInterceptorChain.Interceptor<R,W> An interceptor that preserves the type of objects read and written to the connection.
static interface	TcpServerInterceptorChain.TransformingInterceptor<R,W,RR,WW> An interceptor that changes the type of objects read and written to the connection.

Method Summary

Modifier and Type	Method and Description
ConnectionHandler<R,W>	end(ConnectionHandler<RR,WW> handler) Terminates this chain with the passed ConnectionHandler and returns a ConnectionHandler to be used by a TcpServer
TcpServerInterceptorChain<R,W,RR,WW>	next(TcpServerInterceptorChain.Interceptor<RR,WW> next) Add the next interceptor to this chain.
<RRR> TcpServerInterceptorChain<R,W,RRR,WW>	nextWithReadTransform(TcpServerInterceptorChain.TransformingInterceptor<RR,WW,RRR,WW> next) Add the next interceptor to this chain, which changes the type of objects read from the connections processed by the associated TcpServer.
<RRR,WWW> TcpServerInterceptorChain<R,W,RRR,WWW>	nextWithTransform(TcpServerInterceptorChain.TransformingInterceptor<RR,WW,RRR,WWW> next) Add the next interceptor to this chain, which changes the type of objects read and written from/to the connections processed by the associated TcpServer.
<WWW> TcpServerInterceptorChain<R,W,RR,WWW>	nextWithWriteTransform(TcpServerInterceptorChain.TransformingInterceptor<RR,WW,RR,WWW> next) Add the next interceptor to this chain, which changes the type of objects written to the connections processed by the associated TcpServer.
static <R,W> TcpServerInterceptorChain<R,W,R,W>	start(TcpServerInterceptorChain.Interceptor<R,W> start) One of the methods to start creating the interceptor chain.
static TcpServerInterceptorChain<io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf>	startRaw(TcpServerInterceptorChain.Interceptor<io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf> start) One of the methods to start creating the interceptor chain.

Methods inherited from class java.lang.Object

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

Method Detail

next

public TcpServerInterceptorChain<R,W,RR,WW> next(TcpServerInterceptorChain.Interceptor<RR,WW> next)

Add the next interceptor to this chain.

Parameters:

next - Next interceptor to add.

Returns:

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

nextWithReadTransform

public <RRR> TcpServerInterceptorChain<R,W,RRR,WW> nextWithReadTransform(TcpServerInterceptorChain.TransformingInterceptor<RR,WW,RRR,WW> next)

Add the next interceptor to this chain, which changes the type of objects read from the connections processed by the associated TcpServer.

Parameters:

next - Next interceptor to add.

Returns:

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

nextWithWriteTransform

public <WWW> TcpServerInterceptorChain<R,W,RR,WWW> nextWithWriteTransform(TcpServerInterceptorChain.TransformingInterceptor<RR,WW,RR,WWW> next)

Add the next interceptor to this chain, which changes the type of objects written to the connections processed by the associated TcpServer.

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> TcpServerInterceptorChain<R,W,RRR,WWW> nextWithTransform(TcpServerInterceptorChain.TransformingInterceptor<RR,WW,RRR,WWW> next)

Add the next interceptor to this chain, which changes the type of objects read and written from/to the connections processed by the associated TcpServer.

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 ConnectionHandler<R,W> end(ConnectionHandler<RR,WW> handler)

Terminates this chain with the passed ConnectionHandler and returns a ConnectionHandler to be used by a TcpServer

Parameters:

handler - Connection handler to use.

Returns:

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

start

public static <R,W> TcpServerInterceptorChain<R,W,R,W> start(TcpServerInterceptorChain.Interceptor<R,W> start)

One of the methods to start creating the interceptor chain. The other start methods can be used for starting with interceptors that modify the type of Objects read/written from/to the connections processed by the associated TcpServer.

Type Parameters:

R - The type of objects read from a connection to TcpServer with which this interceptor chain will be used.

W - The type of objects written to a connection to TcpServer with which this interceptor chain will be used.

Parameters:

start - The starting interceptor for this chain.

Returns:

A new interceptor chain.

startRaw

public static TcpServerInterceptorChain<io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf> startRaw(TcpServerInterceptorChain.Interceptor<io.netty.buffer.ByteBuf,io.netty.buffer.ByteBuf> start)

One of the methods to start creating the interceptor chain. The other start methods can be used for starting with interceptors that modify the type of Objects read/written from/to the connections processed by the associated TcpServer.

Parameters:

start - The starting interceptor for this chain.

Returns:

A new interceptor chain.