【Netty官方文档翻译】Getting Started

在这一章节里，会以一个简单的例子来展示Netty的核心结构，来让你快速入门。当你看完这一章节之后，你应该可以写一个客户端和服务端。
　　如果你更喜欢自顶向下的学习方式，你可能想要从章节2[结构概览]开始，然后再回到这里。

Before Getting Started 在开始之前

要运行这个章节的例子的话，最低的要求是最新版的Netty和jdk1.6或以上。最新版本的Netty的下载地址下载。jdk略。
　　当你在阅读的时候，你可能会对这一章节介绍的类有更多的问题。请随时查询API文档。为了你的方便，所有的类名都连接到在线的API文档。
如果有错误的信息，请不要犹豫，联系Netty的社区。

Writing a Discard Server 写一个抛弃信息的服务器

最简单的协议不是"Hello, World"而是DISCARD。这是一个对所有收到的数据不做任何响应的协议。
　　为了实现DISCARD协议，你需要做的事情就是忽略所有收到的数据。让我们直接从处理I/O时间的handler的实现开始吧。

package io.netty.example.discard;

import io.netty.buffer.ByteBuf;

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继承了实现了ChannelInboundHandler
的ChannelInboundHandlerAdapter。ChannelInboundHandler提供了各种你可以重写的事件处理方法。就现在来说，只需要继承 ChannelInboundHandlerAdapter就够了，不需要自己实现handler接口。
2.我们重写了channelRead()事件处理方法。当收到消息的时候这个方法会被调用。在这个例子中，消息的类型是 ByteBuf。
3.为了实现DISCARD协议，这个handler必须忽略收到的消息。ByteBuf
是一个通过release()方法释放的引用计数的对象。请注意，这个handler方法的责任就是使任何引用计数对象通过到达下一个handler。通常，channelRead()处理方法会像下面这样实现:

@Override
public void channelRead(ChannelHandlerContext ctx, Object msg) {
    try {
        // Do something with msg
    } finally {
        ReferenceCountUtil.release(msg);
    }
}

4.当Netty抛出一个I/O异常或者handler实现方法抛出一个异常的时候exceptionCaught()事件处理方法就会被调用。大多数情况下，被catch到的异常应该被记录日志，它所关联的channel也应该被关闭，不过这个方法的具体实现可以根据你的情况而定。例如，你可能会在连接关闭之前发送一个包含错误码的响应消息。

到目前为止一切顺利，我们已经实现了一半DISCARD服务器了。剩下的就是写main()方法来启动DiscardServerHandler。

package io.netty.example.discard;
    
import io.netty.bootstrap.ServerBootstrap;

import io.netty.channel.ChannelFuture;
import io.netty.channel.ChannelInitializer;
import io.netty.channel.ChannelOption;
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
是一个处理I/O操作的多线程事件循环器。Netty提供了多种EventLoopGroup实现用来处理不同的传输。在这个例子里，我们实现一个服务端的应用，所以会用到两个NioEventLoopGroup。第一个被称为"boss"，它接收到来的连接。第二个被称为"worker"，用来处理已经被建立的连接，一旦boss接收了连接，他就会把连接注册到worker上。具体会使用到多少线程，线程怎么映射到已经创建了的Channel上的取决于EventLoopGroup
的实现，甚至可以用构造函数来配置。
2.ServerBootstrap
是一个用来启动服务器的辅助类。你也可以直接用Channel
来启动服务器。然而，请注意这是一个繁琐的过程，在大多数情况下，你都不需要做。
3.这里，我们指定使用 NioServerSocketChannel来初始化一个新的Channel
来接收到来的连接。
4.被指定的处理器会一直被用来处理新接收的Channel。ChannelInitializer
是一个用来帮助我们配置新Channel
的特别handler。最常见的情况是你想要通过增加譬如DiscardServerHandler的handler实现给新的Channel
配置 ChannelPipeline最终实现你的网络应用。当你的应用变得复杂时，你可能会增加更多的handler到pipeline，然后提取提取一个匿名类到最上层。
5.你也可以给Channel的实现设置参数，我们正在写一个TCP/IP的服务器，所以我们可以设置socket选项为tcpNpDelay和keepAlive。请联系 ChannelOption
和特定的ChannelConfig
实现的API文档来获取一个被支持的ChannelOption的概览。
6.你有没有注意到option()和childOption()？前者是为了NioServerSocketChannel接收连接，后者是为了被parent ServerChannel
接收的Channel，在这里， ServerChannel
指的是 NioServerSocketChannel。
7.现在我们准备好了。剩下的就是去绑定端口号，然后启动服务器。这里，我们绑定8080.你现在可以调用bind()方法随意多的次数(使用不同的绑定地址)。

祝贺！你已经完成了你的第一个Netty服务器。

Looking into the Received Data 查看收到的数据

现在我们已经写了我们的第一个服务器，我们需要测试它是不是真的能工作。最简单的方法就是用telnet命令。例如，你可以输入telnet localhost 8080，然后输入一些东西。

然而，这样我们就能说这个服务器能正常工作了吗？我们不知道，因为他是个丢弃数据的服务器。你得不到任何的响应。为了证明它真的可以正常工作，然我们修改一下服务器，让他打印出他收到的消息。

我们已经知道channelRead()方法会在接收到数据的时候被调用。让我们在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.这个低效率的循环可以被简化成System.out.println(in.toString(io.netty.util.CharsetUtil.US_ASCII))
2.你可以用in.release替换这里

如果你再次运行telnet命令，你就会看到服务器打印出了他刚收到的消息。

源代码在io.netty.example.discard