/lib/src/org/apache/http/conn/routing/RouteInfo.java

  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
 28package org.apache.http.conn.routing;
 29
 30import java.net.InetAddress;
 31
 32import org.apache.http.HttpHost;
 33
 34/**
 35 * Read-only interface for route information.
 36 *
 37 * @since 4.0
 38 */
 39public 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}