Package org.apache.hc.client5.http

Class HttpRoute

  • All Implemented Interfaces:
    java.lang.Cloneable, RouteInfo
    @Contract(threading=IMMUTABLE)
public final class HttpRoute
extends java.lang.Object
implements RouteInfo, java.lang.Cloneable
    Connection route definition for HTTP requests.
    Since:
    4.0

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private RouteInfo.LayerType layered
      Whether the route is layered.
      private java.net.InetAddress localAddress
      The local address to connect from.
      private java.util.List<org.apache.hc.core5.http.HttpHost> proxyChain
      The proxy servers, if any.
      private boolean secure
      Whether the route is (supposed to be) secure.
      private org.apache.hc.core5.http.HttpHost targetHost
      The target host to connect to.
      private org.apache.hc.core5.net.NamedEndpoint targetName
      The target name, if different from the target host, null otherwise.
      private RouteInfo.TunnelType tunnelled
      Whether the the route is tunnelled through the proxy.
      private java.nio.file.Path unixDomainSocket
      The path to the UDS to connect to, if any.

    • Constructor Summary

      Constructors 
      Constructor Description
      HttpRoute​(org.apache.hc.core5.http.HttpHost target)
      Creates a new direct insecure route.
      HttpRoute​(org.apache.hc.core5.http.HttpHost target, boolean secure, java.nio.file.Path unixDomainSocket)
      Creates a new direct route that connects over a Unix domain socket rather than TCP.
      HttpRoute​(org.apache.hc.core5.http.HttpHost target, java.net.InetAddress local, boolean secure)
      Creates a new direct route.
      HttpRoute​(org.apache.hc.core5.http.HttpHost target, java.net.InetAddress local, org.apache.hc.core5.http.HttpHost[] proxies, boolean secure, RouteInfo.TunnelType tunnelled, RouteInfo.LayerType layered)
      Creates a new route with all attributes specified explicitly.
      HttpRoute​(org.apache.hc.core5.http.HttpHost target, java.net.InetAddress local, org.apache.hc.core5.http.HttpHost proxy, boolean secure)
      Creates a new route through a proxy.
      HttpRoute​(org.apache.hc.core5.http.HttpHost target, java.net.InetAddress local, org.apache.hc.core5.http.HttpHost proxy, boolean secure, RouteInfo.TunnelType tunnelled, RouteInfo.LayerType layered)
      Creates a new route with at most one proxy.
      HttpRoute​(org.apache.hc.core5.http.HttpHost target, java.nio.file.Path unixDomainSocket)
      Creates a new direct route that connects over a Unix domain socket rather than TCP.
      HttpRoute​(org.apache.hc.core5.http.HttpHost target, org.apache.hc.core5.http.HttpHost proxy)
      Creates a new plain route through a proxy.
      HttpRoute​(org.apache.hc.core5.http.HttpHost target, org.apache.hc.core5.net.NamedEndpoint targetName, java.net.InetAddress local, boolean secure)
      Creates a new direct route.
      HttpRoute​(org.apache.hc.core5.http.HttpHost targetHost, org.apache.hc.core5.net.NamedEndpoint targetName, java.net.InetAddress local, java.util.List<org.apache.hc.core5.http.HttpHost> proxies, java.nio.file.Path unixDomainSocket, boolean secure, RouteInfo.TunnelType tunnelled, RouteInfo.LayerType layered)  
      HttpRoute​(org.apache.hc.core5.http.HttpHost target, org.apache.hc.core5.net.NamedEndpoint targetName, java.net.InetAddress local, org.apache.hc.core5.http.HttpHost[] proxies, boolean secure, RouteInfo.TunnelType tunnelled, RouteInfo.LayerType layered)
      Creates a new route with all attributes specified explicitly.
      HttpRoute​(org.apache.hc.core5.http.HttpHost target, org.apache.hc.core5.net.NamedEndpoint targetName, java.net.InetAddress local, org.apache.hc.core5.http.HttpHost proxy, boolean secure)
      Creates a new route through a proxy.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Object clone()  
      boolean equals​(java.lang.Object obj)
      Compares this route to another.
      int getHopCount()
      Obtains the number of hops in this route.
      org.apache.hc.core5.http.HttpHost getHopTarget​(int hop)
      Obtains the target of a hop in this route.
      RouteInfo.LayerType getLayerType()
      Obtains the layering type of this route.
      java.net.InetAddress getLocalAddress()
      Obtains the local address to connect from.
      java.net.InetSocketAddress getLocalSocketAddress()  
      org.apache.hc.core5.http.HttpHost getProxyHost()
      Obtains the first proxy host.
      org.apache.hc.core5.http.HttpHost getTargetHost()
      Obtains the target host.
      org.apache.hc.core5.net.NamedEndpoint getTargetName()
      Obtains the target name, if different from the target host, null otherwise.
      RouteInfo.TunnelType getTunnelType()
      Obtains the tunnel type of this route.
      java.nio.file.Path getUnixDomainSocket()
      Obtains the Unix domain socket through which to connect to the target host.
      int hashCode()
      Generates a hash code for this route.
      boolean isLayered()
      Checks whether this route includes a layered protocol.
      boolean isSecure()
      Checks whether this route is secure.
      boolean isTunnelled()
      Checks whether this route is tunnelled through a proxy.
      java.lang.String toString()
      Obtains a description of this route.
      private void validateUdsArguments()  

      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • targetHost

        private final org.apache.hc.core5.http.HttpHost targetHost
        The target host to connect to.

      • targetName

        private final org.apache.hc.core5.net.NamedEndpoint targetName
        The target name, if different from the target host, null otherwise.

      • localAddress

        private final java.net.InetAddress localAddress
        The local address to connect from. null indicates that the default should be used.

      • proxyChain

        private final java.util.List<org.apache.hc.core5.http.HttpHost> proxyChain
        The proxy servers, if any. Never null.

      • unixDomainSocket

        private final java.nio.file.Path unixDomainSocket
        The path to the UDS to connect to, if any.

      • tunnelled

        private final RouteInfo.TunnelType tunnelled
        Whether the the route is tunnelled through the proxy.

      • secure

        private final boolean secure
        Whether the route is (supposed to be) secure.

    • Constructor Detail

      • HttpRoute

        HttpRoute​(org.apache.hc.core5.http.HttpHost targetHost,
          org.apache.hc.core5.net.NamedEndpoint targetName,
          java.net.InetAddress local,
          java.util.List<org.apache.hc.core5.http.HttpHost> proxies,
          java.nio.file.Path unixDomainSocket,
          boolean secure,
          RouteInfo.TunnelType tunnelled,
          RouteInfo.LayerType layered)

      • HttpRoute

        public HttpRoute​(org.apache.hc.core5.http.HttpHost target,
                 java.net.InetAddress local,
                 org.apache.hc.core5.http.HttpHost[] proxies,
                 boolean secure,
                 RouteInfo.TunnelType tunnelled,
                 RouteInfo.LayerType layered)
        Creates a new route with all attributes specified explicitly.
        Parameters:
        target - the host to which to route
        local - the local address to route from, or null for the default
        proxies - the proxy chain to use, or null for a direct route
        secure - true if the route is (to be) secure, false otherwise
        tunnelled - the tunnel type of this route
        layered - the layering type of this route

      • HttpRoute

        public HttpRoute​(org.apache.hc.core5.http.HttpHost target,
                 org.apache.hc.core5.net.NamedEndpoint targetName,
                 java.net.InetAddress local,
                 org.apache.hc.core5.http.HttpHost[] proxies,
                 boolean secure,
                 RouteInfo.TunnelType tunnelled,
                 RouteInfo.LayerType layered)
        Creates a new route with all attributes specified explicitly.
        Parameters:
        target - the host to which to route
        targetName - the target targetName if differs from the target host.
        local - the local address to route from, or null for the default
        proxies - the proxy chain to use, or null for a direct route
        secure - true if the route is (to be) secure, false otherwise
        tunnelled - the tunnel type of this route
        layered - the layering type of this route
        Since:
        5.4

      • HttpRoute

        public HttpRoute​(org.apache.hc.core5.http.HttpHost target,
                 java.net.InetAddress local,
                 org.apache.hc.core5.http.HttpHost proxy,
                 boolean secure,
                 RouteInfo.TunnelType tunnelled,
                 RouteInfo.LayerType layered)
        Creates a new route with at most one proxy.
        Parameters:
        target - the host to which to route
        local - the local address to route from, or null for the default
        proxy - the proxy to use, or null for a direct route
        secure - true if the route is (to be) secure, false otherwise
        tunnelled - true if the route is (to be) tunnelled via the proxy, false otherwise
        layered - true if the route includes a layered protocol, false otherwise

      • HttpRoute

        public HttpRoute​(org.apache.hc.core5.http.HttpHost target,
                 java.net.InetAddress local,
                 boolean secure)
        Creates a new direct route. That is a route without a proxy.
        Parameters:
        target - the host to which to route
        local - the local address to route from, or null for the default
        secure - true if the route is (to be) secure, false otherwise

      • HttpRoute

        public HttpRoute​(org.apache.hc.core5.http.HttpHost target,
                 org.apache.hc.core5.net.NamedEndpoint targetName,
                 java.net.InetAddress local,
                 boolean secure)
        Creates a new direct route. That is a route without a proxy.
        Parameters:
        target - the host to which to route
        targetName - the target targetName if differs from the target host.
        local - the local address to route from, or null for the default
        secure - true if the route is (to be) secure, false otherwise
        Since:
        5.4

      • HttpRoute

        public HttpRoute​(org.apache.hc.core5.http.HttpHost target,
                 java.nio.file.Path unixDomainSocket)
        Creates a new direct route that connects over a Unix domain socket rather than TCP.
        Parameters:
        target - the host to which to route
        unixDomainSocket - the path to the Unix domain socket
        Since:
        5.6

      • HttpRoute

        public HttpRoute​(org.apache.hc.core5.http.HttpHost target,
                 boolean secure,
                 java.nio.file.Path unixDomainSocket)
        Creates a new direct route that connects over a Unix domain socket rather than TCP.
        Parameters:
        target - the host to which to route
        secure - true if the route is (to be) secure, false otherwise
        unixDomainSocket - the path to the Unix domain socket
        Since:
        5.6

      • HttpRoute

        public HttpRoute​(org.apache.hc.core5.http.HttpHost target)
        Creates a new direct insecure route.
        Parameters:
        target - the host to which to route

      • HttpRoute

        public HttpRoute​(org.apache.hc.core5.http.HttpHost target,
                 org.apache.hc.core5.net.NamedEndpoint targetName,
                 java.net.InetAddress local,
                 org.apache.hc.core5.http.HttpHost proxy,
                 boolean secure)
        Creates a new route through a proxy. When using this constructor, the proxy MUST be given. For convenience, it is assumed that a secure connection will be layered over a tunnel through the proxy.
        Parameters:
        target - the host to which to route
        targetName - the target targetName if differs from the target host.
        local - the local address to route from, or null for the default
        proxy - the proxy to use
        secure - true if the route is (to be) secure, false otherwise
        Since:
        5.4

      • HttpRoute

        public HttpRoute​(org.apache.hc.core5.http.HttpHost target,
                 java.net.InetAddress local,
                 org.apache.hc.core5.http.HttpHost proxy,
                 boolean secure)
        Creates a new route through a proxy. When using this constructor, the proxy MUST be given. For convenience, it is assumed that a secure connection will be layered over a tunnel through the proxy.
        Parameters:
        target - the host to which to route
        local - the local address to route from, or null for the default
        proxy - the proxy to use
        secure - true if the route is (to be) secure, false otherwise

      • HttpRoute

        public HttpRoute​(org.apache.hc.core5.http.HttpHost target,
                 org.apache.hc.core5.http.HttpHost proxy)
        Creates a new plain route through a proxy.
        Parameters:
        target - the host to which to route
        proxy - the proxy to use
        Since:
        4.3

    • Method Detail

      • validateUdsArguments

        private void validateUdsArguments()

      • getTargetHost

        public org.apache.hc.core5.http.HttpHost getTargetHost()
        Description copied from interface: RouteInfo
        Obtains the target host.
        Specified by:
        getTargetHost in interface RouteInfo
        Returns:
        the target host

      • getTargetName

        public org.apache.hc.core5.net.NamedEndpoint getTargetName()
        Description copied from interface: RouteInfo
        Obtains the target name, if different from the target host, null otherwise.
        Specified by:
        getTargetName in interface RouteInfo
        Since:
        5.4

      • getLocalAddress

        public java.net.InetAddress getLocalAddress()
        Description copied from interface: RouteInfo
        Obtains the local address to connect from.
        Specified by:
        getLocalAddress in interface RouteInfo
        Returns:
        the local address, or null

      • getLocalSocketAddress

        public java.net.InetSocketAddress getLocalSocketAddress()

      • getHopCount

        public int getHopCount()
        Description copied from interface: RouteInfo
        Obtains the number of hops in this route. A direct route has one hop. A route through a proxy has two hops. A route through a chain of n proxies has n+1 hops.
        Specified by:
        getHopCount in interface RouteInfo
        Returns:
        the number of hops in this route

      • getHopTarget

        public org.apache.hc.core5.http.HttpHost getHopTarget​(int hop)
        Description copied from interface: RouteInfo
        Obtains the target of a hop in this route. The target of the last hop is the target host, the target of previous hops is the respective proxy in the chain. For a route through exactly one proxy, target of hop 0 is the proxy and target of hop 1 is the target host.
        Specified by:
        getHopTarget in interface RouteInfo
        Parameters:
        hop - index of the hop for which to get the target, 0 for first
        Returns:
        the target of the given hop

      • getProxyHost

        public org.apache.hc.core5.http.HttpHost getProxyHost()
        Description copied from interface: RouteInfo
        Obtains the first proxy host.
        Specified by:
        getProxyHost in interface RouteInfo
        Returns:
        the first proxy in the proxy chain, or null if this route is direct

      • getUnixDomainSocket

        public java.nio.file.Path getUnixDomainSocket()
        Description copied from interface: RouteInfo
        Obtains the Unix domain socket through which to connect to the target host.
        Specified by:
        getUnixDomainSocket in interface RouteInfo
        Returns:
        the path to the Unix domain socket, or null if none

      • getTunnelType

        public RouteInfo.TunnelType getTunnelType()
        Description copied from interface: RouteInfo
        Obtains the tunnel type of this route. If there is a proxy chain, only end-to-end tunnels are considered.
        Specified by:
        getTunnelType in interface RouteInfo
        Returns:
        the tunnelling type

      • isTunnelled

        public boolean isTunnelled()
        Description copied from interface: RouteInfo
        Checks whether this route is tunnelled through a proxy. If there is a proxy chain, only end-to-end tunnels are considered.
        Specified by:
        isTunnelled in interface RouteInfo
        Returns:
        true if tunnelled end-to-end through at least one proxy, false otherwise

      • getLayerType

        public RouteInfo.LayerType getLayerType()
        Description copied from interface: RouteInfo
        Obtains the layering type of this route. In the presence of proxies, only layering over an end-to-end tunnel is considered.
        Specified by:
        getLayerType in interface RouteInfo
        Returns:
        the layering type

      • isLayered

        public boolean isLayered()
        Description copied from interface: RouteInfo
        Checks whether this route includes a layered protocol. In the presence of proxies, only layering over an end-to-end tunnel is considered.
        Specified by:
        isLayered in interface RouteInfo
        Returns:
        true if layered, false otherwise

      • isSecure

        public boolean isSecure()
        Description copied from interface: RouteInfo
        Checks whether this route is secure.
        Specified by:
        isSecure in interface RouteInfo
        Returns:
        true if secure, false otherwise

      • equals

        public boolean equals​(java.lang.Object obj)
        Compares this route to another.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - the object to compare with
        Returns:
        true if the argument is the same route, false

      • hashCode

        public int hashCode()
        Generates a hash code for this route.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hash code

      • toString

        public java.lang.String toString()
        Obtains a description of this route.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a human-readable representation of this route

      • clone

        public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
        Overrides:
        clone in class java.lang.Object
        Throws:
        java.lang.CloneNotSupportedException