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