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