ClientBuilder (cloudant-client 2.16.0 API)

java.lang.Object
- com.cloudant.client.api.ClientBuilder

public class ClientBuilder
extends java.lang.Object

This class builds new CloudantClient instances.

Create a new CloudantClient instance for a Cloudant account

 
 CloudantClient client = ClientBuilder.account("yourCloudantAccount")
                          .username("yourUsername")
                          .password("yourPassword")
                          .build();

Create a new CloudantClient instance for a Cloudant Bluemix instance

 
 CloudantClient client = ClientBuilder.bluemix(System.getenv("VCAP_SERVICES")).build();

Create a new CloudantClient instance for a Cloudant Local

 
 CloudantClient client = ClientBuilder.url(new URL("https://yourCloudantLocalAddress.example"))
                          .username("yourUsername")
                          .password("yourPassword")
                          .build();

Examples creating instances with additional options

Configure a proxy server

 
 CloudantClient client = ClientBuilder.account("yourCloudantAccount")
                          .username("yourUsername")
                          .password("yourPassword")
                          .proxyURL(new URL("https://yourProxyServerAddress.example"))
                          .proxyUser(yourProxyUser)
                          .proxyPassword(yourProxyPass)
                          .build();

Client with a custom SSL socket factory

 
 CloudantClient client = ClientBuilder.account("yourCloudantAccount")
                          .username("yourUsername")
                          .password("yourPassword")
                          .customSSLSocketFactory(...)
                          .build();

Client with custom connection and read timeouts

 
 CloudantClient client = ClientBuilder.account("yourCloudantAccount")
                          .username("yourUsername")
                          .password("yourPassword")
                          .connectTimeout(1, TimeUnit.MINUTES)
                          .readTimeout(1, TimeUnit.MINUTES)
                          .build();

Since:: 2.0.0

Field Summary

