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}