View Javadoc

1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  
28  package org.apache.http.conn.routing;
29  
30  import java.net.InetAddress;
31  import java.net.InetSocketAddress;
32  import java.util.ArrayList;
33  import java.util.Arrays;
34  import java.util.Collections;
35  import java.util.List;
36  
37  import org.apache.http.HttpHost;
38  import org.apache.http.annotation.Immutable;
39  import org.apache.http.util.Args;
40  import org.apache.http.util.LangUtils;
41  
42  /**
43   * The route for a request.
44   *
45   * @since 4.0
46   */
47  @Immutable
48  public final class HttpRoute implements RouteInfo, Cloneable {
49  
50      /** The target host to connect to. */
51      private final HttpHost targetHost;
52  
53      /**
54       * The local address to connect from.
55       * {@code null} indicates that the default should be used.
56       */
57      private final InetAddress localAddress;
58  
59      /** The proxy servers, if any. Never null. */
60      private final List<HttpHost> proxyChain;
61  
62      /** Whether the the route is tunnelled through the proxy. */
63      private final TunnelType tunnelled;
64  
65      /** Whether the route is layered. */
66      private final LayerType layered;
67  
68      /** Whether the route is (supposed to be) secure. */
69      private final boolean secure;
70  
71      private HttpRoute(final HttpHost target, final InetAddress local, final List<HttpHost> proxies,
72                       final boolean secure, final TunnelType tunnelled, final LayerType layered) {
73          Args.notNull(target, "Target host");
74          this.targetHost = normalize(target);
75          this.localAddress = local;
76          if (proxies != null && !proxies.isEmpty()) {
77              this.proxyChain = new ArrayList<HttpHost>(proxies);
78          } else {
79              this.proxyChain = null;
80          }
81          if (tunnelled == TunnelType.TUNNELLED) {
82              Args.check(this.proxyChain != null, "Proxy required if tunnelled");
83          }
84          this.secure       = secure;
85          this.tunnelled    = tunnelled != null ? tunnelled : TunnelType.PLAIN;
86          this.layered      = layered != null ? layered : LayerType.PLAIN;
87      }
88  
89      //TODO: to be removed in 5.0
90      private static int getDefaultPort(final String schemeName) {
91          if ("http".equalsIgnoreCase(schemeName)) {
92              return 80;
93          } else if ("https".equalsIgnoreCase(schemeName)) {
94              return 443;
95          } else {
96              return -1;
97          }
98  
99      }
100 
101     //TODO: to be removed in 5.0
102     private static HttpHost normalize(final HttpHost target) {
103         if (target.getPort() >= 0 ) {
104             return target;
105         } else {
106             final InetAddress address = target.getAddress();
107             final String schemeName = target.getSchemeName();
108             if (address != null) {
109                 return new HttpHost(address, getDefaultPort(schemeName), schemeName);
110             } else {
111                 final String hostName = target.getHostName();
112                 return new HttpHost(hostName, getDefaultPort(schemeName), schemeName);
113             }
114         }
115     }
116 
117     /**
118      * Creates a new route with all attributes specified explicitly.
119      *
120      * @param target    the host to which to route
121      * @param local     the local address to route from, or
122      *                  {@code null} for the default
123      * @param proxies   the proxy chain to use, or
124      *                  {@code null} for a direct route
125      * @param secure    {@code true} if the route is (to be) secure,
126      *                  {@code false} otherwise
127      * @param tunnelled the tunnel type of this route
128      * @param layered   the layering type of this route
129      */
130     public HttpRoute(final HttpHost target, final InetAddress local, final HttpHost[] proxies,
131                      final boolean secure, final TunnelType tunnelled, final LayerType layered) {
132         this(target, local, proxies != null ? Arrays.asList(proxies) : null,
133                 secure, tunnelled, layered);
134     }
135 
136     /**
137      * Creates a new route with at most one proxy.
138      *
139      * @param target    the host to which to route
140      * @param local     the local address to route from, or
141      *                  {@code null} for the default
142      * @param proxy     the proxy to use, or
143      *                  {@code null} for a direct route
144      * @param secure    {@code true} if the route is (to be) secure,
145      *                  {@code false} otherwise
146      * @param tunnelled {@code true} if the route is (to be) tunnelled
147      *                  via the proxy,
148      *                  {@code false} otherwise
149      * @param layered   {@code true} if the route includes a
150      *                  layered protocol,
151      *                  {@code false} otherwise
152      */
153     public HttpRoute(final HttpHost target, final InetAddress local, final HttpHost proxy,
154                      final boolean secure, final TunnelType tunnelled, final LayerType layered) {
155         this(target, local, proxy != null ? Collections.singletonList(proxy) : null,
156                 secure, tunnelled, layered);
157     }
158 
159     /**
160      * Creates a new direct route.
161      * That is a route without a proxy.
162      *
163      * @param target    the host to which to route
164      * @param local     the local address to route from, or
165      *                  {@code null} for the default
166      * @param secure    {@code true} if the route is (to be) secure,
167      *                  {@code false} otherwise
168      */
169     public HttpRoute(final HttpHost target, final InetAddress local, final boolean secure) {
170         this(target, local, Collections.<HttpHost>emptyList(), secure,
171                 TunnelType.PLAIN, LayerType.PLAIN);
172     }
173 
174     /**
175      * Creates a new direct insecure route.
176      *
177      * @param target    the host to which to route
178      */
179     public HttpRoute(final HttpHost target) {
180         this(target, null, Collections.<HttpHost>emptyList(), false,
181                 TunnelType.PLAIN, LayerType.PLAIN);
182     }
183 
184     /**
185      * Creates a new route through a proxy.
186      * When using this constructor, the {@code proxy} MUST be given.
187      * For convenience, it is assumed that a secure connection will be
188      * layered over a tunnel through the proxy.
189      *
190      * @param target    the host to which to route
191      * @param local     the local address to route from, or
192      *                  {@code null} for the default
193      * @param proxy     the proxy to use
194      * @param secure    {@code true} if the route is (to be) secure,
195      *                  {@code false} otherwise
196      */
197     public HttpRoute(final HttpHost target, final InetAddress local, final HttpHost proxy,
198                      final boolean secure) {
199         this(target, local, Collections.singletonList(Args.notNull(proxy, "Proxy host")), secure,
200              secure ? TunnelType.TUNNELLED : TunnelType.PLAIN,
201              secure ? LayerType.LAYERED    : LayerType.PLAIN);
202     }
203 
204     /**
205      * Creates a new plain route through a proxy.
206      *
207      * @param target    the host to which to route
208      * @param proxy     the proxy to use
209      *
210      * @since 4.3
211      */
212     public HttpRoute(final HttpHost target, final HttpHost proxy) {
213         this(target, null, proxy, false);
214     }
215 
216     @Override
217     public final HttpHost getTargetHost() {
218         return this.targetHost;
219     }
220 
221     @Override
222     public final InetAddress getLocalAddress() {
223         return this.localAddress;
224     }
225 
226     public final InetSocketAddress getLocalSocketAddress() {
227         return this.localAddress != null ? new InetSocketAddress(this.localAddress, 0) : null;
228     }
229 
230     @Override
231     public final int getHopCount() {
232         return proxyChain != null ? proxyChain.size() + 1 : 1;
233     }
234 
235     @Override
236     public final HttpHost getHopTarget(final int hop) {
237         Args.notNegative(hop, "Hop index");
238         final int hopcount = getHopCount();
239         Args.check(hop < hopcount, "Hop index exceeds tracked route length");
240         if (hop < hopcount - 1) {
241             return this.proxyChain.get(hop);
242         } else {
243             return this.targetHost;
244         }
245     }
246 
247     @Override
248     public final HttpHost getProxyHost() {
249         return proxyChain != null && !this.proxyChain.isEmpty() ? this.proxyChain.get(0) : null;
250     }
251 
252     @Override
253     public final TunnelType getTunnelType() {
254         return this.tunnelled;
255     }
256 
257     @Override
258     public final boolean isTunnelled() {
259         return (this.tunnelled == TunnelType.TUNNELLED);
260     }
261 
262     @Override
263     public final LayerType getLayerType() {
264         return this.layered;
265     }
266 
267     @Override
268     public final boolean isLayered() {
269         return (this.layered == LayerType.LAYERED);
270     }
271 
272     @Override
273     public final boolean isSecure() {
274         return this.secure;
275     }
276 
277     /**
278      * Compares this route to another.
279      *
280      * @param obj         the object to compare with
281      *
282      * @return  {@code true} if the argument is the same route,
283      *          {@code false}
284      */
285     @Override
286     public final boolean equals(final Object obj) {
287         if (this == obj) {
288             return true;
289         }
290         if (obj instanceof HttpRoute) {
291             final HttpRoute that = (HttpRoute) obj;
292             return
293                 // Do the cheapest tests first
294                 (this.secure    == that.secure) &&
295                 (this.tunnelled == that.tunnelled) &&
296                 (this.layered   == that.layered) &&
297                 LangUtils.equals(this.targetHost, that.targetHost) &&
298                 LangUtils.equals(this.localAddress, that.localAddress) &&
299                 LangUtils.equals(this.proxyChain, that.proxyChain);
300         } else {
301             return false;
302         }
303     }
304 
305 
306     /**
307      * Generates a hash code for this route.
308      *
309      * @return  the hash code
310      */
311     @Override
312     public final int hashCode() {
313         int hash = LangUtils.HASH_SEED;
314         hash = LangUtils.hashCode(hash, this.targetHost);
315         hash = LangUtils.hashCode(hash, this.localAddress);
316         if (this.proxyChain != null) {
317             for (final HttpHost element : this.proxyChain) {
318                 hash = LangUtils.hashCode(hash, element);
319             }
320         }
321         hash = LangUtils.hashCode(hash, this.secure);
322         hash = LangUtils.hashCode(hash, this.tunnelled);
323         hash = LangUtils.hashCode(hash, this.layered);
324         return hash;
325     }
326 
327     /**
328      * Obtains a description of this route.
329      *
330      * @return  a human-readable representation of this route
331      */
332     @Override
333     public final String toString() {
334         final StringBuilder cab = new StringBuilder(50 + getHopCount()*30);
335         if (this.localAddress != null) {
336             cab.append(this.localAddress);
337             cab.append("->");
338         }
339         cab.append('{');
340         if (this.tunnelled == TunnelType.TUNNELLED) {
341             cab.append('t');
342         }
343         if (this.layered == LayerType.LAYERED) {
344             cab.append('l');
345         }
346         if (this.secure) {
347             cab.append('s');
348         }
349         cab.append("}->");
350         if (this.proxyChain != null) {
351             for (final HttpHost aProxyChain : this.proxyChain) {
352                 cab.append(aProxyChain);
353                 cab.append("->");
354             }
355         }
356         cab.append(this.targetHost);
357         return cab.toString();
358     }
359 
360     // default implementation of clone() is sufficient
361     @Override
362     public Object clone() throws CloneNotSupportedException {
363         return super.clone();
364     }
365 
366 }