View Javadoc

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