Package com.esri.arcgisruntime.io

Class RequestConfiguration

  • public final class RequestConfiguration
extends Object
    Specifies configuration settings that apply to network requests such as the maximum number of retries or a timeout.

    By default, all instances of RemoteResource share a default global RequestConfiguration; the default values for each parameter are described in the getter and setter methods below. You can replace the global default RequestConfiguration using the static method setGlobalRequestConfiguration(RequestConfiguration). For example, you can change the global RequestConfiguration to add an HTML header to all requests without having to set a RequestConfiguration on every RemoteResource.

    Occasionally, you may want to set different configurations on different RemoteResources. To do this, create a new configuration and pass it to RemoteResource.setRequestConfiguration(RequestConfiguration). The new configuration will be used for any request made through the context of that object, such as all requests made using a specific Portal instance. The object-specific RequestConfiguration overrides the global RequestConfiguration described above.

    To stop using an object-specific RequestConfiguration that you previously set, set it back to null. After this is done, requests made through that object will revert to use the global RequestConfiguration.

    Since:
    100.0.0

    • Constructor Detail

      • RequestConfiguration

        public RequestConfiguration()
        Creates a default Request configuration. This should be used if not all properties need to be overwritten, and can then use a fluent pattern to set the desired properties, and use defaults for the others.
        Since:
        100.0.0

      • RequestConfiguration

        public RequestConfiguration​(int connectionTimeout,
                            int socketTimeout,
                            int maxNumberOfAttempts,
                            Map<String,​String> headers,
                            boolean forcePost,
                            boolean issueAuthenticationChallenge)
        Creates a custom RequestConfiguration. This should be used if all properties need to be overwritten. This is a convenience constructor.
        Parameters:
        connectionTimeout - the connection timeout
        socketTimeout - the socket timeout
        headers - the additional headers to be added to the request
        forcePost - whether to force a POST request
        issueAuthenticationChallenge - whether to issue an authentication challenge
        Since:
        100.0.0

    • Method Detail

      • getConnectionTimeout

        public int getConnectionTimeout()
        Gets the connection timeout to use for the request. This timeout specifies how long to wait before a successful TCP/IP handshake has occurred. If this time expires before the handshake has completed successfully, a TimeoutException will be generated. Default value is 10000ms (10 seconds).
        Returns:
        the connection timeout
        Since:
        100.0.0

      • setConnectionTimeout

        public RequestConfiguration setConnectionTimeout​(int connectionTimeout)
        Sets the connection timeout to use for the request. This timeout specifies how long to wait before a successful TCP/IP handshake has occurred. If this time expires before the handshake has completed successfully, a TimeoutException will be generated. Default value is 10000ms (10 seconds).
        Parameters:
        connectionTimeout - the connection timeout
        Returns:
        the request configuration itself, to be further used in a fluent pattern
        Since:
        100.0.0

      • getSocketTimeout

        public int getSocketTimeout()
        Gets the socket timeout to use for the request. This timeout specifies how long a socket may remain open while not receiving any data. If the specified time period elapses without any data transmission, the socket will be closed. Default value is 30000ms (30 seconds).
        Returns:
        the socket timeout
        Since:
        100.0.0

      • setSocketTimeout

        public RequestConfiguration setSocketTimeout​(int socketTimeout)
        Sets the socket timeout to use for the request. This timeout specifies how long a socket may remain open while not receiving any data. If the specified time period elapses without any data transmission, the socket will be closed. Default value is 30000ms (30 seconds).
        Parameters:
        socketTimeout - the socket timeout
        Returns:
        the request configuration itself, to be further used in a fluent pattern
        Since:
        100.0.0

      • getMaxNumberOfAttempts

        public int getMaxNumberOfAttempts()
        Gets the maximum number of times the request should be attempted before failing completely and throwing the original exception. Default value is 5.
        Returns:
        the maximum number of times to attempt the request
        Since:
        100.0.0

      • setMaxNumberOfAttempts

        public RequestConfiguration setMaxNumberOfAttempts​(int maxNumberOfAttempts)
        Sets the maximum number of times the request should be attempted before failing completely and throwing the original exception. Default value is 5.
        Parameters:
        maxNumberOfAttempts - the maximum number of times to attempt the request
        Returns:
        the request configuration itself, to be further used in a fluent pattern
        Since:
        100.0.0

      • getHeaders

        public Map<String,​String> getHeaders()
        Returns the current custom HTTP headers set on the network request. This should be a map of <HeaderKey, HeaderValue> pairs.
        Returns:
        the Map of headers
        Since:
        100.0.0

      • setHeaders

        public RequestConfiguration setHeaders​(Map<String,​String> headers)
        Copies the custom headers into the RequestConfiguration. These headers will only be applied to requests associated with this RequestConfiguration. If a User-Agent is set in the headers, its value will be appended to the end of the predefined user agent string of the API. To apply additional User-Agent information to all requests use setAdditionalUserAgentInfo(String) instead.
        Parameters:
        headers - additional headers to be used with the request
        Returns:
        the request configuration itself, to be further used in a fluent pattern
        Since:
        100.0.0

      • isForcePost

        public boolean isForcePost()
        Checks whether network requests will be forced as a POST request. If true is returned, then even requests which normally use GET will be forced to use POST. Otherwise, it will use GET or POST depending on the default behavior of the request. Default value is false.
        Returns:
        whether the request will be forced as a POST request
        Since:
        100.0.0

      • setForcePost

        public RequestConfiguration setForcePost​(boolean forcePost)
        Sets whether network requests will be forced as a POST request. If true is passed, then even requests which normally use GET will be forced to use POST. Otherwise, it will use GET or POST depending on the default behavior of the request. Default value is false.
        Parameters:
        forcePost - whether network requests will be forced as a POST request
        Returns:
        the request configuration itself, to be further used in a fluent pattern
        Since:
        100.0.0

      • isIssueAuthenticationChallenge

        public boolean isIssueAuthenticationChallenge()
        Checks whether or not an authentication challenge should be issued upon failure to access the requested resource. If true is returned, then the challenge handler will be invoked to prompt the user for credentials. Otherwise, secured services will simply fail. A custom challenge handler may be set if desired. Default value is true. See AuthenticationChallenge, AuthenticationChallengeHandler, and AuthenticationManager
        Returns:
        whether or not an authentication challenge should be issued
        Since:
        100.0.0

      • setIssueAuthenticationChallenge

        public RequestConfiguration setIssueAuthenticationChallenge​(boolean issueAuthenticationChallenge)
        Sets whether or not an authentication challenge should be issued upon failure to access the requested resource. If true is returned, then the challenge handler will be invoked to prompt the user for credentials. Otherwise, secured services will simply fail. A custom challenge handler may be set if desired. Default value is true.
        Parameters:
        issueAuthenticationChallenge - whether or not an authentication challenge should be issued
        Returns:
        the request configuration itself, to be further used in a fluent pattern
        Since:
        100.0.0

      • setProxyInfo

        public static void setProxyInfo​(String proxyHost,
                                int proxyPort)
                         throws IOException
        Sets a proxy with the specified host and port, using the default scheme of HTTP. All subsequent requests will use the proxy.
        Parameters:
        proxyHost - the proxy host, or null to clear the proxy
        proxyPort - the proxy port; may not be null so use any integer if you are clearing the proxy
        Throws:
        IOException - if there is an issue rebuilding the client with the proxy
        Since:
        100.0.0

      • setProxyInfo

        public static void setProxyInfo​(String proxyHost,
                                int proxyPort,
                                String scheme)
                         throws IOException
        Sets a proxy with the specified host, port, and scheme. All subsequent requests will use the proxy.
        Parameters:
        proxyHost - the proxy host, or null to clear the proxy
        proxyPort - the proxy port; may not be null so use any integer if you are clearing the proxy
        scheme - the proxy scheme; null indicates to use the default http scheme
        Throws:
        IOException - if there is an issue rebuilding the client with the proxy
        Since:
        100.0.0

      • setProxyInfo

        public static void setProxyInfo​(String proxyHost,
                                int proxyPort,
                                UserCredential credential)
                         throws IOException
        Sets a proxy with the specified host and port, using the default scheme of HTTP. A UserCredential should be passed if the proxy is secured, or null if it is not. All subsequent requests will use the proxy.
        Parameters:
        proxyHost - the proxy host, or null to clear the proxy
        proxyPort - the proxy port
        credential - a UserCredential with which to authenticate the proxy, or null if unsecured
        Throws:
        IOException - if there is an issue rebuilding the client with the proxy
        Since:
        100.1.0

      • setProxyInfo

        public static void setProxyInfo​(String proxyHost,
                                int proxyPort,
                                String scheme,
                                UserCredential credential)
                         throws IOException
        Sets a proxy with the specified host, port, and scheme. A UserCredential should be passed if the proxy is secured, or null if it is not. All subsequent requests will use the proxy.
        Parameters:
        proxyHost - the proxy host, or null to clear the proxy
        proxyPort - the proxy port
        scheme - the proxy scheme; null indicates to use the default http scheme
        credential - a UserCredential with which to authenticate the proxy, or null if unsecured
        Throws:
        IOException - if there is an issue rebuilding the client with the proxy
        Since:
        100.1.0

      • getGlobalRequestConfiguration

        public static RequestConfiguration getGlobalRequestConfiguration()
        Gets the global request configuration which will be used by default on any requests that do not override it with their own request-level configuration. By default, it uses all default values specified in the getters and setters of the parameters. You can replace this by calling setGlobalRequestConfiguration with your own custom RequestConfiguration.
        Returns:
        the current global request configuration
        Since:
        100.0.0

      • setGlobalRequestConfiguration

        public static void setGlobalRequestConfiguration​(RequestConfiguration globalRequestConfiguration)
        Sets a global request configuration which will be used by default on any requests that do not override it with their own request-level configuration. By default, it uses all default values specified in the getters and setters of the parameters.

        To stop using an object-specific RequestConfiguration that you previously set, set it back to null. After this is done, requests made through that object will revert to use the global RequestConfiguration.

        Parameters:
        globalRequestConfiguration - the global request configuration to set
        Throws:
        IllegalArgumentException - if the globalRequestConfiguration is null
        Since:
        100.0.0

      • getAdditionalUserAgentInfo

        public static String getAdditionalUserAgentInfo()
        Returns the additional information that is put in the User-Agent header field in all HTTP requests. This will be added at the end of the User-Agent field and is intended to identify the name and version of the application software. Default value is null.
        Returns:
        the additional user agent info
        Since:
        100.0.0

      • setAdditionalUserAgentInfo

        public static void setAdditionalUserAgentInfo​(String additionalUserAgentInfo)
                                       throws IOException
        Sets additional information to be put in the User-Agent header field in all HTTP requests. This will be added at the end of the User-Agent field and is intended to identify the name and version of the application software.
        Parameters:
        additionalUserAgentInfo - a string to be added at the end of the User-Agent header field
        Throws:
        IOException - if there is an issue applying the additional user agent info
        Since:
        100.0.0

      • copy

        public RequestConfiguration copy()
        Creates a deep copy of this RequestConfiguration instance.
        Returns:
        a deep copy of this RequestConfiguration instance
        Since:
        100.1.0