Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.io

Class RequestConfiguration

java.lang.Object
com.esri.arcgisruntime.io.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 Details

    • 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 Details

    • 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