The Netty Project 3.x User Guide

The minimum requirements to run the examples which are introduced in this chapter are only two; the latest version of Netty and JDK 1.5 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.

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.

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.

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.

  1 package org.jboss.netty.example.discard;
  2 
    public class DiscardServerHandler extends SimpleChannelHandler {
  4 
        @Override
  6     public void messageReceived(ChannelHandlerContext ctx, MessageEvent e) {
        }
  8 
        @Override
 10     public void exceptionCaught(ChannelHandlerContext ctx, ExceptionEvent e) {
            e.getCause().printStackTrace();
 12         
            Channel ch = e.getChannel();
 14         ch.close();
        }
 16 }

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.

  1 package org.jboss.netty.example.discard;
  2 
    import java.net.InetSocketAddress;
  4 import java.util.concurrent.Executors;
    
  6 public class DiscardServer {
    
  8     public static void main(String[] args) throws Exception {
            ChannelFactory factory =
 10             new NioServerSocketChannelFactory(
                        Executors.newCachedThreadPool(),
 12                     Executors.newCachedThreadPool());
    
 14         ServerBootstrap bootstrap = new ServerBootstrap(factory);
    
 16         bootstrap.setPipelineFactory(new ChannelPipelineFactory() {
                public ChannelPipeline getPipeline() {
 18                 return Channels.pipeline(new DiscardServerHandler());
                }
 20         });
    
 22         bootstrap.setOption("child.tcpNoDelay", true);
            bootstrap.setOption("child.keepAlive", true);
 24 
            bootstrap.bind(new InetSocketAddress(8080));
 26     }
    }

bootstrap.setOption("reuseAddress", true);

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

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.

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.

We already know that MessageEvent is generated whenever data is received and the messageReceived handler method will be invoked. Let us put some code into the messageReceived method of the DiscardServerHandler:

  1 @Override
  2 public void messageReceived(ChannelHandlerContext ctx, MessageEvent e) {
        ChannelBuffer buf = (ChannelBuffer) e.getMessage();
  4     while(buf.readable()) {
            System.out.println((char) buf.readByte());
  6         System.out.flush();
        }
  8 }

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

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

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.

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 messageReceived method:

  1 @Override
  2 public void messageReceived(ChannelHandlerContext ctx, MessageEvent e) {
        Channel ch = e.getChannel();
  4     ch.write(e.getMessage());
    }

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

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

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.

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 messageReceived method this time. Instead, we should override the channelConnected method. The following is the implementation:

  1 package org.jboss.netty.example.time;
  2 
    public class TimeServerHandler extends SimpleChannelHandler {
  4 
        @Override
  6     public void channelConnected(ChannelHandlerContext ctx, ChannelStateEvent e) {
            Channel ch = e.getChannel();
  8         
            ChannelBuffer time = ChannelBuffers.buffer(4);
 10         time.writeInt((int) (System.currentTimeMillis() / 1000L + 2208988800L));
            
 12         ChannelFuture f = ch.write(time);
            
 14         f.addListener(new ChannelFutureListener() {
                public void operationComplete(ChannelFuture future) {
 16                 Channel ch = future.getChannel();
                    ch.close();
 18             }
            });
 20     }
    
 22     @Override
        public void exceptionCaught(ChannelHandlerContext ctx, ExceptionEvent e) {
 24         e.getCause().printStackTrace();
            e.getChannel().close();
 26     }
    }

  1 import static org.jboss.netty.buffer.ChannelBuffers.*;
  2 ...
    ChannelBuffer  dynamicBuf = dynamicBuffer(256);
  4 ChannelBuffer ordinaryBuf = buffer(1024);

  1 Channel ch = ...;
  2 ch.write(message);
    ch.close();

f.addListener(ChannelFutureListener.CLOSE);

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

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

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 ChannelFactory are required. Please take a look at the following code:

  1 package org.jboss.netty.example.time;
  2 
    import java.net.InetSocketAddress;
  4 import java.util.concurrent.Executors;
    
  6 public class TimeClient {
    
  8     public static void main(String[] args) throws Exception {
            String host = args[0];
 10         int port = Integer.parseInt(args[1]);
    
 12         ChannelFactory factory =
                new NioClientSocketChannelFactory(
 14                     Executors.newCachedThreadPool(),
                        Executors.newCachedThreadPool());
 16 
            ClientBootstrap bootstrap = new ClientBootstrap(16)(factory);
 18 
            bootstrap.setPipelineFactory(new ChannelPipelineFactory() {
 20             public ChannelPipeline getPipeline() {
                    return Channels.pipeline(new TimeClientHandler());
 22             }
            });
 24         
            bootstrap.setOption("tcpNoDelay"(17), true);
 26         bootstrap.setOption("keepAlive", true);
    
 28         bootstrap.connect(18)(new InetSocketAddress(host, port));
        }
 30 }

