SockIOPool (Memcached-Java-Client 3.0.2 API)

java.lang.Object
- com.whalin.MemCached.SockIOPool

public class SockIOPool
extends Object

This class is a connection pool for maintaning a pool of persistent connections
to memcached servers. The pool must be initialized prior to use. This should typically be early on
in the lifecycle of the JVM instance.

An example of initializing using defaults:

 
 static {
        String[] serverlist = { "cache0.server.com:12345", "cache1.server.com:12345" };
        SockIOPool pool = SockIOPool.getInstance();
        pool.setServers(serverlist);
        pool.initialize();
 }

An example of initializing using defaults and providing weights for servers:

 static {
        String[] serverlist = { "cache0.server.com:12345", "cache1.server.com:12345" };
        Integer[] weights = { new Integer(5), new Integer(2) };
 
        SockIOPool pool = SockIOPool.getInstance();
        pool.setServers(serverlist);
        pool.setWeights(weights);
        pool.initialize();
 }

An example of initializing overriding defaults:

 static {
        String[] serverlist = { "cache0.server.com:12345", "cache1.server.com:12345" };
        Integer[] weights = { new Integer(5), new Integer(2) };
        int initialConnections = 10;
        int minSpareConnections = 5;
        int maxSpareConnections = 50;
        long maxIdleTime = 1000 * 60 * 30; // 30 minutes
        long maxBusyTime = 1000 * 60 * 5; // 5 minutes
        long maintThreadSleep = 1000 * 5; // 5 seconds
        int socketTimeOut = 1000 * 3; // 3 seconds to block on reads
        int socketConnectTO = 1000 * 3; // 3 seconds to block on initial
                                                                        // connections. If 0, then will use blocking
                                                                        // connect (default)
        boolean failover = false; // turn off auto-failover in event of server down
        boolean nagleAlg = false; // turn off Nagle's algorithm on all sockets in
                                                                // pool
        boolean aliveCheck = false; // disable health check of socket on checkout
        SockIOPool pool = SockIOPool.getInstance();
        pool.setServers(serverlist);
        pool.setWeights(weights);
        pool.setInitConn(initialConnections);
        pool.setMinConn(minSpareConnections);
        pool.setMaxConn(maxSpareConnections);
        pool.setMaxIdle(maxIdleTime);
        pool.setMaxBusyTime(maxBusyTime);
        pool.setMaintSleep(maintThreadSleep);
        pool.setSocketTO(socketTimeOut);
        pool.setNagle(nagleAlg);
        pool.setHashingAlg(SockIOPool.NEW_COMPAT_HASH);
        pool.setAliveCheck(true);
        pool.initialize();
 }

The easiest manner in which to initialize the pool is to set the servers and rely on defaults as in the first example.
After pool is initialized, a client will request a SockIO object by calling getSock with the cache key
The client must always close the SockIO object when finished, which will return the connection back to the pool.

An example of retrieving a SockIO object:

        SockIOPool.SockIO sock = SockIOPool.getInstance().getSock( key );
        try {
                sock.write( "version\r\n" );    
                sock.flush();   
                System.out.println( "Version: " + sock.readLine() );    
        }
        catch (IOException ioe) { System.out.println( "io exception thrown" ) };        
        sock.close();

