| | |
| | | * (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 |
| | |
| | | |
| | | package org.forgerock.opendj.ldap; |
| | | |
| | | |
| | | |
| | | import java.util.LinkedList; |
| | | import java.util.List; |
| | | import java.util.concurrent.TimeUnit; |
| | |
| | | |
| | | 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; |
| | | } |
| | | |
| | | } |