com.nitido.nimx.services.dirpool.mozilla
Class DirPoolServiceImpl

java.lang.Object
  com.nitido.nimx.services.dirpool.mozilla.DirPoolServiceImpl

public class DirPoolServiceImpl
extends java.lang.Object

This class is the Directory Pool Service that utilize Mozilla's Netscape LDAP SDK to connect to the backend server. It is responsible for generate the com.nitido.directory.Directory object that uses the directory pool feature.

The detail of the configuration keys required is included in the description of the init() method of this class.

Field Summary

protected NiM	_confService
static java.lang.String	CONF_KEY_ACCEPTED_ERROR_CODES
static java.lang.String	CONF_KEY_AUTO_RESET_POOL
static java.lang.String	CONF_KEY_BATCH_SIZE
static java.lang.String	CONF_KEY_CHECK_ERROR_CODES
static java.lang.String	CONF_KEY_DEFAULT_MAX_POOL_SIZE
static java.lang.String	CONF_KEY_DEFAULT_MIN_POOL_SIZE
static java.lang.String	CONF_KEY_DEREF
static java.lang.String	CONF_KEY_ENABLE_POOL
static java.lang.String	CONF_KEY_MAX_BACKLOG
static java.lang.String	CONF_KEY_POSTFIX_AUTH_DN
static java.lang.String	CONF_KEY_POSTFIX_AUTH_PWD
static java.lang.String	CONF_KEY_POSTFIX_DEBUG
static java.lang.String	CONF_KEY_POSTFIX_MAX_POOL_SIZE
static java.lang.String	CONF_KEY_POSTFIX_MIN_POOL_SIZE
static java.lang.String	CONF_KEY_POSTFIX_THROTTLE
static java.lang.String	CONF_KEY_PREFIX_POOL_NAME
static java.lang.String	CONF_KEY_PREFIX_POOL_SETTING
static java.lang.String	CONF_KEY_REFERALS
static java.lang.String	CONF_KEY_REFERRALS_HOP_LIMIT
static java.lang.String	CONF_KEY_SERVER_TIME_LIMIT
static java.lang.String	CONF_KEY_SIZE_LIMIT
static java.lang.String	CONF_KEY_SOCKET_TIMEOUT
static java.lang.String	CONF_KEY_TIME_LIMIT
static int	DEFAULT_MAX_SIZE
static int	DEFAULT_MIN_SIZE
static int	DEREF_ALWAYS
static int	DEREF_FINDING
static int	DEREF_NEVER
static int	DEREF_SEARCHING
static int	LEN_CONF_KEY_PREFIX_POOL_NAME
static int	LEN_CONF_KEY_PREFIX_POOL_SETTING

Constructor Summary

DirPoolServiceImpl()

Method Summary

protected void	fetchPoolSettings(java.lang.String confKey, java.lang.String tempValue)
java.util.List<DirPoolStatus>	getAllDirPoolStatus()
protected java.lang.Boolean	getBooleanConfig(java.lang.String confKey, java.lang.Boolean defaultValue)
protected DirConnection	getConnection(java.lang.String poolName, java.lang.String dn, java.lang.String password)
protected DirConnection	getConnectionDirectly(java.lang.String poolName, java.lang.String dn, java.lang.String password)
protected DirConnection	getConnectionFromPool(java.lang.String poolName, java.lang.String dn, java.lang.String password)
Directory	getDirectory(java.lang.String poolName)
DirPoolStatus	getDirPoolStatus(java.lang.String poolName)
static DirPoolServiceImpl	getInstance()
protected int	getIntConfig(java.lang.String confKey, int defaultValue)
protected java.lang.Integer	getIntegerConfig(java.lang.String confKey, java.lang.Integer defaultValue)
protected long	getLongConfig(java.lang.String confKey, long defaultValue)
protected void	init(NiM confService) This method is called by the NiMKernel to initialize the DirPoolService.
protected DirPool	initPool(DirPoolSetting poolSetting)
protected void	internalResetPool(java.lang.String poolName, long timestamp)
protected boolean	isBadErrorCode(int inErrorCode)
protected void	releaseConnection(DirConnection dirCon)
protected void	releaseConnectionToPool(DirConnection dirCon, boolean isGoodConn)
void	resetAllDirPools()
void	resetDirPool(java.lang.String poolName) Reset the specified directory pool.
protected void	setConnectionOptions(netscape.ldap.LDAPConnection con)
protected void	terminateConnection(DirConnection dirCon)

