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 `DatagramChannel`s 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.

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

    - #### 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, `Executor`s 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.
      Specified by:
        `releaseExternalResources` in interface `ChannelFactory`
      Specified by:
        `releaseExternalResources` in interface `ExternalResourceReleasable`

Copyright © 2008-2012 The Netty Project. All Rights Reserved.