Introduction to Netty: Java NIO, IO Models, Reactor Patterns, and Practical Implementation

Introduction to Netty

Netty is an open‑source Java framework provided by JBoss that offers an asynchronous, event‑driven network application framework and tools for quickly developing high‑performance, highly reliable network servers and client programs.

What Netty Can Do

High‑performance RPC communication framework underlying data transfer, e.g., Dubbo.

Server development such as proxy servers.

Client/Server data communication in the gaming industry.

…

Java IO Models

Netty is built on Java NIO, so we first review Java's IO models.

BIO (Blocking IO)

In the synchronous blocking IO model, each client request causes the server to spawn a new thread, limiting concurrency.

public static void main(String[] args) {
    try {
        // Listen on port 8080
        final ServerSocket ss = new ServerSocket(8080);
        while (true) {
            // Block until a connection arrives
            Socket s = ss.accept();
            // After connection, read data
            InputStream is = s.getInputStream();
            int i = 0;
            // Block until data is available (stream‑based)
            while ((i = is.read()) != -1) {
                System.out.print((char) i);
            }
            s.close();
        }
    } catch (IOException e) {
        e.printStackTrace();
    }
}

NIO (Non‑Blocking IO)

In the synchronous non‑blocking model, a single server thread uses a Selector for IO multiplexing, allowing one thread to serve many client connections.

The three core components of NIO are Buffer, Channel, and Selector.

Buffer is essentially an array with important fields such as position, limit, and capacity, and methods like flip() and clear().

// Allocate a buffer
ByteBuffer byteBuffer = ByteBuffer.allocate(256);
// Allocation method source
public static ByteBuffer allocate(int capacity) {
    if (capacity < 0)
        throw new IllegalArgumentException();
    return new HeapByteBuffer(capacity, capacity);
}
// HeapByteBuffer constructor
HeapByteBuffer(int cap, int lim) {
    // second argument is position
    super(-1, 0, lim, cap, new byte[cap], 0);
}

Reading data from a channel into a buffer and then flipping the buffer before reading:

public final Buffer flip() {
    limit = position;
    position = 0;
    mark = -1;
    return this;
}

Clearing a buffer before writing new data:

public final Buffer clear() {
    position = 0;
    limit = capacity;
    mark = -1;
    return this;
}

AIO (Asynchronous IO)

AIO is an asynchronous non‑blocking model where the operating system handles read/write completion and notifies the application thread directly, eliminating the need for explicit polling.

Comparison code between NIO and AIO servers:

NIO Server Implementation

// Create channel
ServerSocketChannel ssc = ServerSocketChannel.open();
ssc.configureBlocking(false);
ssc.socket().bind(new InetSocketAddress(PORT));
// Create selector to listen for accept events
Selector acceptorSel = Selector.open();
ssc.register(acceptorSel, SelectionKey.OP_ACCEPT);
// Poll all IO events
while (true) {
    // Block until events are ready
    acceptorSel.select();
    Set
set = acceptorSel.selectedKeys();
    Iterator
it = set.iterator();
    while (it.hasNext()) {
        SelectionKey sk = it.next();
        it.remove();
        if (sk.isAcceptable()) {
            // Handle accept event …
        }
    }
}

AIO Server Implementation

AsynchronousServerSocketChannel server = AsynchronousServerSocketChannel.open()
    .bind(new InetSocketAddress(IP, PORT));
// Register event and completion handler
server.accept(null, new CompletionHandler
() {
    @Override
    public void completed(AsynchronousSocketChannel result, Object attachment) {
        // IO processing callback
    }
    @Override
    public void failed(Throwable exc, Object attachment) {
        // Exception handling callback
    }
});

Netty Principles

Why use Netty on top of Java NIO?

Java NIO has epoll bugs that can cause empty selector loops.

Network programming often requires handling special cases such as packet framing, reconnection, etc., which Netty abstracts.

Common transport protocols need substantial codec development effort.

Reactor Thread Models

Single‑Reactor Single‑Thread Model

A single Reactor thread listens for client events and processes them directly; suitable for simple workloads but can become a bottleneck when IO‑heavy.

Single‑Reactor Multi‑Thread Model

The Reactor thread delegates business logic to a worker thread pool, leveraging multi‑core CPUs while the Reactor still handles all event registration.

Master‑Slave (Main‑Sub) Reactor Multi‑Thread Model

Multiple Reactors each own a selector; the MainReactor accepts connections and hands them to SubReactors, improving concurrency.

Netty Thread Model

Netty provides two thread groups: BossGroup (similar to MainReactor) for accepting connections and WorkerGroup (similar to SubReactor) for handling read/write events. Each group contains several NioEventLoop instances, each with its own Selector.

Example code that simulates this process:

// Main Reactor
public class NioAcceptorServer {
    Selector acceptorSel = null;
    NioWorker[] workers = null;
    int workerPoint = 0;

    public NioAcceptorServer(int workerNum) {
        workers = new NioWorker[workerNum];
        for (int i = 0; i < workerNum; i++) {
            workers[i] = new NioWorker();
            workers[i].start();
        }
    }

    public NioWorker nextWorker() {
        workerPoint++;
        int i = workerPoint % workers.length;
        return workers[i];
    }

