Stargate SDK Quickstart

This tutorial will guide through the steps to start coding with the Stargate SDK. Stargate nodes will be started in Docker.

ℹ️ You can download the code here 📥 Download

📋 Table of content

1. Prerequisites
2. Start Stargate
3. Setup your project
4. Configuration

1. Prerequisites

📦 Docker

• Use the reference documentation to install Docker Desktop
• Validate your installation with

docker -v
docker run hello-world

📦 Java Development Kit (JDK) 8+

• Use the reference documentation to install a Java Development Kit
• Validate your installation with

java --version

📦 Apache Maven

• Use the reference documentation to install Apache Maven
• Validate your installation with

mvn -version

🏠 Back to Table of Contents

2. Start Stargate

Elements below have been extracted from Stargate documentation

✅ Step 2a: Pull Stargate docker image stargateio

Download Stargate docker image :

docker pull stargateio/stargate-3_11:v1.0.45

✅ Step 2b: Start Stargate container in development mode. (notice the environment variable DEVELOPER_MODE=true)

docker run --name stargate \
  -p 8080:8080 \
  -p 8081:8081 \
  -p 8082:8082 \
  -p 8090:8090 \
  -p 127.0.0.1:9042:9042 \
  -d \
  -e CLUSTER_NAME=stargate \
  -e CLUSTER_VERSION=3.11 \
  -e DEVELOPER_MODE=true \
  stargateio/stargate-3_11:v1.0.45

With development mode enabled, Stargate also plays the role of a data node, as such you do not need any extra Cassandra container.

