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