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}