mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git

Matthew Swift
25.33.2012 263d085885df024dca9250cc03c807912b0a7662
opendj3/opendj-ldap-sdk/src/main/java/org/forgerock/opendj/ldap/LDAPOptions.java
@@ -6,17 +6,16 @@
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at
 * trunk/opendj3/legal-notices/CDDLv1_0.txt
 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
 * or http://forgerock.org/license/CDDLv1.0.html.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * trunk/opendj3/legal-notices/CDDLv1_0.txt.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 * file and include the License file at legal-notices/CDDLv1_0.txt.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
@@ -28,8 +27,6 @@
package org.forgerock.opendj.ldap;
import java.util.LinkedList;
import java.util.List;
import java.util.concurrent.TimeUnit;
@@ -40,317 +37,266 @@
import com.forgerock.opendj.util.Validator;
/**
 * Common options for LDAP client connections.
 */
public final class LDAPOptions
{
  private SSLContext sslContext;
  private boolean useStartTLS;
  private long timeoutInMillis;
  private DecodeOptions decodeOptions;
  private List<String> enabledCipherSuites = new LinkedList<String>();
  private List<String> enabledProtocols = new LinkedList<String>();
  private TCPNIOTransport transport;
public final class LDAPOptions {
    private SSLContext sslContext;
    private boolean useStartTLS;
    private long timeoutInMillis;
    private DecodeOptions decodeOptions;
    private List<String> enabledCipherSuites = new LinkedList<String>();
    private List<String> enabledProtocols = new LinkedList<String>();
    private TCPNIOTransport transport;
  /**
   * Creates a new set of connection options with default settings. SSL will not
   * be enabled, and a default set of decode options will be used.
   */
  public LDAPOptions()
  {
    this.sslContext = null;
    this.timeoutInMillis = 0;
    this.useStartTLS = false;
    this.decodeOptions = new DecodeOptions();
    this.transport = null;
  }
  /**
   * Creates a new set of connection options having the same initial set of
   * options as the provided set of connection options.
   *
   * @param options
   *          The set of connection options to be copied.
   */
  public LDAPOptions(final LDAPOptions options)
  {
    this.sslContext = options.sslContext;
    this.timeoutInMillis = options.timeoutInMillis;
    this.useStartTLS = options.useStartTLS;
    this.decodeOptions = new DecodeOptions(options.decodeOptions);
    this.enabledCipherSuites.addAll(options.getEnabledCipherSuites());
    this.enabledProtocols.addAll(options.getEnabledProtocols());
    this.transport = options.transport;
  }
  /**
   * Returns the decoding options which will be used to control how requests and
   * responses are decoded.
   *
   * @return The decoding options which will be used to control how requests and
   *         responses are decoded (never {@code null}).
   */
  public final DecodeOptions getDecodeOptions()
  {
    return decodeOptions;
  }
  /**
   * Returns the SSL context which will be used when initiating connections with
   * the Directory Server.
   * <p>
   * By default no SSL context will be used, indicating that connections will
   * not be secured. If a non-{@code null} SSL context is returned then
   * connections will be secured using either SSL or StartTLS depending on
   * {@link #useStartTLS()}.
   *
   * @return The SSL context which will be used when initiating secure
   *         connections with the Directory Server, which may be {@code null}
   *         indicating that connections will not be secured.
   */
  public final SSLContext getSSLContext()
  {
    return sslContext;
  }
  /**
   * Returns the Grizzly TCP transport which will be used when initiating
   * connections with the Directory Server.
   * <p>
   * By default this method will return {@code null} indicating that the default
   * transport factory should be used to obtain a TCP transport.
   *
   * @return The Grizzly TCP transport which will be used when initiating
   *         connections with the Directory Server, or {@code null} if the
   *         default transport factory should be used to obtain a TCP transport.
   */
  public final TCPNIOTransport getTCPNIOTransport()
  {
    return transport;
  }
  /**
   * Returns the operation timeout in the specified unit.
   *
   * @param unit
   *          The time unit of use.
   * @return The operation timeout.
   */
  public final long getTimeout(final TimeUnit unit)
  {
    return unit.convert(timeoutInMillis, TimeUnit.MILLISECONDS);
  }
  /**
   * Sets the decoding options which will be used to control how requests and
   * responses are decoded.
   *
   * @param decodeOptions
   *          The decoding options which will be used to control how requests
   *          and responses are decoded (never {@code null}).
   * @return A reference to this LDAP connection options.
   * @throws NullPointerException
   *           If {@code decodeOptions} was {@code null}.
   */
  public final LDAPOptions setDecodeOptions(final DecodeOptions decodeOptions)
  {
    Validator.ensureNotNull(decodeOptions);
    this.decodeOptions = decodeOptions;
    return this;
  }
  /**
   * Sets the SSL context which will be used when initiating connections with
   * the Directory Server.
   * <p>
   * By default no SSL context will be used, indicating that connections will
   * not be secured. If a non-{@code null} SSL context is returned then
   * connections will be secured using either SSL or StartTLS depending on
   * {@link #useStartTLS()}.
   *
   * @param sslContext
   *          The SSL context which will be used when initiating secure
   *          connections with the Directory Server, which may be {@code null}
   *          indicating that connections will not be secured.
   * @return A reference to this LDAP connection options.
   */
  public final LDAPOptions setSSLContext(final SSLContext sslContext)
  {
    this.sslContext = sslContext;
    return this;
  }
  /**
   * Sets the Grizzly TCP transport which will be used when initiating
   * connections with the Directory Server.
   * <p>
   * By default this method will return {@code null} indicating that the default
   * transport factory will be used to obtain a TCP transport.
   *
   * @param transport
   *          The Grizzly TCP transport which will be used when initiating
   *          connections with the Directory Server, or {@code null} if the
   *          default transport factory should be used to obtain a TCP
   *          transport.
   * @return A reference to this LDAP connection options.
   */
  public final LDAPOptions setTCPNIOTransport(final TCPNIOTransport transport)
  {
    this.transport = transport;
    return this;
  }
  /**
   * Sets the operation timeout. If the response is not received from the
   * Directory Server in the timeout period, the operation will be abandoned and
   * an error result returned. A timeout setting of 0 disables timeout limits.
   *
   * @param timeout
   *          The operation timeout to use.
   * @param unit
   *          the time unit of the time argument.
   * @return A reference to this LDAP connection options.
   */
  public final LDAPOptions setTimeout(final long timeout, final TimeUnit unit)
  {
    this.timeoutInMillis = unit.toMillis(timeout);
    return this;
  }
  /**
   * Specifies whether or not SSL or StartTLS should be used for securing
   * connections when an SSL context is specified.
   * <p>
   * By default SSL will be used in preference to StartTLS.
   *
   * @param useStartTLS
   *          {@code true} if StartTLS should be used for securing connections
   *          when an SSL context is specified, otherwise {@code false}
   *          indicating that SSL should be used.
   * @return A reference to this LDAP connection options.
   */
  public final LDAPOptions setUseStartTLS(final boolean useStartTLS)
  {
    this.useStartTLS = useStartTLS;
    return this;
  }
  /**
   * Indicates whether or not SSL or StartTLS should be used for securing
   * connections when an SSL context is specified.
   * <p>
   * By default SSL will be used in preference to StartTLS.
   *
   * @return {@code true} if StartTLS should be used for securing connections
   *         when an SSL context is specified, otherwise {@code false}
   *         indicating that SSL should be used.
   */
  public final boolean useStartTLS()
  {
    return useStartTLS;
  }
  /**
   * Adds the protocol versions enabled for secure connections with the
   * Directory Server.
   * <p>
   * The protocols must be supported by the SSLContext specified in
   * {@link #setSSLContext(SSLContext)}. Following a successful call to this
   * method, only the protocols listed in the protocols parameter are enabled
   * for use.
   *
   * @param protocols
   *          Names of all the protocols to enable.
   * @return A reference to this LDAP connection options.
   */
  public final LDAPOptions addEnabledProtocol(String... protocols)
  {
    for (final String protocol : protocols)
    {
      enabledProtocols.add(Validator.ensureNotNull(protocol));
    /**
     * Creates a new set of connection options with default settings. SSL will
     * not be enabled, and a default set of decode options will be used.
     */
    public LDAPOptions() {
        this.sslContext = null;
        this.timeoutInMillis = 0;
        this.useStartTLS = false;
        this.decodeOptions = new DecodeOptions();
        this.transport = null;
    }
    return this;
  }
  /**
   * Adds the cipher suites enabled for secure connections with the Directory
   * Server.
   * <p>
   * The suites must be supported by the SSLContext specified in
   * {@link #setSSLContext(SSLContext)}. Following a successful call to this
   * method, only the suites listed in the protocols parameter are enabled for
   * use.
   *
   * @param suites
   *          Names of all the suites to enable.
   * @return A reference to this LDAP connection options.
   */
  public final LDAPOptions addEnabledCipherSuite(String... suites)
  {
    for (final String suite : suites)
    {
      enabledCipherSuites.add(Validator.ensureNotNull(suite));
    /**
     * Creates a new set of connection options having the same initial set of
     * options as the provided set of connection options.
     *
     * @param options
     *            The set of connection options to be copied.
     */
    public LDAPOptions(final LDAPOptions options) {
        this.sslContext = options.sslContext;
        this.timeoutInMillis = options.timeoutInMillis;
        this.useStartTLS = options.useStartTLS;
        this.decodeOptions = new DecodeOptions(options.decodeOptions);
        this.enabledCipherSuites.addAll(options.getEnabledCipherSuites());
        this.enabledProtocols.addAll(options.getEnabledProtocols());
        this.transport = options.transport;
    }
    return this;
  }
    /**
     * Returns the decoding options which will be used to control how requests
     * and responses are decoded.
     *
     * @return The decoding options which will be used to control how requests
     *         and responses are decoded (never {@code null}).
     */
    public final DecodeOptions getDecodeOptions() {
        return decodeOptions;
    }
    /**
     * Returns the SSL context which will be used when initiating connections
     * with the Directory Server.
     * <p>
     * By default no SSL context will be used, indicating that connections will
     * not be secured. If a non-{@code null} SSL context is returned then
     * connections will be secured using either SSL or StartTLS depending on
     * {@link #useStartTLS()}.
     *
     * @return The SSL context which will be used when initiating secure
     *         connections with the Directory Server, which may be {@code null}
     *         indicating that connections will not be secured.
     */
    public final SSLContext getSSLContext() {
        return sslContext;
    }
  /**
   * Returns the names of the protocol versions which are currently enabled for
   * secure connections with the Directory Server.
   *
   * @return An array of protocols or empty set if the default protocols are to
   *         be used.
   */
  public final List<String> getEnabledProtocols()
  {
    return enabledProtocols;
  }
    /**
     * Returns the Grizzly TCP transport which will be used when initiating
     * connections with the Directory Server.
     * <p>
     * By default this method will return {@code null} indicating that the
     * default transport factory should be used to obtain a TCP transport.
     *
     * @return The Grizzly TCP transport which will be used when initiating
     *         connections with the Directory Server, or {@code null} if the
     *         default transport factory should be used to obtain a TCP
     *         transport.
     */
    public final TCPNIOTransport getTCPNIOTransport() {
        return transport;
    }
    /**
     * Returns the operation timeout in the specified unit.
     *
     * @param unit
     *            The time unit of use.
     * @return The operation timeout.
     */
    public final long getTimeout(final TimeUnit unit) {
        return unit.convert(timeoutInMillis, TimeUnit.MILLISECONDS);
    }
    /**
     * Sets the decoding options which will be used to control how requests and
     * responses are decoded.
     *
     * @param decodeOptions
     *            The decoding options which will be used to control how
     *            requests and responses are decoded (never {@code null}).
     * @return A reference to this LDAP connection options.
     * @throws NullPointerException
     *             If {@code decodeOptions} was {@code null}.
     */
    public final LDAPOptions setDecodeOptions(final DecodeOptions decodeOptions) {
        Validator.ensureNotNull(decodeOptions);
        this.decodeOptions = decodeOptions;
        return this;
    }
  /**
   * Returns the names of the protocol versions which are currently enabled for
   * secure connections with the Directory Server.
   *
   * @return An array of protocols or empty set if the default protocols are to
   *         be used.
   */
  public final List<String> getEnabledCipherSuites()
  {
    return enabledCipherSuites;
  }
    /**
     * Sets the SSL context which will be used when initiating connections with
     * the Directory Server.
     * <p>
     * By default no SSL context will be used, indicating that connections will
     * not be secured. If a non-{@code null} SSL context is returned then
     * connections will be secured using either SSL or StartTLS depending on
     * {@link #useStartTLS()}.
     *
     * @param sslContext
     *            The SSL context which will be used when initiating secure
     *            connections with the Directory Server, which may be
     *            {@code null} indicating that connections will not be secured.
     * @return A reference to this LDAP connection options.
     */
    public final LDAPOptions setSSLContext(final SSLContext sslContext) {
        this.sslContext = sslContext;
        return this;
    }
    /**
     * Sets the Grizzly TCP transport which will be used when initiating
     * connections with the Directory Server.
     * <p>
     * By default this method will return {@code null} indicating that the
     * default transport factory will be used to obtain a TCP transport.
     *
     * @param transport
     *            The Grizzly TCP transport which will be used when initiating
     *            connections with the Directory Server, or {@code null} if the
     *            default transport factory should be used to obtain a TCP
     *            transport.
     * @return A reference to this LDAP connection options.
     */
    public final LDAPOptions setTCPNIOTransport(final TCPNIOTransport transport) {
        this.transport = transport;
        return this;
    }
    /**
     * Sets the operation timeout. If the response is not received from the
     * Directory Server in the timeout period, the operation will be abandoned
     * and an error result returned. A timeout setting of 0 disables timeout
     * limits.
     *
     * @param timeout
     *            The operation timeout to use.
     * @param unit
     *            the time unit of the time argument.
     * @return A reference to this LDAP connection options.
     */
    public final LDAPOptions setTimeout(final long timeout, final TimeUnit unit) {
        this.timeoutInMillis = unit.toMillis(timeout);
        return this;
    }
    /**
     * Specifies whether or not SSL or StartTLS should be used for securing
     * connections when an SSL context is specified.
     * <p>
     * By default SSL will be used in preference to StartTLS.
     *
     * @param useStartTLS
     *            {@code true} if StartTLS should be used for securing
     *            connections when an SSL context is specified, otherwise
     *            {@code false} indicating that SSL should be used.
     * @return A reference to this LDAP connection options.
     */
    public final LDAPOptions setUseStartTLS(final boolean useStartTLS) {
        this.useStartTLS = useStartTLS;
        return this;
    }
    /**
     * Indicates whether or not SSL or StartTLS should be used for securing
     * connections when an SSL context is specified.
     * <p>
     * By default SSL will be used in preference to StartTLS.
     *
     * @return {@code true} if StartTLS should be used for securing connections
     *         when an SSL context is specified, otherwise {@code false}
     *         indicating that SSL should be used.
     */
    public final boolean useStartTLS() {
        return useStartTLS;
    }
    /**
     * Adds the protocol versions enabled for secure connections with the
     * Directory Server.
     * <p>
     * The protocols must be supported by the SSLContext specified in
     * {@link #setSSLContext(SSLContext)}. Following a successful call to this
     * method, only the protocols listed in the protocols parameter are enabled
     * for use.
     *
     * @param protocols
     *            Names of all the protocols to enable.
     * @return A reference to this LDAP connection options.
     */
    public final LDAPOptions addEnabledProtocol(String... protocols) {
        for (final String protocol : protocols) {
            enabledProtocols.add(Validator.ensureNotNull(protocol));
        }
        return this;
    }
    /**
     * Adds the cipher suites enabled for secure connections with the Directory
     * Server.
     * <p>
     * The suites must be supported by the SSLContext specified in
     * {@link #setSSLContext(SSLContext)}. Following a successful call to this
     * method, only the suites listed in the protocols parameter are enabled for
     * use.
     *
     * @param suites
     *            Names of all the suites to enable.
     * @return A reference to this LDAP connection options.
     */
    public final LDAPOptions addEnabledCipherSuite(String... suites) {
        for (final String suite : suites) {
            enabledCipherSuites.add(Validator.ensureNotNull(suite));
        }
        return this;
    }
    /**
     * Returns the names of the protocol versions which are currently enabled
     * for secure connections with the Directory Server.
     *
     * @return An array of protocols or empty set if the default protocols are
     *         to be used.
     */
    public final List<String> getEnabledProtocols() {
        return enabledProtocols;
    }
    /**
     * Returns the names of the protocol versions which are currently enabled
     * for secure connections with the Directory Server.
     *
     * @return An array of protocols or empty set if the default protocols are
     *         to be used.
     */
    public final List<String> getEnabledCipherSuites() {
        return enabledCipherSuites;
    }
}