Methods inherited from class java.lang.Object

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

Field Detail

DEREF_NEVER

public static final int DEREF_NEVER

See Also:

Constant Field Values

DEREF_SEARCHING

public static final int DEREF_SEARCHING

See Also:

Constant Field Values

DEREF_FINDING

public static final int DEREF_FINDING

See Also:

Constant Field Values

DEREF_ALWAYS

public static final int DEREF_ALWAYS

See Also:

Constant Field Values

CONF_KEY_DEREF

public static final java.lang.String CONF_KEY_DEREF

See Also:

Constant Field Values

CONF_KEY_ENABLE_POOL

public static final java.lang.String CONF_KEY_ENABLE_POOL

See Also:

Constant Field Values

CONF_KEY_SIZE_LIMIT

public static final java.lang.String CONF_KEY_SIZE_LIMIT

See Also:

Constant Field Values

CONF_KEY_TIME_LIMIT

public static final java.lang.String CONF_KEY_TIME_LIMIT

See Also:

Constant Field Values

CONF_KEY_SERVER_TIME_LIMIT

public static final java.lang.String CONF_KEY_SERVER_TIME_LIMIT

See Also:

Constant Field Values

CONF_KEY_SOCKET_TIMEOUT

public static final java.lang.String CONF_KEY_SOCKET_TIMEOUT

See Also:

Constant Field Values

CONF_KEY_REFERALS

public static final java.lang.String CONF_KEY_REFERALS

See Also:

Constant Field Values

CONF_KEY_REFERRALS_HOP_LIMIT

public static final java.lang.String CONF_KEY_REFERRALS_HOP_LIMIT

See Also:

Constant Field Values

CONF_KEY_BATCH_SIZE

public static final java.lang.String CONF_KEY_BATCH_SIZE

See Also:

Constant Field Values

CONF_KEY_MAX_BACKLOG

public static final java.lang.String CONF_KEY_MAX_BACKLOG

See Also:

Constant Field Values

CONF_KEY_DEFAULT_MIN_POOL_SIZE

public static final java.lang.String CONF_KEY_DEFAULT_MIN_POOL_SIZE

See Also:

Constant Field Values

CONF_KEY_DEFAULT_MAX_POOL_SIZE

public static final java.lang.String CONF_KEY_DEFAULT_MAX_POOL_SIZE

See Also:

Constant Field Values

CONF_KEY_AUTO_RESET_POOL

public static final java.lang.String CONF_KEY_AUTO_RESET_POOL

See Also:

Constant Field Values

CONF_KEY_PREFIX_POOL_NAME

public static final java.lang.String CONF_KEY_PREFIX_POOL_NAME

See Also:

Constant Field Values

LEN_CONF_KEY_PREFIX_POOL_NAME

public static final int LEN_CONF_KEY_PREFIX_POOL_NAME

CONF_KEY_PREFIX_POOL_SETTING

public static final java.lang.String CONF_KEY_PREFIX_POOL_SETTING

See Also:

Constant Field Values

LEN_CONF_KEY_PREFIX_POOL_SETTING

public static final int LEN_CONF_KEY_PREFIX_POOL_SETTING

CONF_KEY_ACCEPTED_ERROR_CODES

public static final java.lang.String CONF_KEY_ACCEPTED_ERROR_CODES

See Also:

Constant Field Values

CONF_KEY_CHECK_ERROR_CODES

public static final java.lang.String CONF_KEY_CHECK_ERROR_CODES

See Also:

Constant Field Values

DEFAULT_MIN_SIZE

public static final int DEFAULT_MIN_SIZE

See Also:

Constant Field Values

DEFAULT_MAX_SIZE

