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 Summary
ConstructorDescriptionCreates a default Request configuration.RequestConfiguration
(int connectionTimeout, int socketTimeout, int maxNumberOfAttempts, Map<String, String> headers, boolean forcePost, boolean issueAuthenticationChallenge) Creates a custom RequestConfiguration. -
Method Summary
Modifier and TypeMethodDescriptioncopy()
Creates a deep copy of this RequestConfiguration instance.static String
Returns the additional information that is put in the User-Agent header field in all HTTP requests.int
Gets the connection timeout to use for the request.static RequestConfiguration
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.Returns the current custom HTTP headers set on the network request.int
Gets the maximum number of times the request should be attempted before failing completely and throwing the original exception.int
Gets the socket timeout to use for the request.boolean
Checks whether network requests will be forced as a POST request.boolean
Checks whether or not an authentication challenge should be issued upon failure to access the requested resource.static void
setAdditionalUserAgentInfo
(String additionalUserAgentInfo) Sets additional information to be put in the User-Agent header field in all HTTP requests.setConnectionTimeout
(int connectionTimeout) Sets the connection timeout to use for the request.setForcePost
(boolean forcePost) Sets whether network requests will be forced as a POST request.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.setHeaders
(Map<String, String> headers) Copies the custom headers into the RequestConfiguration.setIssueAuthenticationChallenge
(boolean issueAuthenticationChallenge) Sets whether or not an authentication challenge should be issued upon failure to access the requested resource.setMaxNumberOfAttempts
(int maxNumberOfAttempts) Sets the maximum number of times the request should be attempted before failing completely and throwing the original exception.static void
setProxyInfo
(String proxyHost, int proxyPort) Sets a proxy with the specified host and port, using the default scheme of HTTP.static void
setProxyInfo
(String proxyHost, int proxyPort, UserCredential credential) Sets a proxy with the specified host and port, using the default scheme of HTTP.static void
setProxyInfo
(String proxyHost, int proxyPort, String scheme) Sets a proxy with the specified host, port, and scheme.static void
setProxyInfo
(String proxyHost, int proxyPort, String scheme, UserCredential credential) Sets a proxy with the specified host, port, and scheme.setSocketTimeout
(int socketTimeout) Sets the socket timeout to use for the request.
-
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 timeoutsocketTimeout
- the socket timeoutheaders
- the additional headers to be added to the requestforcePost
- whether to force a POST requestissueAuthenticationChallenge
- 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
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
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
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
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
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 usesetAdditionalUserAgentInfo(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
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. SeeAuthenticationChallenge
,AuthenticationChallengeHandler
, andAuthenticationManager
- Returns:
- whether or not an authentication challenge should be issued
- Since:
- 100.0.0
-
setIssueAuthenticationChallenge
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
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 proxyproxyPort
- 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
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 proxyproxyPort
- the proxy port; may not be null so use any integer if you are clearing the proxyscheme
- 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 proxyproxyPort
- the proxy portcredential
- 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 proxyproxyPort
- the proxy portscheme
- the proxy scheme; null indicates to use the default http schemecredential
- 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
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
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
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
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
Creates a deep copy of this RequestConfiguration instance.- Returns:
- a deep copy of this RequestConfiguration instance
- Since:
- 100.1.0
-