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 }