User guide for Netty 4.x

Preface

前言

The Problem

问题

Nowadays we use general purpose applications or libraries to communicate with each other. For example, we often use an HTTP client library to retrieve information from a web server and to invoke a remote procedure call via web services.

今天我们使用通用程序或类库来相互通信.例如, 我们经常使用HTTP客户端类库来从web服务器获取信息, 或者通过web services进行远程过程调用.

However, a general purpose protocol or its implementation sometimes does not scale very well. It is like we don't use a general purpose HTTP server to exchange huge files, e-mail messages, and near-realtime messages such as financial information and multiplayer game data. What's required is a highly optimized protocol implementation which is dedicated to a special purpose. For example, you might want to implement an HTTP server which is optimized for AJAX-based chat application, media streaming, or large file transfer. You could even want to design and implement a whole new protocol which is precisely tailored to your need.

然而,一个通用的协议或者实现有时候扩展性并不那么好.就像我们不会使用通用的HTTP 服务器来交换大文件, e-mail消息, 以及诸如经济信息和多用户游戏数据的近实时消息.我们需要的是一个专注于特殊目的的高度优化实现.例如,你可能实现一个用来给基于ajax聊天或者媒体流或者大文件传输的程序使用的HTTP Server

Another inevitable case is when you have to deal with a legacy proprietary protocol to ensure the interoperability with an old system. What matters in this case is how quickly we can implement that protocol while not sacrificing the stability and performance of the resulting application.

另一个不可避免的情况是你必须处理遗留的专有协议来保证和一个老系统的互操作性. 这个情况的关键是我们在不牺牲稳定性和结果程序的性能的情况下, 实现这样一个协议.

The Solution

The Netty project is an effort to provide an asynchronous event-driven network application framework and tooling for the rapid development of maintainable high-performance · high-scalability protocol servers and clients.

Netty项目致力于为快速开发可维护和高性能,高稳定性协议服务器和客户端提供一个异步的事件驱动网络编程框架和工具.

In other words, Netty is a NIO client server framework which enables quick and easy development of network applications such as protocol servers and clients. It greatly simplifies and streamlines network programming such as TCP and UDP socket server development.

换句话说, Netty 是一个 NIO 客户端和服务端框架, 他可以快速简单的开发出一个诸如协议服务器和客户端的网络应用程序. 他最大程度的简化和流线化了诸如TCP和UDP socket服务器的网络编程

'Quick and easy' does not mean that a resulting application will suffer from a maintainability or a performance issue. Netty has been designed carefully with the experiences earned from the implementation of a lot of protocols such as FTP, SMTP, HTTP, and various binary and text-based legacy protocols. As a result, Netty has succeeded to find a way to achieve ease of development, performance, stability, and flexibility without a compromise.

'快且简单'并不意味着应用程序会产生维护和性能问题. Netty是一个吸收多了多种协议的设计经验, 包括FTP, SMTP, HTTP, 各种二进制, 文本协议, 的精心设计的框架.所以Netty已经找到了可以在不牺牲性能,稳定性,灵活性的情况下简单的开发的方法

Some users might already have found other network application framework that claims to have the same advantage, and you might want to ask what makes Netty so different from them. The answer is the philosophy where it is built on. Netty is designed to give you the most comfortable experience both in terms of the API and the implementation from the day one. It is not something tangible but you will realize that this philosophy will make your life much easier as you read this guide and play with Netty.

有些用户可能已经找到了一些其他声称有相同优点的网络编程框架, 你可能想问是什么让Netty和他们如此不同. 答案是Netty的设计哲学.Netty的设计的目的是从今天起给在API和实现方法面给你最舒适的体验. 这并不是有形的, 但是随着你在阅读想到和使用netty过程中,你会感受到这种哲学为你生活带来的改变

Getting Started

This chapter tours around the core constructs of Netty with simple examples to let you get started quickly. You will be able to write a client and a server on top of Netty right away when you are at the end of this chapter.

If you prefer top-down approach in learning something, you might want to start from Chapter 2, Architectural Overview and get back here.

这章教程围绕Netty的核心构建进行, 我会会用一些简单的例子让你快速开始. 本章最后,你马上就可以熟练的使用netty写一个客户端和一个服务端了. 你过想自顶向下的学习, 最好从第二章(架构总览)开始, 然后在回来这里看

Before Getting Started

The minimum requirements to run the examples which are introduced in this chapter are only two; the latest version of Netty and JDK 1.7 or above. The latest version of Netty is available in the project download page. To download the right version of JDK, please refer to your preferred JDK vendor's web site.

跑起本章的实例程序的要求有两个: 最新版本的Netty和JDK 1.7或更高版本的jdk. 最新版本的netty可以在这里下载the project download page. JDK请到官网下.

As you read, you might have more questions about the classes introduced in this chapter. Please refer to the API reference whenever you want to know more about them. All class names in this document are linked to the online API reference for your convenience. Also, please don't hesitate to contact the Netty project community and let us know if there's any incorrect information, errors in grammar and typo, and if you have a good idea to improve the documentation.

在本章你可能会有很多关于class介绍的问题.想知道更多关于这些类具体的情况请到api参考手册查看.所有类都会链接到在线API手册. 如果你发现有任何错误信息,错误语法和错别字,或者你有提升这个文档的好主意,请毫不犹豫的联系the Netty project community

Writing a Discard Server

The most simplistic protocol in the world is not 'Hello, World!' but DISCARD. It's a protocol which discards any received data without any response.