As you can see, it is not really different from the server side startup. 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:

  1 package org.jboss.netty.example.time;
  2 
    import java.util.Date;
  4 
    public class TimeClientHandler extends SimpleChannelHandler {
  6 
        @Override
  8     public void messageReceived(ChannelHandlerContext ctx, MessageEvent e) {
            ChannelBuffer buf = (ChannelBuffer) e.getMessage();
 10         long currentTimeMillis = buf.readInt() * 1000L;
            System.out.println(new Date(currentTimeMillis));
 12         e.getChannel().close();
        }
 14 
        @Override
 16     public void exceptionCaught(ChannelHandlerContext ctx, ExceptionEvent e) {
            e.getCause().printStackTrace();
 18         e.getChannel().close();
        }
 20 }

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.

All the examples we have reviewed so far used a ChannelBuffer 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 ChannelBuffer.

The advantage of using a POJO in your ChannelHandler is obvious; your handler becomes more maintainable and reusable by separating the code which extracts information from ChannelBuffer 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 ChannelBuffer directly. However, you will find it is necessary to make the separation as you implement a real world protocol.

First, let us define a new type called UnixTime.

  1 package org.jboss.netty.example.time;
  2 
    import java.util.Date;
  4 
    public class UnixTime {
  6     private final int value;
        
  8     public UnixTime(int value) {
            this.value = value;
 10     }
        
 12     public int getValue() {
            return value;
 14     }
        
 16     @Override
        public String toString() {
 18         return new Date(value * 1000L).toString();
        }
 20 }

We can now revise the TimeDecoder to return a UnixTime instead of a ChannelBuffer.

  1 @Override
  2 protected Object decode(
            ChannelHandlerContext ctx, Channel channel, ChannelBuffer buffer) {
  4     if (buffer.readableBytes() < 4) {
            return null;
  6     }
    
  8     return new UnixTime(buffer.readInt());(26)
    }

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

  1 @Override
  2 public void messageReceived(ChannelHandlerContext ctx, MessageEvent e) {
        UnixTime m = (UnixTime) e.getMessage();
  4     System.out.println(m);
        e.getChannel().close();
  6 }

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

  1 @Override
  2 public void channelConnected(ChannelHandlerContext ctx, ChannelStateEvent e) {
        UnixTime time = new UnixTime(System.currentTimeMillis() / 1000);
  4     ChannelFuture f = e.getChannel().write(time);
        f.addListener(ChannelFutureListener.CLOSE);
  6 }

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

  1 package org.jboss.netty.example.time;
  2     
    import static org.jboss.netty.buffer.ChannelBuffers.*;
  4 
    public class TimeEncoder extends SimpleChannelHandler {
  6 
        public void writeRequested(ChannelHandlerContext ctx, MessageEvent(27) e) {
  8         UnixTime time = (UnixTime) e.getMessage();
            
 10         ChannelBuffer buf = buffer(4);
            buf.writeInt(time.getValue());
 12         
            Channels.write(ctx, e.getFuture(), buf);(28)
 14     }
    }

  1 import static org.jboss.netty.channel.Channels.*;
  2 ...
    ChannelPipeline pipeline = pipeline();
  4 write(ctx, e.getFuture(), buf);
    fireChannelDisconnected(ctx);

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

If you ran the TimeClient, you must have noticed that the application doesn't exit but just keep running doing nothing. Looking from the full stack trace, you will also find a couple I/O threads are running. To shut down the I/O threads and let the application exit gracefully, you need to release the resources allocated by ChannelFactory.

The shutdown process of a typical network application is composed of the following three steps:

To apply the three steps above to the TimeClient, TimeClient.main() could shut itself down gracefully by closing the only one client connection and releasing all resources used by ChannelFactory:

  1 package org.jboss.netty.example.time;
  2 
    public class TimeClient {
  4     public static void main(String[] args) throws Exception {
            ...
  6         ChannelFactory factory = ...;
            ClientBootstrap bootstrap = ...;
  8         ...
            ChannelFuture future(29) = bootstrap.connect(...);
 10         future.awaitUninterruptibly();(30)
            if (!future.isSuccess()) {
 12             future.getCause().printStackTrace();(31)
            }
 14         future.getChannel().getCloseFuture().awaitUninterruptibly();(32)
            factory.releaseExternalResources();(33)
 16     }
    }

Shutting down a client was pretty easy, but how about shutting down a server? You need to unbind from the port and close all open accepted connections. To do this, you need a data structure that keeps track of the list of active connections, and it's not a trivial task. Fortunately, there is a solution, ChannelGroup.

ChannelGroup is a special extension of Java collections API which represents a set of open Channels. If a Channel is added to a ChannelGroup and the added Channel is closed, the closed Channel is removed from its ChannelGroup automatically. You can also perform an operation on all Channels in the same group. For instance, you can close all Channels in a ChannelGroup when you shut down your server.

To keep track of open sockets, you need to modify the TimeServerHandler to add a new open Channel to the global ChannelGroup, TimeServer.allChannels:

  1 @Override
  2 public void channelOpen(ChannelHandlerContext ctx, ChannelStateEvent e) {
        TimeServer.allChannels.add(e.getChannel());(34)
  4 }

