content/api/user-guide/2.1-connection-disconnection.mdtext

Title: 2.1 - Connection and disconnection
NavPrev: 2-basic-ldap-api-usage.html
NavPrevText: 2 - Basic LDAP API usage
NavUp: 2-basic-ldap-api-usage.html
NavUpText: 2 - Basic LDAP API usage
NavNext: 2.2-binding-unbinding.html
NavNextText: 2.2 - Binding and unbinding
Notice: Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at
    .
    http://www.apache.org/licenses/LICENSE-2.0
    .
    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

# 2.1 - Connection and disconnection

The **LDAP** is a protocol requires users to be connected, and likely identified (authenticated), before sending requests to the server. This connection can potentially be maintained forever. What makes the **LDAP** protocol different from, say, the **HTTP** protocol is that the connections are issued explicitly. Here we'll see how it's done.

## Opening a connection

We can open a secure or a standard connection. 

### Standard connection

We can first establish a standard connection, where the data is sent and received in clear text (encoded in ASN.1 BER, but not encrypted). This example shows how it's done:

    :::Java
    LdapConnection connection = new LdapNetworkConnection( "localhost", 389 );

Here we created an unsafe connection locally using the 389 port. Which is quite simple to do but not safe because data is not encrypted.

### Secure connection

Although the **LDAPS** (**LDAP** over **SSL**) is now considered as deprecated, many people still use it. The big advantage of not using **LDAPS** is that you don't need two different listening ports (one for **LDAP** -389- and another one for **LDAPS** -636- ).

The only difference with the previous example is that we tell the connection to use **SSL**, by passing **_true_** as a third parameter (incidentally, passing **_false_** sets an unsafe connection).

Here is an example

    :::Java
    LdapConnection connection = new LdapNetworkConnection( "localhost", 636, true );

## Maintaining the connection opened

We keep the connection open for a limited period of time, defaulting to 30 seconds. This might be not long enough, so one can change this delay by calling the _setTimeOut()_ method :

    :::Java
    LdapConnection connection = new LdapNetworkConnection( "localhost", 389 );
    connection.setTimeOut( 0 );
    ...
    connection.close();

>**Note:** Setting a value equal or below 0 will keep the connection open forever (assuming the connection is not explicitly closed by the client).

## Closing the connection

Once the connection is no longer needed (remember that holding a connection keeps the session open on the server and a socket is held open between the client and the server), then you must close it. This is done by calling the _close()_ method :

    :::Java
    LdapConnection connection = new LdapNetworkConnection( "localhost", 389 );
    ...
    connection.close();

## Using a pool of connections

Creating a connection is expensive. If that connection will be reused, or if your application needs multiple connections, you may want to consider using a _connection pool_.

This process is slightly more complex given that there are many parameters that can be used to tune the pool.  Here is an example:

    :::Java
    LdapConnectionConfig config = new LdapConnectionConfig();
    config.setLdapHost( hostname );
    config.setLdapPort( port );
    config.setName( adminDn );
    config.setCredentials( adminPassword );

    DefaultLdapConnectionFactory factory = new DefaultLdapConnectionFactory( config );
    factory.setTimeOut( connectionTimeout );

    // optional, values below are defaults
    GenericObjectPool.Config poolConfig = new GenericObjectPool.Config();
    poolConfig.lifo = true;
    poolConfig.maxActive = 8;
    poolConfig.maxIdle = 8;
    poolConfig.maxWait = -1L;
    poolConfig.minEvictableIdleTimeMillis = 1000L * 60L * 30L;
    poolConfig.minIdle = 0;
    poolConfig.numTestsPerEvictionRun = 3;
    poolConfig.softMinEvictableIdleTimeMillis = -1L;
    poolConfig.testOnBorrow = false;
    poolConfig.testOnReturn = false;
    poolConfig.testWhileIdle = false;
    poolConfig.timeBetweenEvictionRunsMillis = -1L;
    poolConfig.whenExhaustedAction = GenericObjectPool.WHEN_EXHAUSTED_BLOCK;

    LdapConnectionPool pool = new LdapConnectionPool(
        new DefaultPoolableLdapConnectionFactory( factory ), poolConfig ) );

This creates a pool of connections that are pre-authenticated.  If you don't setName and setCredentials, then the pool will contain unauthenticated connections.

The DefaultPoolableLdapConnectionFactory is sufficient for many cases.  However some operations result in modifications to the connection itself.  For example, when the pool is created, a bind operation will occur with the credentials supplied as part of the config.  If you borrow a connection and perform a bind yourself, that would result in the connection being re-bound as a different user.  The next time that connection gets borrowed, things are likely to break.  If you perform any operation that results in a modification of the connection, you should instead use ValidatingPoolableLdapConnectionFactory:

    :::Java
    ...
    LdapConnectionPool pool = new LdapConnectionPool(
        new ValidatingPoolableLdapConnectionFactory( factory ), poolConfig ) );
    ...

A connection pool using this factory will unbind and rebind any connection that was modified while it was borrowed (_see the javadoc for more detail_).  This will be slower due to the additional operations, but not significantly.