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
010 * trunk/opends/resource/legal-notices/OpenDS.LICENSE
011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 * Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 * Copyright 2008 Sun Microsystems, Inc.
026 */
027 package org.opends.server.admin.std.client;
028
029
030
031 import java.net.InetAddress;
032 import java.util.Collection;
033 import java.util.SortedSet;
034 import org.opends.server.admin.IllegalPropertyValueException;
035 import org.opends.server.admin.ManagedObjectDefinition;
036 import org.opends.server.admin.std.meta.LDAPConnectionHandlerCfgDefn.SSLClientAuthPolicy;
037 import org.opends.server.admin.std.server.LDAPConnectionHandlerCfg;
038
039
040
041 /**
042 * A client-side interface for reading and modifying LDAP Connection
043 * Handler settings.
044 * <p>
045 * The LDAP Connection Handler is used to interact with clients using
046 * LDAP.
047 */
048 public interface LDAPConnectionHandlerCfgClient extends ConnectionHandlerCfgClient {
049
050 /**
051 * Get the configuration definition associated with this LDAP Connection Handler.
052 *
053 * @return Returns the configuration definition associated with this LDAP Connection Handler.
054 */
055 ManagedObjectDefinition<? extends LDAPConnectionHandlerCfgClient, ? extends LDAPConnectionHandlerCfg> definition();
056
057
058
059 /**
060 * Gets the "accept-backlog" property.
061 * <p>
062 * Specifies the maximum number of pending connection attempts that
063 * are allowed to queue up in the accept backlog before the server
064 * starts rejecting new connection attempts.
065 * <p>
066 * This is primarily an issue for cases in which a large number of
067 * connections are established to the server in a very short period
068 * of time (for example, a benchmark utility that creates a large
069 * number of client threads that each have their own connection to
070 * the server) and the connection handler is unable to keep up with
071 * the rate at which the new connections are established.
072 *
073 * @return Returns the value of the "accept-backlog" property.
074 */
075 int getAcceptBacklog();
076
077
078
079 /**
080 * Sets the "accept-backlog" property.
081 * <p>
082 * Specifies the maximum number of pending connection attempts that
083 * are allowed to queue up in the accept backlog before the server
084 * starts rejecting new connection attempts.
085 * <p>
086 * This is primarily an issue for cases in which a large number of
087 * connections are established to the server in a very short period
088 * of time (for example, a benchmark utility that creates a large
089 * number of client threads that each have their own connection to
090 * the server) and the connection handler is unable to keep up with
091 * the rate at which the new connections are established.
092 *
093 * @param value The value of the "accept-backlog" property.
094 * @throws IllegalPropertyValueException
095 * If the new value is invalid.
096 */
097 void setAcceptBacklog(Integer value) throws IllegalPropertyValueException;
098
099
100
101 /**
102 * Gets the "allow-ldap-v2" property.
103 * <p>
104 * Indicates whether connections from LDAPv2 clients are allowed.
105 * <p>
106 * If LDAPv2 clients are allowed, then only a minimal degree of
107 * special support are provided for them to ensure that
108 * LDAPv3-specific protocol elements (for example, Configuration
109 * Guide 25 controls, extended response messages, intermediate
110 * response messages, referrals) are not sent to an LDAPv2 client.
111 *
112 * @return Returns the value of the "allow-ldap-v2" property.
113 */
114 boolean isAllowLDAPV2();
115
116
117
118 /**
119 * Sets the "allow-ldap-v2" property.
120 * <p>
121 * Indicates whether connections from LDAPv2 clients are allowed.
122 * <p>
123 * If LDAPv2 clients are allowed, then only a minimal degree of
124 * special support are provided for them to ensure that
125 * LDAPv3-specific protocol elements (for example, Configuration
126 * Guide 25 controls, extended response messages, intermediate
127 * response messages, referrals) are not sent to an LDAPv2 client.
128 *
129 * @param value The value of the "allow-ldap-v2" property.
130 * @throws IllegalPropertyValueException
131 * If the new value is invalid.
132 */
133 void setAllowLDAPV2(Boolean value) throws IllegalPropertyValueException;
134
135
136
137 /**
138 * Gets the "allow-start-tls" property.
139 * <p>
140 * Indicates whether clients are allowed to use StartTLS.
141 * <p>
142 * If enabled, the LDAP Connection Handler allows clients to use the
143 * StartTLS extended operation to initiate secure communication over
144 * an otherwise insecure channel. Note that this is only allowed if
145 * the LDAP Connection Handler is not configured to use SSL, and if
146 * the server is configured with a valid key manager provider and a
147 * valid trust manager provider.
148 *
149 * @return Returns the value of the "allow-start-tls" property.
150 */
151 boolean isAllowStartTLS();
152
153
154
155 /**
156 * Sets the "allow-start-tls" property.
157 * <p>
158 * Indicates whether clients are allowed to use StartTLS.
159 * <p>
160 * If enabled, the LDAP Connection Handler allows clients to use the
161 * StartTLS extended operation to initiate secure communication over
162 * an otherwise insecure channel. Note that this is only allowed if
163 * the LDAP Connection Handler is not configured to use SSL, and if
164 * the server is configured with a valid key manager provider and a
165 * valid trust manager provider.
166 *
167 * @param value The value of the "allow-start-tls" property.
168 * @throws IllegalPropertyValueException
169 * If the new value is invalid.
170 */
171 void setAllowStartTLS(Boolean value) throws IllegalPropertyValueException;
172
173
174
175 /**
176 * Gets the "allow-tcp-reuse-address" property.
177 * <p>
178 * Indicates whether the LDAP Connection Handler should reuse socket
179 * descriptors.
180 * <p>
181 * If enabled, the SO_REUSEADDR socket option is used on the server
182 * listen socket to potentially allow the reuse of socket descriptors
183 * for clients in a TIME_WAIT state. This may help the server avoid
184 * temporarily running out of socket descriptors in cases in which a
185 * very large number of short-lived connections have been established
186 * from the same client system.
187 *
188 * @return Returns the value of the "allow-tcp-reuse-address" property.
189 */
190 boolean isAllowTCPReuseAddress();
191
192
193
194 /**
195 * Sets the "allow-tcp-reuse-address" property.
196 * <p>
197 * Indicates whether the LDAP Connection Handler should reuse socket
198 * descriptors.
199 * <p>
200 * If enabled, the SO_REUSEADDR socket option is used on the server
201 * listen socket to potentially allow the reuse of socket descriptors
202 * for clients in a TIME_WAIT state. This may help the server avoid
203 * temporarily running out of socket descriptors in cases in which a
204 * very large number of short-lived connections have been established
205 * from the same client system.
206 *
207 * @param value The value of the "allow-tcp-reuse-address" property.
208 * @throws IllegalPropertyValueException
209 * If the new value is invalid.
210 */
211 void setAllowTCPReuseAddress(Boolean value) throws IllegalPropertyValueException;
212
213
214
215 /**
216 * Gets the "java-class" property.
217 * <p>
218 * Specifies the fully-qualified name of the Java class that
219 * provides the LDAP Connection Handler implementation.
220 *
221 * @return Returns the value of the "java-class" property.
222 */
223 String getJavaClass();
224
225
226
227 /**
228 * Sets the "java-class" property.
229 * <p>
230 * Specifies the fully-qualified name of the Java class that
231 * provides the LDAP Connection Handler implementation.
232 *
233 * @param value The value of the "java-class" property.
234 * @throws IllegalPropertyValueException
235 * If the new value is invalid.
236 */
237 void setJavaClass(String value) throws IllegalPropertyValueException;
238
239
240
241 /**
242 * Gets the "keep-stats" property.
243 * <p>
244 * Indicates whether the LDAP Connection Handler should keep
245 * statistics.
246 * <p>
247 * If enabled, the LDAP Connection Handler maintains statistics
248 * about the number and types of operations requested over LDAP and
249 * the amount of data sent and received.
250 *
251 * @return Returns the value of the "keep-stats" property.
252 */
253 boolean isKeepStats();
254
255
256
257 /**
258 * Sets the "keep-stats" property.
259 * <p>
260 * Indicates whether the LDAP Connection Handler should keep
261 * statistics.
262 * <p>
263 * If enabled, the LDAP Connection Handler maintains statistics
264 * about the number and types of operations requested over LDAP and
265 * the amount of data sent and received.
266 *
267 * @param value The value of the "keep-stats" property.
268 * @throws IllegalPropertyValueException
269 * If the new value is invalid.
270 */
271 void setKeepStats(Boolean value) throws IllegalPropertyValueException;
272
273
274
275 /**
276 * Gets the "key-manager-provider" property.
277 * <p>
278 * Specifies the name of the key manager that should be used with
279 * this LDAP Connection Handler .
280 *
281 * @return Returns the value of the "key-manager-provider" property.
282 */
283 String getKeyManagerProvider();
284
285
286
287 /**
288 * Sets the "key-manager-provider" property.
289 * <p>
290 * Specifies the name of the key manager that should be used with
291 * this LDAP Connection Handler .
292 *
293 * @param value The value of the "key-manager-provider" property.
294 * @throws IllegalPropertyValueException
295 * If the new value is invalid.
296 */
297 void setKeyManagerProvider(String value) throws IllegalPropertyValueException;
298
299
300
301 /**
302 * Gets the "listen-address" property.
303 * <p>
304 * Specifies the address or set of addresses on which this LDAP
305 * Connection Handler should listen for connections from LDAP
306 * clients.
307 * <p>
308 * Multiple addresses may be provided as separate values for this
309 * attribute. If no values are provided, then the LDAP Connection
310 * Handler listens on all interfaces.
311 *
312 * @return Returns the values of the "listen-address" property.
313 */
314 SortedSet<InetAddress> getListenAddress();
315
316
317
318 /**
319 * Sets the "listen-address" property.
320 * <p>
321 * Specifies the address or set of addresses on which this LDAP
322 * Connection Handler should listen for connections from LDAP
323 * clients.
324 * <p>
325 * Multiple addresses may be provided as separate values for this
326 * attribute. If no values are provided, then the LDAP Connection
327 * Handler listens on all interfaces.
328 *
329 * @param values The values of the "listen-address" property.
330 * @throws IllegalPropertyValueException
331 * If one or more of the new values are invalid.
332 */
333 void setListenAddress(Collection<InetAddress> values) throws IllegalPropertyValueException;
334
335
336
337 /**
338 * Gets the "listen-port" property.
339 * <p>
340 * Specifies the port number on which the LDAP Connection Handler
341 * will listen for connections from clients.
342 * <p>
343 * Only a single port number may be provided.
344 *
345 * @return Returns the value of the "listen-port" property.
346 */
347 Integer getListenPort();
348
349
350
351 /**
352 * Sets the "listen-port" property.
353 * <p>
354 * Specifies the port number on which the LDAP Connection Handler
355 * will listen for connections from clients.
356 * <p>
357 * Only a single port number may be provided.
358 *
359 * @param value The value of the "listen-port" property.
360 * @throws IllegalPropertyValueException
361 * If the new value is invalid.
362 */
363 void setListenPort(int value) throws IllegalPropertyValueException;
364
365
366
367 /**
368 * Gets the "max-blocked-write-time-limit" property.
369 * <p>
370 * Specifies the maximum length of time that attempts to write data
371 * to LDAP clients should be allowed to block.
372 * <p>
373 * If an attempt to write data to a client takes longer than this
374 * length of time, then the client connection is terminated.
375 *
376 * @return Returns the value of the "max-blocked-write-time-limit" property.
377 */
378 long getMaxBlockedWriteTimeLimit();
379
380
381
382 /**
383 * Sets the "max-blocked-write-time-limit" property.
384 * <p>
385 * Specifies the maximum length of time that attempts to write data
386 * to LDAP clients should be allowed to block.
387 * <p>
388 * If an attempt to write data to a client takes longer than this
389 * length of time, then the client connection is terminated.
390 *
391 * @param value The value of the "max-blocked-write-time-limit" property.
392 * @throws IllegalPropertyValueException
393 * If the new value is invalid.
394 */
395 void setMaxBlockedWriteTimeLimit(Long value) throws IllegalPropertyValueException;
396
397
398
399 /**
400 * Gets the "max-request-size" property.
401 * <p>
402 * Specifies the size of the largest LDAP request message that will
403 * be allowed by this LDAP Connection handler.
404 * <p>
405 * This property is analogous to the maxBERSize configuration
406 * attribute of the Sun Java System Directory Server. This can help
407 * prevent denial-of-service attacks by clients that indicate they
408 * send extremely large requests to the server causing it to attempt
409 * to allocate large amounts of memory.
410 *
411 * @return Returns the value of the "max-request-size" property.
412 */
413 long getMaxRequestSize();
414
415
416
417 /**
418 * Sets the "max-request-size" property.
419 * <p>
420 * Specifies the size of the largest LDAP request message that will
421 * be allowed by this LDAP Connection handler.
422 * <p>
423 * This property is analogous to the maxBERSize configuration
424 * attribute of the Sun Java System Directory Server. This can help
425 * prevent denial-of-service attacks by clients that indicate they
426 * send extremely large requests to the server causing it to attempt
427 * to allocate large amounts of memory.
428 *
429 * @param value The value of the "max-request-size" property.
430 * @throws IllegalPropertyValueException
431 * If the new value is invalid.
432 */
433 void setMaxRequestSize(Long value) throws IllegalPropertyValueException;
434
435
436
437 /**
438 * Gets the "num-request-handlers" property.
439 * <p>
440 * Specifies the number of request handlers that are used to read
441 * requests from clients.
442 * <p>
443 * The LDAP Connection Handler uses one thread to accept new
444 * connections from clients, but uses one or more additional threads
445 * to read requests from existing client connections. This ensures
446 * that new requests are read efficiently and that the connection
447 * handler itself does not become a bottleneck when the server is
448 * under heavy load from many clients at the same time.
449 *
450 * @return Returns the value of the "num-request-handlers" property.
451 */
452 int getNumRequestHandlers();
453
454
455
456 /**
457 * Sets the "num-request-handlers" property.
458 * <p>
459 * Specifies the number of request handlers that are used to read
460 * requests from clients.
461 * <p>
462 * The LDAP Connection Handler uses one thread to accept new
463 * connections from clients, but uses one or more additional threads
464 * to read requests from existing client connections. This ensures
465 * that new requests are read efficiently and that the connection
466 * handler itself does not become a bottleneck when the server is
467 * under heavy load from many clients at the same time.
468 *
469 * @param value The value of the "num-request-handlers" property.
470 * @throws IllegalPropertyValueException
471 * If the new value is invalid.
472 */
473 void setNumRequestHandlers(Integer value) throws IllegalPropertyValueException;
474
475
476
477 /**
478 * Gets the "send-rejection-notice" property.
479 * <p>
480 * Indicates whether the LDAP Connection Handler should send a
481 * notice of disconnection extended response message to the client if
482 * a new connection is rejected for some reason.
483 * <p>
484 * The extended response message may provide an explanation
485 * indicating the reason that the connection was rejected.
486 *
487 * @return Returns the value of the "send-rejection-notice" property.
488 */
489 boolean isSendRejectionNotice();
490
491
492
493 /**
494 * Sets the "send-rejection-notice" property.
495 * <p>
496 * Indicates whether the LDAP Connection Handler should send a
497 * notice of disconnection extended response message to the client if
498 * a new connection is rejected for some reason.
499 * <p>
500 * The extended response message may provide an explanation
501 * indicating the reason that the connection was rejected.
502 *
503 * @param value The value of the "send-rejection-notice" property.
504 * @throws IllegalPropertyValueException
505 * If the new value is invalid.
506 */
507 void setSendRejectionNotice(Boolean value) throws IllegalPropertyValueException;
508
509
510
511 /**
512 * Gets the "ssl-cert-nickname" property.
513 * <p>
514 * Specifies the nickname (also called the alias) of the certificate
515 * that the LDAP Connection Handler should use when performing SSL
516 * communication.
517 * <p>
518 * This is only applicable when the LDAP Connection Handler is
519 * configured to use SSL.
520 *
521 * @return Returns the value of the "ssl-cert-nickname" property.
522 */
523 String getSSLCertNickname();
524
525
526
527 /**
528 * Sets the "ssl-cert-nickname" property.
529 * <p>
530 * Specifies the nickname (also called the alias) of the certificate
531 * that the LDAP Connection Handler should use when performing SSL
532 * communication.
533 * <p>
534 * This is only applicable when the LDAP Connection Handler is
535 * configured to use SSL.
536 *
537 * @param value The value of the "ssl-cert-nickname" property.
538 * @throws IllegalPropertyValueException
539 * If the new value is invalid.
540 */
541 void setSSLCertNickname(String value) throws IllegalPropertyValueException;
542
543
544
545 /**
546 * Gets the "ssl-cipher-suite" property.
547 * <p>
548 * Specifies the names of the SSL cipher suites that are allowed for
549 * use in SSL or StartTLS communication.
550 *
551 * @return Returns the values of the "ssl-cipher-suite" property.
552 */
553 SortedSet<String> getSSLCipherSuite();
554
555
556
557 /**
558 * Sets the "ssl-cipher-suite" property.
559 * <p>
560 * Specifies the names of the SSL cipher suites that are allowed for
561 * use in SSL or StartTLS communication.
562 *
563 * @param values The values of the "ssl-cipher-suite" property.
564 * @throws IllegalPropertyValueException
565 * If one or more of the new values are invalid.
566 */
567 void setSSLCipherSuite(Collection<String> values) throws IllegalPropertyValueException;
568
569
570
571 /**
572 * Gets the "ssl-client-auth-policy" property.
573 * <p>
574 * Specifies the policy that the LDAP Connection Handler should use
575 * regarding client SSL certificates.
576 * <p>
577 * This is only applicable if clients are allowed to use SSL.
578 *
579 * @return Returns the value of the "ssl-client-auth-policy" property.
580 */
581 SSLClientAuthPolicy getSSLClientAuthPolicy();
582
583
584
585 /**
586 * Sets the "ssl-client-auth-policy" property.
587 * <p>
588 * Specifies the policy that the LDAP Connection Handler should use
589 * regarding client SSL certificates.
590 * <p>
591 * This is only applicable if clients are allowed to use SSL.
592 *
593 * @param value The value of the "ssl-client-auth-policy" property.
594 * @throws IllegalPropertyValueException
595 * If the new value is invalid.
596 */
597 void setSSLClientAuthPolicy(SSLClientAuthPolicy value) throws IllegalPropertyValueException;
598
599
600
601 /**
602 * Gets the "ssl-protocol" property.
603 * <p>
604 * Specifies the names of the SSL protocols that are allowed for use
605 * in SSL or StartTLS communication.
606 *
607 * @return Returns the values of the "ssl-protocol" property.
608 */
609 SortedSet<String> getSSLProtocol();
610
611
612
613 /**
614 * Sets the "ssl-protocol" property.
615 * <p>
616 * Specifies the names of the SSL protocols that are allowed for use
617 * in SSL or StartTLS communication.
618 *
619 * @param values The values of the "ssl-protocol" property.
620 * @throws IllegalPropertyValueException
621 * If one or more of the new values are invalid.
622 */
623 void setSSLProtocol(Collection<String> values) throws IllegalPropertyValueException;
624
625
626
627 /**
628 * Gets the "trust-manager-provider" property.
629 * <p>
630 * Specifies the name of the trust manager that should be used with
631 * the LDAP Connection Handler .
632 *
633 * @return Returns the value of the "trust-manager-provider" property.
634 */
635 String getTrustManagerProvider();
636
637
638
639 /**
640 * Sets the "trust-manager-provider" property.
641 * <p>
642 * Specifies the name of the trust manager that should be used with
643 * the LDAP Connection Handler .
644 *
645 * @param value The value of the "trust-manager-provider" property.
646 * @throws IllegalPropertyValueException
647 * If the new value is invalid.
648 */
649 void setTrustManagerProvider(String value) throws IllegalPropertyValueException;
650
651
652
653 /**
654 * Gets the "use-ssl" property.
655 * <p>
656 * Indicates whether the LDAP Connection Handler should use SSL.
657 * <p>
658 * If enabled, the LDAP Connection Handler will use SSL to encrypt
659 * communication with the clients.
660 *
661 * @return Returns the value of the "use-ssl" property.
662 */
663 boolean isUseSSL();
664
665
666
667 /**
668 * Sets the "use-ssl" property.
669 * <p>
670 * Indicates whether the LDAP Connection Handler should use SSL.
671 * <p>
672 * If enabled, the LDAP Connection Handler will use SSL to encrypt
673 * communication with the clients.
674 *
675 * @param value The value of the "use-ssl" property.
676 * @throws IllegalPropertyValueException
677 * If the new value is invalid.
678 */
679 void setUseSSL(Boolean value) throws IllegalPropertyValueException;
680
681
682
683 /**
684 * Gets the "use-tcp-keep-alive" property.
685 * <p>
686 * Indicates whether the LDAP Connection Handler should use TCP
687 * keep-alive.
688 * <p>
689 * If enabled, the SO_KEEPALIVE socket option is used to indicate
690 * that TCP keepalive messages should periodically be sent to the
691 * client to verify that the associated connection is still valid.
692 * This may also help prevent cases in which intermediate network
693 * hardware could silently drop an otherwise idle client connection,
694 * provided that the keepalive interval configured in the underlying
695 * operating system is smaller than the timeout enforced by the
696 * network hardware.
697 *
698 * @return Returns the value of the "use-tcp-keep-alive" property.
699 */
700 boolean isUseTCPKeepAlive();
701
702
703
704 /**
705 * Sets the "use-tcp-keep-alive" property.
706 * <p>
707 * Indicates whether the LDAP Connection Handler should use TCP
708 * keep-alive.
709 * <p>
710 * If enabled, the SO_KEEPALIVE socket option is used to indicate
711 * that TCP keepalive messages should periodically be sent to the
712 * client to verify that the associated connection is still valid.
713 * This may also help prevent cases in which intermediate network
714 * hardware could silently drop an otherwise idle client connection,
715 * provided that the keepalive interval configured in the underlying
716 * operating system is smaller than the timeout enforced by the
717 * network hardware.
718 *
719 * @param value The value of the "use-tcp-keep-alive" property.
720 * @throws IllegalPropertyValueException
721 * If the new value is invalid.
722 */
723 void setUseTCPKeepAlive(Boolean value) throws IllegalPropertyValueException;
724
725
726
727 /**
728 * Gets the "use-tcp-no-delay" property.
729 * <p>
730 * Indicates whether the LDAP Connection Handler should use TCP
731 * no-delay.
732 * <p>
733 * If enabled, the TCP_NODELAY socket option is used to ensure that
734 * response messages to the client are sent immediately rather than
735 * potentially waiting to determine whether additional response
736 * messages can be sent in the same packet. In most cases, using the
737 * TCP_NODELAY socket option provides better performance and lower
738 * response times, but disabling it may help for some cases in which
739 * the server sends a large number of entries to a client in response
740 * to a search request.
741 *
742 * @return Returns the value of the "use-tcp-no-delay" property.
743 */
744 boolean isUseTCPNoDelay();
745
746
747
748 /**
749 * Sets the "use-tcp-no-delay" property.
750 * <p>
751 * Indicates whether the LDAP Connection Handler should use TCP
752 * no-delay.
753 * <p>
754 * If enabled, the TCP_NODELAY socket option is used to ensure that
755 * response messages to the client are sent immediately rather than
756 * potentially waiting to determine whether additional response
757 * messages can be sent in the same packet. In most cases, using the
758 * TCP_NODELAY socket option provides better performance and lower
759 * response times, but disabling it may help for some cases in which
760 * the server sends a large number of entries to a client in response
761 * to a search request.
762 *
763 * @param value The value of the "use-tcp-no-delay" property.
764 * @throws IllegalPropertyValueException
765 * If the new value is invalid.
766 */
767 void setUseTCPNoDelay(Boolean value) throws IllegalPropertyValueException;
768
769 }