User guide for Netty 4.x

• Table of Contents
• Preface
• The Solution
• Getting Started
  • Before Getting Started
  • Writing a Discard Server
  • Looking into the Received Data
  • Writing an Echo Server
  • Writing a Time Server
  • Writing a Time Client
  • Dealing with a Stream-based Transport
  • Speaking in POJO instead of ByteBuf
  • Shutting Down Your Application
  • Summary

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();
    }
}

 

1. 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.
2. 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.

3. 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);
       }
   }

    

4. 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.

1. DiscardServerHander繼承了ChannelInboundHandlerAdapter, 他是ChannelInboundHandler的實現.　ChannelInboundHandler提供了可變事件處理方法, 你可以重寫他們. 目前你只能繼承ChannelInboundHanderAdapter, 而不是自己去實現handler接口
2. 我們重寫了channelRead()時間處理方法. 這個方法當信息收到時被調用. 這個例子中, 收到的信息類型是ByteBuf
3. 為了實現DISCARD協議,  處理器必須忽略到收到的信息. ByteBuf是一個引用計數對象, 他通過調用release()方法來顯式釋放. 請注意, 釋放任何傳到handler的引用計數對象是handler的責任. 通常, channelRead()處理方法實現如下: (看原文代碼)
4. 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();
    }
}

 

1. 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.
2. 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.
3. Here, we specify to use the NioServerSocketChannel class which is used to instantiate a new Channel to accept incoming connections.
4. 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.
5. 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.
6. 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.
7. 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.)

1. NioEventLoopGroup是一個用來處理IO操作的多線程事件循環.netty為不同類型的傳輸提供了不同的EventLoopGroup實現.我們在這個例子實現實現了一個服務端程序, 因此會用到兩個NioEventLoopGroup.第一個叫做'boss', 接受即將來到的連接.第二個叫worker, 用來在boos接受請求並把這些請求注冊給worker的時候處理這些請求的流通.有多少線程會被創建, 他們是如何被映射到創建的通道上的取決於 EventLoopGroup的實現, 並且可以通過構造器來控制
2. ServerBootstrp是一個用來啟動服務器的幫助類.你可以使用Channel直接啟動服務器.然而, 請注意這是一個繁瑣的過程, 大部分情況下你不需要那樣做
3. 這里我們指定了使用NioServerSocketChannel來實例化一個新的Channel來接受到來的連接.
4. 這里指定的handler總會被最近接受的Channel評估. ChannelInitializer是一個用來幫助用戶配置新Channel的特殊處理器.你很有可能通過添加諸如DiscardServerHandler來設置新的Channel的ChannelPipeline來實現你的網絡程序.隨着程序越來越復雜, 你可能想添加更多的處理器到popeline中並最終將這個匿名類提取到頂層類
5. 你也可以為特定的Channel實現設置特定參數.我們寫的是一個TCP/IP服務器, 所以我們允許設置socket選項, 例如 tcpNoDelay和keepAlive. 請查閱ChannelOption和特定的ChannelConfig實現的API文檔來獲取ChannelOption的總覽
6. 你是否注意到了option()和childOption()? option()是設置用來接收到來的連接的NioServerSocketChannel的.childOption()是用來設置被父ServerChannel接收的Channel的, 在這個例子中父ServerChannel就是NioServerSocketChannel.
7. 我們已經准備好了.剩下的就是綁定一個端口並啟動服務器. 這里我們將綁定到所有機器的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)
    }
}

 

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

1. 這個低效的循環可以簡化為: System.out.println(buf.toString(io.netty.util.CharsetUtil.US_ASCII))
2. 你也可以使用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)
  }

 

1. 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.
2. 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.

1. 一個 ChannelHanderContext對象提供了不同的操作用來觸發不同的IO事件和操作. 這里我們調用wirte(Object)方法來逐字寫回接收到的數據.請注意我們沒有像DISCARD例子中那樣釋放收到的message.這是因為Netty會在它被寫出到線上以后為你釋放它
2. 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();
    }
}

 

1. 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.
2. 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.

3. 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.

4. 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);

1. 如屆時的那樣, channelActive()方法會在一個連接被建立並准備產生流量的時候被調用.讓我們在這個方法寫一個代表當前時間的32位正數
2. 為了發送一個新的消息, 我們需要申請一塊新的buffer, 他會包含這個消息. 我們打算寫一個32位整數,所以我們需要一個容量至少是4字節的ByteBuf. 獲取通過ChannelHandlerContext.alloc()當前ByteBufAllocator並分配一個新的buffer
3. 和往常一樣,我們寫一個構造的消息.

          但是等等, 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();
        }
    }
}

 

1. Bootstrap is similar to ServerBootstrap except that it's for non-server channels such as a client-side or connectionless channel.
2. 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.
3. Instead of NioServerSocketChannel, NioSocketChannel is being used to create a client-side Channel.
4. Note that we do not use childOption() here unlike we did with ServerBootstrap because the client-side SocketChannel does not have a parent.
5. We should call the connect() method instead of the bind() method.

1. Bootstrap類似於ServerBootstrap, 除了他是給非服務器通道使用的, 比如客戶端或無連接通道
2. 如果你只指定一個EventLoopGroup, 他會被同時作為boss group和worker group使用. 即使boss group在客戶端根本沒用
3. 替代NioServerSocketChannel, NioSocketChannel用來創建一個客戶端Channel
4. 注意我們沒有像ServerBootstrap那樣使用childOption(), 因為客戶端SocketChannel沒有雙親
5. 我們調用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();
    }
}

 

1. In TCP/IP, Netty reads the data sent from a peer into a `ByteBuf`.
2. 在 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();
    }
}

 

1. 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.
2. First, all received data should be cumulated into buf.
3. 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.

1. 一個 ChannelHandler有兩個生命周期監聽方法: handlerAdded()和handlerRemoved(). 只要他沒有長時間阻塞, 你就可以執行任意的初始化任務
2. 第一, 所有接收到的數據應該被累積到buf中
3. 然后, 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)
    }
}

 

1. ByteToMessageDecoder is an implementation of ChannelInboundHandler which makes it easy to deal with the fragmentation issue.
2. ByteToMessageDecoder calls the decode() method with an internally maintained cumulative buffer whenever new data is received.
3. 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.
4. 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.

1. ByteToMessageDecoder是一個ChannelInboundHandler的實現, 它讓處理碎片問題變得簡單.
2. ByteToMessageDecoder在收到新數據后, 會調用decode()方法來填充一個內部維護的積累緩存 -- in.
3. decode()可以決定當累積buffer中的數據不足的時候不將數據添加到out中
4. 如果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)
    }
}

 

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和它的文檔.