public static final int DEFAULT_MAX_SIZE

See Also:

Constant Field Values

CONF_KEY_POSTFIX_MIN_POOL_SIZE

public static final java.lang.String CONF_KEY_POSTFIX_MIN_POOL_SIZE

See Also:

Constant Field Values

CONF_KEY_POSTFIX_MAX_POOL_SIZE

public static final java.lang.String CONF_KEY_POSTFIX_MAX_POOL_SIZE

See Also:

Constant Field Values

CONF_KEY_POSTFIX_DEBUG

public static final java.lang.String CONF_KEY_POSTFIX_DEBUG

See Also:

Constant Field Values

CONF_KEY_POSTFIX_THROTTLE

public static final java.lang.String CONF_KEY_POSTFIX_THROTTLE

See Also:

Constant Field Values

CONF_KEY_POSTFIX_AUTH_DN

public static final java.lang.String CONF_KEY_POSTFIX_AUTH_DN

See Also:

Constant Field Values

CONF_KEY_POSTFIX_AUTH_PWD

public static final java.lang.String CONF_KEY_POSTFIX_AUTH_PWD

See Also:

Constant Field Values

_confService

protected NiM _confService

Constructor Detail

DirPoolServiceImpl

public DirPoolServiceImpl()

Method Detail

getInstance

public static DirPoolServiceImpl getInstance()
                                      throws InitializationFailedException

Throws:

InitializationFailedException

init

protected void init(NiM confService)
             throws InitializationFailedException

This method is called by the NiMKernel to initialize the DirPoolService.

Parameters:

confService - The ConfigurationService must provide all of the following settings:

• com.nitido.nimx.services.dirpool.mozilla.deref
  • Indicates the model of how LDAP entries are dereferenced.
  • The constant for the key is CONF_KEY_DEREF.
  • This is a required configuration. There is no default value.
  • The valid values is an integer between 0 and 3.
  • If the value is invalid, an InitializationFailedException will be thrown.
    • '0' = never dereference. The constant key is DEREF_NEVER. This is the value for most cases.
    • '1' = dereference when searching the entries beneath the starting point of the search. The constant key is DEREF_SEARCHING.
    • '2' = dereference when finding the starting point for the search (but not when searching under that starting entry). The constant key is DEREF_FINDING.
    • '3' = always dereference. The constant key is DEREF_ALWAYS.
• com.nitido.nimx.services.dirpool.mozilla.enable
  • Indicates whether to enable the connection pool.
  • The constant for the key is CONF_KEY_ENABLE_POOL.
  • This is an optional configuration. The default value is "true".
  • The valid values are either "true" or "false". Any invalid string will be treated as "true". The value is case insensitive. It also ignores the leading and ending spaces.
• com.nitido.nimx.services.dirpool.mozilla.sizelimit
  • Specifies the maximum number of search results to return.
  • The constant for the key is CONF_KEY_SIZE_LIMIT.
  • This is an optional value. The default value is 'null' (no limit).
  • The valid value is an integer. The unit is number of entries.
  • If the value is invalid, an InitializationFailedException will be thrown.
• com.nitido.nimx.services.dirpool.mozilla.timelimit
  • Specifies the maximum time to wait for an operation to complete. This is NOT the socket timeout. It is the time to wait for the server to return the result.
  • The constant for the key is CONF_KEY_TIME_LIMIT.
  • This is anoptional value. The default value is 'null' (no limit).
  • The valid value is an integer. The unit is milliseconds.
  • If the value is invalid, an InitializationFailedException will be thrown.
  • The "timelimit" configuration specifies when should the library abort an operation, while the "servertimelimit" specifies when should the server abort an operation. They are not related.
• com.nitido.nimx.services.dirpool.mozilla.servertimelimit
  • Specifies the maximum time the server will wait for before aborting an operation.
  • The constant for the key is CONF_KEY_SERVER_TIME_LIMIT.
  • This is an optional value. The default value is 'null' (no limit).
  • The valid value is an integer. The unit is milliseconds.
  • If the value is invalid, an InitializationFailedException will be thrown.
  • The "timelimit" configuration specifies when should the library abort an operation, while the "servertimelimit" specifies when should the server abort an operation. They are not related.