Now that the list of all active Channels are maintained automatically, shutting down a server is as easy as shutting down a client:

  1 package org.jboss.netty.example.time;
  2 
    public class TimeServer {
  4 
        static final ChannelGroup allChannels = new DefaultChannelGroup("time-server"(35));
  6 
        public static void main(String[] args) throws Exception {
  8         ...
            ChannelFactory factory = ...;
 10         ServerBootstrap bootstrap = ...;
            ...
 12         Channel channel(36) = bootstrap.bind(...);
            allChannels.add(channel);(37)
 14         waitForShutdownCommand();(38)
            ChannelGroupFuture future = allChannels.close();(39)
 16         future.awaitUninterruptibly();
            factory.releaseExternalResources();
 18     }
    }

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 org.jboss.netty.example package.

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

Netty uses its own buffer API instead of NIO ByteBuffer to represent a sequence of bytes. This approach has significant advantages over using ByteBuffer. Netty's new buffer type, ChannelBuffer has been designed from the ground up to address the problems of ByteBuffer and to meet the daily needs of network application developers. To list a few cool features:

For more information, please refer to the org.jboss.netty.buffer package description.

1.1. Combining and Slicing ChannelBuffers

When transfering data between communication layers, data often needs to be combined or sliced. For example, if a payload is split over multiple packages, it often needs to be be combined for decoding.

Traditionally, data from the multiple packages are combined by copying them into a new byte buffer.

Netty supports a zero-copy approach where by a ChannelBuffer "points" to the required buffers hence eliminating the need to perform a copy.

Traditional I/O APIs in Java provide different types and methods for different transport types. For example, java.net.Socket and java.net.DatagramSocket do not have any common super type and therefore they have very different ways to perform socket I/O.

This mismatch makes porting a network application from one transport to another tedious and difficult. The lack of portability between transports becomes a problem when you need to support additional transports, as this often entails rewriting the network layer of the application. Logically, many protocols can run on more than one transport such as TCP/IP, UDP/IP, SCTP, and serial port communication.

To make matters worse, Java's New I/O (NIO) API introduced incompatibilities with the old blocking I/O (OIO) API and will continue to do so in the next release, NIO.2 (AIO). Because all these APIs are different from each other in design and performance characteristics, you are often forced to determine which API your application will depend on before you even begin the implementation phase.

For instance, you might want to start with OIO because the number of clients you are going to serve will be very small and writing a socket server using OIO is much easier than using NIO. However, you are going to be in trouble when your business grows exponentially and your server needs to serve tens of thousands of clients simultaneously. You could start with NIO, but doing so may hinder rapid development by greatly increasing development time due to the complexity of the NIO Selector API.

Netty has a universal asynchronous I/O interface called a Channel, which abstracts away all operations required for point-to-point communication. That is, once you wrote your application on one Netty transport, your application can run on other Netty transports. Netty provides a number of essential transports via one universal API:

Also, you are even able to take advantage of new transports which aren't yet written (such as serial port communication transport), again by replacing just a couple lines of constructor calls. Moreover, you can write your own transport by extending the core API.

A well-defined and extensible event model is a must for an event-driven application. Netty has a well-defined event model focused on I/O. It also allows you to implement your own event type without breaking the existing code because each event type is distinguished from another by a strict type hierarchy. This is another differentiator against other frameworks. Many NIO frameworks have no or a very limited notion of an event model. If they offer extension at all, they often break the existing code when you try to add custom event types

A ChannelEvent is handled by a list of ChannelHandlers in a ChannelPipeline. The pipeline implements an advanced form of the Intercepting Filter pattern to give a user full control over how an event is handled and how the handlers in the pipeline interact with each other. For example, you can define what to do when data is read from a socket:

  1 public class MyReadHandler implements SimpleChannelHandler {
  2     public void messageReceived(ChannelHandlerContext ctx, MessageEvent evt) {
            Object message = evt.getMessage();
  4         // Do something with the received message.
            ...
  6 
            // And forward the event to the next handler.
  8         ctx.sendUpstream(evt);
        }
 10 }

You can also define what to do when a handler receives a write request:

  1 public class MyWriteHandler implements SimpleChannelHandler {
  2     public void writeRequested(ChannelHandlerContext ctx, MessageEvent evt) {
            Object message = evt.getMessage();
  4         // Do something with the message to be written.
            ...
  6 
            // And forward the event to the next handler.
  8         ctx.sendDownstream(evt);
        }
 10 }

For more information on the event model, please refer to the API documentation of ChannelEvent and ChannelPipeline.

On top of the core components mentioned above, that already enable the implementation of all types of network applications, Netty provides a set of advanced features to accelerate the page of development even more.

In this chapter, we reviewed the overall architecture of Netty from the feature standpoint. Netty has a simple, yet powerful architecture. It is composed of three components - buffer, channel, and event model - and all advanced features are built on top of the three core components. Once you understood how these three work together, it should not be difficult to understand the more advanced features which were covered briefly in this chapter.

You might still have unanswered questions about what the overall architecture looks like exactly and how each of the features work together. If so, it is a good idea to talk to us to improve this guide.