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 ch.boye.httpclientandroidlib.annotation.Immutable;
michael@0: 
michael@0: /**
michael@0:  * Basic implementation of an {@link HttpRouteDirector HttpRouteDirector}.
michael@0:  * This implementation is stateless and therefore thread-safe.
michael@0:  *
michael@0:  * @since 4.0
michael@0:  */
michael@0: @Immutable
michael@0: public class BasicRouteDirector implements HttpRouteDirector {
michael@0: 
michael@0:     /**
michael@0:      * Provides the next step.
michael@0:      *
michael@0:      * @param plan      the planned route
michael@0:      * @param fact      the currently established route, or
michael@0:      *                  <code>null</code> if nothing is established
michael@0:      *
michael@0:      * @return  one of the constants defined in this class, indicating
michael@0:      *          either the next step to perform, or success, or failure.
michael@0:      *          0 is for success, a negative value for failure.
michael@0:      */
michael@0:     public int nextStep(RouteInfo plan, RouteInfo fact) {
michael@0:         if (plan == null) {
michael@0:             throw new IllegalArgumentException
michael@0:                 ("Planned route may not be null.");
michael@0:         }
michael@0: 
michael@0:         int step = UNREACHABLE;
michael@0: 
michael@0:         if ((fact == null) || (fact.getHopCount() < 1))
michael@0:             step = firstStep(plan);
michael@0:         else if (plan.getHopCount() > 1)
michael@0:             step = proxiedStep(plan, fact);
michael@0:         else
michael@0:             step = directStep(plan, fact);
michael@0: 
michael@0:         return step;
michael@0: 
michael@0:     } // nextStep
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Determines the first step to establish a route.
michael@0:      *
michael@0:      * @param plan      the planned route
michael@0:      *
michael@0:      * @return  the first step
michael@0:      */
michael@0:     protected int firstStep(RouteInfo plan) {
michael@0: 
michael@0:         return (plan.getHopCount() > 1) ?
michael@0:             CONNECT_PROXY : CONNECT_TARGET;
michael@0:     }
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Determines the next step to establish a direct connection.
michael@0:      *
michael@0:      * @param plan      the planned route
michael@0:      * @param fact      the currently established route
michael@0:      *
michael@0:      * @return  one of the constants defined in this class, indicating
michael@0:      *          either the next step to perform, or success, or failure
michael@0:      */
michael@0:     protected int directStep(RouteInfo plan, RouteInfo fact) {
michael@0: 
michael@0:         if (fact.getHopCount() > 1)
michael@0:             return UNREACHABLE;
michael@0:         if (!plan.getTargetHost().equals(fact.getTargetHost()))
michael@0:             return UNREACHABLE;
michael@0:         // If the security is too low, we could now suggest to layer
michael@0:         // a secure protocol on the direct connection. Layering on direct
michael@0:         // connections has not been supported in HttpClient 3.x, we don't
michael@0:         // consider it here until there is a real-life use case for it.
michael@0: 
michael@0:         // Should we tolerate if security is better than planned?
michael@0:         // (plan.isSecure() && !fact.isSecure())
michael@0:         if (plan.isSecure() != fact.isSecure())
michael@0:             return UNREACHABLE;
michael@0: 
michael@0:         // Local address has to match only if the plan specifies one.
michael@0:         if ((plan.getLocalAddress() != null) &&
michael@0:             !plan.getLocalAddress().equals(fact.getLocalAddress())
michael@0:             )
michael@0:             return UNREACHABLE;
michael@0: 
michael@0:         return COMPLETE;
michael@0:     }
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Determines the next step to establish a connection via proxy.
michael@0:      *
michael@0:      * @param plan      the planned route
michael@0:      * @param fact      the currently established route
michael@0:      *
michael@0:      * @return  one of the constants defined in this class, indicating
michael@0:      *          either the next step to perform, or success, or failure
michael@0:      */
michael@0:     protected int proxiedStep(RouteInfo plan, RouteInfo fact) {
michael@0: 
michael@0:         if (fact.getHopCount() <= 1)
michael@0:             return UNREACHABLE;
michael@0:         if (!plan.getTargetHost().equals(fact.getTargetHost()))
michael@0:             return UNREACHABLE;
michael@0:         final int phc = plan.getHopCount();
michael@0:         final int fhc = fact.getHopCount();
michael@0:         if (phc < fhc)
michael@0:             return UNREACHABLE;
michael@0: 
michael@0:         for (int i=0; i<fhc-1; i++) {
michael@0:             if (!plan.getHopTarget(i).equals(fact.getHopTarget(i)))
michael@0:                 return UNREACHABLE;
michael@0:         }
michael@0:         // now we know that the target matches and proxies so far are the same
michael@0:         if (phc > fhc)
michael@0:             return TUNNEL_PROXY; // need to extend the proxy chain
michael@0: 
michael@0:         // proxy chain and target are the same, check tunnelling and layering
michael@0:         if ((fact.isTunnelled() && !plan.isTunnelled()) ||
michael@0:             (fact.isLayered()   && !plan.isLayered()))
michael@0:             return UNREACHABLE;
michael@0: 
michael@0:         if (plan.isTunnelled() && !fact.isTunnelled())
michael@0:             return TUNNEL_TARGET;
michael@0:         if (plan.isLayered() && !fact.isLayered())
michael@0:             return LAYER_PROTOCOL;
michael@0: 
michael@0:         // tunnel and layering are the same, remains to check the security
michael@0:         // Should we tolerate if security is better than planned?
michael@0:         // (plan.isSecure() && !fact.isSecure())
michael@0:         if (plan.isSecure() != fact.isSecure())
michael@0:             return UNREACHABLE;
michael@0: 
michael@0:         return COMPLETE;
michael@0:     }
michael@0: 
michael@0: }