Skip to content

Stargate SDK Quickstart

Jump to bottom
Cedrick Lunven edited this page Jan 12, 2022 · 8 revisions

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

docker -v
docker run hello-world

📦 Java Development Kit (JDK) 8+

java --version

📦 Apache Maven

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 Image Version (tag latest semver)

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 Maven Central 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

🏠 Home | Document | Rest | Native Drivers | GraphQL | gRPC | Astra Devops |

I - Getting Started

Home
  1. Overview
  2. What's next
QuickStarts
  1. QuickStart Stargate
  2. QuickStart Astra
Reference Configurations
  1. Stargate SDK
  2. Astra SDK
Reference JavaDoc
  1. latest
  2. 0.3.4
  3. 0.2.6

II - Stargate Apis

Api Rest
  1. Overview
  2. Keyspaces
  3. Tables
  4. Columns
  5. Indexes
  6. User Defined Type
  7. Data
Api Document
  1. Overview
  2. Namespaces
  3. Collections
  4. Documents
  5. DocumentRepository
Api GraphQL
  1. Overview
  2. Cql First
  3. Schema First
  4. Federation
Api Grpc
  1. Overview
  2. BlockingStub
  3. FutureStub
  4. ReactiveStub
Native Drivers
  1. Overview
  2. Cql Session
  3. Object Mapper

III - Astra Apis

Api Devops Databases
  1. Overview
  2. Databases
  3. Regions
  4. AccessList
  5. Private Link
Api Devops Organizations
  1. Overview
  2. Roles
  3. Users
  4. Tokens
Api Devops Streaming
  1. Overview
  2. Tenants
  3. Clusters
  4. Pulsar client
  5. Pulsar admin
  6. Producers
  7. Consumers
  8. Subscriptions

IV - Integrations

Spring Framework
  1. Spring Boot Starter
  2. Spring Data Cassandra
  3. Spring Boot Actuator
  4. Spring Security
Clone this wiki locally