The Netty Project 3.2 User Guide

DiscardServerHandler extends SimpleChannelHandler, which is an implementation of ChannelHandler. SimpleChannelHandler provides various event handler methods that you can override. For now, it is just enough to extend SimpleChannelHandler rather than to implement the handler interfaces by yourself.

We override the messageReceived event handler method here. This method is called with a MessageEvent, which contains the received data, whenever new data is received from a client. In this example, we ignore the received data by doing nothing to implement the DISCARD protocol.

exceptionCaught event handler method is called with an ExceptionEvent when an exception was raised by Netty due to 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.

ChannelFactory is a factory which creates and manages Channels and its related resources. It processes all I/O requests and performs I/O to generate ChannelEvents. Netty provides various ChannelFactory implementations. We are implementing a server-side application in this example, and therefore NioServerSocketChannelFactory was used. Another thing to note is that it does not create I/O threads by itself. It is supposed to acquire threads from the thread pool you specified in the constructor, and it gives you more control over how threads should be managed in the environment where your application runs, such as an application server with a security manager.

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 configure the ChannelPipelineFactory. Whenever a new connection is accepted by the server, a new ChannelPipeline will be created by the specified ChannelPipelineFactory. The new pipeline contains the DiscardServerHandler. 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 note that the "child." prefix was added to all options. It means the options will be applied to the accepted Channels instead of the options of the ServerSocketChannel. You could do the following to set the options of the ServerSocketChannel:

bootstrap.setOption("reuseAddress", true);

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

It is safe to assume the message type in socket transports is always ChannelBuffer. ChannelBuffer is a fundamental data structure which stores a sequence of bytes in Netty. It's similar to NIO ByteBuffer, but it is easier to use and more flexible. For example, Netty allows you to create a composite ChannelBuffer which combines multiple ChannelBuffers reducing the number of unnecessary memory copy.

Although it resembles to NIO ByteBuffer a lot, it is highly recommended to refer to the API reference. Learning how to use ChannelBuffer correctly is a critical step in using Netty without difficulty.

A ChannelEvent object has a reference to its associated Channel. Here, the returned Channel represents the connection which received the MessageEvent. We can get the Channel and call the write method to write something back to the remote peer.

As explained, channelConnected method will be invoked when a connection is established. Let us write the 32-bit integer that represents the current time in seconds here.

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 ChannelBuffer whose capacity is 4 bytes. The ChannelBuffers helper class is used to allocate a new buffer. Besides the buffer method, ChannelBuffers provides a lot of useful methods related to the ChannelBuffer. For more information, please refer to the API reference.

On the other hand, it is a good idea to use static imports for ChannelBuffers:

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

As usual, we write the constructed message.

But wait, where's the flip? Didn't we used to call ByteBuffer.flip() before sending a message in NIO? ChannelBuffer does 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 ChannelBuffer 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 write 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.write(message);
ch.close();

Therefore, you need to call the close method after the ChannelFuture, which was returned by the write method, notifies you 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 the 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);

NioClientSocketChannelFactory, instead of NioServerSocketChannelFactory was used to create a client-side Channel.

ClientBootstrap is a client-side counterpart of ServerBootstrap.

Please note that there's no "child." prefix. A client-side SocketChannel does not have a parent.

We should call the connect method instead of the bind method.

FrameDecoder and ReplayingDecoder allow you to return an object of any type. If they were restricted to return only a ChannelBuffer, we would have to insert another ChannelHandler which transforms a ChannelBuffer into a UnixTime.

An encoder overrides the writeRequested method to intercept a write request. Please note that the MessageEvent parameter here is the same type which was specified in messageReceived but they are interpreted differently. A ChannelEvent can be either an upstream or downstream event depending on the direction where the event flows. For instance, a MessageEvent can be an upstream event when called for messageReceived or a downstream event when called for writeRequested. Please refer to the API reference to learn more about the difference between a upstream event and a downstream event.

Once done with transforming a POJO into a ChannelBuffer, you should forward the new buffer to the previous ChannelDownstreamHandler in the ChannelPipeline. Channels provides various helper methods which generates and sends a ChannelEvent. In this example, Channels.write(...) method creates a new MessageEvent and sends it to the previous ChannelDownstreamHandler in the ChannelPipeline.

On the other hand, it is a good idea to use static imports for Channels:

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

The connect method of ClientBootstrap returns a ChannelFuture which notifies when a connection attempt succeeds or fails. It also has a reference to the Channel which is associated with the connection attempt.

Wait for the returned ChannelFuture to determine if the connection attempt was successful or not.

If failed, we print the cause of the failure to know why it failed. the getCause() method of ChannelFuture will return the cause of the failure if the connection attempt was neither successful nor cancelled.

Now that the connection attempt is over, we need to wait until the connection is closed by waiting for the closeFuture of the Channel. Every Channel has its own closeFuture so that you are notified and can perform a certain action on closure.

Even if the connection attempt has failed the closeFuture will be notified because the Channel will be closed automatically when the connection attempt fails.

All connections have been closed at this point. The only task left is to release the resources being used by ChannelFactory. It is as simple as calling its releaseExternalResources() method. All resources including the NIO Selectors and thread pools will be shut down and terminated automatically.

Yes, ChannelGroup is thread-safe.

DefaultChannelGroup requires the name of the group as a constructor parameter. The group name is solely used to distinguish one group from others.

The bind method of ServerBootstrap returns a server side Channel which is bound to the specified local address. Calling the close() method of the returned Channel will make the Channel unbind from the bound local address.

Any type of Channels can be added to a ChannelGroup regardless if it is either server side, client-side, or accepted. Therefore, you can close the bound Channel along with the accepted Channels in one shot when the server shuts down.

waitForShutdownCommand() is an imaginary method that waits for the shutdown signal. You could wait for a message from a privileged client or the JVM shutdown hook.

You can perform the same operation on all channels in the same ChannelGroup. In this case, we close all channels, which means the bound server-side Channel will be unbound and all accepted connections will be closed asynchronously. To notify when all connections were closed successfully, it returns a ChannelGroupFuture which has a similar role with ChannelFuture.