Fields
Modifier and Type	Field and Description
`static long`	`DEFAULT_CONNECTION_TIMEOUT` Connection timeout defaults to 5 minutes
`static int`	`DEFAULT_MAX_CONNECTIONS` Default max of 6 connections
`static long`	`DEFAULT_READ_TIMEOUT` Read timeout defaults to 5 minutes

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static ClientBuilder`	`account(java.lang.String account)` Constructs a new ClientBuilder for building a CloudantClient instance to connect to the Cloudant server with the specified account.
`static ClientBuilder`	`bluemix(java.lang.String vcapServices)` This is the same as calling `bluemix(String, String)` with `instanceName` set to `null`.
`static ClientBuilder`	`bluemix(java.lang.String vcapServices, java.lang.String instanceName)` Sets Cloudant client credentials by inspecting a service information JSON string.
`static ClientBuilder`	`bluemix(java.lang.String vcapServices, java.lang.String serviceName, java.lang.String instanceName)` Sets Cloudant client credentials by inspecting a service information JSON string.
`CloudantClient`	`build()` Build the `CloudantClient` instance based on the endpoint used to construct this client builder and the options that have been set on it before calling this method.
`ClientBuilder`	`connectTimeout(long connectTimeout, java.util.concurrent.TimeUnit connectTimeoutUnit)` Sets the specified timeout value when opening the client connection.
`ClientBuilder`	`customSSLSocketFactory(javax.net.ssl.SSLSocketFactory factory)` Specifies the custom SSLSocketFactory to use when connecting to Cloudant over a `https` URL, when SSL authentication is enabled.
`ClientBuilder`	`disableSSLAuthentication()` Flag to disable hostname verification and certificate chain validation.
`ClientBuilder`	`gsonBuilder(com.google.gson.GsonBuilder gsonBuilder)` Set a custom GsonBuilder to use when serializing and de-serializing JSON in requests and responses between the CloudantClient and the server.
`ClientBuilder`	`iamApiKey(java.lang.String iamApiKey)` Sets the IAM API key for the client connection.
`ClientBuilder`	`iamApiKey(java.lang.String iamApiKey, java.lang.String iamServerClientId, java.lang.String iamServerClientSecret)` Sets the IAM API key for the client connection.
`ClientBuilder`	`interceptors(HttpConnectionInterceptor... interceptors)` This method adds `HttpConnectionInterceptor`s to be used on the CloudantClient connection.
`ClientBuilder`	`maxConnections(int maxConnections)` Set the maximum number of connections to maintain in the connection pool.
`ClientBuilder`	`password(java.lang.String password)` Sets the password for the client connection.
`ClientBuilder`	`proxyPassword(java.lang.String proxyPassword)` Sets an optional proxy password for the proxy user specified by `proxyUser(String)`.
`ClientBuilder`	`proxyURL(java.net.URL proxyURL)` Sets a proxy url for the client connection.
`ClientBuilder`	`proxyUser(java.lang.String proxyUser)` Sets an optional proxy username for the client connection.
`ClientBuilder`	`readTimeout(long readTimeout, java.util.concurrent.TimeUnit readTimeoutUnit)` Sets the specified timeout value when reading from a `InputStream` with an established client connection.
`static ClientBuilder`	`url(java.net.URL url)` Constructs a new ClientBuilder for building a CloudantClient instance to connect to the Cloudant server with the specified URL.
`ClientBuilder`	`username(java.lang.String username)` Sets a username or API key for the client connection.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_MAX_CONNECTIONS
```
public static final int DEFAULT_MAX_CONNECTIONS
```
    Default max of 6 connections
    
    See Also:
    
    Constant Field Values
  - DEFAULT_CONNECTION_TIMEOUT
```
public static final long DEFAULT_CONNECTION_TIMEOUT
```
    Connection timeout defaults to 5 minutes
    
    See Also:
    
    Constant Field Values
  - DEFAULT_READ_TIMEOUT
```
public static final long DEFAULT_READ_TIMEOUT
```
    Read timeout defaults to 5 minutes
    
    See Also:
    
    Constant Field Values
- Method Detail
  - account
```
public static ClientBuilder account(java.lang.String account)
```
    Constructs a new ClientBuilder for building a CloudantClient instance to connect to the Cloudant server with the specified account.
    
    Parameters:
    
    account - the Cloudant account name to connect to e.g. "example" is the account name for the "example.cloudant.com" endpoint
    
    Returns:
    
    a new ClientBuilder for the account
    
    Throws:
    
    java.lang.IllegalArgumentException - if the specified account name forms an invalid endpoint URL
  - url
```
public static ClientBuilder url(java.net.URL url)
```
    Constructs a new ClientBuilder for building a CloudantClient instance to connect to the Cloudant server with the specified URL.
    
    Parameters:
    
    url - server URL e.g. "https://yourCloudantLocalAddress.example"
    
    Returns:
    
    a new ClientBuilder for the account
  - build
```
public CloudantClient build()
```
    Build the CloudantClient instance based on the endpoint used to construct this client builder and the options that have been set on it before calling this method.
    
    Returns:
    
    the CloudantClient instance for the specified end point and options
  - username
```
public ClientBuilder username(java.lang.String username)
```
    Sets a username or API key for the client connection.
    
    Parameters:
    
    username - the user or API key for the session
    
    Returns:
    
    this ClientBuilder object for setting additional options
  - password
```
public ClientBuilder password(java.lang.String password)
```
    Sets the password for the client connection. The password is the one for the username or API key set by the username(String) method.
    
    Parameters:
    
    password - user password or API key passphrase
    
    Returns:
    
    this ClientBuilder object for setting additional options
  - gsonBuilder
```
public ClientBuilder gsonBuilder(com.google.gson.GsonBuilder gsonBuilder)
```
    Set a custom GsonBuilder to use when serializing and de-serializing JSON in requests and responses between the CloudantClient and the server.
    Note: the supplied GsonBuilder will be augmented with some internal TypeAdapters.
    
    Parameters:
    
    gsonBuilder - the custom GsonBuilder to use
    
    Returns:
    
    this ClientBuilder object for setting additional options
  - maxConnections
```
public ClientBuilder maxConnections(int maxConnections)
```
    Set the maximum number of connections to maintain in the connection pool.
    Note: this setting only applies if using the optional OkHttp dependency. If OkHttp is not present then the JVM configuration is used for pooling. Consult the JVM documentation for the http.maxConnections property for further details.
    Defaults to DEFAULT_MAX_CONNECTIONS
    
    Parameters:
    
    maxConnections - the maximum number of simultaneous connections to open to the server
    
    Returns:
    
    this ClientBuilder object for setting additional options
  - proxyURL
```
public ClientBuilder proxyURL(java.net.URL proxyURL)
```
    Sets a proxy url for the client connection.
    
    Note that this method can only set the configuration for an unencrypted HTTP proxy. Even when using this type of proxy communication from the client to a https database server is encrypted via a SSL tunnel.
    
    Parameters:
    
    proxyURL - the URL of the proxy server
    
    Returns:
    
    this ClientBuilder object for setting additional options
    
    See Also:
    
    Advanced configuration: Proxies
  - proxyUser
```
public ClientBuilder proxyUser(java.lang.String proxyUser)
```
    Sets an optional proxy username for the client connection.
    
    Note: Use Authenticator.setDefault(Authenticator) to configure proxy authentication when using the JVM default HttpURLConnection (i.e. not using the optional okhttp dependency) in combination with a HTTPS database server.
    
    Parameters:
    
    proxyUser - username for the proxy server
    
    Returns:
    
    this ClientBuilder object for setting additional options
    
    See Also:
    
    Advanced configuration: Proxies
  - proxyPassword
```
public ClientBuilder proxyPassword(java.lang.String proxyPassword)
```
    Sets an optional proxy password for the proxy user specified by proxyUser(String).
    
    Note: Use Authenticator.setDefault(Authenticator) to configure proxy authentication when using the JVM default HttpURLConnection (i.e. not using the optional okhttp dependency) in combination with a HTTPS database server.
    
    Parameters:
    
    proxyPassword - password for the proxy server user
    
    Returns:
    
    this ClientBuilder object for setting additional options
    
    See Also:
    
    Advanced configuration: Proxies
  - disableSSLAuthentication
```
public ClientBuilder disableSSLAuthentication()
```
    Flag to disable hostname verification and certificate chain validation. This is not recommended, but for example could be useful for testing with a self-signed certificate.
    The SSL authentication is enabled by default meaning that hostname verification and certificate chain validation is done using the JVM default settings.
    
    Returns:
    
    this ClientBuilder object for setting additional options
    
    Throws:
    
    java.lang.IllegalStateException - if customSSLSocketFactory(SSLSocketFactory) has been called on this ClientBuilder
    
    See Also:
    
    customSSLSocketFactory(SSLSocketFactory)
  - customSSLSocketFactory
```
public ClientBuilder customSSLSocketFactory(javax.net.ssl.SSLSocketFactory factory)
```
    Specifies the custom SSLSocketFactory to use when connecting to Cloudant over a https URL, when SSL authentication is enabled.
    
    Parameters:
    
    factory - An SSLSocketFactory, or null for the default SSLSocketFactory of the JRE.
    
    Returns:
    
    this ClientBuilder object for setting additional options
    
    Throws:
    
    java.lang.IllegalStateException - if disableSSLAuthentication() has been called on this ClientBuilder
    
    See Also:
    
    disableSSLAuthentication()
  - interceptors
```
public ClientBuilder interceptors(HttpConnectionInterceptor... interceptors)
```
    This method adds HttpConnectionInterceptors to be used on the CloudantClient connection. Interceptors can be used to modify the HTTP requests and responses between the CloudantClient and the server.
    An example interceptor use might be to apply a custom authorization mechanism. For instance to use BasicAuth instead of CookieAuth it is possible to use a BasicAuthInterceptor that adds the BasicAuth Authorization header to the request:
```
 
 CloudantClient client = ClientBuilder.account("yourCloudantAccount")
      .interceptors(new BasicAuthInterceptor("yourUsername:yourPassword"))
      .build()
 
 
