michael@0: /*
michael@0:  * ====================================================================
michael@0:  * Licensed to the Apache Software Foundation (ASF) under one
michael@0:  * or more contributor license agreements.  See the NOTICE file
michael@0:  * distributed with this work for additional information
michael@0:  * regarding copyright ownership.  The ASF licenses this file
michael@0:  * to you under the Apache License, Version 2.0 (the
michael@0:  * "License"); you may not use this file except in compliance
michael@0:  * with the License.  You may obtain a copy of the License at
michael@0:  *
michael@0:  *   http://www.apache.org/licenses/LICENSE-2.0
michael@0:  *
michael@0:  * Unless required by applicable law or agreed to in writing,
michael@0:  * software distributed under the License is distributed on an
michael@0:  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
michael@0:  * KIND, either express or implied.  See the License for the
michael@0:  * specific language governing permissions and limitations
michael@0:  * under the License.
michael@0:  * ====================================================================
michael@0:  *
michael@0:  * This software consists of voluntary contributions made by many
michael@0:  * individuals on behalf of the Apache Software Foundation.  For more
michael@0:  * information on the Apache Software Foundation, please see
michael@0:  * <http://www.apache.org/>.
michael@0:  *
michael@0:  */
michael@0: 
michael@0: package ch.boye.httpclientandroidlib.conn.routing;
michael@0: 
michael@0: import java.net.InetAddress;
michael@0: 
michael@0: import ch.boye.httpclientandroidlib.annotation.Immutable;
michael@0: import ch.boye.httpclientandroidlib.util.LangUtils;
michael@0: 
michael@0: import ch.boye.httpclientandroidlib.HttpHost;
michael@0: 
michael@0: /**
michael@0:  * The route for a request.
michael@0:  * Instances of this class are unmodifiable and therefore suitable
michael@0:  * for use as lookup keys.
michael@0:  *
michael@0:  * @since 4.0
michael@0:  */
michael@0: @Immutable
michael@0: public final class HttpRoute implements RouteInfo, Cloneable {
michael@0: 
michael@0:     private static final HttpHost[] EMPTY_HTTP_HOST_ARRAY = new HttpHost[]{};
michael@0: 
michael@0:     /** The target host to connect to. */
michael@0:     private final HttpHost targetHost;
michael@0: 
michael@0:     /**
michael@0:      * The local address to connect from.
michael@0:      * <code>null</code> indicates that the default should be used.
michael@0:      */
michael@0:     private final InetAddress localAddress;
michael@0: 
michael@0:     /** The proxy servers, if any. Never null. */
michael@0:     private final HttpHost[] proxyChain;
michael@0: 
michael@0:     /** Whether the the route is tunnelled through the proxy. */
michael@0:     private final TunnelType tunnelled;
michael@0: 
michael@0:     /** Whether the route is layered. */
michael@0:     private final LayerType layered;
michael@0: 
michael@0:     /** Whether the route is (supposed to be) secure. */
michael@0:     private final boolean secure;
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Internal, fully-specified constructor.
michael@0:      * This constructor does <i>not</i> clone the proxy chain array,
michael@0:      * nor test it for <code>null</code> elements. This conversion and
michael@0:      * check is the responsibility of the public constructors.
michael@0:      * The order of arguments here is different from the similar public
michael@0:      * constructor, as required by Java.
michael@0:      *
michael@0:      * @param local     the local address to route from, or
michael@0:      *                  <code>null</code> for the default
michael@0:      * @param target    the host to which to route
michael@0:      * @param proxies   the proxy chain to use, or
michael@0:      *                  <code>null</code> for a direct route
michael@0:      * @param secure    <code>true</code> if the route is (to be) secure,
michael@0:      *                  <code>false</code> otherwise
michael@0:      * @param tunnelled the tunnel type of this route, or
michael@0:      *                  <code>null</code> for PLAIN
michael@0:      * @param layered   the layering type of this route, or
michael@0:      *                  <code>null</code> for PLAIN
michael@0:      */
michael@0:     private HttpRoute(InetAddress local,
michael@0:                       HttpHost target, HttpHost[] proxies,
michael@0:                       boolean secure,
michael@0:                       TunnelType tunnelled, LayerType layered) {
michael@0:         if (target == null) {
michael@0:             throw new IllegalArgumentException
michael@0:                 ("Target host may not be null.");
michael@0:         }
michael@0:         if (proxies == null) {
michael@0:             throw new IllegalArgumentException
michael@0:                 ("Proxies may not be null.");
michael@0:         }
michael@0:         if ((tunnelled == TunnelType.TUNNELLED) && (proxies.length == 0)) {
michael@0:             throw new IllegalArgumentException
michael@0:                 ("Proxy required if tunnelled.");
michael@0:         }
michael@0: 
michael@0:         // tunnelled is already checked above, that is in line with the default
michael@0:         if (tunnelled == null)
michael@0:             tunnelled = TunnelType.PLAIN;
michael@0:         if (layered == null)
michael@0:             layered = LayerType.PLAIN;
michael@0: 
michael@0:         this.targetHost   = target;
michael@0:         this.localAddress = local;
michael@0:         this.proxyChain   = proxies;
michael@0:         this.secure       = secure;
michael@0:         this.tunnelled    = tunnelled;
michael@0:         this.layered      = layered;
michael@0:     }
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Creates a new route with all attributes specified explicitly.
michael@0:      *
michael@0:      * @param target    the host to which to route
michael@0:      * @param local     the local address to route from, or
michael@0:      *                  <code>null</code> for the default
michael@0:      * @param proxies   the proxy chain to use, or
michael@0:      *                  <code>null</code> for a direct route
michael@0:      * @param secure    <code>true</code> if the route is (to be) secure,
michael@0:      *                  <code>false</code> otherwise
michael@0:      * @param tunnelled the tunnel type of this route
michael@0:      * @param layered   the layering type of this route
michael@0:      */
michael@0:     public HttpRoute(HttpHost target, InetAddress local, HttpHost[] proxies,
michael@0:                      boolean secure, TunnelType tunnelled, LayerType layered) {
michael@0:         this(local, target, toChain(proxies), secure, tunnelled, layered);
michael@0:     }
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Creates a new route with at most one proxy.
michael@0:      *
michael@0:      * @param target    the host to which to route
michael@0:      * @param local     the local address to route from, or
michael@0:      *                  <code>null</code> for the default
michael@0:      * @param proxy     the proxy to use, or
michael@0:      *                  <code>null</code> for a direct route
michael@0:      * @param secure    <code>true</code> if the route is (to be) secure,
michael@0:      *                  <code>false</code> otherwise
michael@0:      * @param tunnelled <code>true</code> if the route is (to be) tunnelled
michael@0:      *                  via the proxy,
michael@0:      *                  <code>false</code> otherwise
michael@0:      * @param layered   <code>true</code> if the route includes a
michael@0:      *                  layered protocol,
michael@0:      *                  <code>false</code> otherwise
michael@0:      */
michael@0:     public HttpRoute(HttpHost target, InetAddress local, HttpHost proxy,
michael@0:                      boolean secure, TunnelType tunnelled, LayerType layered) {
michael@0:         this(local, target, toChain(proxy), secure, tunnelled, layered);
michael@0:     }
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Creates a new direct route.
michael@0:      * That is a route without a proxy.
michael@0:      *
michael@0:      * @param target    the host to which to route
michael@0:      * @param local     the local address to route from, or
michael@0:      *                  <code>null</code> for the default
michael@0:      * @param secure    <code>true</code> if the route is (to be) secure,
michael@0:      *                  <code>false</code> otherwise
michael@0:      */
michael@0:     public HttpRoute(HttpHost target, InetAddress local, boolean secure) {
michael@0:         this(local, target, EMPTY_HTTP_HOST_ARRAY, secure, TunnelType.PLAIN, LayerType.PLAIN);
michael@0:     }
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Creates a new direct insecure route.
michael@0:      *
michael@0:      * @param target    the host to which to route
michael@0:      */
michael@0:     public HttpRoute(HttpHost target) {
michael@0:         this(null, target, EMPTY_HTTP_HOST_ARRAY, false, TunnelType.PLAIN, LayerType.PLAIN);
michael@0:     }
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Creates a new route through a proxy.
michael@0:      * When using this constructor, the <code>proxy</code> MUST be given.
michael@0:      * For convenience, it is assumed that a secure connection will be
michael@0:      * layered over a tunnel through the proxy.
michael@0:      *
michael@0:      * @param target    the host to which to route
michael@0:      * @param local     the local address to route from, or
michael@0:      *                  <code>null</code> for the default
michael@0:      * @param proxy     the proxy to use
michael@0:      * @param secure    <code>true</code> if the route is (to be) secure,
michael@0:      *                  <code>false</code> otherwise
michael@0:      */
michael@0:     public HttpRoute(HttpHost target, InetAddress local, HttpHost proxy,
michael@0:                      boolean secure) {
michael@0:         this(local, target, toChain(proxy), secure,
michael@0:              secure ? TunnelType.TUNNELLED : TunnelType.PLAIN,
michael@0:              secure ? LayerType.LAYERED    : LayerType.PLAIN);
michael@0:         if (proxy == null) {
michael@0:             throw new IllegalArgumentException
michael@0:                 ("Proxy host may not be null.");
michael@0:         }
michael@0:     }
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Helper to convert a proxy to a proxy chain.
michael@0:      *
michael@0:      * @param proxy     the only proxy in the chain, or <code>null</code>
michael@0:      *
michael@0:      * @return  a proxy chain array, may be empty (never null)
michael@0:      */
michael@0:     private static HttpHost[] toChain(HttpHost proxy) {
michael@0:         if (proxy == null)
michael@0:             return EMPTY_HTTP_HOST_ARRAY;
michael@0: 
michael@0:         return new HttpHost[]{ proxy };
michael@0:     }
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Helper to duplicate and check a proxy chain.
michael@0:      * <code>null</code> is converted to an empty proxy chain.
michael@0:      *
michael@0:      * @param proxies   the proxy chain to duplicate, or <code>null</code>
michael@0:      *
michael@0:      * @return  a new proxy chain array, may be empty (never null)
michael@0:      */
michael@0:     private static HttpHost[] toChain(HttpHost[] proxies) {
michael@0:         if ((proxies == null) || (proxies.length < 1))
michael@0:             return EMPTY_HTTP_HOST_ARRAY;
michael@0: 
michael@0:         for (HttpHost proxy : proxies) {
michael@0:             if (proxy == null)
michael@0:                 throw new IllegalArgumentException
michael@0:                         ("Proxy chain may not contain null elements.");
michael@0:         }
michael@0: 
michael@0:         // copy the proxy chain, the traditional way
michael@0:         HttpHost[] result = new HttpHost[proxies.length];
michael@0:         System.arraycopy(proxies, 0, result, 0, proxies.length);
michael@0: 
michael@0:         return result;
michael@0:     }
michael@0: 
michael@0: 
michael@0: 
michael@0:     // non-JavaDoc, see interface RouteInfo
michael@0:     public final HttpHost getTargetHost() {
michael@0:         return this.targetHost;
michael@0:     }
michael@0: 
michael@0: 
michael@0:     // non-JavaDoc, see interface RouteInfo
michael@0:     public final InetAddress getLocalAddress() {
michael@0:         return this.localAddress;
michael@0:     }
michael@0: 
michael@0: 
michael@0:     public final int getHopCount() {
michael@0:         return proxyChain.length+1;
michael@0:     }
michael@0: 
michael@0: 
michael@0:     public final HttpHost getHopTarget(int hop) {
michael@0:         if (hop < 0)
michael@0:             throw new IllegalArgumentException
michael@0:                 ("Hop index must not be negative: " + hop);
michael@0:         final int hopcount = getHopCount();
michael@0:         if (hop >= hopcount)
michael@0:             throw new IllegalArgumentException
michael@0:                 ("Hop index " + hop +
michael@0:                  " exceeds route length " + hopcount);
michael@0: 
michael@0:         HttpHost result = null;
michael@0:         if (hop < hopcount-1)
michael@0:             result = this.proxyChain[hop];
michael@0:         else
michael@0:             result = this.targetHost;
michael@0: 
michael@0:         return result;
michael@0:     }
michael@0: 
michael@0: 
michael@0:     public final HttpHost getProxyHost() {
michael@0:         return (this.proxyChain.length == 0) ? null : this.proxyChain[0];
michael@0:     }
michael@0: 
michael@0: 
michael@0:     public final TunnelType getTunnelType() {
michael@0:         return this.tunnelled;
michael@0:     }
michael@0: 
michael@0: 
michael@0:     public final boolean isTunnelled() {
michael@0:         return (this.tunnelled == TunnelType.TUNNELLED);
michael@0:     }
michael@0: 
michael@0: 
michael@0:     public final LayerType getLayerType() {
michael@0:         return this.layered;
michael@0:     }
michael@0: 
michael@0: 
michael@0:     public final boolean isLayered() {
michael@0:         return (this.layered == LayerType.LAYERED);
michael@0:     }
michael@0: 
michael@0: 
michael@0:     public final boolean isSecure() {
michael@0:         return this.secure;
michael@0:     }
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Compares this route to another.
michael@0:      *
michael@0:      * @param obj         the object to compare with
michael@0:      *
michael@0:      * @return  <code>true</code> if the argument is the same route,
michael@0:      *          <code>false</code>
michael@0:      */
michael@0:     @Override
michael@0:     public final boolean equals(Object obj) {
michael@0:         if (this == obj) return true;
michael@0:         if (obj instanceof HttpRoute) {
michael@0:             HttpRoute that = (HttpRoute) obj;
michael@0:             return 
michael@0:                 // Do the cheapest tests first
michael@0:                 (this.secure    == that.secure) &&
michael@0:                 (this.tunnelled == that.tunnelled) &&
michael@0:                 (this.layered   == that.layered) &&
michael@0:                 LangUtils.equals(this.targetHost, that.targetHost) &&
michael@0:                 LangUtils.equals(this.localAddress, that.localAddress) &&
michael@0:                 LangUtils.equals(this.proxyChain, that.proxyChain);
michael@0:         } else {
michael@0:             return false;
michael@0:         }
michael@0:     }
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Generates a hash code for this route.
michael@0:      *
michael@0:      * @return  the hash code
michael@0:      */
michael@0:     @Override
michael@0:     public final int hashCode() {
michael@0:         int hash = LangUtils.HASH_SEED;
michael@0:         hash = LangUtils.hashCode(hash, this.targetHost);
michael@0:         hash = LangUtils.hashCode(hash, this.localAddress);
michael@0:         for (int i = 0; i < this.proxyChain.length; i++) {
michael@0:             hash = LangUtils.hashCode(hash, this.proxyChain[i]);
michael@0:         }
michael@0:         hash = LangUtils.hashCode(hash, this.secure);
michael@0:         hash = LangUtils.hashCode(hash, this.tunnelled);
michael@0:         hash = LangUtils.hashCode(hash, this.layered);
michael@0:         return hash;
michael@0:     }
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Obtains a description of this route.
michael@0:      *
michael@0:      * @return  a human-readable representation of this route
michael@0:      */
michael@0:     @Override
michael@0:     public final String toString() {
michael@0:         StringBuilder cab = new StringBuilder(50 + getHopCount()*30);
michael@0: 
michael@0:         cab.append("HttpRoute[");
michael@0:         if (this.localAddress != null) {
michael@0:             cab.append(this.localAddress);
michael@0:             cab.append("->");
michael@0:         }
michael@0:         cab.append('{');
michael@0:         if (this.tunnelled == TunnelType.TUNNELLED)
michael@0:             cab.append('t');
michael@0:         if (this.layered == LayerType.LAYERED)
michael@0:             cab.append('l');
michael@0:         if (this.secure)
michael@0:             cab.append('s');
michael@0:         cab.append("}->");
michael@0:         for (HttpHost aProxyChain : this.proxyChain) {
michael@0:             cab.append(aProxyChain);
michael@0:             cab.append("->");
michael@0:         }
michael@0:         cab.append(this.targetHost);
michael@0:         cab.append(']');
michael@0: 
michael@0:         return cab.toString();
michael@0:     }
michael@0: 
michael@0: 
michael@0:     // default implementation of clone() is sufficient
michael@0:     @Override
michael@0:     public Object clone() throws CloneNotSupportedException {
michael@0:         return super.clone();
michael@0:     }
michael@0: 
michael@0: }