这个世界最简单的协议不是'hello word'而是DISCARD(拒绝协议).这是一个丢弃所有收到的数据并且没有任何响应的协议.

To implement the DISCARD protocol, the only thing you need to do is to ignore all received data. Let us start straight from the handler implementation, which handles I/O events generated by Netty.

要实现DISCARD协议, 唯一一件事情是忽略所有接收到的数据. 让我们直接使用netty创建的I/O事件处理程序来实现一下.

package io.netty.example.discard;



import io.netty.channel.ChannelHandlerContext;

import io.netty.channel.ChannelInboundHandlerAdapter;



/**

 * Handles a server-side channel.

 */

public class DiscardServerHandler extends ChannelInboundHandlerAdapter { // (1)



    @Override

    public void channelRead(ChannelHandlerContext ctx, Object msg) { // (2)

        // Discard the received data silently.

        ((ByteBuf) msg).release(); // (3)

    }



    @Override

    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) { // (4)

        // Close the connection when an exception is raised.

        cause.printStackTrace();

        ctx.close();

    }

}

DiscardServerHandler extends ChannelInboundHandlerAdapter, which is an implementation of ChannelInboundHandler. ChannelInboundHandler provides various event handler methods that you can override. For now, it is just enough to extend ChannelInboundHandlerAdapter rather than to implement the handler interface by yourself.
We override the channelRead() event handler method here. This method is called with the received message, whenever new data is received from a client. In this example, the type of the received message is ByteBuf.
To implement the DISCARD protocol, the handler has to ignore the received message. ByteBuf is a reference-counted object which has to be released explicitly via the release() method. Please keep in mind that it is the handler's responsibility to release any reference-counted object passed to the handler. Usually, channelRead() handler method is implemented like the following:
```
@Override

public void channelRead(ChannelHandlerContext ctx, Object msg) {

    try {

        // Do something with msg

    } finally {

        ReferenceCountUtil.release(msg);

    }

}
```
The exceptionCaught() event handler method is called with a Throwable when an exception was raised by Netty due to an I/O error or by a handler implementation due to the exception thrown while processing events. In most cases, the caught exception should be logged and its associated channel should be closed here, although the implementation of this method can be different depending on what you want to do to deal with an exceptional situation. For example, you might want to send a response message with an error code before closing the connection.

DiscardServerHander继承了ChannelInboundHandlerAdapter, 他是ChannelInboundHandler的实现.　ChannelInboundHandler提供了可变事件处理方法, 你可以重写他们. 目前你只能继承ChannelInboundHanderAdapter, 而不是自己去实现handler接口
我们重写了channelRead()时间处理方法. 这个方法当信息收到时被调用. 这个例子中, 收到的信息类型是ByteBuf
为了实现DISCARD协议, 处理器必须忽略到收到的信息. ByteBuf是一个引用计数对象, 他通过调用release()方法来显式释放. 请注意, 释放任何传到handler的引用计数对象是handler的责任. 通常, channelRead()处理方法实现如下: (看原文代码)
exceptionCaught()时间处理方法会在如下情况被调用,在netty抛出一个I/O异常, 或hander的实现在处理时间过程中抛出异常时. 大部分情况, 被捕获的异常应该被logged, 并且和他相关的通道应该被关闭, 即使这个方法的实现可能会因你想处理的异常状况不同而不同. 例如,你可能想在关闭连接之前发送一个响应消息.

So far so good. We have implemented the first half of the DISCARD server. What's left now is to write the main() method which starts the server with the DiscardServerHandler.

目前为止一切都很好. 我们已经实现了DISCARD服务器的一半了. 剩下的就是写一个main()方法来启动服务器.

package io.netty.example.discard;

    

import io.netty.bootstrap.ServerBootstrap;

import io.netty.channel.ChannelFuture;

import io.netty.channel.ChannelInitializer;

import io.netty.channel.EventLoopGroup;

import io.netty.channel.nio.NioEventLoopGroup;

import io.netty.channel.socket.SocketChannel;

import io.netty.channel.socket.nio.NioServerSocketChannel;

    

/**

 * Discards any incoming data.

 */

public class DiscardServer {

    

    private int port;

    

    public DiscardServer(int port) {

        this.port = port;

    }

    

    public void run() throws Exception {

        EventLoopGroup bossGroup = new NioEventLoopGroup(); // (1)

        EventLoopGroup workerGroup = new NioEventLoopGroup();

        try {

            ServerBootstrap b = new ServerBootstrap(); // (2)

            b.group(bossGroup, workerGroup)

             .channel(NioServerSocketChannel.class) // (3)

             .childHandler(new ChannelInitializer<SocketChannel>() { // (4)

                 @Override

                 public void initChannel(SocketChannel ch) throws Exception {

                     ch.pipeline().addLast(new DiscardServerHandler());

                 }

             })

             .option(ChannelOption.SO_BACKLOG, 128)          // (5)

             .childOption(ChannelOption.SO_KEEPALIVE, true); // (6)

    

            // Bind and start to accept incoming connections.

            ChannelFuture f = b.bind(port).sync(); // (7)

    

            // Wait until the server socket is closed.

            // In this example, this does not happen, but you can do that to gracefully

            // shut down your server.

            f.channel().closeFuture().sync();

        } finally {

            workerGroup.shutdownGracefully();

            bossGroup.shutdownGracefully();

        }

    }

    

    public static void main(String[] args) throws Exception {

        int port;

        if (args.length > 0) {

            port = Integer.parseInt(args[0]);

        } else {

            port = 8080;

        }

        new DiscardServer(port).run();

    }

}