```
    Parameters:
    
    interceptors - one or more HttpConnectionInterceptor objects
    
    Returns:
    
    this ClientBuilder object for setting additional options
    
    See Also:
    
    HttpConnectionInterceptor
  - connectTimeout
```
public ClientBuilder connectTimeout(long connectTimeout,
                                    java.util.concurrent.TimeUnit connectTimeoutUnit)
```
    Sets the specified timeout value when opening the client connection. If the timeout expires before the connection can be established, a SocketTimeoutException is raised.
    Example creating a CloudantClient with a connection timeout of 2 seconds:
```
 
 CloudantClient client = ClientBuilder.account("yourCloudantAccount")
      .username("yourUsername")
      .password("yourPassword")
      .connectTimeout(2, TimeUnit.SECONDS)
      .build();
 
 
```
    Defaults to DEFAULT_CONNECTION_TIMEOUT with TimeUnit.MINUTES.
    Parameters:
    
    connectTimeout - duration of the read timeout
    
    connectTimeoutUnit - unit of measurement of the read timeout parameter
    
    Returns:
    
    this ClientBuilder object for setting additional options
    
    See Also:
    
    URLConnection.setConnectTimeout(int)
  - readTimeout
```
public ClientBuilder readTimeout(long readTimeout,
                                 java.util.concurrent.TimeUnit readTimeoutUnit)
```
    Sets the specified timeout value when reading from a InputStream with an established client connection. If the timeout expires before there is data available for read, a SocketTimeoutException is raised.
    Example creating a CloudantClient with a read timeout of 2 seconds:
```
 
 CloudantClient client = ClientBuilder.account("yourCloudantAccount")
      .username("yourUsername")
      .password("yourPassword")
      .readTimeout(2, TimeUnit.SECONDS)
      .build();
 
 
