org.jboss.netty.channel.socket.nio

Class NioDatagramChannelFactory

java.lang.Object

org.jboss.netty.channel.socket.nio.NioDatagramChannelFactory

All Implemented Interfaces:

ChannelFactory, DatagramChannelFactory, ExternalResourceReleasable

public class NioDatagramChannelFactory
extends Object
implements DatagramChannelFactory

A DatagramChannelFactory that creates a NIO-based connectionless DatagramChannel. It utilizes the non-blocking I/O mode which was introduced with NIO to serve many number of concurrent connections efficiently.

How threads work

There is only one thread type in a NioDatagramChannelFactory; worker threads.

Worker threads

One NioDatagramChannelFactory can have one or more worker threads. A worker thread performs non-blocking read and write for one or more DatagramChannels in a non-blocking mode.

Life cycle of threads and graceful shutdown

All worker threads are acquired from the Executor which was specified when a NioDatagramChannelFactory was created. Therefore, you should make sure the specified Executor is able to lend the sufficient number of threads. It is the best bet to specify a cached thread pool.

All worker threads are acquired lazily, and then released when there's nothing left to process. All the related resources such as Selector are also released when the worker threads are released. Therefore, to shut down a service gracefully, you should do the following:

1. close all channels created by the factory usually using ChannelGroup.close(), and
2. call releaseExternalResources().

Please make sure not to shut down the executor until all channels are closed. Otherwise, you will end up with a RejectedExecutionException and the related resources might not be released properly.

Limitation

Multicast is not supported. Please use OioDatagramChannelFactory instead.

Constructor Summary

Constructors

Constructor and Description
NioDatagramChannelFactory() Create a new NioDatagramChannelFactory with a Executors.newCachedThreadPool() and without preferred InternetProtocolFamily.
NioDatagramChannelFactory(Executor workerExecutor) Creates a new instance.
NioDatagramChannelFactory(Executor workerExecutor, int workerCount) Creates a new instance.
NioDatagramChannelFactory(Executor workerExecutor, InternetProtocolFamily family) Creates a new instance.
NioDatagramChannelFactory(Executor workerExecutor, int workerCount, InternetProtocolFamily family) Creates a new instance.
NioDatagramChannelFactory(InternetProtocolFamily family) Create a new NioDatagramChannelFactory with a Executors.newCachedThreadPool().
NioDatagramChannelFactory(WorkerPool<NioDatagramWorker> workerPool) Creates a new instance.
NioDatagramChannelFactory(WorkerPool<NioDatagramWorker> workerPool, InternetProtocolFamily family) Creates a new instance.

Method Summary

Methods

Modifier and Type	Method and Description
DatagramChannel	newChannel(ChannelPipeline pipeline) Creates and opens a new Channel and attaches the specified ChannelPipeline to the new Channel.
void	releaseExternalResources() Releases the external resources that this factory depends on to function.
void	shutdown() Shudown the ChannelFactory and all the resource it created internal.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NioDatagramChannelFactory

public NioDatagramChannelFactory()

Create a new NioDatagramChannelFactory with a Executors.newCachedThreadPool() and without preferred InternetProtocolFamily. Please note that the InternetProtocolFamily of the channel will be platform (and possibly configuration) dependent and therefore unspecified. Use NioDatagramChannelFactory(InternetProtocolFamily) if unsure. See NioDatagramChannelFactory(Executor)

NioDatagramChannelFactory

public NioDatagramChannelFactory(InternetProtocolFamily family)

Create a new NioDatagramChannelFactory with a Executors.newCachedThreadPool(). See NioDatagramChannelFactory(Executor)

NioDatagramChannelFactory

public NioDatagramChannelFactory(Executor workerExecutor)

Creates a new instance. Calling this constructor is same with calling NioDatagramChannelFactory(Executor, int) with 2 * the number of available processors in the machine. The number of available processors is obtained by Runtime.availableProcessors().

Please note that the InternetProtocolFamily of the channel will be platform (and possibly configuration) dependent and therefore unspecified. Use NioDatagramChannelFactory(Executor, InternetProtocolFamily) if unsure.

Parameters:

workerExecutor - the Executor which will execute the I/O worker threads

NioDatagramChannelFactory

public NioDatagramChannelFactory(Executor workerExecutor,
                         int workerCount)

Creates a new instance.

Please note that the InternetProtocolFamily of the channel will be platform (and possibly configuration) dependent and therefore unspecified. Use NioDatagramChannelFactory(Executor, int, InternetProtocolFamily) if unsure.

Parameters:

workerExecutor - the Executor which will execute the I/O worker threads

workerCount - the maximum number of I/O worker threads

NioDatagramChannelFactory

public NioDatagramChannelFactory(WorkerPool<NioDatagramWorker> workerPool)

Creates a new instance.

Please note that the InternetProtocolFamily of the channel will be platform (and possibly configuration) dependent and therefore unspecified. Use NioDatagramChannelFactory(WorkerPool, InternetProtocolFamily) if unsure.

Parameters:

workerPool - the WorkerPool which will be used to obtain the NioDatagramWorker that execute the I/O worker threads

NioDatagramChannelFactory

public NioDatagramChannelFactory(Executor workerExecutor,
                         InternetProtocolFamily family)

Creates a new instance. Calling this constructor is same with calling NioDatagramChannelFactory(Executor, int) with 2 * the number of available processors in the machine. The number of available processors is obtained by Runtime.availableProcessors().

Parameters:

workerExecutor - the Executor which will execute the I/O worker threads

family - the InternetProtocolFamily to use. This should be used for UDP multicast. Be aware that this option is only considered when running on java7+

NioDatagramChannelFactory

public NioDatagramChannelFactory(Executor workerExecutor,
                         int workerCount,
                         InternetProtocolFamily family)

Creates a new instance.

Parameters:

workerExecutor - the Executor which will execute the I/O worker threads

workerCount - the maximum number of I/O worker threads

family - the InternetProtocolFamily to use. This should be used for UDP multicast. Be aware that this option is only considered when running on java7+

NioDatagramChannelFactory

public NioDatagramChannelFactory(WorkerPool<NioDatagramWorker> workerPool,
                         InternetProtocolFamily family)

Creates a new instance.

Parameters:

workerPool - the WorkerPool which will be used to obtain the Worker that execute the I/O worker threads

family - the InternetProtocolFamily to use. This should be used for UDP multicast. Be aware that this option is only considered when running on java7+

Method Detail

newChannel

public DatagramChannel newChannel(ChannelPipeline pipeline)

Description copied from interface: ChannelFactory

Creates and opens a new Channel and attaches the specified ChannelPipeline to the new Channel.

Specified by:

newChannel in interface ChannelFactory

Specified by:

newChannel in interface DatagramChannelFactory

Parameters:

pipeline - the ChannelPipeline which is going to be attached to the new Channel

Returns:

the newly open channel

shutdown

public void shutdown()

Description copied from interface: ChannelFactory

Shudown the ChannelFactory and all the resource it created internal.

Specified by:

shutdown in interface ChannelFactory

releaseExternalResources

public void releaseExternalResources()

Description copied from interface: ChannelFactory

Releases the external resources that this factory depends on to function. An external resource is a resource that this factory didn't create by itself. For example, Executors that you specified in the factory constructor are external resources. You can call this method to release all external resources conveniently when the resources are not used by this factory or any other part of your application. An unexpected behavior will be resulted in if the resources are released when there's an open channel which is managed by this factory. This will also call ChannelFactory.shutdown() before do any action

Specified by:

releaseExternalResources in interface ChannelFactory

Specified by:

releaseExternalResources in interface ExternalResourceReleasable