NioEventLoopGroup is a multithreaded event loop that handles I/O operation. Netty provides various EventLoopGroupimplementations for different kind of transports. We are implementing a server-side application in this example, and therefore two NioEventLoopGroup will be used. The first one, often called 'boss', accepts an incoming connection. The second one, often called 'worker', handles the traffic of the accepted connection once the boss accepts the connection and registers the accepted connection to the worker. How many Threads are used and how they are mapped to the created Channels depends on the EventLoopGroup implementation and may be even configurable via a constructor.
ServerBootstrap is a helper class that sets up a server. You can set up the server using a Channel directly. However, please note that this is a tedious process, and you do not need to do that in most cases.
Here, we specify to use the NioServerSocketChannel class which is used to instantiate a new Channel to accept incoming connections.
The handler specified here will always be evaluated by a newly accepted Channel. The ChannelInitializer is a special handler that is purposed to help a user configure a new Channel. It is most likely that you want to configure the ChannelPipeline of the new Channel by adding some handlers such as DiscardServerHandler to implement your network application. As the application gets complicated, it is likely that you will add more handlers to the pipeline and extract this anonymous class into a top level class eventually.
You can also set the parameters which are specific to the Channel implementation. We are writing a TCP/IP server, so we are allowed to set the socket options such as tcpNoDelay and keepAlive. Please refer to the apidocs of ChannelOption and the specific ChannelConfig implementations to get an overview about the supported ChannelOptions.
Did you notice option() and childOption()? option() is for the NioServerSocketChannel that accepts incoming connections. childOption() is for the Channels accepted by the parent ServerChannel, which is NioServerSocketChannel in this case.
We are ready to go now. What's left is to bind to the port and to start the server. Here, we bind to the port 8080 of all NICs (network interface cards) in the machine. You can now call the bind() method as many times as you want (with different bind addresses.)

NioEventLoopGroup是一个用来处理IO操作的多线程事件循环.netty为不同类型的传输提供了不同的EventLoopGroup实现.我们在这个例子实现实现了一个服务端程序, 因此会用到两个NioEventLoopGroup.第一个叫做'boss', 接受即将来到的连接.第二个叫worker, 用来在boos接受请求并把这些请求注册给worker的时候处理这些请求的流通.有多少线程会被创建, 他们是如何被映射到创建的通道上的取决于 EventLoopGroup的实现, 并且可以通过构造器来控制
ServerBootstrp是一个用来启动服务器的帮助类.你可以使用Channel直接启动服务器.然而, 请注意这是一个繁琐的过程, 大部分情况下你不需要那样做
这里我们指定了使用NioServerSocketChannel来实例化一个新的Channel来接受到来的连接.
这里指定的handler总会被最近接受的Channel评估. ChannelInitializer是一个用来帮助用户配置新Channel的特殊处理器.你很有可能通过添加诸如DiscardServerHandler来设置新的Channel的ChannelPipeline来实现你的网络程序.随着程序越来越复杂, 你可能想添加更多的处理器到popeline中并最终将这个匿名类提取到顶层类
你也可以为特定的Channel实现设置特定参数.我们写的是一个TCP/IP服务器, 所以我们允许设置socket选项, 例如 tcpNoDelay和keepAlive. 请查阅ChannelOption和特定的ChannelConfig实现的API文档来获取ChannelOption的总览
你是否注意到了option()和childOption()? option()是设置用来接收到来的连接的NioServerSocketChannel的.childOption()是用来设置被父ServerChannel接收的Channel的, 在这个例子中父ServerChannel就是NioServerSocketChannel.
我们已经准备好了.剩下的就是绑定一个端口并启动服务器. 这里我们将绑定到所有机器的NICs的端口8080.你现在可以任意调用bind()方法了(到不同的绑定地址)

Congratulations! You've just finished your first server on top of Netty.

恭喜! 你已经完成了你第一个使用netty搭建的服务器

Looking into the Received Data

Now that we have written our first server, we need to test if it really works. The easiest way to test it is to use the telnet command. For example, you could enter telnet localhost 8080 in the command line and type something.

现在我们已经写好了我们的第一个server, 我们需要测试他是否正确工作. 最简单的方法是使用telnet命令来测试.例如,你可以在命令行输入 telnet localhost 8080 并输入一些东西.

However, can we say that the server is working fine? We cannot really know that because it is a discard server. You will not get any response at all. To prove it is really working, let us modify the server to print what it has received.

然而要如何确定服务器正常工作呢?我们并不知道因为他是个DISCARD服务器.你无法得到任何响应.为了证明服务器真的在工作, 我们将服务器改为输出他收到的东西.

We already know that channelRead() method is invoked whenever data is received. Let us put some code into the channelRead()method of the DiscardServerHandler:

我们已经知道了channelRead()方法在服务器收到数据的时候会被调用. 让我们改写一下DiscardServerHandler的channelRead()的代码

@Override

public void channelRead(ChannelHandlerContext ctx, Object msg) {

    ByteBuf in = (ByteBuf) msg;

    try {

        while (in.isReadable()) { // (1)

            System.out.print((char) in.readByte());

            System.out.flush();

        }

    } finally {

        ReferenceCountUtil.release(msg); // (2)

    }

}

This inefficient loop can actually be simplified to: System.out.println(buf.toString(io.netty.util.CharsetUtil.US_ASCII))
Alternatively, you could do in.release() here.

这个低效的循环可以简化为: System.out.println(buf.toString(io.netty.util.CharsetUtil.US_ASCII))
你也可以使用in.release()作为替代方法

