com.sdl.delivery.iq.index.client.http

Class ApiClient

java.lang.Object

com.sdl.delivery.iq.index.client.http.ApiClient

public class ApiClient
extends Object

Http Client wrapper.

Constructor Summary

Constructors

Constructor and Description
ApiClient()

Method Summary

Modifier and Type	Method and Description
ApiClient	addDefaultHeader(String key, String value) Add a default header.
okhttp3.Call	buildCall(String path, String method, List<Pair> queryParams, Object body, Map<String,String> headerParams, Map<String,Object> formParams, String[] authNames, ProgressRequestBody.ProgressRequestListener progressRequestListener) Build HTTP call with the given options.
okhttp3.RequestBody	buildRequestBodyFormEncoding(Map<String,Object> formParams) Build a form-encoding request body with the given form parameters.
okhttp3.RequestBody	buildRequestBodyMultipart(Map<String,Object> formParams) Build a multipart (file uploading) request body with the given form parameters, which could contain text fields and file fields.
String	buildUrl(String path, List<Pair> queryParams) Build full URL by concatenating base path, the given sub path and query parameters.
<T> Optional<T>	deserialize(okhttp3.Response response, Class<T> returnType) Deserialize response body to Java object, according to the return type and the Content-Type response header.
File	downloadFileFromResponse(okhttp3.Response response) Download file from the given response.
String	escapeString(String str) Escape the given string to be used as URL query value.
<T> ApiResponse<T>	execute(okhttp3.Call call) execute(Call, Class).
<T> ApiResponse<T>	execute(okhttp3.Call call, Class<T> returnType) Execute HTTP call and deserialize the HTTP response body into the given return type.
<T> void	executeAsync(okhttp3.Call call, ApiCallback<T> callback) executeAsync(Call, Class, ApiCallback).
<T> void	executeAsync(okhttp3.Call call, Class<T> returnType, ApiCallback<T> callback) Execute HTTP call asynchronously.
<T extends QueryResultData<R>,R extends QueryResult> ApiResponse<T>	executeWithResultSet(okhttp3.Call call, Class<T> resultSetClass)
String	formatDate(Date date) Format the given Date object into string (Date format).
String	formatDatetime(Date date) Format the given Date object into string (Datetime format).
Authentication	getAuthentication(String authName) Get authentication for the given name.
Map<String,Authentication>	getAuthentications() Get authentications (key: authentication name, value: authentication).
String	getBasePath() Get base path.
int	getConnectTimeout() Get connection timeout (in milliseconds).
DateFormat	getDateFormat()
DateFormat	getDatetimeFormat()
okhttp3.OkHttpClient	getHttpClient() Get HTTP client.
int	getReadTimeout() Gets the current read timeout for a call.
InputStream	getSslCaCert() Get SSL CA cert.
String	getTempFolderPath() The path of temporary folder used to store downloaded files from endpoints with file response.
int	getWriteTimeout() Gets the current write timeout for a call.
String	guessContentTypeFromFile(File file) Guess Content-Type header from the given file (defaults to "APPLICATION/octet-stream").
<T> Optional<T>	handleResponse(okhttp3.Response response, Class<T> returnType) Handle the given response, return the deserialized object when the response is successful.
<T extends QueryResultData<R>,R extends QueryResult> Optional<T>	handleResponseWithResultSet(okhttp3.Response response, Class<T> resultSetClass) Handle the given response, return the deserialized object with the given result set classes when the response is successful.
boolean	isDebugging() Check that whether debugging is enabled for this API client.
boolean	isJsonMime(String mime) Check if the given MIME is a JSON MIME.
boolean	isLenientDatetimeFormat() Whether to allow various ISO 8601 datetime formats when parsing a datetime string.
boolean	isVerifyingSsl() True if isVerifyingSsl flag is on.
String	parameterToString(Object param) Format the given parameter object into string.
Date	parseDate(String str) Parse the given date string into Date object.
Date	parseDateOrDatetime(String str)
Date	parseDatetime(String str) Parse the given datetime string into Date object.
File	prepareDownloadFile(okhttp3.Response response) Prepare file for download.
void	processHeaderParams(Map<String,String> headerParams, okhttp3.Request.Builder reqBuilder) Set header parameters to the request builder, including default headers.
String	sanitizeFilename(String filename) Sanitize filename by removing path.
String	selectHeaderAccept(String[] accepts) Select the Accept header's value from the given accepts array.
String	selectHeaderContentType(String[] contentTypes) Select the Content-Type header's value from the given array: if JSON exists in the given array, use it; otherwise use the first one of the array.
okhttp3.RequestBody	serialize(Object obj, String contentType) Serialize the given Java object into request body according to the object's class and the request Content-Type.
void	setApiKey(String apiKey) Helper method to set API key value for the first API key authentication.
void	setApiKeyPrefix(String apiKeyPrefix) Helper method to set API key prefix for the first API key authentication.
ApiClient	setBasePath(String path) Set base path.
ApiClient	setConnectTimeout(int connectionTimeout) Sets the connect timeout (in milliseconds).
ApiClient	setDateFormat(DateFormat format)
ApiClient	setDatetimeFormat(DateFormat format)
ApiClient	setDebugging(boolean debugOn) Enable/disable debugging for this API client.
ApiClient	setHttpClient(okhttp3.OkHttpClient client) Set HTTP client.
ApiClient	setLenientDatetimeFormat(boolean lenientFormat)
ApiClient	setMaxIdleConnections(int maxIdleConnections) Sets the maximum number of idle connections in the pool.
void	setPassword(String password) Helper method to set PASSWORD for the first HTTP basic authentication.
ApiClient	setReadTimeout(int readTimeout) Sets the read time out.
ApiClient	setSslCaCert(InputStream cert) Configure the CA certificate to be trusted when making https requests.
ApiClient	setTempFolderPath(String folderPath) Set the temporary folder path (for downloading files).
ApiClient	setUserAgent(String userAgent) Set the User-Agent header's value (by adding to the default header map).
void	setUsername(String username) Helper method to set username for the first HTTP basic authentication.
ApiClient	setVerifyingSsl(boolean sslOn) Configure whether to verify certificate and hostname when making https requests.
ApiClient	setWriteTimeout(int writeTimeout) Sets the write time out.
void	updateParamsForAuth(String[] authNames, List<Pair> queryParams, Map<String,String> headerParams) Update query and header parameters based on authentication settings.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ApiClient

