|
You configure connection pooling by using a number of system properties at program startup time. Note that these are system properties, not environment properties and that they affect all connection pooling requests.
Here is an example of a command line that sets the maximum pool size to 20, the preferred pool size to 10, and the idle timeout to a minute for pooled connections.
# java -Dcom.sun.jndi.ldap.connect.pool.maxsize=20 \
-Dcom.sun.jndi.ldap.connect.pool.prefsize=10 \
-Dcom.sun.jndi.ldap.connect.pool.timeout=60000 \
UsePool
The following table lists the system properties for configuring connection pooling. They are described in more detail in the rest of this section.
| System Property Name | Description | Default |
|---|---|---|
| com.sun.jndi.ldap.connect.pool.authentication | A list of space-separated authentication types of connections that may be pooled. Valid types are "none", "simple", and "DIGEST-MD5". | "none simple" |
| com.sun.jndi.ldap.connect.pool.debug | A string that indicates the level of debug output to produce. Valid values are "fine" (trace connection creation and removal) and "all" (all debugging information). | |
| com.sun.jndi.ldap.connect.pool.initsize | The string representation of an integer that represents the number of connections per connection identity to create when initially creating a connection for the identity. | 1 |
| com.sun.jndi.ldap.connect.pool.maxsize | The string representation of an integer that represents the maximum number of connections per connection identity that can be maintained concurrently. | no maximum size |
| com.sun.jndi.ldap.connect.pool.prefsize | The string representation of an integer that represents the preferred number of connections per connection identity that should be maintained concurrently. | no preferred size |
| com.sun.jndi.ldap.connect.pool.protocol | A list of space-separated protocol types of connections that may be pooled. Valid types are "plain" and "ssl". | "plain" |
| com.sun.jndi.ldap.connect.pool.timeout | The string representation of an integer that represents the number of milliseconds that an idle connection may remain in the pool without being closed and removed from the pool. | no timeout |
There are a couple of environment properties that automatically disqualify a Context instance from using a pooled connection. A Context instance cannot use a pooled connection if it has its "java.naming.ldap.factory.socket" property set to a custom socket factory class, or its "java.naming.security.sasl.callback" property set to a custom callback handler class, or its "com.sun.jndi.ldap.trace.ber" property set to enable protocol tracing.
A connection identity is the set of the parameters required to create a possibly authenticated LDAP connection. Its composition depends on the authentication type of the request, as shown in the following table.
| Authentication Type | Connection Identity Contents |
|---|---|
| none |
|
| simple |
|
| DIGEST-MD5 |
|
The initial pool size is the number of connections per connection identity that the LDAP service provider creates when first creating the pool (which corresponds to when the application first requests a pooled connection for that connection identity). Authentication of each connection in the pool is performed on demand, as the connection gets used. By default, the initial pool size is 1 and can be changed by using the system property "com.sun.jndi.ldap.connect.pool.initsize". It is typically used at application start-up time to prime the pool with a certain number of connections to a server.
The maximum pool size is the maximum number of connections per connection identity that can be maintained concurrently by the LDAP service provider. Both in-use and idle connections contribute to this number. When the pool size reaches this number, no new connection for the corresponding connection identity may be created until a connection in the pool has been removed (i.e., the physical connection is closed). When the pool size reaches the maximum and all of the connections in the pool are in use, the application's request for a connection from that pool is blocked until a connection in the pool either becomes idle or is removed. A maximum pool size of 0 means that there is no maximum size: A request for a pooled connection will use an existing pooled idle connection or a newly created pooled connection.
The preferred pool size is the preferred number of connections per connection identity that the LDAP service provider should maintain. Both in-use and idle connections contribute to this number. When an application requests the use of a pooled connection and the pool size is less than the preferred size, the LDAP provider will create and use a new pooled connection regardless of whether an idle connection is available. When an application is finished with a pooled connection (by invoking Context.close() on all contexts that share the connection) and the pool size is greater than the preferred size, the LDAP provider will close and remove the pooled connection from the pool. A preferred pool size of 0 means that there is no preferred size: A request for a pooled connection will result in a newly created connection only if no idle ones are available.
Note that the maximum pool size overrides both the initial and preferred pool sizes. For example, setting the preferred pool size greater than the maximum pool size is effectively setting it to the maximum pool size.
|
