Package com.neovisionaries.ws.client

Class ProxySettings

  • public class ProxySettings
extends java.lang.Object
    Proxy settings.

    If a proxy server's host name is set (= if getHost() returns a non-null value), a socket factory that creates a socket to communicate with the proxy server is selected based on the settings of this ProxySettings instance. The following is the concrete flow to select a socket factory.

    1. If isSecure() returns true,
      1. If an SSLContext instance has been set by setSSLContext(SSLContext), the value returned from SSLContext.getSocketFactory() method of the instance is used.
      2. Otherwise, if an SSLSocketFactory instance has been set by setSSLSocketFactory(SSLSocketFactory), the instance is used.
      3. Otherwise, the value returned from SSLSocketFactory.getDefault() is used.
    2. Otherwise (= isSecure() returns false),
      1. If a SocketFactory instance has been set by setSocketFactory(SocketFactory), the instance is used.
      2. Otherwise, the value returned from SocketFactory.getDefault() is used.

    Note that the current implementation supports only Basic Authentication for authentication at the proxy server.

    Since:
    1.3
    See Also:
    WebSocketFactory.getProxySettings()

    • Field Detail

      • mHeaders

        private final java.util.Map<java.lang.String,​java.util.List<java.lang.String>> mHeaders

      • mSecure

        private boolean mSecure

      • mHost

        private java.lang.String mHost

      • mPort

        private int mPort

      • mId

        private java.lang.String mId

      • mPassword

        private java.lang.String mPassword

      • mServerNames

        private java.lang.String[] mServerNames

    • Constructor Detail

      • ProxySettings

        ProxySettings​(WebSocketFactory factory)
        Constructor. A WebSocketFactory instance to be associated with.
        Parameters:
        factory -

      • ProxySettings

        ProxySettings​(WebSocketFactory factory,
              ProxySettings settings)
        Constructor with settings.
        Parameters:
        factory - A WebSocketFactory instance to be associated with.
        settings - Settings to copy.
        Since:
        2.10

    • Method Detail

      • reset

        public ProxySettings reset()
        Reset the proxy settings. To be concrete, parameter values are set as shown below.
        Name Value Description
        Secure false Use TLS to connect to the proxy server or not.
        Host null The host name of the proxy server.
        Port -1 The port number of the proxy server.
        ID null The ID for authentication at the proxy server.
        Password null The password for authentication at the proxy server.
        Headers Cleared Additional HTTP headers passed to the proxy server.
        Server Names null Server names for SNI (Server Name Indication).
        Returns:
        this object.

      • isSecure

        public boolean isSecure()
        Check whether use of TLS is enabled or disabled.
        Returns:
        true if TLS is used in the communication with the proxy server.

      • setSecure

        public ProxySettings setSecure​(boolean secure)
        Enable or disable use of TLS.
        Parameters:
        secure - true to use TLS in the communication with the proxy server.
        Returns:
        this object.

      • getHost

        public java.lang.String getHost()
        Get the host name of the proxy server.

        The default value is null. If this method returns a non-null value, it is used as the proxy server.

        Returns:
        The host name of the proxy server.

      • setHost

        public ProxySettings setHost​(java.lang.String host)
        Set the host name of the proxy server.

        If a non-null value is set, it is used as the proxy server.

        Parameters:
        host - The host name of the proxy server.
        Returns:
        this object.

      • getPort

        public int getPort()
        Get the port number of the proxy server.

        The default value is -1. -1 means that the default port number (80 for non-secure connections and 443 for secure connections) should be used.

        Returns:
        The port number of the proxy server.

      • setPort

        public ProxySettings setPort​(int port)
        Set the port number of the proxy server.

        If -1 is set, the default port number (80 for non-secure connections and 443 for secure connections) is used.

        Parameters:
        port - The port number of the proxy server.
        Returns:
        this object.

      • getId

        public java.lang.String getId()
        Get the ID for authentication at the proxy server.

        The default value is null. If this method returns a non-null value, it is used as the ID for authentication at the proxy server. To be concrete, the value is used to generate the value of Proxy-Authorization header.

        Returns:
        The ID for authentication at the proxy server.

      • setId

        public ProxySettings setId​(java.lang.String id)
        Set the ID for authentication at the proxy server.

        If a non-null value is set, it is used as the ID for authentication at the proxy server. To be concrete, the value is used to generate the value of Proxy-Authorization header.

        Parameters:
        id - The ID for authentication at the proxy server.
        Returns:
        this object.

      • getPassword

        public java.lang.String getPassword()
        Get the password for authentication at the proxy server.
        Returns:
        The password for authentication at the proxy server.

      • setPassword

        public ProxySettings setPassword​(java.lang.String password)
        Set the password for authentication at the proxy server.
        Parameters:
        password - The password for authentication at the proxy server.
        Returns:
        this object.

      • setCredentials

        public ProxySettings setCredentials​(java.lang.String id,
                                    java.lang.String password)
        Set credentials for authentication at the proxy server. This method is an alias of setId (id).setPassword (password).
        Parameters:
        id - The ID.
        password - The password.
        Returns:
        this object.

      • setServer

        public ProxySettings setServer​(java.lang.String uri)
        Set the proxy server by a URI. See the description of setServer(URI) about how the parameters are updated.
        Parameters:
        uri - The URI of the proxy server. If null is given, none of the parameters are updated.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - Failed to convert the given string to a URI instance.

      • setServer

        public ProxySettings setServer​(java.net.URL url)
        Set the proxy server by a URL. See the description of setServer(URI) about how the parameters are updated.
        Parameters:
        url - The URL of the proxy server. If null is given, none of the parameters are updated.
        Returns:
        this object.
        Throws:
        java.lang.IllegalArgumentException - Failed to convert the given URL to a URI instance.

      • setServer

        public ProxySettings setServer​(java.net.URI uri)
        Set the proxy server by a URI. The parameters are updated as described below.
        Secure

        If the URI contains the scheme part and its value is either "http" or "https" (case-insensitive), the secure parameter is updated to false or to true accordingly. In other cases, the parameter is not updated.

        ID & Password

        If the URI contains the userinfo part and the ID embedded in the userinfo part is not an empty string, the id parameter and the password parameter are updated accordingly. In other cases, the parameters are not updated.

        Host

        The host parameter is always updated by the given URI.

        Port

        The port parameter is always updated by the given URI.

        Parameters:
        uri - The URI of the proxy server. If null is given, none of the parameters is updated.
        Returns:
        this object.

      • setServer

        private ProxySettings setServer​(java.lang.String scheme,
                                java.lang.String userInfo,
                                java.lang.String host,
                                int port)

      • setByScheme

        private void setByScheme​(java.lang.String scheme)

      • setByUserInfo

        private void setByUserInfo​(java.lang.String userInfo)

      • getHeaders

        public java.util.Map<java.lang.String,​java.util.List<java.lang.String>> getHeaders()
        Get additional HTTP headers passed to the proxy server.
        Returns:
        Additional HTTP headers passed to the proxy server. The comparator of the returned map is String.CASE_INSENSITIVE_ORDER.

      • addHeader

        public ProxySettings addHeader​(java.lang.String name,
                               java.lang.String value)
        Add an additional HTTP header passed to the proxy server.
        Parameters:
        name - The name of an HTTP header (case-insensitive). If null or an empty string is given, nothing is added.
        value - The value of the HTTP header.
        Returns:
        this object.

      • getSocketFactory

        public javax.net.SocketFactory getSocketFactory()
        Get the socket factory that has been set by setSocketFactory(SocketFactory).
        Returns:
        The socket factory.

      • setSocketFactory

        public ProxySettings setSocketFactory​(javax.net.SocketFactory factory)
        Set a socket factory.
        Parameters:
        factory - A socket factory.
        Returns:
        this instance.

      • getSSLSocketFactory

        public javax.net.ssl.SSLSocketFactory getSSLSocketFactory()
        Get the SSL socket factory that has been set by setSSLSocketFactory(SSLSocketFactory).
        Returns:
        The SSL socket factory.

      • setSSLSocketFactory

        public ProxySettings setSSLSocketFactory​(javax.net.ssl.SSLSocketFactory factory)
        Set an SSL socket factory.
        Parameters:
        factory - An SSL socket factory.
        Returns:
        this instance.

      • getSSLContext

        public javax.net.ssl.SSLContext getSSLContext()
        Get the SSL context that has been set by setSSLContext(SSLContext).
        Returns:
        The SSL context.

      • setSSLContext

        public ProxySettings setSSLContext​(javax.net.ssl.SSLContext context)
        Set an SSL context to get a socket factory.
        Parameters:
        context - An SSL context.
        Returns:
        this instance.

      • selectSocketFactory

        javax.net.SocketFactory selectSocketFactory()

      • getServerNames

        public java.lang.String[] getServerNames()
        Get server names for SNI (Server Name Indication).
        Returns:
        List of host names.
        Since:
        2.4

      • setServerNames

        public ProxySettings setServerNames​(java.lang.String[] serverNames)
        Set server names for SNI (Server Name Indication). If setServerNames(List<SNIServerName>) method of SSLParameters class is available in the underlying system, the method is called to set up server names for SNI (Server Name Indication).
        Parameters:
        serverNames - List of host names.
        Returns:
        this object.
        Since:
        2.4

      • setServerName

        public ProxySettings setServerName​(java.lang.String serverName)
        Set a server name for SNI (Server Name Indication). This method internally creates a String array of size 1 which contains the given serverName and calls setServerNames(String[]).
        Parameters:
        serverName - A host name.
        Returns:
        this object.
        Since:
        2.4