Version:: 1.5
Author:: greg whalin

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`SockIOPool.MaintThread` Class which extends thread and handles maintenance of the pool.
`static class`	`SockIOPool.SockIO` MemCached client for Java, utility class for Socket IO.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CONSISTENT_HASH`
`static long`	`MAX_RETRY_DELAY`
`static int`	`NATIVE_HASH`
`static int`	`NEW_COMPAT_HASH`
`static int`	`OLD_COMPAT_HASH`

Constructor Summary

Constructors
Modifier Constructor and Description

protected SockIOPool()

Constructors
Modifier	Constructor and Description
`protected`	`SockIOPool()`

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`addSocketToPool(Map<String,Map<SockIOPool.SockIO,Long>> pool, String host, SockIOPool.SockIO socket)` Adds a socket to a given pool for the given host.
`protected void`	`clearHostFromPool(Map<String,Map<SockIOPool.SockIO,Long>> pool, String host)` Closes and removes all sockets from specified pool for host.
`protected SockIOPool.SockIO`	`createSocket(String host)` Creates a new SockIO obj for the given server.
`boolean`	`getAliveCheck()` Returns the current status of the aliveCheck flag.
`int`	`getBufferSize()`
`SockIOPool.SockIO`	`getConnection(String host)` Returns a SockIO object from the pool for the passed in host.
`boolean`	`getFailback()` Returns current state of failover flag.
`boolean`	`getFailover()` Returns current state of failover flag.
`int`	`getHashingAlg()` Returns current status of customHash flag
`String`	`getHost(String key)`
`String`	`getHost(String key, Integer hashcode)` Gets the host that a particular key / hashcode resides on.
`int`	`getInitConn()` Returns the current setting for the initial number of connections per server in the available pool.
`static SockIOPool`	`getInstance()` Single argument version of factory used for back compat.
`static SockIOPool`	`getInstance(boolean isTcp)`
`static SockIOPool`	`getInstance(String poolName)` Factory to create/retrieve new pools given a unique poolName.
`static SockIOPool`	`getInstance(String poolName, boolean isTcp)`
`long`	`getMaintSleep()` Returns the current maint thread sleep time.
`long`	`getMaxBusy()` Returns the current max busy setting.
`int`	`getMaxConn()` Returns the maximum number of spare connections allowed in available pool.
`int`	`getMaxIdle()` Returns the current max idle setting.
`int`	`getMinConn()` Returns the minimum number of spare connections in available pool.
`boolean`	`getNagle()` Returns current status of nagle flag
`String[]`	`getServers()` Returns the current list of all cache servers.
`SockIOPool.SockIO`	`getSock(String key)` Returns appropriate SockIO object given string cache key.
`SockIOPool.SockIO`	`getSock(String key, Integer hashCode)` Returns appropriate SockIO object given string cache key and optional hashcode.
`int`	`getSocketConnectTO()` Returns the socket timeout for connect.
`int`	`getSocketTO()` Returns the socket timeout for reads.
`Integer[]`	`getWeights()` Returns the current list of weights.
`void`	`initialize()` Initializes the pool.
`boolean`	`isInitialized()` Returns state of pool.
`protected void`	`removeSocketFromPool(Map<String,Map<SockIOPool.SockIO,Long>> pool, String host, SockIOPool.SockIO socket)` Removes a socket from specified pool for host.
`protected void`	`selfMaint()` Runs self maintenance on all internal pools.
`void`	`setAliveCheck(boolean aliveCheck)` Sets the aliveCheck flag for the pool.
`void`	`setBufferSize(int bufferSize)` In memcached 1.4+, user can specify memory size for each memcached item. You can specify it with parameter "-I" in the server side. While in our client side, we make the max memcached item size with the default value 1Mb. In this scenario, you can extend the size as what you want, please be sure you have enough memory in the client side, since we are using direct buffer to hold the memory, they will not be free until shutdown.
`void`	`setFailback(boolean failback)` Sets the failback flag for the pool.
`void`	`setFailover(boolean failover)` Sets the failover flag for the pool.
`void`	`setHashingAlg(int alg)` Sets the hashing algorithm we will use.
`void`	`setInitConn(int initConn)` Sets the initial number of connections per server in the available pool.
`void`	`setMaintSleep(long maintSleep)` Set the sleep time between runs of the pool maintenance thread.
`void`	`setMaxBusyTime(long maxBusyTime)` Sets the max busy time for threads in the busy pool.
`void`	`setMaxConn(int maxConn)` Sets the maximum number of spare connections allowed in our available pool.
`void`	`setMaxIdle(int maxIdle)` Sets the max idle time for threads in the available pool.
`void`	`setMinConn(int minConn)` Sets the minimum number of spare connections to maintain in our available pool.
`void`	`setNagle(boolean nagle)` Sets the Nagle alg flag for the pool.
`void`	`setServers(String[] servers)` Sets the list of all cache servers.
`void`	`setSocketConnectTO(int socketConnectTO)` Sets the socket timeout for connect.
`void`	`setSocketTO(int socketTO)` Sets the socket timeout for reads.
`void`	`setWeights(Integer[] weights)` Sets the list of weights to apply to the server list.
`void`	`shutDown()` Shuts down the pool.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - NATIVE_HASH
```
public static final int NATIVE_HASH
```
    See Also:
    Constant Field Values
  - OLD_COMPAT_HASH
```
public static final int OLD_COMPAT_HASH
```
    See Also:
    Constant Field Values
  - NEW_COMPAT_HASH
```
public static final int NEW_COMPAT_HASH
```
    See Also:
    Constant Field Values
  - CONSISTENT_HASH
```
public static final int CONSISTENT_HASH
```
    See Also:
    Constant Field Values
  - MAX_RETRY_DELAY
```
public static final long MAX_RETRY_DELAY
```
    See Also:
    Constant Field Values
- Constructor Detail
  - SockIOPool
```
protected SockIOPool()
```
- Method Detail
  - getInstance
```
public static SockIOPool getInstance(String poolName)
```
    Factory to create/retrieve new pools given a unique poolName.
    
    Parameters:
    poolName - unique name of the pool
    
    Returns:
    instance of SockIOPool
  - getInstance
```
public static SockIOPool getInstance(boolean isTcp)
```
  - getInstance
```
public static SockIOPool getInstance(String poolName,
                     boolean isTcp)
