Merge pull request #33 from HubSpot/explain-httpconfig-settings

Add java docs to explain how the max connection settings are used

Author: jaredstehler

HorizonCore/src/main/java/com/hubspot/horizon/HttpConfig.java

@@ -78,10 +78,37 @@ public static Builder newBuilder() {
     return new Builder();
   }
 
+  /**
+   * The HttpClient will use this setting to throttle requests.
+   *
+   * If the client gets a request, but the max connections are already in use,
+   * the client will block indefinitely until it has a free connection for the request,
+   * then make the request once it's able.
+   *
+   * The default value is 100.
+   */
   public int getMaxConnections() {
     return maxConnections;
   }
 
+  /**
+   * Unlike {@link #getMaxConnections()}, the HttpClient will use this per-host setting to IMMEDIATELY FAIL any requests
+   * that would cause it to exceed the connections per host limit.
+   * The client does NOT block / wait for any amount of time if it gets a request when the max connections per host are already used up;
+   * instead, a {@link org.asynchttpclient.shaded.exception.TooManyConnectionsPerHostException} is thrown from the client immediately.
+   *
+   * Note, {@link #getConnectTimeoutMillis()} doesn't come into play in this connection limiting.
+   * Instead, the internal `acquireTimeout` is the timeout for acquiring a connection permit;
+   * this setting isn't exposed and the default is 0.
+   *
+   * If you want to use the client to throttle requests indefinitely without throwing exceptions for connection limits,
+   * use {@link Builder#setMaxConnectionsPerHost(int)} to a higher number than {@link #getMaxConnections()} works
+   * most of the time (except there's some race condition that can be hit when the client is being totally overwhelmed).
+   * If possible, it can be better to limit requests to the client.
+   * For example, it might be possible to limit a thread pool that uses the client accordingly.
+   *
+   * The default value is 25.
+   */
   public int getMaxConnectionsPerHost() {
     return maxConnectionsPerHost;
   }