HTTPCLIENT-716: new params for route planner, including a forced route

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@606447 13f79535-47bb-0310-9956-ffa450edef68

RELEASE_NOTES.txt

@@ -1,6 +1,12 @@
 Changes since 4.0 Alpha 2
 -------------------
 
+* [HTTPCLIENT-716] Allow application-defined routes.
+  Contributed by Roland Weber <rolandw at apache.org>
+
+* [HTTPCLIENT-712] Improve HttpRoute API
+  Contributed by Roland Weber <rolandw at apache.org>
+
 * [HTTPCLIENT-711] Bad route computed for redirected requests
   Contributed by Oleg Kalnichevski <olegk at apache.org>
 

module-client/src/main/java/org/apache/http/conn/params/ConnRoutePNames.java

@@ -38,7 +38,7 @@ package org.apache.http.conn.params;
  * @since 4.0
  */
 public interface ConnRoutePNames {
-     
+
     /**
      * Parameter for the default proxy.
      * The default value will be used by some
@@ -48,7 +48,40 @@ public interface ConnRoutePNames {
      * This parameter expects a value of type {@link org.apache.http.HttpHost}.
      * </p>
      */
-    public static final String DEFAULT_PROXY = "http.default-proxy";
+    public static final String DEFAULT_PROXY = "http.route.default-proxy";
+
+
+    /**
+     * Parameter for the local address.
+     * On machines with multiple network interfaces, this parameter
+     * can be used to select the network interface from which the
+     * connection originates.
+     * It will be interpreted by the standard
+     * {@link org.apache.http.conn.HttpRoutePlanner HttpRoutePlanner}
+     * implementations, in particular the default implementation.
+     * <p>
+     * This parameter expects a value of type {@link java.net.INetAddress}.
+     * </p>
+     */
+    public static final String LOCAL_ADDRESS = "http.route.local-address";
+
+
+    /**
+     * Parameter for an forced route.
+     * The forced route can be set as a parameter or a context attribute.
+     * If both are present, the context attribute takes precedence.
+     * The forced route will be interpreted by the standard
+     * {@link org.apache.http.conn.HttpRoutePlanner HttpRoutePlanner}
+     * implementations.
+     * Instead of computing a route, the given forced route will be
+     * returned, even if it points to the wrong target host.
+     * <p>
+     * This parameter or context attribute should be used with care.
+     * It expects a value of type
+     * {@link org.apache.http.conn.HttpRoute HttpRoute}.
+     * </p>
+     */
+    public static final String FORCED_ROUTE = "http.route.forced-route";
 
 }
 

module-client/src/main/java/org/apache/http/impl/conn/DefaultHttpRoutePlanner.java

@@ -31,6 +31,9 @@
 
 package org.apache.http.impl.conn;
 
+
+import java.net.InetAddress;
+
 import org.apache.http.HttpException;
 import org.apache.http.HttpHost;
 import org.apache.http.HttpRequest;
@@ -46,7 +49,7 @@ import org.apache.http.conn.params.ConnRoutePNames;
 
 /**
  * Default implementation of an {@link HttpRoutePlanner}.
- * This implementation is based on parameters.
+ * This implementation is based on {@link ConnRoutePNames parameters}.
  * It will not make use of any Java system properties.
  */
 public class DefaultHttpRoutePlanner implements HttpRoutePlanner {
@@ -72,29 +75,49 @@ public class DefaultHttpRoutePlanner implements HttpRoutePlanner {
                                     HttpContext context)
         throws HttpException {
 
-        if (target == null) {
-            throw new IllegalStateException
-                ("Target host must not be null.");
-        }
         if (request == null) {
             throw new IllegalStateException
                 ("Request must not be null.");
         }
 
-        HttpHost proxy = (HttpHost)
+        // If we have a forced route, we can do without a target.
+        // Check the context first, it might have been set by a retry handler.
+        HttpRoute route = null;
+        if (context != null) {
+            route = (HttpRoute)
+                context.getAttribute(ConnRoutePNames.FORCED_ROUTE);
+        }
+        if (route == null) {
+            route = (HttpRoute)
+                request.getParams().getParameter(ConnRoutePNames.FORCED_ROUTE);
+        }
+
+        if (route != null)
+            return route;
+
+        // If we get here, there is no forced route.
+        // So we need a target to compute a route.
+
+        if (target == null) {
+            throw new IllegalStateException
+                ("Target host must not be null.");
+        }
+
+        final InetAddress local = (InetAddress)
+            request.getParams().getParameter(ConnRoutePNames.LOCAL_ADDRESS);
+        final HttpHost proxy = (HttpHost)
             request.getParams().getParameter(ConnRoutePNames.DEFAULT_PROXY);
 
-        Scheme schm = this.connectionManager.getSchemeRegistry().
+        final Scheme schm = this.connectionManager.getSchemeRegistry().
             getScheme(target.getSchemeName());
         // as it is typically used for TLS/SSL, we assume that
         // a layered scheme implies a secure connection
-        boolean secure = schm.isLayered();
+        final boolean secure = schm.isLayered();
 
-        HttpRoute route = null;
         if (proxy == null) {
-            route = new HttpRoute(target, null, secure);
+            route = new HttpRoute(target, local, secure);
         } else {
-            route = new HttpRoute(target, null, proxy, secure);
+            route = new HttpRoute(target, local, proxy, secure);
         }
         return route;
     }