```
  - getInstance
```
public static SockIOPool getInstance()
```
    Single argument version of factory used for back compat. Simply creates a pool named "default".
    
    Returns:
    instance of SockIOPool
  - setServers
```
public void setServers(String[] servers)
```
    Sets the list of all cache servers.
    
    Parameters:
    servers - String array of servers [host:port]
  - getServers
```
public String[] getServers()
```
    Returns the current list of all cache servers.
    
    Returns:
    String array of servers [host:port]
  - setWeights
```
public void setWeights(Integer[] weights)
```
    Sets the list of weights to apply to the server list. This is an int array with each element corresponding to an element
    in the same position in the server String array.
    
    Parameters:
    weights - Integer array of weights
  - getWeights
```
public Integer[] getWeights()
```
    Returns the current list of weights.
    
    Returns:
    int array of weights
  - setInitConn
```
public void setInitConn(int initConn)
```
    Sets the initial number of connections per server in the available pool.
    
    Parameters:
    initConn - int number of connections
  - getInitConn
```
public int getInitConn()
```
    Returns the current setting for the initial number of connections per server in the available pool.
    
    Returns:
    number of connections
  - setMinConn
```
public void setMinConn(int minConn)
```
    Sets the minimum number of spare connections to maintain in our available pool.
    
    Parameters:
    minConn - number of connections
  - getMinConn
```
public int getMinConn()
```
    Returns the minimum number of spare connections in available pool.
    
    Returns:
    number of connections
  - setMaxConn
```
public void setMaxConn(int maxConn)
```
    Sets the maximum number of spare connections allowed in our available pool.
    
    Parameters:
    maxConn - number of connections
  - getMaxConn
```
public int getMaxConn()
```
    Returns the maximum number of spare connections allowed in available pool.
    
    Returns:
    number of connections
  - setMaxBusyTime
```
public void setMaxBusyTime(long maxBusyTime)
```
    Sets the max busy time for threads in the busy pool.
    
    Parameters:
    maxBusyTime - idle time in ms
  - getMaxBusy
```
public long getMaxBusy()
```
    Returns the current max busy setting.
    
    Returns:
    max busy setting in ms
  - setSocketTO
```
public void setSocketTO(int socketTO)
```
    Sets the socket timeout for reads.
    
    Parameters:
    socketTO - timeout in ms
  - getSocketTO
```
public int getSocketTO()
```
    Returns the socket timeout for reads.
    
    Returns:
    timeout in ms
  - setSocketConnectTO
```
public void setSocketConnectTO(int socketConnectTO)
```
    Sets the socket timeout for connect.
    
    Parameters:
    socketConnectTO - timeout in ms
  - getSocketConnectTO
```
public int getSocketConnectTO()
```
    Returns the socket timeout for connect.
    
    Returns:
    timeout in ms
  - setMaxIdle
```
public void setMaxIdle(int maxIdle)
```
    Sets the max idle time for threads in the available pool.
    
    Parameters:
    maxIdle - idle time in ms
  - getMaxIdle
```
public int getMaxIdle()
```
    Returns the current max idle setting.
    
    Returns:
    max idle setting in ms
  - setMaintSleep
```
public void setMaintSleep(long maintSleep)
```
    Set the sleep time between runs of the pool maintenance thread. If set to 0, then the maint thread will not be started.
    
    Parameters:
    maintSleep - sleep time in ms
  - getMaintSleep
```
public long getMaintSleep()
```
    Returns the current maint thread sleep time.
    
    Returns:
    sleep time in ms
  - setFailover
```
public void setFailover(boolean failover)
```
    Sets the failover flag for the pool. If this flag is set to true, and a socket fails to connect,
    the pool will attempt to return a socket from another server
    if one exists. If set to false, then getting a socket
    will return null if it fails to connect to the requested server.
    
    Parameters:
    failover - true/false
  - getFailover
```
public boolean getFailover()
```
    Returns current state of failover flag.
    
    Returns:
    true/false
  - setFailback
```
public void setFailback(boolean failback)
```
    Sets the failback flag for the pool. If this is true and we have marked a host as dead, will try to bring it back. If it is false, we will never try to resurrect a dead host.
    
    Parameters:
    failback - true/false
  - getFailback
```
public boolean getFailback()
```
    Returns current state of failover flag.
    
    Returns:
    true/false
  - setAliveCheck
```
public void setAliveCheck(boolean aliveCheck)
```
    Sets the aliveCheck flag for the pool. When true, this will attempt to talk to the server on every connection checkout to make sure the connection is still valid. This adds extra network chatter and thus is defaulted off. May be useful if you want to ensure you do not have any problems talking to the server on a dead connection.
    
    Parameters:
    aliveCheck - true/false
  - getAliveCheck
```
public boolean getAliveCheck()
```
    Returns the current status of the aliveCheck flag.
    
    Returns:
    true / false
  - setNagle
```
public void setNagle(boolean nagle)
```
    Sets the Nagle alg flag for the pool. If false, will turn off Nagle's algorithm on all sockets created.
    
    Parameters:
    nagle - true/false
  - getNagle
```
public boolean getNagle()
```
    Returns current status of nagle flag
    
    Returns:
    true/false
  - setHashingAlg
```
public void setHashingAlg(int alg)
```
    Sets the hashing algorithm we will use. The types are as follows. SockIOPool.NATIVE_HASH (0) - native String.hashCode() - fast (cached) but not compatible with other clients SockIOPool.OLD_COMPAT_HASH (1) - original compatibility hashing alg (works with other clients) SockIOPool.NEW_COMPAT_HASH (2) - new CRC32 based compatibility hashing algorithm (fast and works with other clients)
    
    Parameters:
    alg - int value representing hashing algorithm
  - getHashingAlg
```
public int getHashingAlg()
```
    Returns current status of customHash flag
    
    Returns:
    true/false
  - initialize
```
public void initialize()
```
    Initializes the pool.
  - isInitialized
```
public boolean isInitialized()
```
    Returns state of pool.
    
    Returns:
    true if initialized.
  - getHost
```
public String getHost(String key)
```
    Parameters:
    key -
    
    Returns:
  - getHost
```
public String getHost(String key,
             Integer hashcode)