If you run the telnet command again, you will see the server prints what has received.

如果你再次运行telnet命令,你将会看到服务器输出了收到的东西

The full source code of the discard server is located in the io.netty.example.discard package of the distribution.

discard服务器源代码在io.netty.example.discard 可以找到

Writing an Echo Server

So far, we have been consuming data without responding at all. A server, however, is usually supposed to respond to a request. Let us learn how to write a response message to a client by implementing the ECHO protocol, where any received data is sent back.

目前我们已经使用了数据但是未作出任何响应. 然而一个服务器通常是用来响应一个请求的. 让我们学习如何写一个实现ECHO协议响应消息给客户端的服务器, 任何收到的消息都会被发回去

The only difference from the discard server we have implemented in the previous sections is that it sends the received data back instead of printing the received data out to the console. Therefore, it is enough again to modify the channelRead() method:

和discard服务器唯一的不同是他发回收到的数据, 而不是将收到的数据答应道控制台.因此, 修改一下channelRead()方法:

  @Override

  public void channelRead(ChannelHandlerContext ctx, Object msg) {

      ctx.write(msg); // (1)

      ctx.flush(); // (2)

  }

A ChannelHandlerContext object provides various operations that enable you to trigger various I/O events and operations. Here, we invoke write(Object) to write the received message in verbatim. Please note that we did not release the received message unlike we did in the DISCARD example. It is because Netty releases it for you when it is written out to the wire.
ctx.write(Object) does not make the message written out to the wire. It is buffered internally, and then flushed out to the wire by ctx.flush(). Alternatively, you could call ctx.writeAndFlush(msg) for brevity.

一个 ChannelHanderContext对象提供了不同的操作用来触发不同的IO事件和操作. 这里我们调用wirte(Object)方法来逐字写回接收到的数据.请注意我们没有像DISCARD例子中那样释放收到的message.这是因为Netty会在它被写出到线上以后为你释放它
ctx.write(Object)并不会让消息写出到线上.他会被立刻缓存, 并且在调用ctx.flush()以后才会被刷新到线上.替代的, 为了简介起见你可以调用ctx.writeAndFlush(msg)

If you run the telnet command again, you will see the server sends back whatever you have sent to it.

如果你再次运行telnet命令, 你会看到server将你输入的数据返回了

The full source code of the echo server is located in the io.netty.example.echo package of the distribution.

完整的源代码在这里io.netty.example.echo

Writing a Time Server

The protocol to implement in this section is the TIME protocol. It is different from the previous examples in that it sends a message, which contains a 32-bit integer, without receiving any requests and loses the connection once the message is sent. In this example, you will learn how to construct and send a message, and to close the connection on completion.

这个章节要实现的协议是TIME协议. 他和前面的例子的区别是他会发送一个32位的正数, 他不会接受任何请求数据, 并且一旦消息发送完毕则会关闭连接. 这个例子中, 你将会学到如何构建和发送一个消息, 并且在发送完毕后关闭连接

Because we are going to ignore any received data but to send a message as soon as a connection is established, we cannot use the channelRead() method this time. Instead, we should override the channelActive() method. The following is the implementation:

因为我们需要忽略所有收到的数据, 但是一旦连接建立则发送一个消息, 所以我们不能使用channelRead()方法, 而是使用channelActive()方法代替.下面是实现

package io.netty.example.time;



public class TimeServerHandler extends ChannelInboundHandlerAdapter {



    @Override

    public void channelActive(final ChannelHandlerContext ctx) { // (1)

        final ByteBuf time = ctx.alloc().buffer(4); // (2)

        time.writeInt((int) (System.currentTimeMillis() / 1000L + 2208988800L));

        

        final ChannelFuture f = ctx.writeAndFlush(time); // (3)

        f.addListener(new ChannelFutureListener() {

            @Override

            public void operationComplete(ChannelFuture future) {

                assert f == future;

                ctx.close();

            }

        }); // (4)

    }

    

    @Override

    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) {

        cause.printStackTrace();

        ctx.close();

    }

}

As explained, the channelActive() method will be invoked when a connection is established and ready to generate traffic. Let's write a 32-bit integer that represents the current time in this method.
To send a new message, we need to allocate a new buffer which will contain the message. We are going to write a 32-bit integer, and therefore we need a ByteBuf whose capacity is at least 4 bytes. Get the current ByteBufAllocator via ChannelHandlerContext.alloc() and allocate a new buffer.
As usual, we write the constructed message.

But wait, where's the flip? Didn't we used to call java.nio.ByteBuffer.flip() before sending a message in NIO? ByteBufdoes not have such a method because it has two pointers; one for read operations and the other for write operations. The writer index increases when you write something to a ByteBuf while the reader index does not change. The reader index and the writer index represents where the message starts and ends respectively.

In contrast, NIO buffer does not provide a clean way to figure out where the message content starts and ends without calling the flip method. You will be in trouble when you forget to flip the buffer because nothing or incorrect data will be sent. Such an error does not happen in Netty because we have different pointer for different operation types. You will find it makes your life much easier as you get used to it -- a life without flipping out!