• com.nitido.nimx.services.dirpool.mozilla.sockettimeout
  • Specifies the socket connection timeout limit.
  • The constant for the key is CONF_KEY_SOCKET_TIMEOUT.
  • This is an optional configuration. The default value is 0 (no limit).
  • The valid value is an integer. The unit is milliseconds.
  • If the value is invalid, an InitializationFailedException will be thrown.
  • NOTE: in most scenarios, application deployer doesn't need to configure this parameters. It is usually controlled at the OS level already.
• com.nitido.nimx.services.dirpool.mozilla.referrals
  • Indicates whether LDAP referrals should be followed.
  • The constant for the key is CONF_KEY_REFERALS.
  • This is an optional value. The default value is "true".
  • The valid values are either "true" or "false". Any invalid string will be treated as "true". The value is case insensitive. It also ignores the leading and ending spaces.
• com.nitido.nimx.services.dirpool.mozilla.referralshoplimit
  • Specifies the maximum number of hops that the library will follow the referral.
  • The constant for the key is CONF_KEY_REFERRALS_HOP_LIMIT.
  • This is an optional value. The default value is 'null' (no limit).
  • The valid value is an integer. The unit is number of hops. 'null' or '0' means no limit.
  • If the value is invalid, an InitializationFailedException will be thrown.
• com.nitido.nimx.services.dirpool.mozilla.batchsize
  • Specifies the number of results to return in a batch.
  • This is NOT the "size limit". A search result can contain more than one batch. If you want to limit the number of entries returned by a search query, you should modify the configuration com.nitido.nimx.services.dirpool.mozilla.sizelimit.
  • The constant for the key is CONF_KEY_BATCH_SIZE.
  • This is an optional value. The default value is 'null' (no limit).
  • The valid value is an integer. The unit is number of hops. 'null' or '0' means no limit.
  • If the value is invalid, an InitializationFailedException will be thrown.
• com.nitido.nimx.services.dirpool.mozilla.maxbacklog
  • Specifies the maximum number of entries to be cached in the library.
  • This is an optimization configuration when the application has very limited memory. It is rarely used.
  • The constant for the key is CONF_KEY_MAX_BACKLOG.
  • This is an optional value. The default value is 'null' (no limit).
  • The valid value is an integer. The unit is number of hops. 'null' or '0' means no limit.
  • If the value is invalid, an InitializationFailedException will be thrown.
• com.nitido.nimx.services.dirpool.mozilla.default.minpoolsize
  • Specifies the default minimum size of the directory pool. This value will be used if a directory pool does not contain any configuration for its minimum pool size.
  • The minimum pool size is the number of directory connections the pool will maintain when there is no pending requests. This is a performance optimization configuration and need to be adjusted according to the overall system and network architecture.
  • The constant for the key is CONF_KEY_DEFAULT_MIN_POOL_SIZE.
  • This is an optional configuration. The default value is 0.
  • The valid value is an integer. The unit is the number of connection.
  • If the value is invalid, an InitializationFailedException will be thrown.
• com.nitido.nimx.services.dirpool.mozilla.default.maxpoolsize
  • Specifies the default maximum size of the directory pool. This value will be used if a directory pool does not contain any configuration for its maximum pool size.
  • The minimum pool size is the largest number of directory connections the pool will established. This is a performance optimization configuration and need to be adjusted according to the overall system and network architecture.
  • The constant for the key is CONF_KEY_DEFAULT_MAX_POOL_SIZE.
  • This is an optional configuration. The default value is 1.
  • The valid value is an integer. The unit is the number of connection.
  • If the value is invalid, an InitializationFailedException will be thrown.