```
    Defaults to DEFAULT_READ_TIMEOUT with TimeUnit.MINUTES.
    Parameters:
    
    readTimeout - duration of the read timeout
    
    readTimeoutUnit - unit of measurement of the read timeout parameter
    
    Returns:
    
    this ClientBuilder object for setting additional options
    
    See Also:
    
    URLConnection.setReadTimeout(int)
  - bluemix
```
public static ClientBuilder bluemix(java.lang.String vcapServices)
```
    This is the same as calling bluemix(String, String) with instanceName set to null.
    
    Parameters:
    
    vcapServices - service information JSON string, for example the contents of VCAP_SERVICES environment variable
    
    Returns:
    
    a new ClientBuilder for the account
    
    Throws:
    
    java.lang.IllegalArgumentException - see bluemix(String, String) for conditions that cause IllegalArgumentException to be thrown.
  - bluemix
```
public static ClientBuilder bluemix(java.lang.String vcapServices,
                                    java.lang.String instanceName)
```
    Sets Cloudant client credentials by inspecting a service information JSON string. This object takes the form of a VCAP_SERVICES environment variable which is a JSON object that contains information that you can use to interact with a service instance in Bluemix.
    Note: Specifying an instance name is only required when multiple Cloudant service instances are present. If there is only a single Cloudant service instance then bluemix(String) can also be used.
    Parameters:
    
    vcapServices - service information JSON string, for example the contents of VCAP_SERVICES environment variable
    
    instanceName - name of Bluemix service instance or null to try to use the only available Cloudant service
    
    Returns:
    
    a new ClientBuilder for the account
    
    Throws:
    java.lang.IllegalArgumentException - if any of the following conditions are true:
    
    The vcapServices is null.
    
    The vcapServices is not valid.
    
    A service with the name matching "cloudantNoSQLDB" could not be found in vcapServices.
    
    An instance with a name matching instanceName could not be found in vcapServices.
    
    The instanceName is null and multiple Cloudant service instances exist in vcapServices.
  - bluemix
```
public static ClientBuilder bluemix(java.lang.String vcapServices,
                                    java.lang.String serviceName,
                                    java.lang.String instanceName)
```
    Sets Cloudant client credentials by inspecting a service information JSON string. This object takes the form of a VCAP_SERVICES environment variable which is a JSON object that contains information that you can use to interact with a service instance in Bluemix.
    Parameters:
    
    vcapServices - service information JSON string, for example the contents of VCAP_SERVICES environment variable
    
    serviceName - name of Bluemix service to use
    
    instanceName - name of Bluemix service instance or null to try to use the only available Cloudant service
    
    Returns:
    
    a new ClientBuilder for the account
    
    Throws:
    java.lang.IllegalArgumentException - if any of the following conditions are true:
    
    The vcapServices is null.
    
    The serviceName is null.
    
    The vcapServices is not valid.
    
    A service with the name matching serviceName could not be found in vcapServices.
    
    An instance with a name matching instanceName could not be found in vcapServices.
    
    The instanceName is null and multiple Cloudant service instances exist in vcapServices.
  - iamApiKey
```
public ClientBuilder iamApiKey(java.lang.String iamApiKey)
```
    Sets the IAM API key for the client connection.
    Example creating a CloudantClient using IAM authentication:
```
 
 CloudantClient client = ClientBuilder.account("yourCloudantAccount")
      .iamApiKey("yourIamApiKey")
      .build();
 
 
```
    Parameters:
    
    iamApiKey - the IAM API key for the session
    
    Returns:
    
    this ClientBuilder object for setting additional options
  - iamApiKey
```
public ClientBuilder iamApiKey(java.lang.String iamApiKey,
                               java.lang.String iamServerClientId,
                               java.lang.String iamServerClientSecret)
```
    Sets the IAM API key for the client connection. Also allows a client ID and secret to be specified for use when authenticating with the IAM token server.
    Example creating a CloudantClient using IAM authentication:
```
 
 CloudantClient client = ClientBuilder.account("yourCloudantAccount")
      .iamApiKey("yourIamApiKey", "yourClientId", "yourClientSecret")
      .build();
 
 
```
    Parameters:
    
    iamApiKey - the IAM API key for the session
    
    iamServerClientId - Client ID used to authenticate with IAM token server
    
    iamServerClientSecret - Client secret used to authenticate with IAM token server
    
    Returns:
    
    this ClientBuilder object for setting additional options

Class ClientBuilder

Create a new CloudantClient instance for a Cloudant account

Create a new CloudantClient instance for a Cloudant Bluemix instance

Create a new CloudantClient instance for a Cloudant Local

Examples creating instances with additional options

Configure a proxy server

Client with a custom SSL socket factory

Client with custom connection and read timeouts

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_MAX_CONNECTIONS

DEFAULT_CONNECTION_TIMEOUT

DEFAULT_READ_TIMEOUT

Method Detail

account

url

build

username

password

gsonBuilder

maxConnections

proxyURL

proxyUser

proxyPassword

disableSSLAuthentication

customSSLSocketFactory

interceptors

connectTimeout

readTimeout

bluemix

bluemix

bluemix

iamApiKey

iamApiKey