org.ldaptive.Connection Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ldaptive Show documentation
Java LDAP API
There is a newer version: 2.4.0
/* See LICENSE for licensing and NOTICE for copyright. */
package org.ldaptive;

import org.ldaptive.control.RequestControl;
import org.ldaptive.provider.ProviderConnection;

/**
 * Interface for ldap connection implementations.
 *
 * @author  Middleware Services
 */
public interface Connection extends AutoCloseable
{


  /**
   * Returns the connection config for this connection. The config may be read-only.
   *
   * @return  connection config
   */
  ConnectionConfig getConnectionConfig();


  /**
   * This will establish a connection to the LDAP. This connection should be closed using {@link #close()}.
   *
   * @return  response associated with the {@link ConnectionInitializer} or an empty response if no connection
   *          initializer was configured
   *
   * @throws  IllegalStateException  if the connection is already open
   * @throws  LdapException  if the LDAP cannot be reached
   */
  Response open()
    throws LdapException;


  /**
   * This will establish a connection to the LDAP using the supplied bind request. This connection should be closed
   * using {@link #close()}.
   *
   * @param  request  containing bind information
   *
   * @return  response associated with the bind operation
   *
   * @throws  IllegalStateException  if the connection is already open
   * @throws  LdapException  if the LDAP cannot be reached
   */
  Response open(BindRequest request)
    throws LdapException;


  /**
   * Returns whether {@link #open(BindRequest)} was successfully invoked on this connection and {@link #close()} has not
   * been invoked. This method does not indicate the viability of this connection for use.
   *
   * @return  whether this connection is open
   */
  boolean isOpen();


  /**
   * Returns the provider connection to invoke the provider specific implementation. Must be called after a successful
   * call to {@link #open()}.
   *
   * @return  provider connection
   */
  ProviderConnection getProviderConnection();


  /** This will close the connection to the LDAP. */
  void close();


  /**
   * This will close the connection to the LDAP using the supplied controls.
   *
   * @param  controls  request controls
   */
  void close(RequestControl[] controls);


  /**
   * This will close an existing connection to the LDAP and establish a new connection to the LDAP.
   *
   * @return  response associated with the {@link ConnectionInitializer} or an empty response if no connection
   *          initializer was configured
   *
   * @throws  LdapException  if the LDAP cannot be reached
   */
  Response reopen()
    throws LdapException;


  /**
   * This will close an existing connection to the LDAP and establish a new connection to the LDAP using the supplied
   * bind request.
   *
   * @param  request  containing bind information
   *
   * @return  response associated with the bind operation
   *
   * @throws  LdapException  if the LDAP cannot be reached
   */
  Response reopen(BindRequest request)
    throws LdapException;
}