Another point to note is that the ChannelHandlerContext.write() (and writeAndFlush()) method returns a ChannelFuture. A ChannelFuture represents an I/O operation which has not yet occurred. It means, any requested operation might not have been performed yet because all operations are asynchronous in Netty. For example, the following code might close the connection even before a message is sent:
```
Channel ch = ...;

ch.writeAndFlush(message);

ch.close();
```
Therefore, you need to call the close() method after the ChannelFuture is complete, which was returned by the write()method, and it notifies its listeners when the write operation has been done. Please note that, close() also might not close the connection immediately, and it returns a ChannelFuture.
How do we get notified when a write request is finished then? This is as simple as adding a ChannelFutureListener to the returned ChannelFuture. Here, we created a new anonymous ChannelFutureListener which closes the Channel when the operation is done.

Alternatively, you could simplify the code using a pre-defined listener:
```
f.addListener(ChannelFutureListener.CLOSE);
```

如届时的那样, channelActive()方法会在一个连接被建立并准备产生流量的时候被调用.让我们在这个方法写一个代表当前时间的32位正数
为了发送一个新的消息, 我们需要申请一块新的buffer, 他会包含这个消息. 我们打算写一个32位整数,所以我们需要一个容量至少是4字节的ByteBuf. 获取通过ChannelHandlerContext.alloc()当前ByteBufAllocator并分配一个新的buffer
和往常一样,我们写一个构造的消息.

但是等等, flip在哪里? 我们在发送一个消息之前不是都会先用 java.nio.ByteBuffer.flip()吗? ByteBuf不需要这个方法, 因为他有两个指针; 一个用来读操作, 一个用来写操作.写的索引会在你写东西的时候增加,但是读的索引不会改变.读的索引和写的索引分别代表消息的开始和结束

　　　相比之下, NIO buffer并没有提供一个清晰的方法来指出消息内容在哪里开始和结束.如果你忘记调用flip这个buffer可能会有麻烦, 因为将不会发送任何数据, 或者发送错误的数据.这样的错误不会再netty中发生, 因为我们对不同的操作有不同的指针.你将会发现你使用他的时候,你的生活变得更加　　　　　简单 -- 一个没有 flipping out 的生活!

　　　　另外一个要注意的是ChannelHandlerContext.write()(还有writeAndFlush())方法返回一个ChannelFuture. 一个 ChannelFuture代表一个还没发生的IO操作. 他的意思是, 任何请求操作都还没有发生, 因为所有的操作在netty中都是异步的. 例如, 下面的代码可能会在消息发送出去之前就关闭连接:

Channel ch = ...;

ch.writeAndFlush(message);

ch.close();

　　　　因此, 你需要在ChannelFuture完成以后再调用close()方法, 这个对象会在write()方法调用之后返回, 当他的写操作完成后他会通知他的监听器. 请注意, close()也有可能不会立即关闭连接, 他返回一个ChannelFuture.

4. 当一个写的请求完成以后我们如何被通知? 只需要讲一个ChannelFutureListener到返回的ChannelFuture. 这里,我们会创建一个匿名的ChannelFutureListener, 用来当错做完成的时候关闭Channel. 二选一, 你可以使用预定义的listener来简化如下的代码

　　　　f.addListener(ChannelFutureListener.CLOSE);

To test if our time server works as expected, you can use the UNIX rdate command:

为了测试我们的时间服务器是否按预期工作, 你可以使用UNIX rdate命令

$ rdate -o <port> -p <host>

where <port> is the port number you specified in the main() method and <host> is usually localhost.

<port>是你在main()方法指定的端口号, host一般使用localhost

Writing a Time Client

Unlike DISCARD and ECHO servers, we need a client for the TIME protocol because a human cannot translate a 32-bit binary data into a date on a calendar. In this section, we discuss how to make sure the server works correctly and learn how to write a client with Netty.

The biggest and only difference between a server and a client in Netty is that different Bootstrap and Channel implementations are used. Please take a look at the following code:

不像DISCARD和ECHO服务器, 我们需要为TIME协议创建一个客户端, 因为一个人类不能讲32位二进制数据转换成一个日期.在本章节, 我们会讨论如何保证服务器正确工作, 并学习如何使用netty写一个客户端.

package io.netty.example.time;



public class TimeClient {

    public static void main(String[] args) throws Exception {

        String host = args[0];

        int port = Integer.parseInt(args[1]);

        EventLoopGroup workerGroup = new NioEventLoopGroup();

        

        try {

            Bootstrap b = new Bootstrap(); // (1)

            b.group(workerGroup); // (2)

            b.channel(NioSocketChannel.class); // (3)

            b.option(ChannelOption.SO_KEEPALIVE, true); // (4)

            b.handler(new ChannelInitializer<SocketChannel>() {

                @Override

                public void initChannel(SocketChannel ch) throws Exception {

                    ch.pipeline().addLast(new TimeClientHandler());

                }

            });

            

            // Start the client.

            ChannelFuture f = b.connect(host, port).sync(); // (5)



            // Wait until the connection is closed.

            f.channel().closeFuture().sync();

        } finally {

            workerGroup.shutdownGracefully();

        }

    }

}

Bootstrap is similar to ServerBootstrap except that it's for non-server channels such as a client-side or connectionless channel.
If you specify only one EventLoopGroup, it will be used both as a boss group and as a worker group. The boss worker is not used for the client side though.
Instead of NioServerSocketChannel, NioSocketChannel is being used to create a client-side Channel.
Note that we do not use childOption() here unlike we did with ServerBootstrap because the client-side SocketChannel does not have a parent.
We should call the connect() method instead of the bind() method.

Bootstrap类似于ServerBootstrap, 除了他是给非服务器通道使用的, 比如客户端或无连接通道
如果你只指定一个EventLoopGroup, 他会被同时作为boss group和worker group使用. 即使boss group在客户端根本没用
替代NioServerSocketChannel, NioSocketChannel用来创建一个客户端Channel
注意我们没有像ServerBootstrap那样使用childOption(), 因为客户端SocketChannel没有双亲
我们调用connet()方法而不是bind()方法

