RouteInfo.java revision 417f3b92ba4549b2f22340e3107d869d2b9c5bb8 
1/*
2 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/conn/routing/RouteInfo.java $
3 * $Revision: 652200 $
4 * $Date: 2008-04-29 17:22:43 -0700 (Tue, 29 Apr 2008) $
5 *
6 * ====================================================================
7 * Licensed to the Apache Software Foundation (ASF) under one
8 * or more contributor license agreements.  See the NOTICE file
9 * distributed with this work for additional information
10 * regarding copyright ownership.  The ASF licenses this file
11 * to you under the Apache License, Version 2.0 (the
12 * "License"); you may not use this file except in compliance
13 * with the License.  You may obtain a copy of the License at
14 *
15 *   http://www.apache.org/licenses/LICENSE-2.0
16 *
17 * Unless required by applicable law or agreed to in writing,
18 * software distributed under the License is distributed on an
19 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
20 * KIND, either express or implied.  See the License for the
21 * specific language governing permissions and limitations
22 * under the License.
23 * ====================================================================
24 *
25 * This software consists of voluntary contributions made by many
26 * individuals on behalf of the Apache Software Foundation.  For more
27 * information on the Apache Software Foundation, please see
28 * <http://www.apache.org/>.
29 *
30 */
31
32package org.apache.http.conn.routing;
33
34import java.net.InetAddress;
35
36import org.apache.http.HttpHost;
37
38
39/**
40 * Read-only interface for route information.
41 *
42 * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
43 *
44 *
45 * <!-- empty lines to avoid svn diff problems -->
46 * @version $Revision: 652200 $
47 *
48 * @since 4.0
49 */
50public interface RouteInfo {
51
52    /**
53     * The tunnelling type of a route.
54     * Plain routes are established by connecting to the target or
55     * the first proxy.
56     * Tunnelled routes are established by connecting to the first proxy
57     * and tunnelling through all proxies to the target.
58     * Routes without a proxy cannot be tunnelled.
59     */
60    public enum TunnelType { PLAIN, TUNNELLED }
61
62    /**
63     * The layering type of a route.
64     * Plain routes are established by connecting or tunnelling.
65     * Layered routes are established by layering a protocol such as TLS/SSL
66     * over an existing connection.
67     * Protocols can only be layered over a tunnel to the target, or
68     * or over a direct connection without proxies.
69     * <br/>
70     * Layering a protocol
71     * over a direct connection makes little sense, since the connection
72     * could be established with the new protocol in the first place.
73     * But we don't want to exclude that use case.
74     */
75    public enum LayerType  { PLAIN, LAYERED }
76
77
78
79    /**
80     * Obtains the target host.
81     *
82     * @return the target host
83     */
84    HttpHost getTargetHost()
85        ;
86
87
88    /**
89     * Obtains the local address to connect from.
90     *
91     * @return  the local address,
92     *          or <code>null</code>
93     */
94    InetAddress getLocalAddress()
95        ;
96
97
98    /**
99     * Obtains the number of hops in this route.
100     * A direct route has one hop. A route through a proxy has two hops.
101     * A route through a chain of <i>n</i> proxies has <i>n+1</i> hops.
102     *
103     * @return  the number of hops in this route
104     */
105    int getHopCount()
106        ;
107
108
109    /**
110     * Obtains the target of a hop in this route.
111     * The target of the last hop is the {@link #getTargetHost target host},
112     * the target of previous hops is the respective proxy in the chain.
113     * For a route through exactly one proxy, target of hop 0 is the proxy
114     * and target of hop 1 is the target host.
115     *
116     * @param hop       index of the hop for which to get the target,
117     *                  0 for first
118     *
119     * @return  the target of the given hop
120     *
121     * @throws IllegalArgumentException
122     *  if the argument is negative or not less than
123     *  {@link #getHopCount getHopCount()}
124     */
125    HttpHost getHopTarget(int hop)
126        ;
127
128
129    /**
130     * Obtains the first proxy host.
131     *
132     * @return the first proxy in the proxy chain, or
133     *         <code>null</code> if this route is direct
134     */
135    HttpHost getProxyHost()
136        ;
137
138
139    /**
140     * Obtains the tunnel type of this route.
141     * If there is a proxy chain, only end-to-end tunnels are considered.
142     *
143     * @return  the tunnelling type
144     */
145    TunnelType getTunnelType()
146        ;
147
148
149    /**
150     * Checks whether this route is tunnelled through a proxy.
151     * If there is a proxy chain, only end-to-end tunnels are considered.
152     *
153     * @return  <code>true</code> if tunnelled end-to-end through at least
154     *          one proxy,
155     *          <code>false</code> otherwise
156     */
157    boolean isTunnelled()
158        ;
159
160
161    /**
162     * Obtains the layering type of this route.
163     * In the presence of proxies, only layering over an end-to-end tunnel
164     * is considered.
165     *
166     * @return  the layering type
167     */
168    LayerType getLayerType()
169        ;
170
171
172    /**
173     * Checks whether this route includes a layered protocol.
174     * In the presence of proxies, only layering over an end-to-end tunnel
175     * is considered.
176     *
177     * @return  <code>true</code> if layered,
178     *          <code>false</code> otherwise
179     */
180    boolean isLayered()
181        ;
182
183
184    /**
185     * Checks whether this route is secure.
186     *
187     * @return  <code>true</code> if secure,
188     *          <code>false</code> otherwise
189     */
190    boolean isSecure()
191        ;
192
193
194} // interface RouteInfo
195