public ApiClient()

Method Detail

getBasePath

public String getBasePath()

Get base path.

Returns:

Base path

setBasePath

public ApiClient setBasePath(String path)

Set base path.

Parameters:

path - Base path of the URL (e.g https://localhost:8080/v1

Returns:

An instance of OkHttpClient.

getHttpClient

public okhttp3.OkHttpClient getHttpClient()

Get HTTP client.

Returns:

An instance of OkHttpClient.

setHttpClient

public ApiClient setHttpClient(okhttp3.OkHttpClient client)

Set HTTP client.

Parameters:

client - An instance of OkHttpClient

Returns:

Api Client

isVerifyingSsl

public boolean isVerifyingSsl()

True if isVerifyingSsl flag is on.

Returns:

True if isVerifySsl flag is on.

setVerifyingSsl

public ApiClient setVerifyingSsl(boolean sslOn)
                          throws ApiException

Configure whether to verify certificate and hostname when making https requests. Default to true. NOTE: Do NOT set to false in production code, otherwise you would face multiple types of cryptographic attacks.

Parameters:

sslOn - True to verify TLS/SSL connection

Returns:

ApiClient

Throws:

ApiException

getSslCaCert

public InputStream getSslCaCert()

Get SSL CA cert.

Returns:

Input stream to the SSL CA cert

setSslCaCert

public ApiClient setSslCaCert(InputStream cert)
                       throws ApiException

Configure the CA certificate to be trusted when making https requests. Use null to reset to default.

Parameters:

cert - input stream for SSL CA cert

Returns:

ApiClient

Throws:

ApiException

getDateFormat

public DateFormat getDateFormat()

setDateFormat

public ApiClient setDateFormat(DateFormat format)

getDatetimeFormat

public DateFormat getDatetimeFormat()

setDatetimeFormat

public ApiClient setDatetimeFormat(DateFormat format)

isLenientDatetimeFormat

public boolean isLenientDatetimeFormat()

Whether to allow various ISO 8601 datetime formats when parsing a datetime string.

Returns:

True if lenientDatetimeFormat flag is set to true

See Also:

parseDatetime(String)

setLenientDatetimeFormat

public ApiClient setLenientDatetimeFormat(boolean lenientFormat)

parseDate

public Date parseDate(String str)

Parse the given date string into Date object. The default dateFormat supports these ISO 8601 date formats: 2015-08-16 2015-8-16

Parameters:

str - String to be parsed

Returns:

Date

parseDatetime

public Date parseDatetime(String str)

Parse the given datetime string into Date object. When lenientDatetimeFormat is enabled, the following ISO 8601 datetime formats are supported: 2015-08-16T08:20:05Z 2015-8-16T8:20:05Z 2015-08-16T08:20:05+00:00 2015-08-16T08:20:05+0000 2015-08-16T08:20:05.376Z 2015-08-16T08:20:05.376+00:00 2015-08-16T08:20:05.376+00 Note: The 3-digit milli-seconds is optional. Time zone is required and can be in one of these formats: Z (same with +0000) +08:00 (same with +0800) -02 (same with -0200) -0200

Parameters:

str - Date time string to be parsed

Returns:

Date representation of the string

See Also:

ISO 8601

parseDateOrDatetime

public Date parseDateOrDatetime(String str)

formatDate

public String formatDate(Date date)

Format the given Date object into string (Date format).

Parameters:

date - Date object

Returns:

Formatted date in string representation

formatDatetime

public String formatDatetime(Date date)

Format the given Date object into string (Datetime format).

Parameters:

date - Date object

Returns:

Formatted datetime in string representation

getAuthentications

public Map<String,Authentication> getAuthentications()

Get authentications (key: authentication name, value: authentication).

Returns:

Map of authentication objects

getAuthentication

public Authentication getAuthentication(String authName)

Get authentication for the given name.

Parameters:

authName - The authentication name

Returns:

The authentication, null if not found

setUsername

public void setUsername(String username)
                 throws ApiException

Helper method to set username for the first HTTP basic authentication.

Parameters:

username - Username

Throws:

ApiException

setPassword

public void setPassword(String password)
                 throws ApiException

Helper method to set PASSWORD for the first HTTP basic authentication.

Parameters:

password - Password

Throws:

ApiException

setApiKey

public void setApiKey(String apiKey)
               throws ApiException

Helper method to set API key value for the first API key authentication.

Parameters:

apiKey - API key

Throws:

ApiException

setApiKeyPrefix

public void setApiKeyPrefix(String apiKeyPrefix)
                     throws ApiException

Helper method to set API key prefix for the first API key authentication.

Parameters:

apiKeyPrefix - API key prefix

Throws:

ApiException

setUserAgent

public ApiClient setUserAgent(String userAgent)

Set the User-Agent header's value (by adding to the default header map).

Parameters:

userAgent - HTTP request's user agent

Returns:

ApiClient

addDefaultHeader

public ApiClient addDefaultHeader(String key,
                                  String value)

Add a default header.

Parameters:

key - The header's key

value - The header's value

Returns:

ApiClient

isDebugging

public boolean isDebugging()

Check that whether debugging is enabled for this API client.

Returns:

True if debugging is enabled, false otherwise.

setDebugging

public ApiClient setDebugging(boolean debugOn)

Enable/disable debugging for this API client.

Parameters:

debugOn - To enable (true) or disable (false) debugging

Returns:

ApiClient

getTempFolderPath

public String getTempFolderPath()

The path of temporary folder used to store downloaded files from endpoints with file response. The default value is null, i.e. using the system's default tempopary folder.

Returns:

Temporary folder path

See Also:

createTempFile

setTempFolderPath

public ApiClient setTempFolderPath(String folderPath)

Set the temporary folder path (for downloading files).

Parameters:

folderPath - Temporary folder path

Returns:

ApiClient

getConnectTimeout

public int getConnectTimeout()

Get connection timeout (in milliseconds).

Returns:

Timeout in milliseconds

setConnectTimeout

public ApiClient setConnectTimeout(int connectionTimeout)

Sets the connect timeout (in milliseconds). A value of 0 means no timeout, otherwise values must be between 1 and

Parameters:

connectionTimeout - connection timeout in milliseconds

Returns:

Api client

setMaxIdleConnections

public ApiClient setMaxIdleConnections(int maxIdleConnections)

Sets the maximum number of idle connections in the pool.

Parameters:

maxIdleConnections - The number of max idle connections

Returns:

the Api client

getReadTimeout

public int getReadTimeout()

Gets the current read timeout for a call.

Returns:

the timeout value in ms.

setReadTimeout

public ApiClient setReadTimeout(int readTimeout)

Sets the read time out.

Parameters:

readTimeout - int in milliseconds

Returns:

the ApiClient.

getWriteTimeout

public int getWriteTimeout()

Gets the current write timeout for a call.

Returns:

the timeout value in ms.

setWriteTimeout

public ApiClient setWriteTimeout(int writeTimeout)

Sets the write time out.

Parameters:

writeTimeout - int in milliseconds

Returns:

the ApiClient.

parameterToString

public String parameterToString(Object param)

Format the given parameter object into string.

Parameters:

param - Parameter

Returns:

String representation of the parameter

sanitizeFilename

public String sanitizeFilename(String filename)

Sanitize filename by removing path. e.g. ../../sun.gif becomes sun.gif

Parameters:

filename - The filename to be sanitized

Returns:

The sanitized filename

isJsonMime

public boolean isJsonMime(String mime)

Check if the given MIME is a JSON MIME. JSON MIME examples: APPLICATION/json APPLICATION/json; charset=UTF8 APPLICATION/JSON

Parameters:

mime - MIME (Multipurpose Internet Mail Extensions)

Returns:

True if the given MIME is JSON, false otherwise.

selectHeaderAccept

public String selectHeaderAccept(String[] accepts)

Select the Accept header's value from the given accepts array. if JSON exists in the given array, use it; otherwise use all of them (joining into a string)

Parameters:

accepts - The accepts array to select from

Returns:

The Accept header to use. If the given array is empty, null will be returned (not to set the Accept header explicitly).

selectHeaderContentType

public String selectHeaderContentType(String[] contentTypes)

Select the Content-Type header's value from the given array: if JSON exists in the given array, use it; otherwise use the first one of the array.

Parameters:

contentTypes - The Content-Type array to select from

Returns:

The Content-Type header to use. If the given array is empty, JSON will be used.

escapeString

public String escapeString(String str)

Escape the given string to be used as URL query value.

Parameters:

str - String to be escaped

Returns:

Escaped string

deserialize

public <T> Optional<T> deserialize(okhttp3.Response response,
                                   Class<T> returnType)
                            throws ApiException

Deserialize response body to Java object, according to the return type and the Content-Type response header.

Type Parameters:

T - Type

Parameters:

response - HTTP response

returnType - The type of the Java object

Returns:

The deserialized Java object

Throws:

ApiException - If fail to deserialize response body, i.e. cannot read response body or the Content-Type of the response is not supported.

serialize

public okhttp3.RequestBody serialize(Object obj,
                                     String contentType)
                              throws ApiException

Serialize the given Java object into request body according to the object's class and the request Content-Type.

Parameters:

obj - The Java object

contentType - The request Content-Type

Returns:

The serialized request body

Throws:

ApiException - If fail to serialize the given object

downloadFileFromResponse

public File downloadFileFromResponse(okhttp3.Response response)
                              throws ApiException

Download file from the given response.

Parameters:

response - An instance of the Response object

Returns:

Downloaded file

Throws:

ApiException - If fail to read file content from response and write to disk

prepareDownloadFile

public File prepareDownloadFile(okhttp3.Response response)
                         throws IOException

Prepare file for download.

Parameters:

response - An instance of the Response object

Returns:

Prepared file for the download

Throws:

IOException - If fail to prepare file for download

execute

public <T> ApiResponse<T> execute(okhttp3.Call call)
                           throws ApiException

execute(Call, Class).

Type Parameters:

T - Type

Parameters:

call - An instance of the Call object

Returns:

ApiResponse<T>

Throws:

ApiException - If fail to execute the call

execute

public <T> ApiResponse<T> execute(okhttp3.Call call,
                                  Class<T> returnType)
                           throws ApiException

Execute HTTP call and deserialize the HTTP response body into the given return type.

Type Parameters:

T - The return type corresponding to (same with) returnType

Parameters:

returnType - The return type used to deserialize HTTP response body

call - Call

Returns:

ApiResponse object containing response status, headers and data, which is a Java object deserialized from response body and would be null when returnType is null.

Throws:

ApiException - If fail to execute the call

executeWithResultSet

public <T extends QueryResultData<R>,R extends QueryResult> ApiResponse<T> executeWithResultSet(okhttp3.Call call,
                                                                                                Class<T> resultSetClass)
                                                                                         throws ApiException

Throws:

ApiException

executeAsync

public <T> void executeAsync(okhttp3.Call call,
                             ApiCallback<T> callback)

executeAsync(Call, Class, ApiCallback).

Type Parameters:

T - Type

Parameters:

call - An instance of the Call object

callback - ApiCallback<T>

executeAsync

public <T> void executeAsync(okhttp3.Call call,
                             Class<T> returnType,
                             ApiCallback<T> callback)

Execute HTTP call asynchronously.

Type Parameters:

T - Type

Parameters:

call - The callback to be executed when the API call finishes

returnType - Return type

callback - ApiCallback

See Also:

execute(Call, Class)

handleResponse

public <T> Optional<T> handleResponse(okhttp3.Response response,
                                      Class<T> returnType)
                               throws ApiException

Handle the given response, return the deserialized object when the response is successful.

Type Parameters:

T - Type

Parameters:

response - Response

returnType - Return type

Returns:

Type

Throws:

ApiException - If the response has a unsuccessful status code or fail to deserialize the response body

handleResponseWithResultSet

public <T extends QueryResultData<R>,R extends QueryResult> Optional<T> handleResponseWithResultSet(okhttp3.Response response,
                                                                                                    Class<T> resultSetClass)
                                                                                             throws ApiException

Handle the given response, return the deserialized object with the given result set classes when the response is successful.

Type Parameters:

T - Type extending QueryResultData.

R - Type extending QueryResult

Parameters:

response - Response

resultSetClass - Container result set class

Returns:

a QueryResultData

Throws:

ApiException - If the response has a unsuccessful status code or fail to deserialize the response body

buildCall

public okhttp3.Call buildCall(String path,
                              String method,
                              List<Pair> queryParams,
                              Object body,
                              Map<String,String> headerParams,
                              Map<String,Object> formParams,
                              String[] authNames,
                              ProgressRequestBody.ProgressRequestListener progressRequestListener)
                       throws ApiException

Build HTTP call with the given options.

Parameters:

path - The sub-path of the HTTP URL

method - The request method, one of "GET", "HEAD", "OPTIONS", "POST", "PUT", "PATCH" and "DELETE"

queryParams - The query parameters

body - The request body object

headerParams - The header parameters

formParams - The form parameters

authNames - The authentications to apply

progressRequestListener - Progress request listener

Returns:

The HTTP call

Throws:

ApiException - If fail to serialize the request body object

buildUrl

public String buildUrl(String path,
                       List<Pair> queryParams)

Build full URL by concatenating base path, the given sub path and query parameters.

Parameters:

path - The sub path

queryParams - The query parameters

Returns:

The full URL

processHeaderParams

public void processHeaderParams(Map<String,String> headerParams,
                                okhttp3.Request.Builder reqBuilder)

Set header parameters to the request builder, including default headers.

Parameters:

headerParams - Header parameters in the ofrm of Map

reqBuilder - Reqeust.Builder

updateParamsForAuth

public void updateParamsForAuth(String[] authNames,
                                List<Pair> queryParams,
                                Map<String,String> headerParams)
                         throws ApiException

Update query and header parameters based on authentication settings.

Parameters:

authNames - The authentications to apply

queryParams - List of query parameters

headerParams - Map of header parameters

Throws:

ApiException

buildRequestBodyFormEncoding

public okhttp3.RequestBody buildRequestBodyFormEncoding(Map<String,Object> formParams)

Build a form-encoding request body with the given form parameters.

Parameters:

formParams - Form parameters in the form of Map

Returns:

RequestBody

buildRequestBodyMultipart

public okhttp3.RequestBody buildRequestBodyMultipart(Map<String,Object> formParams)

Build a multipart (file uploading) request body with the given form parameters, which could contain text fields and file fields.

Parameters:

formParams - Form parameters in the form of Map

Returns:

RequestBody

guessContentTypeFromFile

public String guessContentTypeFromFile(File file)

Guess Content-Type header from the given file (defaults to "APPLICATION/octet-stream").

Parameters:

file - The given file

Returns:

The guessed Content-Type