As you can see, it is not really different from the the server-side code. What about the ChannelHandler implementation? It should receive a 32-bit integer from the server, translate it into a human readable format, print the translated time, and close the connection:

如你所见, 并不是真的和服务端的代码不同. 那么 ChannelHandler的实现呢? 他应该接受一个来自服务器的32位正数, 转换成一个人类可读的格式, 打印转换后的时间, 并关闭连接

package io.netty.example.time;



import java.util.Date;



public class TimeClientHandler extends ChannelInboundHandlerAdapter {

    @Override

    public void channelRead(ChannelHandlerContext ctx, Object msg) {

        ByteBuf m = (ByteBuf) msg; // (1)

        try {

            long currentTimeMillis = (m.readUnsignedInt() - 2208988800L) * 1000L;

            System.out.println(new Date(currentTimeMillis));

            ctx.close();

        } finally {

            m.release();

        }

    }



    @Override

    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) {

        cause.printStackTrace();

        ctx.close();

    }

}

In TCP/IP, Netty reads the data sent from a peer into a `ByteBuf`.
在 TCP/IP, Netty将另一端发送过来的数据读入到一个`ByteBuf`

It looks very simple and does not look any different from the server side example. However, this handler sometimes will refuse to work raising an IndexOutOfBoundsException. We discuss why this happens in the next section.

他看起来非常简单, 并且和服务端的例子没有任何区别. 然而, 这个handler有时候会拒绝工作而是抛出IndexOutOfBoundsException. 我们会在下个章节讨论为什么会这样.

Dealing with a Stream-based Transport

One Small Caveat of Socket Buffer

In a stream-based transport such as TCP/IP, received data is stored into a socket receive buffer. Unfortunately, the buffer of a stream-based transport is not a queue of packets but a queue of bytes. It means, even if you sent two messages as two independent packets, an operating system will not treat them as two messages but as just a bunch of bytes. Therefore, there is no guarantee that what you read is exactly what your remote peer wrote. For example, let us assume that the TCP/IP stack of an operating system has received three packets:

在一个基于流的传输, 例如TCP/IP, 收到的数据是存储在socket接受缓存里的. 不幸的是, 基于流的传输的缓存并不是一个数据包队列, 而是一个字节队列. 这意味着, 就算你用两个单独的数据包来发送两个消息, 操作系统也不会将他们当做两条消息, 而是作为遗传字节对待. 因此, 你从远端读到的东西到底是什么是没有保障的. 举个例子, 我们假设操作系统的TCP/IP栈收到了三个数据包:

Because of this general property of a stream-based protocol, there's high chance of reading them in the following fragmented form in your application:

因为一个基于流的协议的参数, 很有可能你会按照下面的片段来读取他们

Therefore, a receiving part, regardless it is server-side or client-side, should defrag the received data into one or more meaningful frames that could be easily understood by the application logic. In case of the example above, the received data should be framed like the following:

因此, 一个接收部分, 不管是服务端还是客户端, 都应该对收到的数据进行碎片整理, 让他们变为一个或多个更有意义的结构, 这样对于程序的逻辑来说更好理解.对于上面的例子, 收到的数据结构应该被整理成下面这样

The First Solution

Now let us get back to the TIME client example. We have the same problem here. A 32-bit integer is a very small amount of data, and it is not likely to be fragmented often. However, the problem is that it can be fragmented, and the possibility of fragmentation will increase as the traffic increases.

现在让我们回到TIME客户端的例子. 我们这里也有相同的问题. 一个32位的整形是很小的数据, 他并不经常会被分裂.然而, 问题是他也是有可能被分裂的, 特别是当流量增加的时候分裂的可能性也会增加

The simplistic solution is to create an internal cumulative buffer and wait until all 4 bytes are received into the internal buffer. The following is the modified TimeClientHandler implementation that fixes the problem:

最简单的办法是在建立一个内部的累计缓存, 并一直等到所有4个字节全都接收到内部缓存中. 下面是对TimeClientHandler实现的修改, 他修复了这个问题:

package io.netty.example.time;



import java.util.Date;



public class TimeClientHandler extends ChannelInboundHandlerAdapter {

    private ByteBuf buf;

    

    @Override

    public void handlerAdded(ChannelHandlerContext ctx) {

        buf = ctx.alloc().buffer(4); // (1)

    }

    

    @Override

    public void handlerRemoved(ChannelHandlerContext ctx) {

        buf.release(); // (1)

        buf = null;

    }

    

    @Override

    public void channelRead(ChannelHandlerContext ctx, Object msg) {

        ByteBuf m = (ByteBuf) msg;

        buf.writeBytes(m); // (2)

        m.release();

        

        if (buf.readableBytes() >= 4) { // (4)

            long currentTimeMillis = (buf.readInt() - 2208988800L) * 1000L;

            System.out.println(new Date(currentTimeMillis));

            ctx.close();

        }

    }

    

    @Override

    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) {

        cause.printStackTrace();

        ctx.close();

    }

}

A ChannelHandler has two life cycle listener methods: handlerAdded() and handlerRemoved(). You can perform an arbitrary (de)initialization task as long as it does not block for a long time.
First, all received data should be cumulated into buf.
And then, the handler must check if buf has enough data, 4 bytes in this example, and proceed to the actual business logic. Otherwise, Netty will call the channelRead() method again when more data arrives, and eventually all 4 bytes will be cumulated.

