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.client;
027
028
029
030import java.net.InetAddress;
031import java.util.Collection;
032import java.util.SortedSet;
033import org.opends.server.admin.ManagedObjectDefinition;
034import org.opends.server.admin.PropertyException;
035import org.opends.server.admin.std.meta.HTTPConnectionHandlerCfgDefn.SSLClientAuthPolicy;
036import org.opends.server.admin.std.server.HTTPConnectionHandlerCfg;
037
038
039
040/**
041 * A client-side interface for reading and modifying HTTP Connection
042 * Handler settings.
043 * <p>
044 * The HTTP Connection Handler is used to interact with clients using
045 * HTTP.
046 */
047public interface HTTPConnectionHandlerCfgClient extends ConnectionHandlerCfgClient {
048
049  /**
050   * Get the configuration definition associated with this HTTP Connection Handler.
051   *
052   * @return Returns the configuration definition associated with this HTTP Connection Handler.
053   */
054  ManagedObjectDefinition<? extends HTTPConnectionHandlerCfgClient, ? extends HTTPConnectionHandlerCfg> definition();
055
056
057
058  /**
059   * Gets the "accept-backlog" property.
060   * <p>
061   * Specifies the maximum number of pending connection attempts that
062   * are allowed to queue up in the accept backlog before the server
063   * starts rejecting new connection attempts.
064   * <p>
065   * This is primarily an issue for cases in which a large number of
066   * connections are established to the server in a very short period
067   * of time (for example, a benchmark utility that creates a large
068   * number of client threads that each have their own connection to
069   * the server) and the connection handler is unable to keep up with
070   * the rate at which the new connections are established.
071   *
072   * @return Returns the value of the "accept-backlog" property.
073   */
074  int getAcceptBacklog();
075
076
077
078  /**
079   * Sets the "accept-backlog" property.
080   * <p>
081   * Specifies the maximum number of pending connection attempts that
082   * are allowed to queue up in the accept backlog before the server
083   * starts rejecting new connection attempts.
084   * <p>
085   * This is primarily an issue for cases in which a large number of
086   * connections are established to the server in a very short period
087   * of time (for example, a benchmark utility that creates a large
088   * number of client threads that each have their own connection to
089   * the server) and the connection handler is unable to keep up with
090   * the rate at which the new connections are established.
091   *
092   * @param value The value of the "accept-backlog" property.
093   * @throws PropertyException
094   *           If the new value is invalid.
095   */
096  void setAcceptBacklog(Integer value) throws PropertyException;
097
098
099
100  /**
101   * Gets the "allow-tcp-reuse-address" property.
102   * <p>
103   * Indicates whether the HTTP Connection Handler should reuse socket
104   * descriptors.
105   * <p>
106   * If enabled, the SO_REUSEADDR socket option is used on the server
107   * listen socket to potentially allow the reuse of socket descriptors
108   * for clients in a TIME_WAIT state. This may help the server avoid
109   * temporarily running out of socket descriptors in cases in which a
110   * very large number of short-lived connections have been established
111   * from the same client system.
112   *
113   * @return Returns the value of the "allow-tcp-reuse-address" property.
114   */
115  boolean isAllowTCPReuseAddress();
116
117
118
119  /**
120   * Sets the "allow-tcp-reuse-address" property.
121   * <p>
122   * Indicates whether the HTTP Connection Handler should reuse socket
123   * descriptors.
124   * <p>
125   * If enabled, the SO_REUSEADDR socket option is used on the server
126   * listen socket to potentially allow the reuse of socket descriptors
127   * for clients in a TIME_WAIT state. This may help the server avoid
128   * temporarily running out of socket descriptors in cases in which a
129   * very large number of short-lived connections have been established
130   * from the same client system.
131   *
132   * @param value The value of the "allow-tcp-reuse-address" property.
133   * @throws PropertyException
134   *           If the new value is invalid.
135   */
136  void setAllowTCPReuseAddress(Boolean value) throws PropertyException;
137
138
139
140  /**
141   * Gets the "authentication-required" property.
142   * <p>
143   * Specifies whether only authenticated requests can be processed by
144   * the HTTP Connection Handler.
145   * <p>
146   * If true, only authenticated requests will be processed by the
147   * HTTP Connection Handler. If false, both authenticated requests and
148   * unauthenticated requests will be processed. All requests are
149   * subject to ACI limitations and unauthenticated requests are
150   * subject to server limits like maximum number of entries returned.
151   * Note that setting ds-cfg-reject-unauthenticated-requests to true
152   * will override the current setting.
153   *
154   * @return Returns the value of the "authentication-required" property.
155   */
156  boolean isAuthenticationRequired();
157
158
159
160  /**
161   * Sets the "authentication-required" property.
162   * <p>
163   * Specifies whether only authenticated requests can be processed by
164   * the HTTP Connection Handler.
165   * <p>
166   * If true, only authenticated requests will be processed by the
167   * HTTP Connection Handler. If false, both authenticated requests and
168   * unauthenticated requests will be processed. All requests are
169   * subject to ACI limitations and unauthenticated requests are
170   * subject to server limits like maximum number of entries returned.
171   * Note that setting ds-cfg-reject-unauthenticated-requests to true
172   * will override the current setting.
173   *
174   * @param value The value of the "authentication-required" property.
175   * @throws PropertyException
176   *           If the new value is invalid.
177   */
178  void setAuthenticationRequired(boolean value) throws PropertyException;
179
180
181
182  /**
183   * Gets the "buffer-size" property.
184   * <p>
185   * Specifies the size in bytes of the HTTP response message write
186   * buffer.
187   * <p>
188   * This property specifies write buffer size allocated by the server
189   * for each client connection and used to buffer HTTP response
190   * messages data when writing.
191   *
192   * @return Returns the value of the "buffer-size" property.
193   */
194  long getBufferSize();
195
196
197
198  /**
199   * Sets the "buffer-size" property.
200   * <p>
201   * Specifies the size in bytes of the HTTP response message write
202   * buffer.
203   * <p>
204   * This property specifies write buffer size allocated by the server
205   * for each client connection and used to buffer HTTP response
206   * messages data when writing.
207   *
208   * @param value The value of the "buffer-size" property.
209   * @throws PropertyException
210   *           If the new value is invalid.
211   */
212  void setBufferSize(Long value) throws PropertyException;
213
214
215
216  /**
217   * Gets the "config-file" property.
218   * <p>
219   * Specifies the name of the configuration file for the HTTP
220   * Connection Handler.
221   *
222   * @return Returns the value of the "config-file" property.
223   */
224  String getConfigFile();
225
226
227
228  /**
229   * Sets the "config-file" property.
230   * <p>
231   * Specifies the name of the configuration file for the HTTP
232   * Connection Handler.
233   *
234   * @param value The value of the "config-file" property.
235   * @throws PropertyException
236   *           If the new value is invalid.
237   */
238  void setConfigFile(String value) throws PropertyException;
239
240
241
242  /**
243   * Gets the "java-class" property.
244   * <p>
245   * Specifies the fully-qualified name of the Java class that
246   * provides the HTTP Connection Handler implementation.
247   *
248   * @return Returns the value of the "java-class" property.
249   */
250  String getJavaClass();
251
252
253
254  /**
255   * Sets the "java-class" property.
256   * <p>
257   * Specifies the fully-qualified name of the Java class that
258   * provides the HTTP Connection Handler implementation.
259   *
260   * @param value The value of the "java-class" property.
261   * @throws PropertyException
262   *           If the new value is invalid.
263   */
264  void setJavaClass(String value) throws PropertyException;
265
266
267
268  /**
269   * Gets the "keep-stats" property.
270   * <p>
271   * Indicates whether the HTTP Connection Handler should keep
272   * statistics.
273   * <p>
274   * If enabled, the HTTP Connection Handler maintains statistics
275   * about the number and types of operations requested over HTTP and
276   * the amount of data sent and received.
277   *
278   * @return Returns the value of the "keep-stats" property.
279   */
280  boolean isKeepStats();
281
282
283
284  /**
285   * Sets the "keep-stats" property.
286   * <p>
287   * Indicates whether the HTTP Connection Handler should keep
288   * statistics.
289   * <p>
290   * If enabled, the HTTP Connection Handler maintains statistics
291   * about the number and types of operations requested over HTTP and
292   * the amount of data sent and received.
293   *
294   * @param value The value of the "keep-stats" property.
295   * @throws PropertyException
296   *           If the new value is invalid.
297   */
298  void setKeepStats(Boolean value) throws PropertyException;
299
300
301
302  /**
303   * Gets the "key-manager-provider" property.
304   * <p>
305   * Specifies the name of the key manager that should be used with
306   * this HTTP Connection Handler .
307   *
308   * @return Returns the value of the "key-manager-provider" property.
309   */
310  String getKeyManagerProvider();
311
312
313
314  /**
315   * Sets the "key-manager-provider" property.
316   * <p>
317   * Specifies the name of the key manager that should be used with
318   * this HTTP Connection Handler .
319   *
320   * @param value The value of the "key-manager-provider" property.
321   * @throws PropertyException
322   *           If the new value is invalid.
323   */
324  void setKeyManagerProvider(String value) throws PropertyException;
325
326
327
328  /**
329   * Gets the "listen-address" property.
330   * <p>
331   * Specifies the address or set of addresses on which this HTTP
332   * Connection Handler should listen for connections from HTTP
333   * clients.
334   * <p>
335   * Multiple addresses may be provided as separate values for this
336   * attribute. If no values are provided, then the HTTP Connection
337   * Handler listens on all interfaces.
338   *
339   * @return Returns the values of the "listen-address" property.
340   */
341  SortedSet<InetAddress> getListenAddress();
342
343
344
345  /**
346   * Sets the "listen-address" property.
347   * <p>
348   * Specifies the address or set of addresses on which this HTTP
349   * Connection Handler should listen for connections from HTTP
350   * clients.
351   * <p>
352   * Multiple addresses may be provided as separate values for this
353   * attribute. If no values are provided, then the HTTP Connection
354   * Handler listens on all interfaces.
355   *
356   * @param values The values of the "listen-address" property.
357   * @throws PropertyException
358   *           If one or more of the new values are invalid.
359   */
360  void setListenAddress(Collection<InetAddress> values) throws PropertyException;
361
362
363
364  /**
365   * Gets the "listen-port" property.
366   * <p>
367   * Specifies the port number on which the HTTP Connection Handler
368   * will listen for connections from clients.
369   * <p>
370   * Only a single port number may be provided.
371   *
372   * @return Returns the value of the "listen-port" property.
373   */
374  Integer getListenPort();
375
376
377
378  /**
379   * Sets the "listen-port" property.
380   * <p>
381   * Specifies the port number on which the HTTP Connection Handler
382   * will listen for connections from clients.
383   * <p>
384   * Only a single port number may be provided.
385   *
386   * @param value The value of the "listen-port" property.
387   * @throws PropertyException
388   *           If the new value is invalid.
389   */
390  void setListenPort(int value) throws PropertyException;
391
392
393
394  /**
395   * Gets the "max-blocked-write-time-limit" property.
396   * <p>
397   * Specifies the maximum length of time that attempts to write data
398   * to HTTP clients should be allowed to block.
399   * <p>
400   * If an attempt to write data to a client takes longer than this
401   * length of time, then the client connection is terminated.
402   *
403   * @return Returns the value of the "max-blocked-write-time-limit" property.
404   */
405  long getMaxBlockedWriteTimeLimit();
406
407
408
409  /**
410   * Sets the "max-blocked-write-time-limit" property.
411   * <p>
412   * Specifies the maximum length of time that attempts to write data
413   * to HTTP clients should be allowed to block.
414   * <p>
415   * If an attempt to write data to a client takes longer than this
416   * length of time, then the client connection is terminated.
417   *
418   * @param value The value of the "max-blocked-write-time-limit" property.
419   * @throws PropertyException
420   *           If the new value is invalid.
421   */
422  void setMaxBlockedWriteTimeLimit(Long value) throws PropertyException;
423
424
425
426  /**
427   * Gets the "max-concurrent-ops-per-connection" property.
428   * <p>
429   * Specifies the maximum number of internal operations that each
430   * HTTP client connection can execute concurrently.
431   * <p>
432   * This property allow to limit the impact that each HTTP request
433   * can have on the whole server by limiting the number of internal
434   * operations that each HTTP request can execute concurrently. A
435   * value of 0 means that no limit is enforced.
436   *
437   * @return Returns the value of the "max-concurrent-ops-per-connection" property.
438   */
439  Integer getMaxConcurrentOpsPerConnection();
440
441
442
443  /**
444   * Sets the "max-concurrent-ops-per-connection" property.
445   * <p>
446   * Specifies the maximum number of internal operations that each
447   * HTTP client connection can execute concurrently.
448   * <p>
449   * This property allow to limit the impact that each HTTP request
450   * can have on the whole server by limiting the number of internal
451   * operations that each HTTP request can execute concurrently. A
452   * value of 0 means that no limit is enforced.
453   *
454   * @param value The value of the "max-concurrent-ops-per-connection" property.
455   * @throws PropertyException
456   *           If the new value is invalid.
457   */
458  void setMaxConcurrentOpsPerConnection(Integer value) throws PropertyException;
459
460
461
462  /**
463   * Gets the "max-request-size" property.
464   * <p>
465   * Specifies the size in bytes of the largest HTTP request message
466   * that will be allowed by the HTTP Connection Handler.
467   * <p>
468   * This can help prevent denial-of-service attacks by clients that
469   * indicate they send extremely large requests to the server causing
470   * it to attempt to allocate large amounts of memory.
471   *
472   * @return Returns the value of the "max-request-size" property.
473   */
474  long getMaxRequestSize();
475
476
477
478  /**
479   * Sets the "max-request-size" property.
480   * <p>
481   * Specifies the size in bytes of the largest HTTP request message
482   * that will be allowed by the HTTP Connection Handler.
483   * <p>
484   * This can help prevent denial-of-service attacks by clients that
485   * indicate they send extremely large requests to the server causing
486   * it to attempt to allocate large amounts of memory.
487   *
488   * @param value The value of the "max-request-size" property.
489   * @throws PropertyException
490   *           If the new value is invalid.
491   */
492  void setMaxRequestSize(Long value) throws PropertyException;
493
494
495
496  /**
497   * Gets the "num-request-handlers" property.
498   * <p>
499   * Specifies the number of request handlers that are used to read
500   * requests from clients.
501   * <p>
502   * The HTTP Connection Handler uses one thread to accept new
503   * connections from clients, but uses one or more additional threads
504   * to read requests from existing client connections. This ensures
505   * that new requests are read efficiently and that the connection
506   * handler itself does not become a bottleneck when the server is
507   * under heavy load from many clients at the same time.
508   *
509   * @return Returns the value of the "num-request-handlers" property.
510   */
511  Integer getNumRequestHandlers();
512
513
514
515  /**
516   * Sets the "num-request-handlers" property.
517   * <p>
518   * Specifies the number of request handlers that are used to read
519   * requests from clients.
520   * <p>
521   * The HTTP Connection Handler uses one thread to accept new
522   * connections from clients, but uses one or more additional threads
523   * to read requests from existing client connections. This ensures
524   * that new requests are read efficiently and that the connection
525   * handler itself does not become a bottleneck when the server is
526   * under heavy load from many clients at the same time.
527   *
528   * @param value The value of the "num-request-handlers" property.
529   * @throws PropertyException
530   *           If the new value is invalid.
531   */
532  void setNumRequestHandlers(Integer value) throws PropertyException;
533
534
535
536  /**
537   * Gets the "ssl-cert-nickname" property.
538   * <p>
539   * Specifies the nickname (also called the alias) of the certificate
540   * that the HTTP Connection Handler should use when performing SSL
541   * communication.
542   * <p>
543   * This is only applicable when the HTTP Connection Handler is
544   * configured to use SSL.
545   *
546   * @return Returns the value of the "ssl-cert-nickname" property.
547   */
548  String getSSLCertNickname();
549
550
551
552  /**
553   * Sets the "ssl-cert-nickname" property.
554   * <p>
555   * Specifies the nickname (also called the alias) of the certificate
556   * that the HTTP Connection Handler should use when performing SSL
557   * communication.
558   * <p>
559   * This is only applicable when the HTTP Connection Handler is
560   * configured to use SSL.
561   *
562   * @param value The value of the "ssl-cert-nickname" property.
563   * @throws PropertyException
564   *           If the new value is invalid.
565   */
566  void setSSLCertNickname(String value) throws PropertyException;
567
568
569
570  /**
571   * Gets the "ssl-cipher-suite" property.
572   * <p>
573   * Specifies the names of the SSL cipher suites that are allowed for
574   * use in SSL communication.
575   *
576   * @return Returns the values of the "ssl-cipher-suite" property.
577   */
578  SortedSet<String> getSSLCipherSuite();
579
580
581
582  /**
583   * Sets the "ssl-cipher-suite" property.
584   * <p>
585   * Specifies the names of the SSL cipher suites that are allowed for
586   * use in SSL communication.
587   *
588   * @param values The values of the "ssl-cipher-suite" property.
589   * @throws PropertyException
590   *           If one or more of the new values are invalid.
591   */
592  void setSSLCipherSuite(Collection<String> values) throws PropertyException;
593
594
595
596  /**
597   * Gets the "ssl-client-auth-policy" property.
598   * <p>
599   * Specifies the policy that the HTTP Connection Handler should use
600   * regarding client SSL certificates. Clients can use the SASL
601   * EXTERNAL mechanism only if the policy is set to "optional" or
602   * "required".
603   * <p>
604   * This is only applicable if clients are allowed to use SSL.
605   *
606   * @return Returns the value of the "ssl-client-auth-policy" property.
607   */
608  SSLClientAuthPolicy getSSLClientAuthPolicy();
609
610
611
612  /**
613   * Sets the "ssl-client-auth-policy" property.
614   * <p>
615   * Specifies the policy that the HTTP Connection Handler should use
616   * regarding client SSL certificates. Clients can use the SASL
617   * EXTERNAL mechanism only if the policy is set to "optional" or
618   * "required".
619   * <p>
620   * This is only applicable if clients are allowed to use SSL.
621   *
622   * @param value The value of the "ssl-client-auth-policy" property.
623   * @throws PropertyException
624   *           If the new value is invalid.
625   */
626  void setSSLClientAuthPolicy(SSLClientAuthPolicy value) throws PropertyException;
627
628
629
630  /**
631   * Gets the "ssl-protocol" property.
632   * <p>
633   * Specifies the names of the SSL protocols that are allowed for use
634   * in SSL communication.
635   *
636   * @return Returns the values of the "ssl-protocol" property.
637   */
638  SortedSet<String> getSSLProtocol();
639
640
641
642  /**
643   * Sets the "ssl-protocol" property.
644   * <p>
645   * Specifies the names of the SSL protocols that are allowed for use
646   * in SSL communication.
647   *
648   * @param values The values of the "ssl-protocol" property.
649   * @throws PropertyException
650   *           If one or more of the new values are invalid.
651   */
652  void setSSLProtocol(Collection<String> values) throws PropertyException;
653
654
655
656  /**
657   * Gets the "trust-manager-provider" property.
658   * <p>
659   * Specifies the name of the trust manager that should be used with
660   * the HTTP Connection Handler .
661   *
662   * @return Returns the value of the "trust-manager-provider" property.
663   */
664  String getTrustManagerProvider();
665
666
667
668  /**
669   * Sets the "trust-manager-provider" property.
670   * <p>
671   * Specifies the name of the trust manager that should be used with
672   * the HTTP Connection Handler .
673   *
674   * @param value The value of the "trust-manager-provider" property.
675   * @throws PropertyException
676   *           If the new value is invalid.
677   */
678  void setTrustManagerProvider(String value) throws PropertyException;
679
680
681
682  /**
683   * Gets the "use-ssl" property.
684   * <p>
685   * Indicates whether the HTTP Connection Handler should use SSL.
686   * <p>
687   * If enabled, the HTTP Connection Handler will use SSL to encrypt
688   * communication with the clients.
689   *
690   * @return Returns the value of the "use-ssl" property.
691   */
692  boolean isUseSSL();
693
694
695
696  /**
697   * Sets the "use-ssl" property.
698   * <p>
699   * Indicates whether the HTTP Connection Handler should use SSL.
700   * <p>
701   * If enabled, the HTTP Connection Handler will use SSL to encrypt
702   * communication with the clients.
703   *
704   * @param value The value of the "use-ssl" property.
705   * @throws PropertyException
706   *           If the new value is invalid.
707   */
708  void setUseSSL(Boolean value) throws PropertyException;
709
710
711
712  /**
713   * Gets the "use-tcp-keep-alive" property.
714   * <p>
715   * Indicates whether the HTTP Connection Handler should use TCP
716   * keep-alive.
717   * <p>
718   * If enabled, the SO_KEEPALIVE socket option is used to indicate
719   * that TCP keepalive messages should periodically be sent to the
720   * client to verify that the associated connection is still valid.
721   * This may also help prevent cases in which intermediate network
722   * hardware could silently drop an otherwise idle client connection,
723   * provided that the keepalive interval configured in the underlying
724   * operating system is smaller than the timeout enforced by the
725   * network hardware.
726   *
727   * @return Returns the value of the "use-tcp-keep-alive" property.
728   */
729  boolean isUseTCPKeepAlive();
730
731
732
733  /**
734   * Sets the "use-tcp-keep-alive" property.
735   * <p>
736   * Indicates whether the HTTP Connection Handler should use TCP
737   * keep-alive.
738   * <p>
739   * If enabled, the SO_KEEPALIVE socket option is used to indicate
740   * that TCP keepalive messages should periodically be sent to the
741   * client to verify that the associated connection is still valid.
742   * This may also help prevent cases in which intermediate network
743   * hardware could silently drop an otherwise idle client connection,
744   * provided that the keepalive interval configured in the underlying
745   * operating system is smaller than the timeout enforced by the
746   * network hardware.
747   *
748   * @param value The value of the "use-tcp-keep-alive" property.
749   * @throws PropertyException
750   *           If the new value is invalid.
751   */
752  void setUseTCPKeepAlive(Boolean value) throws PropertyException;
753
754
755
756  /**
757   * Gets the "use-tcp-no-delay" property.
758   * <p>
759   * Indicates whether the HTTP Connection Handler should use TCP
760   * no-delay.
761   * <p>
762   * If enabled, the TCP_NODELAY socket option is used to ensure that
763   * response messages to the client are sent immediately rather than
764   * potentially waiting to determine whether additional response
765   * messages can be sent in the same packet. In most cases, using the
766   * TCP_NODELAY socket option provides better performance and lower
767   * response times, but disabling it may help for some cases in which
768   * the server sends a large number of entries to a client in response
769   * to a search request.
770   *
771   * @return Returns the value of the "use-tcp-no-delay" property.
772   */
773  boolean isUseTCPNoDelay();
774
775
776
777  /**
778   * Sets the "use-tcp-no-delay" property.
779   * <p>
780   * Indicates whether the HTTP Connection Handler should use TCP
781   * no-delay.
782   * <p>
783   * If enabled, the TCP_NODELAY socket option is used to ensure that
784   * response messages to the client are sent immediately rather than
785   * potentially waiting to determine whether additional response
786   * messages can be sent in the same packet. In most cases, using the
787   * TCP_NODELAY socket option provides better performance and lower
788   * response times, but disabling it may help for some cases in which
789   * the server sends a large number of entries to a client in response
790   * to a search request.
791   *
792   * @param value The value of the "use-tcp-no-delay" property.
793   * @throws PropertyException
794   *           If the new value is invalid.
795   */
796  void setUseTCPNoDelay(Boolean value) throws PropertyException;
797
798}