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.hc.client5.http;
29
30 import java.net.InetAddress;
31
32 import org.apache.hc.core5.http.HttpHost;
33 import org.apache.hc.core5.net.NamedEndpoint;
34
35 /**
36 * Connection route information.
37 *
38 * @since 4.0
39 */
40 public interface RouteInfo {
41
42 /**
43 * The tunnelling type of a route.
44 * Plain routes are established by connecting to the target or
45 * the first proxy.
46 * Tunnelled routes are established by connecting to the first proxy
47 * and tunnelling through all proxies to the target.
48 * Routes without a proxy cannot be tunnelled.
49 */
50 enum TunnelType { PLAIN, TUNNELLED }
51
52 /**
53 * The layering type of a route.
54 * Plain routes are established by connecting or tunnelling.
55 * Layered routes are established by layering a protocol such as TLS/SSL
56 * over an existing connection.
57 * Protocols can only be layered over a tunnel to the target, or
58 * or over a direct connection without proxies.
59 * <p>
60 * Layering a protocol
61 * over a direct connection makes little sense, since the connection
62 * could be established with the new protocol in the first place.
63 * But we don't want to exclude that use case.
64 * </p>
65 */
66 enum LayerType { PLAIN, LAYERED }
67
68 /**
69 * Obtains the target host.
70 *
71 * @return the target host
72 */
73 HttpHost getTargetHost();
74
75 /**
76 * Obtains the target name, if different from the target host, {@code null} otherwise.
77 *
78 * @since 5.4
79 */
80 default NamedEndpoint getTargetName() {
81 return null;
82 }
83
84 /**
85 * Obtains the local address to connect from.
86 *
87 * @return the local address,
88 * or {@code null}
89 */
90 InetAddress getLocalAddress();
91
92 /**
93 * Obtains the number of hops in this route.
94 * A direct route has one hop. A route through a proxy has two hops.
95 * A route through a chain of <i>n</i> proxies has <i>n+1</i> hops.
96 *
97 * @return the number of hops in this route
98 */
99 int getHopCount();
100
101 /**
102 * Obtains the target of a hop in this route.
103 * The target of the last hop is the {@link #getTargetHost target host},
104 * the target of previous hops is the respective proxy in the chain.
105 * For a route through exactly one proxy, target of hop 0 is the proxy
106 * and target of hop 1 is the target host.
107 *
108 * @param hop index of the hop for which to get the target,
109 * 0 for first
110 *
111 * @return the target of the given hop
112 *
113 * @throws IllegalArgumentException
114 * if the argument is negative or not less than
115 * {@link #getHopCount getHopCount()}
116 */
117 HttpHost getHopTarget(int hop);
118
119 /**
120 * Obtains the first proxy host.
121 *
122 * @return the first proxy in the proxy chain, or
123 * {@code null} if this route is direct
124 */
125 HttpHost getProxyHost();
126
127 /**
128 * Obtains the tunnel type of this route.
129 * If there is a proxy chain, only end-to-end tunnels are considered.
130 *
131 * @return the tunnelling type
132 */
133 TunnelType getTunnelType();
134
135 /**
136 * Checks whether this route is tunnelled through a proxy.
137 * If there is a proxy chain, only end-to-end tunnels are considered.
138 *
139 * @return {@code true} if tunnelled end-to-end through at least
140 * one proxy,
141 * {@code false} otherwise
142 */
143 boolean isTunnelled();
144
145 /**
146 * Obtains the layering type of this route.
147 * In the presence of proxies, only layering over an end-to-end tunnel
148 * is considered.
149 *
150 * @return the layering type
151 */
152 LayerType getLayerType();
153
154 /**
155 * Checks whether this route includes a layered protocol.
156 * In the presence of proxies, only layering over an end-to-end tunnel
157 * is considered.
158 *
159 * @return {@code true} if layered,
160 * {@code false} otherwise
161 */
162 boolean isLayered();
163
164 /**
165 * Checks whether this route is secure.
166 *
167 * @return {@code true} if secure,
168 * {@code false} otherwise
169 */
170 boolean isSecure();
171
172 }