一个 ChannelHandler有两个生命周期监听方法: handlerAdded()和handlerRemoved(). 只要他没有长时间阻塞, 你就可以执行任意的初始化任务
第一, 所有接收到的数据应该被累积到buf中
然后, handler必须检查buf是否有足够的数据, 在这个例子中是4个字节, 并继续真正的业务逻辑. 否则, 当更多数据到达的时候, netty会再次调用channelRead()方法, 并最终所有4个字节都会被累加起来.

The Second Solution

Although the first solution has resolved the problem with the TIME client, the modified handler does not look that clean. Imagine a more complicated protocol which is composed of multiple fields such as a variable length field. Your ChannelInboundHandlerimplementation will become unmaintainable very quickly.

虽然第一种解决方案已经解决了TIME clinet的问题, 但是修改过后的handler看起来不够干净. 想象一下更复杂的协议, 它可以组合多个字段, 例如变量长度字段. 你的 ChannelInboundHandler实现将会很快变得不可维护

As you may have noticed, you can add more than one ChannelHandler to a ChannelPipeline, and therefore, you can split one monolithic ChannelHandler into multiple modular ones to reduce the complexity of your application. For example, you could split TimeClientHandler into two handlers:

可能已经意识到了, 你可以加入超过一个ChannelHandler到ChannelPipeline中, 因此, 你可以将一个巨大的ChannelHandler切分为多个模块化的getinstance, 来减少你的程序的复杂程度. 例如, 你可以将TimeClientHandler切分为两个handler

TimeDecoder which deals with the fragmentation issue, and
TimeDecoder 用来处理碎片问题
the initial simple version of TimeClientHandler.
TimeClientHandler的初始简单版本

Fortunately, Netty provides an extensible class which helps you write the first one out of the box:

幸运的是, netty提供了一个可扩展的类, 用来帮助你写第一个可用的类:

package io.netty.example.time;



public class TimeDecoder extends ByteToMessageDecoder { // (1)

    @Override

    protected void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) { // (2)

        if (in.readableBytes() < 4) {

            return; // (3)

        }

        

        out.add(in.readBytes(4)); // (4)

    }

}

ByteToMessageDecoder is an implementation of ChannelInboundHandler which makes it easy to deal with the fragmentation issue.
ByteToMessageDecoder calls the decode() method with an internally maintained cumulative buffer whenever new data is received.
decode() can decide to add nothing to out where there is not enough data in the cumulative buffer. ByteToMessageDecoderwill call decode() again when there is more data received.
If decode() adds an object to out, it means the decoder decoded a message successfully. ByteToMessageDecoder will discard the read part of the cumulative buffer. Please remember that you don't need to decode multiple messages. ByteToMessageDecoder will keep calling the decode() method until it adds nothing to out.

ByteToMessageDecoder是一个ChannelInboundHandler的实现, 它让处理碎片问题变得简单.
ByteToMessageDecoder在收到新数据后, 会调用decode()方法来填充一个内部维护的积累缓存 -- in.
decode()可以决定当累积buffer中的数据不足的时候不将数据添加到out中
如果decode()添加了一个对象到out中, 他表示decoder成功decode了一个消息. ByteToMessageDecoder会丢弃累积缓存中已经读过的部分.请记住你不需要解码多个消息. ByteToMessageDecoder会一直调用decode()方法直到他被添加到out中.

Now that we have another handler to insert into the ChannelPipeline, we should modify the ChannelInitializer implementation in the TimeClient:

现在我们有另一个handler需要插入到ChannelPipeline中, 我们应该修改TimeClient中ChannelInitializer的实现:

b.handler(new ChannelInitializer<SocketChannel>() {

    @Override

    public void initChannel(SocketChannel ch) throws Exception {

        ch.pipeline().addLast(new TimeDecoder(), new TimeClientHandler());

    }

});

If you are an adventurous person, you might want to try the ReplayingDecoder which simplifies the decoder even more. You will need to consult the API reference for more information though.

如果你是一个爱冒险的人, 你可能想尝试ReplayingDecoder, 他可以更加简化decoder. 具体详情去查询一下API手册

public class TimeDecoder extends ReplayingDecoder<VoidEnum> {

    @Override

    protected void decode(

            ChannelHandlerContext ctx, ByteBuf in, List<Object> out, VoidEnum state) {

        out.add(in.readBytes(4));

    }

}

Additionally, Netty provides out-of-the-box decoders which enables you to implement most protocols very easily and helps you avoid from ending up with a monolithic unmaintainable handler implementation. Please refer to the following packages for more detailed examples:

另外, netty提供了直接可用的decoder实现, 你可以用他们很容易地的实现大部分协议, 她帮助你避开了庞大的不可维护的handler实现. 请查阅下面的包查看更具体的例子

io.netty.example.factorial for a binary protocol, and // 二进制协议处理器
io.netty.example.telnet for a text line-based protocol. // 基于文本的协议

Speaking in POJO instead of `ByteBuf`

All the examples we have reviewed so far used a ByteBuf as a primary data structure of a protocol message. In this section, we will improve the TIME protocol client and server example to use a POJO instead of a ByteBuf.

回顾一下所有的例子, 目前我们都是使用ByteBuf作为协议消息的主要数据结构. 这个章节, 我们会提升TIME协议客户端和服务端例子, 使用POJO来替代ByteBuf