```
    Gets the host that a particular key / hashcode resides on.
    
    Parameters:
    key -
    hashcode -
    
    Returns:
  - shutDown
```
public void shutDown()
```
    Shuts down the pool. Cleanly closes all sockets.
    Stops the maint thread.
    Nulls out all internal maps
  - setBufferSize
```
public void setBufferSize(int bufferSize)
```
    In memcached 1.4+, user can specify memory size for each memcached item.
    You can specify it with parameter "-I" in the server side.
    While in our client side, we make the max memcached item size with the default value 1Mb.
    In this scenario, you can extend the size as what you want, please be sure you have enough memory in the client side, since we are using direct buffer to hold the memory, they will not be free until shutdown.
    
    Parameters:
    bufferSize - specified buffer size.
  - getBufferSize
```
public int getBufferSize()
```
  - getSock
```
public SockIOPool.SockIO getSock(String key)
```
    Returns appropriate SockIO object given string cache key.
    
    Parameters:
    key - hashcode for cache key
    
    Returns:
    SockIO obj connected to server
  - getSock
```
public SockIOPool.SockIO getSock(String key,
                        Integer hashCode)
```
    Returns appropriate SockIO object given string cache key and optional hashcode. Trys to get SockIO from pool. Fails over to additional pools in event of server failure.
    
    Parameters:
    key - hashcode for cache key
    hashCode - if not null, then the int hashcode to use
    
    Returns:
    SockIO obj connected to server
  - getConnection
```
public SockIOPool.SockIO getConnection(String host)
```
    Returns a SockIO object from the pool for the passed in host. Meant to be called from a more intelligent method
    which handles choosing appropriate server
    and failover.
    
    Parameters:
    host - host from which to retrieve object
    
    Returns:
    SockIO object or null if fail to retrieve one
  - createSocket
```
protected SockIOPool.SockIO createSocket(String host)
```
    Creates a new SockIO obj for the given server. If server fails to connect, then return null and do not try
    again until a duration has passed. This duration will grow
    by doubling after each failed attempt to connect.
    
    Parameters:
    host - host:port to connect to
    
    Returns:
    SockIO obj or null if failed to create
  - selfMaint
```
protected void selfMaint()
```
    Runs self maintenance on all internal pools. This is typically called by the maintenance thread to manage pool size.
  - addSocketToPool
```
protected void addSocketToPool(Map<String,Map<SockIOPool.SockIO,Long>> pool,
                   String host,
                   SockIOPool.SockIO socket)
