ClientBuilder (cloudant-client 2.0.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 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.
`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`	`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
equals, 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.
    
    Parameters:
    
    proxyURL - the URL of the proxy server
    
    Returns:
    
    this ClientBuilder object for setting additional options
  - proxyUser
```
public ClientBuilder proxyUser(java.lang.String proxyUser)
```
    Sets an optional proxy username for the client connection.
    
    Parameters:
    
    proxyUser - username for the proxy server
    
    Returns:
    
    this ClientBuilder object for setting additional options
  - proxyPassword
```
public ClientBuilder proxyPassword(java.lang.String proxyPassword)
```
    Sets an optional proxy password for the proxy user specified by proxyUser(String).
    
    Parameters:
    
    proxyPassword - password for the proxy server user
    
    Returns:
    
    this ClientBuilder object for setting additional options
  - 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)

Class ClientBuilder

Create a new CloudantClient instance for a Cloudant account

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