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}