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 32 package org.apache.http.conn.routing; 33 34 import java.net.InetAddress; 35 36 import 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 */ 50 public 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 */ getTargetHost()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 */ getLocalAddress()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 */ getHopCount()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 */ getHopTarget(int hop)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 */ getProxyHost()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 */ getTunnelType()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 */ isTunnelled()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 */ getLayerType()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 */ isLayered()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 */ isSecure()190 boolean isSecure() 191 ; 192 193 194 } // interface RouteInfo 195