001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2008 Sun Microsystems, Inc.
025 */
026package org.opends.server.admin.std.server;
027
028
029
030import java.net.InetAddress;
031import java.util.SortedSet;
032import org.opends.server.admin.server.ConfigurationChangeListener;
033import org.opends.server.admin.std.meta.LDAPConnectionHandlerCfgDefn.SSLClientAuthPolicy;
034import org.opends.server.types.DN;
035
036
037
038/**
039 * A server-side interface for querying LDAP Connection Handler
040 * settings.
041 * <p>
042 * The LDAP Connection Handler is used to interact with clients using
043 * LDAP.
044 */
045public interface LDAPConnectionHandlerCfg extends ConnectionHandlerCfg {
046
047  /**
048   * Gets the configuration class associated with this LDAP Connection Handler.
049   *
050   * @return Returns the configuration class associated with this LDAP Connection Handler.
051   */
052  Class<? extends LDAPConnectionHandlerCfg> configurationClass();
053
054
055
056  /**
057   * Register to be notified when this LDAP Connection Handler is changed.
058   *
059   * @param listener
060   *          The LDAP Connection Handler configuration change listener.
061   */
062  void addLDAPChangeListener(ConfigurationChangeListener<LDAPConnectionHandlerCfg> listener);
063
064
065
066  /**
067   * Deregister an existing LDAP Connection Handler configuration change listener.
068   *
069   * @param listener
070   *          The LDAP Connection Handler configuration change listener.
071   */
072  void removeLDAPChangeListener(ConfigurationChangeListener<LDAPConnectionHandlerCfg> listener);
073
074
075
076  /**
077   * Gets the "accept-backlog" property.
078   * <p>
079   * Specifies the maximum number of pending connection attempts that
080   * are allowed to queue up in the accept backlog before the server
081   * starts rejecting new connection attempts.
082   * <p>
083   * This is primarily an issue for cases in which a large number of
084   * connections are established to the server in a very short period
085   * of time (for example, a benchmark utility that creates a large
086   * number of client threads that each have their own connection to
087   * the server) and the connection handler is unable to keep up with
088   * the rate at which the new connections are established.
089   *
090   * @return Returns the value of the "accept-backlog" property.
091   */
092  int getAcceptBacklog();
093
094
095
096  /**
097   * Gets the "allow-ldap-v2" property.
098   * <p>
099   * Indicates whether connections from LDAPv2 clients are allowed.
100   * <p>
101   * If LDAPv2 clients are allowed, then only a minimal degree of
102   * special support are provided for them to ensure that
103   * LDAPv3-specific protocol elements (for example, Configuration
104   * Guide 25 controls, extended response messages, intermediate
105   * response messages, referrals) are not sent to an LDAPv2 client.
106   *
107   * @return Returns the value of the "allow-ldap-v2" property.
108   */
109  boolean isAllowLDAPV2();
110
111
112
113  /**
114   * Gets the "allow-start-tls" property.
115   * <p>
116   * Indicates whether clients are allowed to use StartTLS.
117   * <p>
118   * If enabled, the LDAP Connection Handler allows clients to use the
119   * StartTLS extended operation to initiate secure communication over
120   * an otherwise insecure channel. Note that this is only allowed if
121   * the LDAP Connection Handler is not configured to use SSL, and if
122   * the server is configured with a valid key manager provider and a
123   * valid trust manager provider.
124   *
125   * @return Returns the value of the "allow-start-tls" property.
126   */
127  boolean isAllowStartTLS();
128
129
130
131  /**
132   * Gets the "allow-tcp-reuse-address" property.
133   * <p>
134   * Indicates whether the LDAP Connection Handler should reuse socket
135   * descriptors.
136   * <p>
137   * If enabled, the SO_REUSEADDR socket option is used on the server
138   * listen socket to potentially allow the reuse of socket descriptors
139   * for clients in a TIME_WAIT state. This may help the server avoid
140   * temporarily running out of socket descriptors in cases in which a
141   * very large number of short-lived connections have been established
142   * from the same client system.
143   *
144   * @return Returns the value of the "allow-tcp-reuse-address" property.
145   */
146  boolean isAllowTCPReuseAddress();
147
148
149
150  /**
151   * Gets the "buffer-size" property.
152   * <p>
153   * Specifies the size in bytes of the LDAP response message write
154   * buffer.
155   * <p>
156   * This property specifies write buffer size allocated by the server
157   * for each client connection and used to buffer LDAP response
158   * messages data when writing.
159   *
160   * @return Returns the value of the "buffer-size" property.
161   */
162  long getBufferSize();
163
164
165
166  /**
167   * Gets the "java-class" property.
168   * <p>
169   * Specifies the fully-qualified name of the Java class that
170   * provides the LDAP Connection Handler implementation.
171   *
172   * @return Returns the value of the "java-class" property.
173   */
174  String getJavaClass();
175
176
177
178  /**
179   * Gets the "keep-stats" property.
180   * <p>
181   * Indicates whether the LDAP Connection Handler should keep
182   * statistics.
183   * <p>
184   * If enabled, the LDAP Connection Handler maintains statistics
185   * about the number and types of operations requested over LDAP and
186   * the amount of data sent and received.
187   *
188   * @return Returns the value of the "keep-stats" property.
189   */
190  boolean isKeepStats();
191
192
193
194  /**
195   * Gets the "key-manager-provider" property.
196   * <p>
197   * Specifies the name of the key manager that should be used with
198   * this LDAP Connection Handler .
199   *
200   * @return Returns the value of the "key-manager-provider" property.
201   */
202  String getKeyManagerProvider();
203
204
205
206  /**
207   * Gets the "key-manager-provider" property as a DN.
208   * <p>
209   * Specifies the name of the key manager that should be used with
210   * this LDAP Connection Handler .
211   *
212   * @return Returns the DN value of the "key-manager-provider"
213   *         property.
214   */
215  DN getKeyManagerProviderDN();
216
217
218
219  /**
220   * Gets the "listen-address" property.
221   * <p>
222   * Specifies the address or set of addresses on which this LDAP
223   * Connection Handler should listen for connections from LDAP
224   * clients.
225   * <p>
226   * Multiple addresses may be provided as separate values for this
227   * attribute. If no values are provided, then the LDAP Connection
228   * Handler listens on all interfaces.
229   *
230   * @return Returns an unmodifiable set containing the values of the "listen-address" property.
231   */
232  SortedSet<InetAddress> getListenAddress();
233
234
235
236  /**
237   * Gets the "listen-port" property.
238   * <p>
239   * Specifies the port number on which the LDAP Connection Handler
240   * will listen for connections from clients.
241   * <p>
242   * Only a single port number may be provided.
243   *
244   * @return Returns the value of the "listen-port" property.
245   */
246  int getListenPort();
247
248
249
250  /**
251   * Gets the "max-blocked-write-time-limit" property.
252   * <p>
253   * Specifies the maximum length of time that attempts to write data
254   * to LDAP clients should be allowed to block.
255   * <p>
256   * If an attempt to write data to a client takes longer than this
257   * length of time, then the client connection is terminated.
258   *
259   * @return Returns the value of the "max-blocked-write-time-limit" property.
260   */
261  long getMaxBlockedWriteTimeLimit();
262
263
264
265  /**
266   * Gets the "max-request-size" property.
267   * <p>
268   * Specifies the size in bytes of the largest LDAP request message
269   * that will be allowed by this LDAP Connection handler.
270   * <p>
271   * This property is analogous to the maxBERSize configuration
272   * attribute of the Sun Java System Directory Server. This can help
273   * prevent denial-of-service attacks by clients that indicate they
274   * send extremely large requests to the server causing it to attempt
275   * to allocate large amounts of memory.
276   *
277   * @return Returns the value of the "max-request-size" property.
278   */
279  long getMaxRequestSize();
280
281
282
283  /**
284   * Gets the "num-request-handlers" property.
285   * <p>
286   * Specifies the number of request handlers that are used to read
287   * requests from clients.
288   * <p>
289   * The LDAP Connection Handler uses one thread to accept new
290   * connections from clients, but uses one or more additional threads
291   * to read requests from existing client connections. This ensures
292   * that new requests are read efficiently and that the connection
293   * handler itself does not become a bottleneck when the server is
294   * under heavy load from many clients at the same time.
295   *
296   * @return Returns the value of the "num-request-handlers" property.
297   */
298  Integer getNumRequestHandlers();
299
300
301
302  /**
303   * Gets the "send-rejection-notice" property.
304   * <p>
305   * Indicates whether the LDAP Connection Handler should send a
306   * notice of disconnection extended response message to the client if
307   * a new connection is rejected for some reason.
308   * <p>
309   * The extended response message may provide an explanation
310   * indicating the reason that the connection was rejected.
311   *
312   * @return Returns the value of the "send-rejection-notice" property.
313   */
314  boolean isSendRejectionNotice();
315
316
317
318  /**
319   * Gets the "ssl-cert-nickname" property.
320   * <p>
321   * Specifies the nickname (also called the alias) of the certificate
322   * that the LDAP Connection Handler should use when performing SSL
323   * communication.
324   * <p>
325   * This is only applicable when the LDAP Connection Handler is
326   * configured to use SSL.
327   *
328   * @return Returns the value of the "ssl-cert-nickname" property.
329   */
330  String getSSLCertNickname();
331
332
333
334  /**
335   * Gets the "ssl-cipher-suite" property.
336   * <p>
337   * Specifies the names of the SSL cipher suites that are allowed for
338   * use in SSL or StartTLS communication.
339   *
340   * @return Returns an unmodifiable set containing the values of the "ssl-cipher-suite" property.
341   */
342  SortedSet<String> getSSLCipherSuite();
343
344
345
346  /**
347   * Gets the "ssl-client-auth-policy" property.
348   * <p>
349   * Specifies the policy that the LDAP Connection Handler should use
350   * regarding client SSL certificates. Clients can use the SASL
351   * EXTERNAL mechanism only if the policy is set to "optional" or
352   * "required".
353   * <p>
354   * This is only applicable if clients are allowed to use SSL.
355   *
356   * @return Returns the value of the "ssl-client-auth-policy" property.
357   */
358  SSLClientAuthPolicy getSSLClientAuthPolicy();
359
360
361
362  /**
363   * Gets the "ssl-protocol" property.
364   * <p>
365   * Specifies the names of the SSL protocols that are allowed for use
366   * in SSL or StartTLS communication.
367   *
368   * @return Returns an unmodifiable set containing the values of the "ssl-protocol" property.
369   */
370  SortedSet<String> getSSLProtocol();
371
372
373
374  /**
375   * Gets the "trust-manager-provider" property.
376   * <p>
377   * Specifies the name of the trust manager that should be used with
378   * the LDAP Connection Handler .
379   *
380   * @return Returns the value of the "trust-manager-provider" property.
381   */
382  String getTrustManagerProvider();
383
384
385
386  /**
387   * Gets the "trust-manager-provider" property as a DN.
388   * <p>
389   * Specifies the name of the trust manager that should be used with
390   * the LDAP Connection Handler .
391   *
392   * @return Returns the DN value of the "trust-manager-provider"
393   *         property.
394   */
395  DN getTrustManagerProviderDN();
396
397
398
399  /**
400   * Gets the "use-ssl" property.
401   * <p>
402   * Indicates whether the LDAP Connection Handler should use SSL.
403   * <p>
404   * If enabled, the LDAP Connection Handler will use SSL to encrypt
405   * communication with the clients.
406   *
407   * @return Returns the value of the "use-ssl" property.
408   */
409  boolean isUseSSL();
410
411
412
413  /**
414   * Gets the "use-tcp-keep-alive" property.
415   * <p>
416   * Indicates whether the LDAP Connection Handler should use TCP
417   * keep-alive.
418   * <p>
419   * If enabled, the SO_KEEPALIVE socket option is used to indicate
420   * that TCP keepalive messages should periodically be sent to the
421   * client to verify that the associated connection is still valid.
422   * This may also help prevent cases in which intermediate network
423   * hardware could silently drop an otherwise idle client connection,
424   * provided that the keepalive interval configured in the underlying
425   * operating system is smaller than the timeout enforced by the
426   * network hardware.
427   *
428   * @return Returns the value of the "use-tcp-keep-alive" property.
429   */
430  boolean isUseTCPKeepAlive();
431
432
433
434  /**
435   * Gets the "use-tcp-no-delay" property.
436   * <p>
437   * Indicates whether the LDAP Connection Handler should use TCP
438   * no-delay.
439   * <p>
440   * If enabled, the TCP_NODELAY socket option is used to ensure that
441   * response messages to the client are sent immediately rather than
442   * potentially waiting to determine whether additional response
443   * messages can be sent in the same packet. In most cases, using the
444   * TCP_NODELAY socket option provides better performance and lower
445   * response times, but disabling it may help for some cases in which
446   * the server sends a large number of entries to a client in response
447   * to a search request.
448   *
449   * @return Returns the value of the "use-tcp-no-delay" property.
450   */
451  boolean isUseTCPNoDelay();
452
453}