Prerequisites
- Get a bearer token
- Create a keyspace
- Create a table in your keyspace(optional): REST
Install software
You'll need to install the following software if it is not already installed:
Add dependencies
To begin, add the required dependency to your project pom.xml :
If you do not add it, you will observe the following error:
- 1
Authentication
This example assumes that you're running Stargate on Astra DB.For more information regarding authentication please see theManage application tokens section.
You'll need to download your bearer token from the Astra DB dashboard andadd the token to the connection portion of the script.
Creating a client
To connect to your Stargate instance, create the client.For a local Stargate instance, for instance, the following client code willfetch an auth token with a REST call:
A simple query can be performed by passing a CQL query to the client using the`ExecuteQuery()` function for standard query execution:
Data definition (DDL) queries are supported in the same manner:
In general, users will create a keyspace and table first.
If you would like to use abatch statement,the client also provides an `ExecuteBatch()` function to execute a batch query:
The ExecuteQuery function can be used to execute a single query.
This example inserts two values into the keyspace table test.users .Only INSERT , UPDATE , and DELETE operations can be used in a batch query.
After executing a query, a response returns rows that match the SELECT statement.If there are no rows, the returned payload is unset.The convenience function `getResultSet()` is provided to help transform thisresponse into a result set that's easier to work with.
Since the result type is known, the `getString` function transforms the value into a native string.Additional functions also exist for other types such as `int`, `map`, and `blob`.The full list can be found inValues.java.
To put all the pieces together, here is a sample script that combines all the piecesshown above:
Generating gRPC code stubs
To see a guide how the Java code is compiled from the proto files see thegRPC setup project dependencies.To update the protobuf files being used, add the new files to the top-level protodirectory and then run `make proto` from the root of the project.
More notes on the asynchronous use of the gRPC API
Up to this point, we were using the blocking version of the generated stub.We can also interact with the Stargate API using the async version of the stub.To do so, we need to pass theStreamObserverthat will be called asynchronously when the results are available.
Every StreamObserver needs to implement 3 methods: `onNext()`, `onError() and onComplete()`.For example:
Please note that this is a very simplified version only for demonstration purposes and should not be used on production.
Once we have the StreamObserver, we can pass it to the executeQuery method on the async stub:
This query will return immediately because it is non-blocking.If your program (or test) is progressing to the end, you may not be able to see the results.Your program may exit before the data arrives.After some time, when the data arrives, the streamObserver will be called.
The output of our program will look like this:
Please note, that at the end we have a completed emitted.This is called by the onCompleted method.
The Stargate gRPC Java Client repository is located athttps://github.com/stargate/stargate-grpc-java-client.