org.jboss.netty.channel.socket.nio

## Class NioClientSocketChannelFactory

- java.lang.Object
- - org.jboss.netty.channel.socket.nio.NioClientSocketChannelFactory

All Implemented Interfaces:
  ChannelFactory, ClientSocketChannelFactory, ExternalResourceReleasable

    public class NioClientSocketChannelFactory
    extends Object
    implements ClientSocketChannelFactory

A `ClientSocketChannelFactory` which creates a client-side NIO-based `SocketChannel`. 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 are two types of threads in a `NioClientSocketChannelFactory`; one is boss thread and the other is worker thread.

#### Boss thread

One `NioClientSocketChannelFactory` has one boss thread. It makes a connection attempt on request. Once a connection attempt succeeds, the boss thread passes the connected `Channel` to one of the worker threads that the `NioClientSocketChannelFactory` manages.

#### Worker threads

One `NioClientSocketChannelFactory` can have one or more worker threads. A worker thread performs non-blocking read and write for one or more `Channel`s in a non-blocking mode.

### Life cycle of threads and graceful shutdown

All threads are acquired from the `Executor`s which were specified when a `NioClientSocketChannelFactory` was created. A boss thread is acquired from the `bossExecutor`, and worker threads are acquired from the `workerExecutor`. Therefore, you should make sure the specified `Executor`s are able to lend the sufficient number of threads. It is the best bet to specify a cached thread pool.

Both boss and 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 boss and 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.

### Constructor Summary

Constructors
Constructor and Description
`NioClientSocketChannelFactory()` Creates a new `NioClientSocketChannelFactory` which uses `Executors.newCachedThreadPool()` for the worker and boss executors.
`NioClientSocketChannelFactory(Executor bossExecutor, Executor workerExecutor)` Creates a new instance.
`NioClientSocketChannelFactory(Executor bossExecutor, Executor workerExecutor, int workerCount)` Creates a new instance.
`NioClientSocketChannelFactory(Executor bossExecutor, Executor workerExecutor, int bossCount, int workerCount)` Creates a new instance.
`NioClientSocketChannelFactory(Executor bossExecutor, int bossCount, WorkerPool<NioWorker> workerPool)`

### Method Summary

Methods
`SocketChannel` `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

#### NioClientSocketChannelFactory

    public NioClientSocketChannelFactory()

Creates a new `NioClientSocketChannelFactory` which uses `Executors.newCachedThreadPool()` for the worker and boss executors. See `NioClientSocketChannelFactory(Executor, Executor)`

#### NioClientSocketChannelFactory

    public NioClientSocketChannelFactory(Executor bossExecutor,
                                 Executor workerExecutor)

Creates a new instance. Calling this constructor is same with calling `NioClientSocketChannelFactory(Executor, Executor, int, int)` with 1 and (2 * the number of available processors in the machine) for `bossCount` and `workerCount` respectively. The number of available processors is obtained by `Runtime.availableProcessors()`.

Parameters:
  `bossExecutor` - the `Executor` which will execute the boss thread
  `workerExecutor` - the `Executor` which will execute the worker threads

#### NioClientSocketChannelFactory

    public NioClientSocketChannelFactory(Executor bossExecutor,
                                 Executor workerExecutor,
                                 int workerCount)

Creates a new instance. Calling this constructor is same with calling `NioClientSocketChannelFactory(Executor, Executor, int, int)` with 1 as `bossCount`.

Parameters:
  `bossExecutor` - the `Executor` which will execute the boss thread
  `workerExecutor` - the `Executor` which will execute the worker threads
  `workerCount` - the maximum number of I/O worker threads

#### NioClientSocketChannelFactory

    public NioClientSocketChannelFactory(Executor bossExecutor,
                                 Executor workerExecutor,
                                 int bossCount,
                                 int workerCount)

Creates a new instance.

Parameters:
  `bossExecutor` - the `Executor` which will execute the boss thread
  `workerExecutor` - the `Executor` which will execute the worker threads
  `bossCount` - the maximum number of boss threads
  `workerCount` - the maximum number of I/O worker threads

#### NioClientSocketChannelFactory

    public NioClientSocketChannelFactory(Executor bossExecutor,
                                 int bossCount,
                                 WorkerPool<NioWorker> workerPool)

### Method Detail

#### newChannel

    public SocketChannel 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 `ClientSocketChannelFactory`
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`