    public void run() {
        try {
            ServerSocketChannel ssc = ServerSocketChannel.open();
            ssc.configureBlocking(false);
            ssc.socket().bind(new InetSocketAddress(8080));
            acceptorSel = Selector.open();
            ssc.register(acceptorSel, SelectionKey.OP_ACCEPT);
            while (true) {
                acceptorSel.select();
                Set
set = acceptorSel.selectedKeys();
                Iterator
it = set.iterator();
                while (it.hasNext()) {
                    SelectionKey sk = it.next();
                    it.remove();
                    if (sk.isAcceptable()) {
                        ServerSocketChannel ssc1 = (ServerSocketChannel) sk.channel();
                        SocketChannel sc = ssc1.accept();
                        NioWorker worker = nextWorker();
                        worker.register(sc);
                    }
                }
            }
        } catch (ClosedChannelException e1) {
            e1.printStackTrace();
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

// Sub Reactor (Worker)
public class NioWorker extends Thread {
    private Selector selector = null;
    public NioWorker() {
        try {
            selector = Selector.open();
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
    public void register(SocketChannel sc) {
        try {
            sc.configureBlocking(false);
            ByteBuffer bb = ByteBuffer.allocate(4);
            sc.register(selector, SelectionKey.OP_READ, bb);
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
    @Override
    public void run() {
        while (true) {
            try {
                selector.select();
                Set
set = selector.selectedKeys();
                Iterator
it = set.iterator();
                while (it.hasNext()) {
                    SelectionKey sk = it.next();
                    it.remove();
                    if (sk.isReadable()) {
                        SocketChannel sc = (SocketChannel) sk.channel();
                        ByteBuffer bb = (ByteBuffer) sk.attachment();
                        try {
                            int i = sc.read(bb);
                            if (i == -1) {
                                // end of stream
                            }
                        } catch (IOException e) {
                            e.printStackTrace();
                        }
                    }
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    }
}

Handler Pipeline

Each Channel has a ChannelPipeline, a doubly‑linked list of ChannelHandlerContext objects that wrap ChannelHandlers. The pipeline follows the Chain of Responsibility pattern: after one handler processes an event, it passes the event to the next handler.

Handlers are divided into inbound (handling read events) and outbound (handling write events). Developers add handlers to the pipeline via methods such as addLast(), and the order of addition determines execution order.

Because the entire processing chain runs on the same IO thread (NioEventLoop), there is no thread‑context switch, and data is not subject to concurrent modification.

Netty Practical Example: HTTP Server

The following concise code demonstrates a Netty‑based HTTP server.

public class NettyServer {
    public void startServer() throws Exception {
        int defaultThreadNum = Runtime.getRuntime().availableProcessors() * 2;
        EventLoopGroup bossGroup = new NioEventLoopGroup(defaultThreadNum,
                new ThreadFactoryBuilder().setNameFormat("boss-group").build());
        EventLoopGroup workerGroup = new NioEventLoopGroup(defaultThreadNum,
                new ThreadFactoryBuilder().setNameFormat("worker-group").build());
        ServerBootstrap b = new ServerBootstrap();
        b.option(ChannelOption.SO_REUSEADDR, true);
        b.childOption(ChannelOption.ALLOCATOR, PooledByteBufAllocator.DEFAULT);
        b.childOption(ChannelOption.RCVBUF_ALLOCATOR, AdaptiveRecvByteBufAllocator.DEFAULT);
        b.childOption(ChannelOption.TCP_NODELAY, true);
        b.group(bossGroup, workerGroup)
         .channel(NioServerSocketChannel.class)
         .childHandler(new DispatchHandler());
        b.bind(8080).addListener(new ChannelFutureListener() {
            @Override
            public void operationComplete(ChannelFuture future) throws Exception {
                if (future.isSuccess()) {
                    log.info("Netty server started successfully");
                } else {
                    log.error("Netty server failed to start, cause: ", future.cause());
                }
            }
        }).await();
    }
}

public class DispatchHandler extends ChannelInitializer
{
    private final int maxAggregateSize = 1024 * 1024 * 5;
    private final int httpClientCodecMaxInitialLineLength = 4096;
    private final int httpClientCodecMaxHeaderSize = 64 * 1024;
    private final int httpClientCodecMaxChunkSize = 128 * 1024;
    @Override
    protected void initChannel(SocketChannel ch) throws Exception {
        ChannelPipeline p = ch.pipeline();
        p.addLast(new HttpRequestDecoder(httpClientCodecMaxInitialLineLength, httpClientCodecMaxHeaderSize, httpClientCodecMaxChunkSize));
        p.addLast(new HttpResponseEncoder());
        p.addLast(new HttpObjectAggregator(maxAggregateSize));
        p.addLast(new HttpBusinessHandler());
    }
}

public class HttpBusinessHandler extends ChannelInboundHandlerAdapter {
    @Override
    public void channelRead(ChannelHandlerContext ctx, Object msg) throws Exception {
        FullHttpRequest httpRequest = (FullHttpRequest) msg;
        // Business logic processing …
        String responseMessage = "ok";
        FullHttpResponse httpResponse = new DefaultFullHttpResponse(HTTP_1_1,
                HttpResponseStatus.OK, Unpooled.wrappedBuffer(responseMessage.getBytes()));
        ctx.writeAndFlush(httpResponse);
    }
}

Netty Practical Experience Summary

In most cases, Netty's built‑in handlers satisfy common scenarios; developers only need to focus on business logic handlers.

Simple, time‑bounded tasks can be processed directly on the IO thread.

Complex or time‑unpredictable tasks should be delegated to a backend thread pool.

Business threads should avoid directly manipulating ChannelHandlers.

Author: Yang Xin (Yang Guo)

Reviewer: Wu Youqiang (Ji Dian)

Editor: Wu Youqiang (Ji Dian)