Instantiate a client object (Java)

All Data API interactions through a client start with a DataAPIClient object. Once you have a DataAPIClient object, you can connect to a database and the perform CRUD operations on your data.

Creating a client object is an essential component of Data API client scripts. For more information, see Get started with the Data API (Java).

For more information about the Data API client hierarchy, see Python client internals, TypeScript client internals, Go client internals, Java client internals, and C# client internals.

Result

Returns a DataAPIClient object that you can use to interact with the Data API.

Parameters

Name Type Summary

token

String

Optional.

An application token, or an instance of TokenProvider. For more information about how to generate a token, see Get endpoint and token.

The username and password used to generate the token must be tied to a role that has sufficient permissions to perform the desired operations.

DataAPIClient objects aren’t specific to a database. Therefore, when you instantiate a client, you can omit this parameter and specify a token later with client.getDatabase() or client.getAdmin().

options

DataAPIClientOptions

A class wrapping the advanced configuration of the client, such as as HttpClient settings like timeouts.

Examples

The following examples demonstrate how to instantiate a client.

Instantiate a client

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIDestination;
import com.datastax.astra.client.core.auth.UsernamePasswordTokenProvider;
import com.datastax.astra.client.core.options.DataAPIClientOptions;

public class Example {

  public static void main(String[] args) {
    String token =
        new UsernamePasswordTokenProvider("USERNAME", "PASSWORD").getTokenAsString();
    DataAPIClientOptions clientOptions =
        new DataAPIClientOptions().destination(DataAPIDestination.HCD);
    DataAPIClient client = new DataAPIClient(token, clientOptions);
  }
}

Instantiate a client and pass a token

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIDestination;
import com.datastax.astra.client.core.auth.UsernamePasswordTokenProvider;
import com.datastax.astra.client.core.options.DataAPIClientOptions;

public class Example {
  public static void main(String[] args) {
    String token =
        new UsernamePasswordTokenProvider("USERNAME", "PASSWORD").getTokenAsString();
    DataAPIClientOptions clientOptions =
        new DataAPIClientOptions().destination(DataAPIDestination.HCD);
    DataAPIClient client = new DataAPIClient(token, clientOptions);
  }
}

Instantiate a client and specify options

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIDestination;
import com.datastax.astra.client.core.http.HttpClientOptions;
import com.datastax.astra.client.core.http.HttpProxy;
import com.datastax.astra.client.core.options.DataAPIClientOptions;
import com.datastax.astra.client.core.options.TimeoutOptions;
import com.datastax.astra.internal.command.CommandObserver;
import com.datastax.astra.internal.command.ExecutionInfos;
import java.net.http.HttpClient;
import java.time.Duration;

public class Example {
  public static void main(String[] args) {
    DataAPIClientOptions options = new DataAPIClientOptions();

    // Specify the environment
    options.destination(DataAPIDestination.HCD);

    // Specify the HTTP client
    HttpClientOptions httpClientOptions =
        new HttpClientOptions()
            .retryCount(3)
            .retryDelay(Duration.ofMillis(200))
            .httpRedirect(HttpClient.Redirect.NORMAL)
            .httpVersion(HttpClient.Version.HTTP_2)
            .httpProxy(new HttpProxy().hostname("localhost").port(8080));
    options.httpClientOptions(httpClientOptions);

    // Specify timeouts
    TimeoutOptions timeoutsOptions =
        new TimeoutOptions()
            .collectionAdminTimeoutMillis(5000)
            .collectionAdminTimeout(Duration.ofMillis(5000))
            .tableAdminTimeoutMillis(5000)
            .tableAdminTimeout(Duration.ofMillis(5000))
            .databaseAdminTimeoutMillis(15000)
            .databaseAdminTimeout(Duration.ofMillis(15000))
            .generalMethodTimeoutMillis(1000)
            .generalMethodTimeout(Duration.ofMillis(1000))
            .requestTimeoutMillis(200)
            .requestTimeout(Duration.ofMillis(200))
            .connectTimeoutMillis(100)
            .connectTimeout(Duration.ofMillis(100));
    options.timeoutOptions(timeoutsOptions);

    // Add your application in the chain of callers in the header
    options.addCaller("MySampleApplication", "1.0.0");

    // Add headers to calls for admin or database operations
    options.addAdminAdditionalHeader("X-My-Header", "MyValue");
    options.addDatabaseAdditionalHeader("X-My-Header", "MyValue");

    // Add loggers and observers
    options.addObserver(
        "my_dummy_logger",
        new CommandObserver() {
          @Override
          public void onCommand(ExecutionInfos executionInfo) {
            System.out.println("Command executed: " + executionInfo.getCommand().getName());
          }
        });
    // Get a sl4j logger at debug level
    options.logRequests();

    DataAPIClient client = new DataAPIClient(options);
  }
}

Client reference

For more information, see the client reference.

Was this helpful?