ChannelPipelineCoverage annotates a handler type to tell if the handler instance of the annotated type can be shared by more than one Channel (and its associated ChannelPipeline). DiscardServerHandler does not manage any stateful information, and therefore it is annotated with the value "all".

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 add the DiscardServerHandler to the default ChannelPipeline. Whenever a new connection is accepted by the server, a new ChannelPipeline will be created for a newly accepted Channel and all the ChannelHandlers added here will be added to the new ChannelPipeline. It's just like a shallow-copy operation; all Channel and their ChannelPipelines will share the same DiscardServerHandler instance.

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

The ChannelPipelineCoverage value of an encoder is usually "all" because an encoder is stateless in most cases.

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.getChannel(), e.getFuture(), buf);
fireChannelDisconnected(ctx, e.getChannel());