org.apache.mina.core.polling

## Class AbstractPollingIoConnector<T extends AbstractIoSession,H>

- java.lang.Object
- - org.apache.mina.core.service.AbstractIoService
  - - org.apache.mina.core.service.AbstractIoConnector
    - - org.apache.mina.core.polling.AbstractPollingIoConnector<T,H>

- All Implemented Interfaces:
    IoConnector, IoService
  Direct Known Subclasses:
    AprSocketConnector, NioDatagramConnector, NioSocketConnector

      public abstract class AbstractPollingIoConnector<T extends AbstractIoSession,H>
      extends AbstractIoConnector

  A base class for implementing client transport using a polling strategy. The underlying sockets will be checked in an active loop and woke up when an socket needed to be processed. This class handle the logic behind binding, connecting and disposing the client sockets. A `Executor` will be used for running client connection, and an `AbstractPollingIoProcessor` will be used for processing connected client I/O operations like reading, writing and closing. All the low level methods for binding, connecting, closing need to be provided by the subclassing implementation.
  Author:
    Apache MINA Project
  See Also:
    `for a example of implementation`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `AbstractPollingIoConnector.ConnectionRequest`

    - ### Nested classes/interfaces inherited from class org.apache.mina.core.service.AbstractIoService

      `AbstractIoService.ServiceOperationFuture`

  - ### Field Summary

    - ### Fields inherited from class org.apache.mina.core.service.AbstractIoService

      `disposalLock`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractPollingIoConnector(IoSessionConfig sessionConfig, Class<? extends IoProcessor<T>> processorClass)` Constructor for `AbstractPollingIoConnector`.
    `protected` | `AbstractPollingIoConnector(IoSessionConfig sessionConfig, Class<? extends IoProcessor<T>> processorClass, int processorCount)` Constructor for `AbstractPollingIoConnector`.
    `protected` | `AbstractPollingIoConnector(IoSessionConfig sessionConfig, Executor executor, IoProcessor<T> processor)` Constructor for `AbstractPollingIoConnector`.
    `protected` | `AbstractPollingIoConnector(IoSessionConfig sessionConfig, IoProcessor<T> processor)` Constructor for `AbstractPollingIoConnector`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract Iterator<H>` | `allHandles()` `Iterator` for all the client sockets polled for connection.
    `protected abstract void` | `close(H handle)` Close a client socket.
    `protected abstract boolean` | `connect(H handle, SocketAddress remoteAddress)` Connect a newly created client socket handle to a remote `SocketAddress`.
    `protected ConnectFuture` | `connect0(SocketAddress remoteAddress, SocketAddress localAddress, IoSessionInitializer<? extends ConnectFuture> sessionInitializer)` Implement this method to perform the actual connect operation.
    `protected abstract void` | `destroy()` Destroy the polling system, will be called when this `IoConnector` implementation will be disposed.
    `protected void` | `dispose0()` Implement this method to release any acquired resources.
    `protected abstract boolean` | `finishConnect(H handle)` Finish the connection process of a client socket after it was marked as ready to process by the `select(int)` call.
    `protected abstract AbstractPollingIoConnector.ConnectionRequest` | `getConnectionRequest(H handle)` get the `AbstractPollingIoConnector.ConnectionRequest` for a given client socket handle
    `protected abstract void` | `init()` Initialize the polling system, will be called at construction time.
    `protected abstract H` | `newHandle(SocketAddress localAddress)` Create a new client socket handle from a local `SocketAddress`
    `protected abstract T` | `newSession(IoProcessor<T> processor, H handle)` Create a new `IoSession` from a connected socket client handle.
    `protected abstract void` | `register(H handle, AbstractPollingIoConnector.ConnectionRequest request)` Register a new client socket for connection, add it to connection polling
    `protected abstract int` | `select(int timeout)` Check for connected sockets, interrupt when at least a connection is processed (connected or failed to connect).
    `protected abstract Iterator<H>` | `selectedHandles()` `Iterator` for the set of client sockets found connected or failed to connect during the last `#select()` call.
    `protected abstract void` | `wakeup()` Interrupt the `#select()` method.

    - ### Methods inherited from class org.apache.mina.core.service.AbstractIoConnector

      `connect, connect, connect, connect, connect, connect, finishSessionInitialization0, getConnectTimeout, getConnectTimeoutCheckInterval, getConnectTimeoutMillis, getDefaultRemoteAddress, setConnectTimeout, setConnectTimeoutCheckInterval, setConnectTimeoutMillis, setDefaultRemoteAddress, toString`

    - ### Methods inherited from class org.apache.mina.core.service.AbstractIoService

      `addListener, broadcast, dispose, dispose, executeWorker, executeWorker, getActivationTime, getFilterChain, getFilterChainBuilder, getHandler, getListeners, getManagedSessionCount, getManagedSessions, getScheduledWriteBytes, getScheduledWriteMessages, getSessionConfig, getSessionDataStructureFactory, getStatistics, initSession, isActive, isDisposed, isDisposing, removeListener, setFilterChainBuilder, setHandler, setSessionDataStructureFactory`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface org.apache.mina.core.service.IoService

      `addListener, broadcast, dispose, dispose, getActivationTime, getFilterChain, getFilterChainBuilder, getHandler, getManagedSessionCount, getManagedSessions, getScheduledWriteBytes, getScheduledWriteMessages, getSessionConfig, getSessionDataStructureFactory, getStatistics, getTransportMetadata, isActive, isDisposed, isDisposing, removeListener, setFilterChainBuilder, setHandler, setSessionDataStructureFactory`

