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 nicknames (also called the aliases) of the
540   * certificates that the HTTP Connection Handler should use when
541   * performing SSL communication. The property can be used multiple
542   * times (referencing different nicknames) when an RSA, a DSA, and an
543   * ECC based server certificate is used in parallel.
544   * <p>
545   * This is only applicable when the HTTP Connection Handler is
546   * configured to use SSL.
547   *
548   * @return Returns the values of the "ssl-cert-nickname" property.
549   */
550  SortedSet<String> getSSLCertNickname();
551
552
553
554  /**
555   * Sets the "ssl-cert-nickname" property.
556   * <p>
557   * Specifies the nicknames (also called the aliases) of the
558   * certificates that the HTTP Connection Handler should use when
559   * performing SSL communication. The property can be used multiple
560   * times (referencing different nicknames) when an RSA, a DSA, and an
561   * ECC based server certificate is used in parallel.
562   * <p>
563   * This is only applicable when the HTTP Connection Handler is
564   * configured to use SSL.
565   *
566   * @param values The values of the "ssl-cert-nickname" property.
567   * @throws PropertyException
568   *           If one or more of the new values are invalid.
569   */
570  void setSSLCertNickname(Collection<String> values) throws PropertyException;
571
572
573
574  /**
575   * Gets the "ssl-cipher-suite" property.
576   * <p>
577   * Specifies the names of the SSL cipher suites that are allowed for
578   * use in SSL communication.
579   *
580   * @return Returns the values of the "ssl-cipher-suite" property.
581   */
582  SortedSet<String> getSSLCipherSuite();
583
584
585
586  /**
587   * Sets the "ssl-cipher-suite" property.
588   * <p>
589   * Specifies the names of the SSL cipher suites that are allowed for
590   * use in SSL communication.
591   *
592   * @param values The values of the "ssl-cipher-suite" property.
593   * @throws PropertyException
594   *           If one or more of the new values are invalid.
595   */
596  void setSSLCipherSuite(Collection<String> values) throws PropertyException;
597
598
599
600  /**
601   * Gets the "ssl-client-auth-policy" property.
602   * <p>
603   * Specifies the policy that the HTTP Connection Handler should use
604   * regarding client SSL certificates. Clients can use the SASL
605   * EXTERNAL mechanism only if the policy is set to "optional" or
606   * "required".
607   * <p>
608   * This is only applicable if clients are allowed to use SSL.
609   *
610   * @return Returns the value of the "ssl-client-auth-policy" property.
611   */
612  SSLClientAuthPolicy getSSLClientAuthPolicy();
613
614
615
616  /**
617   * Sets the "ssl-client-auth-policy" property.
618   * <p>
619   * Specifies the policy that the HTTP Connection Handler should use
620   * regarding client SSL certificates. Clients can use the SASL
621   * EXTERNAL mechanism only if the policy is set to "optional" or
622   * "required".
623   * <p>
624   * This is only applicable if clients are allowed to use SSL.
625   *
626   * @param value The value of the "ssl-client-auth-policy" property.
627   * @throws PropertyException
628   *           If the new value is invalid.
629   */
630  void setSSLClientAuthPolicy(SSLClientAuthPolicy value) throws PropertyException;
631
632
633
634  /**
635   * Gets the "ssl-protocol" property.
636   * <p>
637   * Specifies the names of the SSL protocols that are allowed for use
638   * in SSL communication.
639   *
640   * @return Returns the values of the "ssl-protocol" property.
641   */
642  SortedSet<String> getSSLProtocol();
643
644
645
646  /**
647   * Sets the "ssl-protocol" property.
648   * <p>
649   * Specifies the names of the SSL protocols that are allowed for use
650   * in SSL communication.
651   *
652   * @param values The values of the "ssl-protocol" property.
653   * @throws PropertyException
654   *           If one or more of the new values are invalid.
655   */
656  void setSSLProtocol(Collection<String> values) throws PropertyException;
657
658
659
660  /**
661   * Gets the "trust-manager-provider" property.
662   * <p>
663   * Specifies the name of the trust manager that should be used with
664   * the HTTP Connection Handler .
665   *
666   * @return Returns the value of the "trust-manager-provider" property.
667   */
668  String getTrustManagerProvider();
669
670
671
672  /**
673   * Sets the "trust-manager-provider" property.
674   * <p>
675   * Specifies the name of the trust manager that should be used with
676   * the HTTP Connection Handler .
677   *
678   * @param value The value of the "trust-manager-provider" property.
679   * @throws PropertyException
680   *           If the new value is invalid.
681   */
682  void setTrustManagerProvider(String value) throws PropertyException;
683
684
685
686  /**
687   * Gets the "use-ssl" property.
688   * <p>
689   * Indicates whether the HTTP Connection Handler should use SSL.
690   * <p>
691   * If enabled, the HTTP Connection Handler will use SSL to encrypt
692   * communication with the clients.
693   *
694   * @return Returns the value of the "use-ssl" property.
695   */
696  boolean isUseSSL();
697
698
699
700  /**
701   * Sets the "use-ssl" property.
702   * <p>
703   * Indicates whether the HTTP Connection Handler should use SSL.
704   * <p>
705   * If enabled, the HTTP Connection Handler will use SSL to encrypt
706   * communication with the clients.
707   *
708   * @param value The value of the "use-ssl" property.
709   * @throws PropertyException
710   *           If the new value is invalid.
711   */
712  void setUseSSL(Boolean value) throws PropertyException;
713
714
715
716  /**
717   * Gets the "use-tcp-keep-alive" property.
718   * <p>
719   * Indicates whether the HTTP Connection Handler should use TCP
720   * keep-alive.
721   * <p>
722   * If enabled, the SO_KEEPALIVE socket option is used to indicate
723   * that TCP keepalive messages should periodically be sent to the
724   * client to verify that the associated connection is still valid.
725   * This may also help prevent cases in which intermediate network
726   * hardware could silently drop an otherwise idle client connection,
727   * provided that the keepalive interval configured in the underlying
728   * operating system is smaller than the timeout enforced by the
729   * network hardware.
730   *
731   * @return Returns the value of the "use-tcp-keep-alive" property.
732   */
733  boolean isUseTCPKeepAlive();
734
735
736
737  /**
738   * Sets the "use-tcp-keep-alive" property.
739   * <p>
740   * Indicates whether the HTTP Connection Handler should use TCP
741   * keep-alive.
742   * <p>
743   * If enabled, the SO_KEEPALIVE socket option is used to indicate
744   * that TCP keepalive messages should periodically be sent to the
745   * client to verify that the associated connection is still valid.
746   * This may also help prevent cases in which intermediate network
747   * hardware could silently drop an otherwise idle client connection,
748   * provided that the keepalive interval configured in the underlying
749   * operating system is smaller than the timeout enforced by the
750   * network hardware.
751   *
752   * @param value The value of the "use-tcp-keep-alive" property.
753   * @throws PropertyException
754   *           If the new value is invalid.
755   */
756  void setUseTCPKeepAlive(Boolean value) throws PropertyException;
757
758
759
760  /**
761   * Gets the "use-tcp-no-delay" property.
762   * <p>
763   * Indicates whether the HTTP Connection Handler should use TCP
764   * no-delay.
765   * <p>
766   * If enabled, the TCP_NODELAY socket option is used to ensure that
767   * response messages to the client are sent immediately rather than
768   * potentially waiting to determine whether additional response
769   * messages can be sent in the same packet. In most cases, using the
770   * TCP_NODELAY socket option provides better performance and lower
771   * response times, but disabling it may help for some cases in which
772   * the server sends a large number of entries to a client in response
773   * to a search request.
774   *
775   * @return Returns the value of the "use-tcp-no-delay" property.
776   */
777  boolean isUseTCPNoDelay();
778
779
780
781  /**
782   * Sets the "use-tcp-no-delay" property.
783   * <p>
784   * Indicates whether the HTTP Connection Handler should use TCP
785   * no-delay.
786   * <p>
787   * If enabled, the TCP_NODELAY socket option is used to ensure that
788   * response messages to the client are sent immediately rather than
789   * potentially waiting to determine whether additional response
790   * messages can be sent in the same packet. In most cases, using the
791   * TCP_NODELAY socket option provides better performance and lower
792   * response times, but disabling it may help for some cases in which
793   * the server sends a large number of entries to a client in response
794   * to a search request.
795   *
796   * @param value The value of the "use-tcp-no-delay" property.
797   * @throws PropertyException
798   *           If the new value is invalid.
799   */
800  void setUseTCPNoDelay(Boolean value) throws PropertyException;
801
802}