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