• com.nitido.nimx.services.dirpool.mozilla.autoresetpool
  • Specifies the time period to wait before automatically reset the connection pool.
  • This configuration is introduced for system that has a load balancer for the LDAP servers, AND, the load balancer does not reset and rebalance the connection if one of the LDAP servers recovers from a failure. For such cases, the application will need to drop and reconnect all connections in the pool periodically.
  • The constant for the key is CONF_KEY_AUTO_RESET_POOL.
  • This is an optional configuration. The default value is 0 (no auto-reset).
  • The valid value is a long integer. The unit is milliseconds.
  • If the value is invalid, an InitializationFailedException will be thrown.
• com.nitido.nimx.services.dirpool.mozilla.poolname.poolname
  • Declares the pool name and the corresponding host and port.
  • The poolname is the string the application use when invoking the method getDirectory( String poolName ). It is a unique identifier of a specific connection pool used by the application.
  • The constant for the key prefix is CONF_KEY_PREFIX_POOL_NAME (which is "com.nitido.nimx.services.dirpool.mozilla.poolname."). The poolname is defined by the application developer and deployer.
  • A valid poolname is a string of regular alphanumeric characters. It should contain no spaces, comma, etc. It is case sensitive.
  • The value should be in the format of host:port. The host is the host name or IP of the LDAP server. The port is the port number of the LDAP server.
  • During initialization, this class will only perform limited check on the configuration, such as validating the strings. It will throw an InitializationFailedException if the check fails. However, it will not check if it can actually establish the connection to the backend LDAP server. It will try to connect only when the application requests a connection from the pool.
• com.nitido.nimx.services.dirpool.mozilla.poolsetting.poolname.minpoolsize
  • Specifies the minimum pool size for the specific directory pool with the name poolname.
  • This is an optional value. If a connection pool poolname has no minpoolsize setting, this class will use the value specified in com.nitido.nimx.services.dirpool.mozilla.default.minpoolsize
  • The valid value is an integer. The unit is the number of connection.
  • If the value is invalid, an InitializationFailedException will be thrown.
• com.nitido.nimx.services.dirpool.mozilla.poolsetting.poolname.maxpoolsize
  • Specifies the maximum pool size for the specific directory pool with the name poolname.
  • This is an optional value. If a connection pool poolname has no maxpoolsize setting, this class will use the value specified in com.nitido.nimx.services.dirpool.mozilla.default.maxpoolsize
  • The valid value is an integer. The unit is the number of connection.
  • If the value is invalid, an InitializationFailedException will be thrown.
• com.nitido.nimx.services.dirpool.mozilla.poolsetting.poolname.debug
  • Indicates whether the Mozilla LDAP SDK library's debugging is enabled for the pool with the name poolname.
  • This is an optional value. If a connection pool poolname has no ".debug" setting, the Mozilla LDAP SDK will disable the debugging (i.e. treat it as if "false").
  • The valid value is a string of "true" or "false", case insensitive. A "true" value means debugging is enabled.
  • If the value is invalid, an InitializationFailedException will be thrown.
• com.nitido.nimx.services.dirpool.mozilla.poolsetting.poolname.auth.dn
  • The default authentication DN of the pool with the name poolname.
  • This is an optional value. If a connection pool poolname has no ".auth.dn" setting, the Mozilla LDAP SDK should not attempt to do any binding when the connection is obtained from or released back to the pool. If it is specified, the SDK will re-bind to the default authentication DN if the connection was not binded or binded as somebody else.
  • The valid value is a string of valid DN. If the value is a string of all spaces, it will be treated as empty string. (i.e. anonymous login to LDAP).
• com.nitido.nimx.services.dirpool.mozilla.poolsetting.poolname.auth.pwd
  • The default authentication password of the pool with the name poolname.
  • This configuration is required if the configuration "com.nitido.nimx.services.dirpool.mozilla.poolsetting.poolname.auth.dn" is specified. Otherwise, it is ignored.
  • If a connection pool poolname has no ".auth.dn" setting, the Mozilla LDAP SDK should not attempt to do any binding when the connection is obtained from or released back to the pool. If it is specified, the SDK will re-bind to the default authentication DN if the connection was not binded or binded as somebody else.
  • The valid value is a string of valid password.
  • If the value is missing while the ".auth.dn" is specified, an InitializationFailedException will be thrown.

Throws:

InitializationFailedException