```
    Adds a socket to a given pool for the given host. THIS METHOD IS NOT THREADSAFE, SO BE CAREFUL WHEN USING! Internal utility method.
    
    Parameters:
    pool - pool to add to
    host - host this socket is connected to
    socket - socket to add
  - removeSocketFromPool
```
protected void removeSocketFromPool(Map<String,Map<SockIOPool.SockIO,Long>> pool,
                        String host,
                        SockIOPool.SockIO socket)
```
    Removes a socket from specified pool for host. THIS METHOD IS NOT THREADSAFE, SO BE CAREFUL WHEN USING! Internal utility method.
    
    Parameters:
    pool - pool to remove from
    host - host pool
    socket - socket to remove
  - clearHostFromPool
```
protected void clearHostFromPool(Map<String,Map<SockIOPool.SockIO,Long>> pool,
                     String host)
```
    Closes and removes all sockets from specified pool for host. THIS METHOD IS NOT THREADSAFE, SO BE CAREFUL WHEN USING! Internal utility method.
    
    Parameters:
    pool - pool to clear
    host - host to clear

Class SockIOPool

An example of initializing using defaults:

An example of initializing using defaults and providing weights for servers:

An example of initializing overriding defaults:

An example of retrieving a SockIO object:

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NATIVE_HASH

OLD_COMPAT_HASH

NEW_COMPAT_HASH

CONSISTENT_HASH

MAX_RETRY_DELAY

Constructor Detail

SockIOPool

Method Detail

getInstance

getInstance

getInstance

getInstance

setServers

getServers

setWeights

getWeights

setInitConn

getInitConn

setMinConn

getMinConn

setMaxConn

getMaxConn

setMaxBusyTime

getMaxBusy

setSocketTO

getSocketTO

setSocketConnectTO

getSocketConnectTO

setMaxIdle

getMaxIdle

setMaintSleep

getMaintSleep

setFailover

getFailover

setFailback

getFailback

setAliveCheck

getAliveCheck

setNagle

getNagle

setHashingAlg

getHashingAlg

initialize

isInitialized

getHost

getHost

shutDown

setBufferSize

getBufferSize

getSock

getSock

getConnection

createSocket

selfMaint

addSocketToPool

removeSocketFromPool

clearHostFromPool