Native Driver Alternatives Using Stargate gRPC API in Java
Author: Tomasz Lelek
Stargate makes it even easier for developers to build applications on Apache Cassandra®. The new Stargate gRPC API lets you use Java to call any microservice in any cloud.
Developers should be able to build highly scalable apps even when they call multilingual and multi-cloud microservices. That’s why the Stargate team recently made a new API generally available to help developers build applications with their preferred language.
The new API is called gRPC Remote Procedure Call (gRPC), and we built it on the framework created by Google. In this post, we’ll show you how easy it is to start using this API from the Java ecosystem. We’ll also explain the basic methods exposed to the clients that allow us to interact with the gRPC API.
The setup is simple. The generated code based on protobuf files (“query.proto” and “stargate.proto”) is shipped with the grpc-proto dependency. In your client application, you only need to add two dependencies, the client and a functional channel service provider. In this example we picked netty:
If you don’t add the grpc-netty-shaded, you’ll get the following error:
Once we have all the needed dependencies we should be able to use the Stargate gRPC-stub API.
After this step, you should have StargateGrpc available on your classpath from the grpc-proto dependency. It contains the logic for interacting with Stargate gRPC API.
Putting the Stargate gRPC API to use
Once we have the generated code with the StargateGrpc class shipped within grpc-proto dependency, we’re ready to create the client.
Before delving into the code, we need to generate the auth token that will be used to perform authorization. Please visit the Stargate Authz documentation for a guide on this. Here’s some code that will work for our needs:
In this snippet, we’re assuming that Stargate is running on the localhost:8081. Once we have that, we can connect to the gRPC API. First, we need to generate the Channel that is used to perform the connection:
Please note that usePlaintext() should only be used for development and testing. When used in a production environment it should use a load balancer that terminates transport layer security (TLS). For local development of Stargate, it will be:
Next, we can generate the StargateGrpc stub. There are two ways of interacting with the gRPC API. The first one is synchronous (blocking):
The second way of interacting is asynchronous (non-blocking):
We will focus on the blocking approach in this example since it is simpler to illustrate. Please be aware that for your use case you might need to use the second approach.
We need to set up the CallCredentials, using the token-value generated in the previous step. We will assume that all queries are executed within the existing keyspace ksand table test. The table definition is as follows:
The Stargate gRPC API provides a way to execute two types of queries: Standard CQL queries and batch queries containing N CQL queries.
Build and execute a standard query with the gRPC API
When we want to run a standard query we can start by inserting a record using the gRPC stub:
This will build and execute a single query. Next, we can retrieve the inserted record(s):
If we print out the result set, it will have the following structure:
The value contains the binary data, that we can deserialize. First, we need to unwrap the result set:
We can get all rows with thegetRowsList() method and iterate over the result or get the specific row using its index and pass it to the getRows(int index) method. We picked the latter approach in the example above.
Our retrieval query (SELECT k, v FROM ks.test) stated explicitly which columns should be retrieved. Because of that, we can safely get the values using their positions via the getValues() method.
The getString() and getInt() perform deserialization of data. These methods were used because we knew the underlying type of the corresponding columns. The API provides utility methods for deserialization for more types as well. For the full list of available types, see value section in the query.proto file. If you want to iterate over all results, you can with this snippet:
This will allow you to operate on a single row. When you execute it, you’ll get the following:
Run Batch queries with Stargate gRPC API
In case we want to execute N queries, we can use the executeBatch method:
This takes the Batch as an argument. A Batch can contain N queries of type INSERT, UPDATE, or DELETE. We are adding two queries via the addQueries method. You can learn more about handling the Batch request in the Batch Documentation.
Now you know how to integrate the gRPC client via blockingStub. If you want to dive deeper into it take a look at the Java Client documentation on gRPC.
Follow the DataStax Tech Blog for more developer stories. Check out our YouTube channel for tutorials and here for DataStax Developers on Twitter for the latest news about our developer community.
