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.NotThreadSafe;
michael@0: import ch.boye.httpclientandroidlib.util.LangUtils;
michael@0: 
michael@0: import ch.boye.httpclientandroidlib.HttpHost;
michael@0: 
michael@0: /**
michael@0:  * Helps tracking the steps in establishing a route.
michael@0:  *
michael@0:  * @since 4.0
michael@0:  */
michael@0: @NotThreadSafe
michael@0: public final class RouteTracker implements RouteInfo, Cloneable {
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 attributes above are fixed at construction time
michael@0:     // now follow attributes that indicate the established route
michael@0: 
michael@0:     /** Whether the first hop of the route is established. */
michael@0:     private boolean connected;
michael@0: 
michael@0:     /** The proxy chain, if any. */
michael@0:     private HttpHost[] proxyChain;
michael@0: 
michael@0:     /** Whether the the route is tunnelled end-to-end through proxies. */
michael@0:     private TunnelType tunnelled;
michael@0: 
michael@0:     /** Whether the route is layered over a tunnel. */
michael@0:     private LayerType layered;
michael@0: 
michael@0:     /** Whether the route is secure. */
michael@0:     private boolean secure;
michael@0: 
michael@0:     /**
michael@0:      * Creates a new route tracker.
michael@0:      * The target and origin need to be specified at creation time.
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:      */
michael@0:     public RouteTracker(HttpHost target, InetAddress local) {
michael@0:         if (target == null) {
michael@0:             throw new IllegalArgumentException("Target host may not be null.");
michael@0:         }
michael@0:         this.targetHost   = target;
michael@0:         this.localAddress = local;
michael@0:         this.tunnelled    = TunnelType.PLAIN;
michael@0:         this.layered      = LayerType.PLAIN;
michael@0:     }
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Creates a new tracker for the given route.
michael@0:      * Only target and origin are taken from the route,
michael@0:      * everything else remains to be tracked.
michael@0:      *
michael@0:      * @param route     the route to track
michael@0:      */
michael@0:     public RouteTracker(HttpRoute route) {
michael@0:         this(route.getTargetHost(), route.getLocalAddress());
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Tracks connecting to the target.
michael@0:      *
michael@0:      * @param secure    <code>true</code> if the route is secure,
michael@0:      *                  <code>false</code> otherwise
michael@0:      */
michael@0:     public final void connectTarget(boolean secure) {
michael@0:         if (this.connected) {
michael@0:             throw new IllegalStateException("Already connected.");
michael@0:         }
michael@0:         this.connected = true;
michael@0:         this.secure = secure;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Tracks connecting to the first proxy.
michael@0:      *
michael@0:      * @param proxy     the proxy connected to
michael@0:      * @param secure    <code>true</code> if the route is secure,
michael@0:      *                  <code>false</code> otherwise
michael@0:      */
michael@0:     public final void connectProxy(HttpHost proxy, boolean secure) {
michael@0:         if (proxy == null) {
michael@0:             throw new IllegalArgumentException("Proxy host may not be null.");
michael@0:         }
michael@0:         if (this.connected) {
michael@0:             throw new IllegalStateException("Already connected.");
michael@0:         }
michael@0:         this.connected  = true;
michael@0:         this.proxyChain = new HttpHost[]{ proxy };
michael@0:         this.secure     = secure;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Tracks tunnelling to the target.
michael@0:      *
michael@0:      * @param secure    <code>true</code> if the route is secure,
michael@0:      *                  <code>false</code> otherwise
michael@0:      */
michael@0:     public final void tunnelTarget(boolean secure) {
michael@0:         if (!this.connected) {
michael@0:             throw new IllegalStateException("No tunnel unless connected.");
michael@0:         }
michael@0:         if (this.proxyChain == null) {
michael@0:             throw new IllegalStateException("No tunnel without proxy.");
michael@0:         }
michael@0:         this.tunnelled = TunnelType.TUNNELLED;
michael@0:         this.secure    = secure;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Tracks tunnelling to a proxy in a proxy chain.
michael@0:      * This will extend the tracked proxy chain, but it does not mark
michael@0:      * the route as tunnelled. Only end-to-end tunnels are considered there.
michael@0:      *
michael@0:      * @param proxy     the proxy tunnelled to
michael@0:      * @param secure    <code>true</code> if the route is secure,
michael@0:      *                  <code>false</code> otherwise
michael@0:      */
michael@0:     public final void tunnelProxy(HttpHost proxy, boolean secure) {
michael@0:         if (proxy == null) {
michael@0:             throw new IllegalArgumentException("Proxy host may not be null.");
michael@0:         }
michael@0:         if (!this.connected) {
michael@0:             throw new IllegalStateException("No tunnel unless connected.");
michael@0:         }
michael@0:         if (this.proxyChain == null) {
michael@0:             throw new IllegalStateException("No proxy tunnel without proxy.");
michael@0:         }
michael@0: 
michael@0:         // prepare an extended proxy chain
michael@0:         HttpHost[] proxies = new HttpHost[this.proxyChain.length+1];
michael@0:         System.arraycopy(this.proxyChain, 0,
michael@0:                          proxies, 0, this.proxyChain.length);
michael@0:         proxies[proxies.length-1] = proxy;
michael@0: 
michael@0:         this.proxyChain = proxies;
michael@0:         this.secure     = secure;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Tracks layering a protocol.
michael@0:      *
michael@0:      * @param secure    <code>true</code> if the route is secure,
michael@0:      *                  <code>false</code> otherwise
michael@0:      */
michael@0:     public final void layerProtocol(boolean secure) {
michael@0:         // it is possible to layer a protocol over a direct connection,
michael@0:         // although this case is probably not considered elsewhere
michael@0:         if (!this.connected) {
michael@0:             throw new IllegalStateException
michael@0:                 ("No layered protocol unless connected.");
michael@0:         }
michael@0:         this.layered = LayerType.LAYERED;
michael@0:         this.secure  = secure;
michael@0:     }
michael@0: 
michael@0:     public final HttpHost getTargetHost() {
michael@0:         return this.targetHost;
michael@0:     }
michael@0: 
michael@0:     public final InetAddress getLocalAddress() {
michael@0:         return this.localAddress;
michael@0:     }
michael@0: 
michael@0:     public final int getHopCount() {
michael@0:         int hops = 0;
michael@0:         if (this.connected) {
michael@0:             if (proxyChain == null)
michael@0:                 hops = 1;
michael@0:             else
michael@0:                 hops = proxyChain.length + 1;
michael@0:         }
michael@0:         return hops;
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 tracked route length " + hopcount +".");
michael@0:         }
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:     public final HttpHost getProxyHost() {
michael@0:         return (this.proxyChain == null) ? null : this.proxyChain[0];
michael@0:     }
michael@0: 
michael@0:     public final boolean isConnected() {
michael@0:         return this.connected;
michael@0:     }
michael@0: 
michael@0:     public final TunnelType getTunnelType() {
michael@0:         return this.tunnelled;
michael@0:     }
michael@0: 
michael@0:     public final boolean isTunnelled() {
michael@0:         return (this.tunnelled == TunnelType.TUNNELLED);
michael@0:     }
michael@0: 
michael@0:     public final LayerType getLayerType() {
michael@0:         return this.layered;
michael@0:     }
michael@0: 
michael@0:     public final boolean isLayered() {
michael@0:         return (this.layered == LayerType.LAYERED);
michael@0:     }
michael@0: 
michael@0:     public final boolean isSecure() {
michael@0:         return this.secure;
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Obtains the tracked route.
michael@0:      * If a route has been tracked, it is {@link #isConnected connected}.
michael@0:      * If not connected, nothing has been tracked so far.
michael@0:      *
michael@0:      * @return  the tracked route, or
michael@0:      *          <code>null</code> if nothing has been tracked so far
michael@0:      */
michael@0:     public final HttpRoute toRoute() {
michael@0:         return !this.connected ?
michael@0:             null : new HttpRoute(this.targetHost, this.localAddress,
michael@0:                                  this.proxyChain, this.secure,
michael@0:                                  this.tunnelled, this.layered);
michael@0:     }
michael@0: 
michael@0:     /**
michael@0:      * Compares this tracked route to another.
michael@0:      *
michael@0:      * @param o         the object to compare with
michael@0:      *
michael@0:      * @return  <code>true</code> if the argument is the same tracked route,
michael@0:      *          <code>false</code>
michael@0:      */
michael@0:     @Override
michael@0:     public final boolean equals(Object o) {
michael@0:         if (o == this)
michael@0:             return true;
michael@0:         if (!(o instanceof RouteTracker))
michael@0:             return false;
michael@0: 
michael@0:         RouteTracker that = (RouteTracker) o;
michael@0:         return
michael@0:             // Do the cheapest checks first
michael@0:             (this.connected == that.connected) &&
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:     }
michael@0: 
michael@0:     /**
michael@0:      * Generates a hash code for this tracked route.
michael@0:      * Route trackers are modifiable and should therefore not be used
michael@0:      * as lookup keys. Use {@link #toRoute toRoute} to obtain an
michael@0:      * unmodifiable representation of the tracked 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:         if (this.proxyChain != null) {
michael@0:             for (int i = 0; i < this.proxyChain.length; i++) {
michael@0:                 hash = LangUtils.hashCode(hash, this.proxyChain[i]);
michael@0:             }
michael@0:         }
michael@0:         hash = LangUtils.hashCode(hash, this.connected);
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:      * Obtains a description of the tracked route.
michael@0:      *
michael@0:      * @return  a human-readable representation of the tracked 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("RouteTracker[");
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.connected)
michael@0:             cab.append('c');
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:         if (this.proxyChain != null) {
michael@0:             for (int i=0; i<this.proxyChain.length; i++) {
michael@0:                 cab.append(this.proxyChain[i]);
michael@0:                 cab.append("->");
michael@0:             }
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: }