org.jboss.netty.channel.socket.oio

## Class OioClientSocketChannelFactory

- java.lang.Object
- - org.jboss.netty.channel.socket.oio.OioClientSocketChannelFactory

All Implemented Interfaces:
  ChannelFactory, ClientSocketChannelFactory, ExternalResourceReleasable

    public class OioClientSocketChannelFactory
    extends Object
    implements ClientSocketChannelFactory

A `ClientSocketChannelFactory` which creates a client-side blocking I/O based `SocketChannel`. It utilizes the good old blocking I/O API which is known to yield better throughput and latency when there are relatively small number of connections to serve.

### How threads work

There is only one type of threads in `OioClientSocketChannelFactory`; worker threads.

#### Worker threads

Each connected `Channel` has a dedicated worker thread, just like a traditional blocking I/O thread model.

### Life cycle of threads and graceful shutdown

Worker threads are acquired from the `Executor` which was specified when a `OioClientSocketChannelFactory` was created (i.e. `workerExecutor`.) Therefore, you should make sure the specified `Executor` is able to lend the sufficient number of threads.

Worker threads are acquired lazily, and then released when there's nothing left to process. All the related resources 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

A `SocketChannel` created by this factory does not support asynchronous operations. Any I/O requests such as `"connect"` and `"write"` will be performed in a blocking manner.

### Constructor Summary

Constructors
Constructor and Description
`OioClientSocketChannelFactory()` Creates a new instance with a `Executors.newCachedThreadPool()` as worker executor.
`OioClientSocketChannelFactory(Executor workerExecutor)` Creates a new instance.

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

#### OioClientSocketChannelFactory

    public OioClientSocketChannelFactory()

Creates a new instance with a `Executors.newCachedThreadPool()` as worker executor. See `OioClientSocketChannelFactory(Executor)`

#### OioClientSocketChannelFactory

    public OioClientSocketChannelFactory(Executor workerExecutor)

Creates a new instance.

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

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