Multiple ports have been declared are here what they are used for. The tools listed here (playground, swagger-ui( will be available about 40s after the docker run commmand.

• 8080 is the Graphql port you can access the playground on http://localhost:8080/playground
• 8081 is the Authentication port to retrieve a your token based on user/password
• 8082 is the Rest API port. You can access Swagger documentation on http://localhost:8082/swagger-ui/#/ also the health check is done through http://localhost:8082/health
• 8090 is the Grpc port. A socket is open listening from Grpc calls.
• 9042 is the default CQL port. A socker is open listening CQL calls coming from the native drivers.

🏠 Back to Table of Contents

3. Setup your project

✅ Step 3a: Create the project sdk-quickstart-stargate with a maven archetype:

mvn archetype:generate \
  -DarchetypeGroupId=org.apache.maven.archetypes \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.4 \
  -DgroupId=com.datastax.tutorial \
  -DartifactId=sdk-quickstart-stargate \
  -Dversion=1.0.0-SNAPSHOT \
  -DinteractiveMode=false

✅ Step 3b: Import the project favorite IDE, and replace the pom.xml with the following XML.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.datastax.tutorial</groupId>
  <artifactId>sdk-quickstart-stargate</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <name>sdk-quickstart-stargate</name>
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>
  <dependencies>
    <dependency>
	  <groupId>com.datastax.stargate</groupId>
	  <artifactId>stargate-sdk</artifactId>
	  <version>0.2.5</version>
    </dependency>
  </dependencies>
</project>

✅ Step 3c: Delete folder src/test/java, we will experiment with a main class.

ℹ️ Informations:

• We removed the Junit classes generated as we will work a main class.
• We added the latest version of stargate-sdk dependency. The xml below may no be up-to-date.

🏠 Back to Table of Contents

4. Configuration

✅ Step 4a: Initialize Stargate client

StargateClient is the class you will have to work with, from there you leverage on a fluent api.

Rename App.java to QuickstartStargate.java and update the class accordingly.

public static void main(String[] args) {
  try (StargateClient stargateClient = configureStargateClient()) {
    // work with Stargate
  }
}
public static StargateClient configureStargateClient() {
  return StargateClient.builder()
    .withCqlContactPoints("localhost:9042")
    .withLocalDatacenter("datacenter1")
    .withAuthCredentials("cassandra", "cassandra")
    .withApiNode(new StargateNodeConfig("127.0.0.1"))
    .build();
}

ℹ️ Informations

• Based on parameters provided in the builder, the 5 apis (cql,rest,doc,graphQL,grpc) will be enabled of not.

• As CqlSession is stateful you need to close it at the application shutdown. StargateClient is no different, if you enable Cql api, you need to close it at the application shutdown. To cope with this constraint the class is Autocloseable.

• Cql: needs contact-points, localdatacenter and credentials. If not provided the default values for contact points is localhost:9042

• Https Api need the hostname, port numbers and credentials. But if you are using the default ports no need to specified them.

✅ Step 4b: Execute the main class QuickstartStargate.java

To run the application you can either use your IDE or maven

mvn exec:java -Dexec.main=com.datastax.tutorial.QuickstartStargate

👁️ Expected output

INFO com.datastax.stargate.sdk.StargateClient       : Initializing [StargateClient]
INFO com.datastax.stargate.sdk.StargateClient       : + Stargate nodes #[1] in [datacenter1]
INFO com.datastax.stargate.sdk.StargateClient       : + CqlSession   :[ENABLED]
INFO com.datastax.stargate.sdk.rest.ApiDataClient   : + API Data     :[ENABLED]
INFO com.datastax.stargate.sdk.doc.ApiDocumentClient: + API Document :[ENABLED]
INFO com.datastax.stargate.sdk.gql.ApiGraphQLClient : + API GraphQL  :[ENABLED]
INFO com.datastax.stargate.sdk.grpc.ApiGrpcClient . : + API Grpc     :[ENABLED]
INFO com.datastax.stargate.sdk.StargateClient       : Closing CqlSession.

✅ Step 4c: Check you can invoke each Api. Add the following utilities methods in QuickstartStargate.java

public static void testCqlApi(StargateClient stargateClient) {
  CqlSession cqlSession = stargateClient.cqlSession().get();
  System.out.println("Cql Version (cql)   : " + cqlSession
    .execute("SELECT cql_version from system.local")
    .one().getString("cql_version"));
}
    
public static void testRestApi(StargateClient stargateClient) {
  System.out.println("Keyspaces (rest)    : " + 
    stargateClient.apiRest()
                  .keyspaceNames()
                  .collect(Collectors.toList()));
}
    
public static void testDocumentaApi(StargateClient stargateClient) {
  System.out.println("Namespaces (doc)    : " + 
    stargateClient.apiDocument()
                  .namespaceNames()
                  .collect(Collectors.toList()));
}
    
public static void testGraphQLApi(StargateClient stargateClient) {
  System.out.println("Keyspaces (graphQL) : " + 
    stargateClient.apiGraphQL().cqlSchema().keyspaces());
}
    
public static void testGrpcApi(StargateClient stargateClient) {
  System.out.println("Cql Version (grpc)  : " + 
    stargateClient.apiGrpc()
                  .execute("SELECT cql_version from system.local")
                  .one().getString("cql_version"));
}

✅ Step 4d: Update the main method accordingly:

public static void main(String[] args) {
   try (StargateClient stargateClient = configureStargateClientDefault()) {
      testCqlApi(stargateClient);
      testRestApi(stargateClient);
      testDocumentaApi(stargateClient);
      testGraphQLApi(stargateClient);
      testGrpcApi(stargateClient);
   }
}

✅ Step 4e: Execute the main class QuickstartStargate.java again

👁️ Expected output

INFO com.datastax.stargate.sdk.StargateClient       : Initializing [StargateClient]
INFO com.datastax.stargate.sdk.StargateClient       : + Stargate nodes #[1] in [datacenter1]
INFO com.datastax.stargate.sdk.StargateClient       : + CqlSession   :[ENABLED]
INFO com.datastax.stargate.sdk.rest.ApiDataClient   : + API Data     :[ENABLED]
INFO com.datastax.stargate.sdk.doc.ApiDocumentClient: + API Document :[ENABLED]
INFO com.datastax.stargate.sdk.gql.ApiGraphQLClient : + API GraphQL  :[ENABLED]
INFO com.datastax.stargate.sdk.grpc.ApiGrpcClient . : + API Grpc     :[ENABLED]
Cql Version (cql)   : 3.4.4
Keyspaces (rest)    : [system_distributed, system, data_endpoint_auth, system_schema, java, stargate_system, system_auth, system_traces]
Namespaces (doc)    : [system_distributed, system, data_endpoint_auth, system_schema, java, stargate_system, system_auth, system_traces]
Keyspaces (graphQL) : {"data":{"keyspaces":[{"name":"system_distributed"},{"name":"system"},{"name":"data_endpoint_auth"},{"name":"system_schema"},{"name":"java"},{"name":"stargate_system"},{"name":"system_auth"},{"name":"system_traces"}]}}
Cql Version (grpc)  : 3.4.4
INFO com.datastax.stargate.sdk.StargateClient       : Closing CqlSession.

ℹ️ Reminder: You can download the code here 📥 Download

Congratulations: you are ready to explore each Api leveraging the fluent api.

🏠 Back to Table of Contents