001/*
002 * ====================================================================
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *   http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing,
014 * software distributed under the License is distributed on an
015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
016 * KIND, either express or implied.  See the License for the
017 * specific language governing permissions and limitations
018 * under the License.
019 * ====================================================================
020 *
021 * This software consists of voluntary contributions made by many
022 * individuals on behalf of the Apache Software Foundation.  For more
023 * information on the Apache Software Foundation, please see
024 * <http://www.apache.org/>.
025 *
026 */
027
028package org.apache.http.conn.routing;
029
030import java.net.InetAddress;
031
032import org.apache.http.HttpHost;
033
034/**
035 * Read-only interface for route information.
036 *
037 * @since 4.0
038 */
039public interface RouteInfo {
040
041    /**
042     * The tunnelling type of a route.
043     * Plain routes are established by   connecting to the target or
044     * the first proxy.
045     * Tunnelled routes are established by connecting to the first proxy
046     * and tunnelling through all proxies to the target.
047     * Routes without a proxy cannot be tunnelled.
048     */
049    public enum TunnelType { PLAIN, TUNNELLED }
050
051    /**
052     * The layering type of a route.
053     * Plain routes are established by connecting or tunnelling.
054     * Layered routes are established by layering a protocol such as TLS/SSL
055     * over an existing connection.
056     * Protocols can only be layered over a tunnel to the target, or
057     * or over a direct connection without proxies.
058     * <p>
059     * Layering a protocol
060     * over a direct connection makes little sense, since the connection
061     * could be established with the new protocol in the first place.
062     * But we don't want to exclude that use case.
063     * </p>
064     */
065    public enum LayerType  { PLAIN, LAYERED }
066
067    /**
068     * Obtains the target host.
069     *
070     * @return the target host
071     */
072    HttpHost getTargetHost();
073
074    /**
075     * Obtains the local address to connect from.
076     *
077     * @return  the local address,
078     *          or {@code null}
079     */
080    InetAddress getLocalAddress();
081
082    /**
083     * Obtains the number of hops in this route.
084     * A direct route has one hop. A route through a proxy has two hops.
085     * A route through a chain of <i>n</i> proxies has <i>n+1</i> hops.
086     *
087     * @return  the number of hops in this route
088     */
089    int getHopCount();
090
091    /**
092     * Obtains the target of a hop in this route.
093     * The target of the last hop is the {@link #getTargetHost target host},
094     * the target of previous hops is the respective proxy in the chain.
095     * For a route through exactly one proxy, target of hop 0 is the proxy
096     * and target of hop 1 is the target host.
097     *
098     * @param hop       index of the hop for which to get the target,
099     *                  0 for first
100     *
101     * @return  the target of the given hop
102     *
103     * @throws IllegalArgumentException
104     *  if the argument is negative or not less than
105     *  {@link #getHopCount getHopCount()}
106     */
107    HttpHost getHopTarget(int hop);
108
109    /**
110     * Obtains the first proxy host.
111     *
112     * @return the first proxy in the proxy chain, or
113     *         {@code null} if this route is direct
114     */
115    HttpHost getProxyHost();
116
117    /**
118     * Obtains the tunnel type of this route.
119     * If there is a proxy chain, only end-to-end tunnels are considered.
120     *
121     * @return  the tunnelling type
122     */
123    TunnelType getTunnelType();
124
125    /**
126     * Checks whether this route is tunnelled through a proxy.
127     * If there is a proxy chain, only end-to-end tunnels are considered.
128     *
129     * @return  {@code true} if tunnelled end-to-end through at least
130     *          one proxy,
131     *          {@code false} otherwise
132     */
133    boolean isTunnelled();
134
135    /**
136     * Obtains the layering type of this route.
137     * In the presence of proxies, only layering over an end-to-end tunnel
138     * is considered.
139     *
140     * @return  the layering type
141     */
142    LayerType getLayerType();
143
144    /**
145     * Checks whether this route includes a layered protocol.
146     * In the presence of proxies, only layering over an end-to-end tunnel
147     * is considered.
148     *
149     * @return  {@code true} if layered,
150     *          {@code false} otherwise
151     */
152    boolean isLayered();
153
154    /**
155     * Checks whether this route is secure.
156     *
157     * @return  {@code true} if secure,
158     *          {@code false} otherwise
159     */
160    boolean isSecure();
161
162}