isBadErrorCode

protected boolean isBadErrorCode(int inErrorCode)

resetDirPool

public void resetDirPool(java.lang.String poolName)
                  throws DirectoryException

Reset the specified directory pool. This method will reinitializes the specified connection pool. Future requests for connection will be obtained from the new pool instead. However, any connections that have already been allocated from the pool will NOT be closed. They will be retired only after the application has release them back to this service.

Throws:

DirectoryException

resetAllDirPools

public void resetAllDirPools()
                      throws DirectoryException

Throws:

DirectoryException

getDirectory

public Directory getDirectory(java.lang.String poolName)
                       throws DirectoryException

Throws:

DirectoryException

getConnection

protected DirConnection getConnection(java.lang.String poolName,
                                      java.lang.String dn,
                                      java.lang.String password)
                               throws DirectoryException,
                                      netscape.ldap.LDAPException

Throws:

DirectoryException

netscape.ldap.LDAPException

releaseConnection

protected void releaseConnection(DirConnection dirCon)
                          throws DirectoryException,
                                 netscape.ldap.LDAPException

Throws:

DirectoryException

netscape.ldap.LDAPException

terminateConnection

protected void terminateConnection(DirConnection dirCon)
                            throws DirectoryException,
                                   netscape.ldap.LDAPException

Throws:

DirectoryException

netscape.ldap.LDAPException

getConnectionFromPool

protected DirConnection getConnectionFromPool(java.lang.String poolName,
                                              java.lang.String dn,
                                              java.lang.String password)
                                       throws DirectoryException,
                                              netscape.ldap.LDAPException

Throws:

DirectoryException

netscape.ldap.LDAPException

getConnectionDirectly

protected DirConnection getConnectionDirectly(java.lang.String poolName,
                                              java.lang.String dn,
                                              java.lang.String password)
                                       throws DirectoryException,
                                              netscape.ldap.LDAPException

Throws:

DirectoryException

netscape.ldap.LDAPException

releaseConnectionToPool

protected void releaseConnectionToPool(DirConnection dirCon,
                                       boolean isGoodConn)
                                throws DirectoryException,
                                       netscape.ldap.LDAPException

Throws:

DirectoryException

netscape.ldap.LDAPException

setConnectionOptions

protected void setConnectionOptions(netscape.ldap.LDAPConnection con)
                             throws netscape.ldap.LDAPException

Throws:

netscape.ldap.LDAPException

getBooleanConfig

protected java.lang.Boolean getBooleanConfig(java.lang.String confKey,
                                             java.lang.Boolean defaultValue)
                                      throws InitializationFailedException

Throws:

InitializationFailedException

getIntegerConfig

protected java.lang.Integer getIntegerConfig(java.lang.String confKey,
                                             java.lang.Integer defaultValue)
                                      throws InitializationFailedException

Throws:

InitializationFailedException

getLongConfig

protected long getLongConfig(java.lang.String confKey,
                             long defaultValue)
                      throws InitializationFailedException

Throws:

InitializationFailedException

getIntConfig

protected int getIntConfig(java.lang.String confKey,
                           int defaultValue)
                    throws InitializationFailedException

Throws:

InitializationFailedException

fetchPoolSettings

protected void fetchPoolSettings(java.lang.String confKey,
                                 java.lang.String tempValue)
                          throws InitializationFailedException

Throws:

InitializationFailedException

initPool

protected DirPool initPool(DirPoolSetting poolSetting)
                    throws DirectoryException

Throws:

DirectoryException

internalResetPool

protected void internalResetPool(java.lang.String poolName,
                                 long timestamp)
                          throws DirectoryException

Parameters:

poolName -

timestamp - If the timestamp is 0, that means we just reset the pool, period. Otherwise, we will check if the current pool's timestamp matches the specified one. No reset will occur if the current pool is not the specified one.

Throws:

DirectoryException

getAllDirPoolStatus

public java.util.List<DirPoolStatus> getAllDirPoolStatus()

getDirPoolStatus

public DirPoolStatus getDirPoolStatus(java.lang.String poolName)