- - ### Constructor Detail

    - #### AbstractPollingIoConnector

          protected AbstractPollingIoConnector(IoSessionConfig sessionConfig,
                                    Class<? extends IoProcessor<T>> processorClass)

      Constructor for `AbstractPollingIoConnector`. You need to provide a default session configuration, a class of `IoProcessor` which will be instantiated in a `SimpleIoProcessorPool` for better scaling in multiprocessor systems. The default pool size will be used.
      Parameters:
        `sessionConfig` - the default configuration for the managed `IoSession`
        `processorClass` - a `Class` of `IoProcessor` for the associated `IoSession` type.
      See Also:
        `SimpleIoProcessorPool`

    - #### AbstractPollingIoConnector

          protected AbstractPollingIoConnector(IoSessionConfig sessionConfig,
                                    Class<? extends IoProcessor<T>> processorClass,
                                    int processorCount)

      Constructor for `AbstractPollingIoConnector`. You need to provide a default session configuration, a class of `IoProcessor` which will be instantiated in a `SimpleIoProcessorPool` for using multiple thread for better scaling in multiprocessor systems.
      Parameters:
        `sessionConfig` - the default configuration for the managed `IoSession`
        `processorClass` - a `Class` of `IoProcessor` for the associated `IoSession` type.
        `processorCount` - the amount of processor to instantiate for the pool
      See Also:
        `SimpleIoProcessorPool`

    - #### AbstractPollingIoConnector

          protected AbstractPollingIoConnector(IoSessionConfig sessionConfig,
                                    IoProcessor<T> processor)

      Constructor for `AbstractPollingIoConnector`. You need to provide a default session configuration, a default `Executor` will be created using `Executors.newCachedThreadPool()`. `AbstractIoService#AbstractIoService(IoSessionConfig, Executor)`
      Parameters:
        `sessionConfig` - the default configuration for the managed `IoSession`
        `processor` - the `IoProcessor` for processing the `IoSession` of this transport, triggering events to the bound `IoHandler` and processing the chains of `IoFilter`

    - #### AbstractPollingIoConnector

          protected AbstractPollingIoConnector(IoSessionConfig sessionConfig,
                                    Executor executor,
                                    IoProcessor<T> processor)

      Constructor for `AbstractPollingIoConnector`. You need to provide a default session configuration and an `Executor` for handling I/O events. If null `Executor` is provided, a default one will be created using `Executors.newCachedThreadPool()`. `AbstractIoService#AbstractIoService(IoSessionConfig, Executor)`
      Parameters:
        `sessionConfig` - the default configuration for the managed `IoSession`
        `executor` - the `Executor` used for handling asynchronous execution of I/O events. Can be `null`.
        `processor` - the `IoProcessor` for processing the `IoSession` of this transport, triggering events to the bound `IoHandler` and processing the chains of `IoFilter`

  - ### Method Detail

    - #### init

          protected abstract void init()
                                throws Exception

      Initialize the polling system, will be called at construction time.
      Throws:
        `Exception` - any exception thrown by the underlying system calls

    - #### destroy

          protected abstract void destroy()
                                   throws Exception

      Destroy the polling system, will be called when this `IoConnector` implementation will be disposed.
      Throws:
        `Exception` - any exception thrown by the underlying systems calls

    - #### newHandle

          protected abstract H newHandle(SocketAddress localAddress)
                                  throws Exception

      Create a new client socket handle from a local `SocketAddress`
      Parameters:
        `localAddress` - the socket address for binding the new client socket
      Returns:
        a new client socket handle
      Throws:
        `Exception` - any exception thrown by the underlying systems calls

    - #### connect

          protected abstract boolean connect(H handle,
                        SocketAddress remoteAddress)
                                      throws Exception

      Connect a newly created client socket handle to a remote `SocketAddress`. This operation is non-blocking, so at end of the call the socket can be still in connection process.
      Parameters:
        `handle` - the client socket handle
        `remoteAddress` - the remote address where to connect
      Returns:
        `true` if a connection was established, `false` if this client socket is in non-blocking mode and the connection operation is in progress
      Throws:
        `Exception`

    - #### finishConnect

          protected abstract boolean finishConnect(H handle)
                                            throws Exception

      Finish the connection process of a client socket after it was marked as ready to process by the `select(int)` call. The socket will be connected or reported as connection failed.
      Parameters:
        `handle` - the client socket handle to finsh to connect
      Returns:
        true if the socket is connected
      Throws:
        `Exception` - any exception thrown by the underlying systems calls

    - #### newSession

          protected abstract T newSession(IoProcessor<T> processor,
                     H handle)
                                                             throws Exception

      Create a new `IoSession` from a connected socket client handle. Will assign the created `IoSession` to the given `IoProcessor` for managing future I/O events.
      Parameters:
        `processor` - the processor in charge of this session
        `handle` - the newly connected client socket handle
      Returns:
        a new `IoSession`
      Throws:
        `Exception` - any exception thrown by the underlying systems calls

    - #### close

          protected abstract void close(H handle)
                                 throws Exception

      Close a client socket.
      Parameters:
        `handle` - the client socket
      Throws:
        `Exception` - any exception thrown by the underlying systems calls

    - #### wakeup

          protected abstract void wakeup()

      Interrupt the `#select()` method. Used when the poll set need to be modified.

    - #### select

          protected abstract int select(int timeout)
                                 throws Exception

      Check for connected sockets, interrupt when at least a connection is processed (connected or failed to connect). All the client socket descriptors processed need to be returned by `selectedHandles()`
      Returns:
        The number of socket having received some data
      Throws:
        `Exception` - any exception thrown by the underlying systems calls

    - #### selectedHandles

          protected abstract Iterator<H> selectedHandles()

      `Iterator` for the set of client sockets found connected or failed to connect during the last `#select()` call.
      Returns:
        the list of client socket handles to process

    - #### allHandles

          protected abstract Iterator<H> allHandles()

      `Iterator` for all the client sockets polled for connection.
      Returns:
        the list of client sockets currently polled for connection

    - #### register

          protected abstract void register(H handle,
                      AbstractPollingIoConnector.ConnectionRequest request)
                                    throws Exception

      Register a new client socket for connection, add it to connection polling
      Parameters:
        `handle` - client socket handle
        `request` - the associated `AbstractPollingIoConnector.ConnectionRequest`
      Throws:
        `Exception` - any exception thrown by the underlying systems calls

    - #### getConnectionRequest

          protected abstract AbstractPollingIoConnector.ConnectionRequest getConnectionRequest(H handle)

      get the `AbstractPollingIoConnector.ConnectionRequest` for a given client socket handle
      Parameters:
        `handle` - the socket client handle
      Returns:
        the connection request if the socket is connecting otherwise `null`

    - #### dispose0

          protected final void dispose0()
                                 throws Exception

      Implement this method to release any acquired resources. This method is invoked only once by `AbstractIoService.dispose()`.
      Specified by:
        `dispose0` in class `AbstractIoService`
      Throws:
        `Exception`

    - #### connect0

          protected final ConnectFuture connect0(SocketAddress remoteAddress,
                               SocketAddress localAddress,
                               IoSessionInitializer<? extends ConnectFuture> sessionInitializer)

      Implement this method to perform the actual connect operation.
      Specified by:
        `connect0` in class `AbstractIoConnector`
        `localAddress` - `null` if no local address is specified

Copyright © 2004-2012 Apache MINA Project. All Rights Reserved.