Stargate SDK Quickstart

This tutorial will guide through the steps to start coding with the java Stargate SDK. Stargate 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

2. Start Stargate

The element below have been extracted from Stargate documentation

✅ Step 2a: Pull the docker image

Download Stargate docker image :

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

✅ Step 2b: Start stargate container in development mode.

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.41

With Development mode Stargate also the role of a data node, you do not need an extra Cassandra container.

All apis are enabled, here is the port list:

• 8080 is the graphql port
• 8081 is the authentication port
• 8082 is the rest port
• 8090 is the grpc port

After 30 seconds you should be able to following URLs:

• URL for health: http://localhost:8082/health
• URL for Open Api specification: http://localhost:8082/swagger-ui/#/
• URL for graphql Playground: http://localhost:8080/playground

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.1</version>
    </dependency>
  </dependencies>
</project>

ℹ️Informations:

• We removed the Junit as we will work a main class.
• We added the latest version of dependency to the stargate-sdk.

<dependency>
  <groupId>com.datastax.stargate</groupId>
  <artifactId>stargate-sdk</artifactId>
  <version>${latest-version}</version>
</dependency>

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

4. Configuration

✅ Step 4a: Initialize Stargate client

StargateClient is the only class you will have to work with, you should then leverage on the 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

👁️ 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.

• API Cql
• API Rest
• API Document
• API GraphQL
• API Grpc API