The advantage of using a POJO in your ChannelHandlers is obvious; your handler becomes more maintainable and reusable by separating the code which extracts information from ByteBuf out from the handler. In the TIME client and server examples, we read only one 32-bit integer and it is not a major issue to use ByteBuf directly. However, you will find it is necessary to make the separation as you implement a real world protocol.

ChannelHandler中使用POJO的优势很明显, 通过将从ByteBuf中提取信息的代码从handler中分离出来, 你的handler会变得更好维护和重用.在TIME客户端和服务端的例子中, 我们只会读取32位整数, 这并不是直接使用ByteBuf会导致的主要问题.然而,你会发现在你实现一个真正的世界级协议的时候, 做这种代码分离是非常有必要的

First, let us define a new type called UnixTime.

首先, 让我们定义一个新的类型叫做 UnixTime

package io.netty.example.time;



import java.util.Date;



public class UnixTime {



    private final int value;

    

    public UnixTime() {

        this((int) (System.currentTimeMillis() / 1000L + 2208988800L));

    }

    

    public UnixTime(int value) {

        this.value = value;

    }

        

    public int value() {

        return value;

    }

        

    @Override

    public String toString() {

        return new Date((value() - 2208988800L) * 1000L).toString();

    }

}

We can now revise the TimeDecoder to produce a UnixTime instead of a ByteBuf.

我们现在可以修正TimeDecoder来生成一个UnixTime而不是一个ByteBuf.

@Override

protected void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) {

    if (in.readableBytes() < 4) {

        return;

    }



    out.add(new UnixTime(in.readInt()));

}

With the updated decoder, the TimeClientHandler does not use ByteBuf anymore:

更新完decoder后, TimeClientHandler不会再使用ByteBuf了.

@Override

public void channelRead(ChannelHandlerContext ctx, Object msg) {

    UnixTime m = (UnixTime) msg;

    System.out.println(m);

    ctx.close();

}

Much simpler and elegant, right? The same technique can be applied on the server side. Let us update the TimeServerHandler first this time:

更简单和优雅了,对吧? 相同的技术也可以用在服务端. 让我们更新一下TimeServerHandler:

@Override

public void channelActive(ChannelHandlerContext ctx) {

    ChannelFuture f = ctx.writeAndFlush(new UnixTime());

    f.addListener(ChannelFutureListener.CLOSE);

}

Now, the only missing piece is an encoder, which is an implementation of ChannelOutboundHandler that translates a UnixTime back into a ByteBuf. It's much simpler than writing a decoder because there's no need to deal with packet fragmentation and assembly when encoding a message.

现在, 唯一缺少的一点就是encoder, 一个ChannelOutboundHandler实现, 他将一个UnixTime转回ByteBuf. 他比写一个decoder简单得多, 因为在编码一个消息的时候没有必要去处理数据包分裂和装配.

package io.netty.example.time;



public class TimeEncoder extends ChannelOutboundHandlerAdapter {

    @Override

    public void write(ChannelHandlerContext ctx, Object msg, ChannelPromise promise) {

        UnixTime m = (UnixTime) msg;

        ByteBuf encoded = ctx.alloc().buffer(4);

        encoded.writeInt(m.value());

        ctx.write(encoded, promise); // (1)

    }

}

There are quite a few important things to important in this single line.

First, we pass the original ChannelPromise as-is so that Netty marks it as success or failure when the encoded data is actually written out to the wire.

Second, we did not call ctx.flush(). There is a separate handler method void flush(ChannelHandlerContext ctx) which is purposed to override the flush() operation.

　　　　这一行有几件很重要的事情.

　　　　第一, 我们需要传递原样的ChannelPromise, 这样Netty在编码的数据真正写入到线上的时候, 可以把它当做成功和失败的标志.

　　　　第二, 我们不会调用ctx.flush(). 这里有一个分离的处理器方法 void flush(ChannelHandlerContext ctx), 重来重写flush()操作

To simplify even further, you can make use of MessageToByteEncoder:

为了更加简化, 你可以使用MessageToByteEncoder:

public class TimeEncoder extends MessageToByteEncoder<UnixTime> {

    @Override

    protected void encode(ChannelHandlerContext ctx, UnixTime msg, ByteBuf out) {

        out.writeInt(msg.value());

    }

}

The last task left is to insert a TimeEncoder into the ChannelPipeline on the server side, and it is left as a trivial exercise.

最后剩下的就是将一个TimeEncoder插入到服务端的ChannelPipeline, 这个作为练习.

Shutting Down Your Application

Shutting down a Netty application is usually as simple as shutting down all EventLoopGroups you created via shutdownGracefully(). It returns a Future that notifies you when the EventLoopGroup has been terminated completely and all Channels that belong to the group have been closed.

关闭一个netty应用通常跟使用shutdownGracefully()关闭所有你创建的EventLoopGroup一样简单. 他返回一个Future, 用来通知你EventLoopGroup已经被完全终止以及所有属于这个group的Channel都已经被关闭.

Summary

In this chapter, we had a quick tour of Netty with a demonstration on how to write a fully working network application on top of Netty.

There is more detailed information about Netty in the upcoming chapters. We also encourage you to review the Netty examples in the io.netty.example package.

Please also note that the community is always waiting for your questions and ideas to help you and keep improving Netty and its documentation based on your feed back.

这个章节, 我们展示了一个如何使用Netty写一个完整工作的网络应用程序的范例

在接下来的章节还有更多关于netty的细节.我们鼓励你回顾一下io.netty.example包的例子

同时请注意如果你有问题和idea, the community 永远在等着你, 它可以帮助你并通过你的反馈继续完善netty和它的文档.