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}