Development Environment Configuration

First, you’ll need to access the driver in your development environment. You could download the driver directly from the URL listed before and manage the dependencies manually, but it is more typical in modern Java development to use a tool like Maven or Gradle to manage dependencies. If you’re using Maven, you’ll need to add something like the following to your project pom.xml file, while specifying a value for the driver version:

<dependency>
  <groupId>com.datastax.oss</groupId>
  <artifactId>java-driver-core</artifactId>
  <version>${driver.version}</version>
</dependency>

You can find the documentation manual for the Java drivers at https://docs.datastax.com/en/developer/java-driver/latest, and Javadoc for the Java driver at https://docs.datastax.com/en/drivers/java/latest/. Alternatively, the Javadocs are also part of the source distribution.

All of the DataStax drivers are managed as open source projects on GitHub. If you’re interested in seeing the Java driver source, you can get a read-only trunk version using this command:

$ git clone https://github.com/datastax/java-driver.git

If you’re interested in learning more about the internals of the driver or even potentially contributing to the project, there’s also a Developer Guide on the DataStax documentation site.

Connecting to a Cluster

Once you’ve configured your environment, it’s time to start coding. We’ll base the code samples for this chapter around the Reservation Service, a microservice implementation based on the hotel data model introduced in Chapter 5 and the corresponding application design discussed in Chapter 7. The source code for the Reservation Service is available at https://github.com/jeffreyscarpenter/reservation-service.

To start building your application, you’ll use the driver’s API to connect to a cluster. In the Java driver, connectivity to a cluster is represented by the com.datastax.oss.driver.api.core.CqlSession class.

The CqlSession class is the main entry point of the driver. It supports a fluent-style API using the builder pattern. For example, the following line creates a CqlSession that will attempt to connect to a Cassandra node on the local host at the default Cassandra native protocol port number:

CqlSession cqlSession = CqlSession.builder()
    .addContactPoint(new InetSocketAddress("127.0.0.1", 9042))
    .build()

In the terminology of the driver, the nodes you explicitly identify when creating a CqlSession are known as contact points. Contact points are similar to the concept of seed nodes that a Cassandra node uses to connect to other nodes in the same cluster.

The minimum required information to create a CqlSession is a single contact point. The driver defaults to a single contact point consisting of the local host and default port, so this statement is equivalent to the previous one:

CqlSession cqlSession = CqlSession.builder().build()

While this configuration is useful for development, when you might be running a Cassandra node on your local machine, for production environments you’ll want to specify multiple contact points. This is a good practice in case one of the nodes you pick happens to be down when the client application is attempting to create a CqlSession. You’ll also want to specify the name of the local data center. We’ll discuss naming of data centers in Chapter 10.

CqlSession cqlSession = CqlSession.builder()
    .addContactPoint(new InetSocketAddress("<some IP address>", 9042))
    .addContactPoint(new InetSocketAddress("<another IP address>", 9042))
    .withLocalDatacenter("<data center name>")
    .build()

When we create a CqlSession, the driver connects to one of the configured contact points to obtain metadata about the cluster. This action will throw a NoHostAvailableException if none of the contact points is available, or an AuthenticationException if authentication fails. We’ll discuss authentication in more detail in Chapter 14.

You can optionally provide the name of a keyspace to connect to, as in this example that connects to the reservation keyspace:

CqlSession cqlSession = CqlSession.builder()
    .addContactPoint(new InetSocketAddress("<some IP address>", 9042))
    .addContactPoint(new InetSocketAddress("<another IP address>", 9042))
    .withKeyspace("reservation")
    .build()

If you do not specify a keyspace name when creating the CqlSession, you’ll have to qualify every table reference in your queries with the appropriate keyspace name.

Each CqlSession manages connections to a Cassandra cluster, which are used to execute queries and control operations using the Cassandra native protocol. The CqlSession contains a pool of TCP connections for each host.

Statements

Once you have created a CqlSession to connect to a cluster, you’re ready to perform reads or writes. To begin doing some real application work, you’ll create and execute CQL statements using implementations of Statement. Statement is an interface with several implementations, including SimpleStatement, BoundStatement, and BatchStatement.

The simplest way to create and execute a statement is to call the CqlSession.execute() operation with a string representing the statement. Here’s an example of a statement that will return the entire contents of the reservations table:

cqlSession.execute("SELECT * from reservation.reservations_by_confirmation");

This statement creates and executes a query in a single method call. In practice, this could turn out to be a very expensive query to execute in a large database, but it does serve as a useful example of a very simple query. Most queries will be more complex, as you’ll have search criteria to specify or specific values to insert. You can certainly use Java’s various string utilities to build up the syntax of your query by hand, but this of course is error prone. It may even expose your application to injection attacks, if you’re not careful to sanitize strings that come from end users.

Simple Statements

Thankfully, you needn’t make things so hard on yourself. The Java driver provides the SimpleStatement class to help construct parameterized statements. As it turns out, the execute() operation is a convenience method for creating a SimpleStatement. The code above is equivalent to the following, using the SimpleStatement.newInstance() method:

cqlSession.execute(SimpleStatement.newInstance("SELECT * from reservation.reservations_by_confirmation"));

The newInstance() is most useful in cases where you already have a set query string. Let’s try building a query with variable parameters using a SimpleStatementBuilder. Here’s an example of a statement that will insert a row in the reservations table, which you can then execute:

SimpleStatement reservationInsert = SimpleStatement.builder(
  "INSERT INTO reservations_by_confirmation (confirmation_number, hotel_id, start_date, end_date, room_number, guest_id) VALUES (?, ?, ?, ?, ?, ?)")
  .addPositionalValue("RS2G0Z")
  .addPositionalValue("NY456")
  .addPositionalValue("2020-06-08")
  .addPositionalValue("2020-06-10")
  .addPositionalValue(111)
  .addPositionalValue("1b4d86f4-ccff-4256-a63d-45c905df2677")
  .build();
cqlSession.execute(reservationInsert);

The first parameter to the call is the basic syntax of your query, indicating the table and columns you are interested in. The question marks are used to indicate values that you’ll be providing in additional parameters. You use simple strings to hold the values of the hotel ID, name, and phone number.

If you’ve created your statement correctly, the insert will execute successfully (and silently). Now let’s create another statement to read back the row you just inserted:

SimpleStatement reservationSelect = SimpleStatement.builder(
  "SELECT * FROM reservations_by_confirmation WHERE confirmation_number=?")
  .addPositionalValue("RS2G0Z")
  .build();
ResultSet reservationSelectResult = cqlSession.execute(reservationSelect);

Again, you make use of parameterization to provide the ID for the search. This time, when you execute the query, make sure to receive the ResultSet which is returned from the execute() method. You can iterate through the rows returned by the ResultSet as follows:

for (Row row : reservationSelectResult) {
  System.out.format("confirmation_number: %s, hotel_id: %, start_date: %s, end_date %s, room_number: %i, guest_id: %s
",
  row.getString("confirmation_number"), row.getString("hotel_id"), row.getLocalDate("start_date"), row.getLocalDate("end_date"), row.getInt("room_number"), row.getUuid("guest_id"));
}

This code uses the ResultSet.iterator() option to get an Iterator over the rows in the result set and loop over each row, printing out the desired column values. Note that you use special accessors to obtain the value of each column depending on the desired type—in this case, Row.getString(), getInt(), and getUuid(). As you might expect, this will print out a result such as:

confirmation_number: RS2G0Z, hotel_id: NY456, start_date: 2020-06-08, end_date: 2020-06-10, room_number: 111, guest_id: 1b4d86f4-ccff-4256-a63d-45c905df2677

Of course, you typically will set columns to values you receive as variables, rather than the hardcoded value used here. You can find code samples for working with SimpleStatements on the simple-statement-solution branch of the Reservation Service repository.

Prepared Statements

While SimpleStatements are quite useful for creating ad hoc queries, most applications tend to perform the same set of queries repeatedly. The PreparedStatement is designed to handle these queries more efficiently. The structure of the statement is sent to nodes a single time for preparation, and a handle for the statement is returned. To use the prepared statement, only the handle and the parameters need to be sent.

As you’re building your application, you’ll typically create PreparedStatements for reading data, corresponding to each access pattern you derive in your data model, plus others for writing data to your tables to support those access patterns.

Let’s create some PreparedStatements to represent the same reservation queries as before, using the CqlSession.prepare() operation:

PreparedStatement reservationInsertPrepared = cqlSession.prepare(
  "INSERT INTO reservations_by_confirmation (confirmation_number, hotel_id, start_date, end_date, room_number, guest_id) VALUES (?, ?, ?, ?, ?, ?)");

PreparedStatement reservationSelectPrepared = cqlSession.prepare(
  "SELECT * FROM reservations_by_confirmation WHERE confirmation_number=?");

Note that the PreparedStatement uses the same parameterized syntax used earlier for the SimpleStatement. A key difference, however, is that a PreparedStatement is not a subtype of Statement. This prevents the error of trying to pass an unbound PreparedStatement to the CqlSession to execute. Note that there is also a variant of CqlSession.prepare() that accepts a parameterized SimpleStatement as input.

Let’s take a step back and discuss what is happening behind the scenes of the CqlSession.prepare() operation:

• The driver passes the contents of your PreparedStatement to a Cassandra node and gets back a unique identifier for the statement. This unique identifier is referenced when you create a BoundStatement. If you’re curious, you can actually see this reference by calling PreparedStatement.getId().

• Once the driver prepares the statement on one node, it proceeds to prepare the statement on the other nodes in the cluster. Nodes keep track of prepared statements in an internal table so that they are present if the node goes down and comes back up.

• The driver also provides the advanced.prepared-statements.reprepare-on-up configuration options. If re-preparation is enabled (the default), it will re-prepare statements on nodes that have come back up.

• If the driver tries to execute a PreparedStatement on a node where it has not been prepared, the driver automatically prepares the statement, at the cost of an additional round trip between the driver and the node.

You can think of a PreparedStatement as a template for creating queries. In addition to specifying the form of your query, there are other attributes that you can set on a PreparedStatement that will be used as defaults for statements it is used to create, including a default consistency level, retry policy, and tracing.

In addition to improving efficiency, PreparedStatements also improve security by separating the query logic of CQL from the data. This provides protection against injection attacks, which attempt to embed commands into data fields in order to gain unauthorized access.

BoundStatement reservationSelectBound = reservationSelectPrepared.bind("RS2G0Z");

BoundStatement reservationInsertBound = reservationInsertPrepared.bind()
  .setString("confirmation_number", "RS2G0Z")
  .setString("hotel_id", "NY456")
  .setLocalDate("start_date", "2020-06-08")
  .setLocalDate("end_date", "2020-06-10")
  .setShort(111)
  .setUuid("1b4d86f4-ccff-4256-a63d-45c905df2677")

Query Builder

The driver also provides a QueryBuilder, which uses a fluent-style API for creating queries programmatically. This is especially useful for cases where there is variation in the query structure (such as optional parameters) that would make using PreparedStatements difficult. Similar to PreparedStatement, it also provides some protection against injection attacks.

To use the QueryBuilder, you’ll need to include an additional dependency, for example in a Maven POM file:

<dependency>
  <groupId>com.datastax.oss</groupId>
  <artifactId>java-driver-query-builder</artifactId>
  <version>${driver.version}</version>
</dependency>

The QueryBuilder provides a set of static methods to facilitate building different types of statements represented by different classes. The common usage is to import the static methods of the QueryBuilder class:

import static com.datastax.oss.driver.api.querybuilder.QueryBuilder.*;

Importing methods statically improves code readability, as you’ll see as we look at some examples.

The QueryBuilder produces objects that implement the com.datastax.oss.driver.api.querybuilder.BuildableQuery interface and its sub-interfaces, such as Select, Insert, Update, Delete and others. The methods on these interfaces return objects that represent the content of a query as it is being built up. You’ll likely find your IDE quite useful in helping to identify the allowed operations as you’re building queries.

Let’s reproduce the queries from before using the QueryBuilder to see how it works. First, build a CQL INSERT query:

Insert reservationInsert = insertInto("reservation", "reservations_by_confirmation")
  .value("confirmation_number", "RS2G0Z")
  .value("hotel_id", "NY456")
  .value("start_date", "2020-06-08")
  .value("end_date", "2020-06-10")
  .value("room_number", 111)
  .value("guest_id", "1b4d86f4-ccff-4256-a63d-45c905df2677");

SimpleStatement reservationInsertStatement = reservationInsert.build();

The first operation calls the QueryBuilder.insertInto() operation to create an Insert statement for the reservations_by_confirmation table. Then use the Insert.value() operation repeatedly to specify values for each column you are inserting. The Insert.build() operation returns a SimpleStatement you can then pass to CqlSession.execute().

The construction of the CQL SELECT command is similar:

Select reservationSelect = selectFrom("reservation", "reservations_by_confirmation")
  .all()
  .whereColumn("confirmation_number").isEqualTo("RS2G0Z");

SimpleStatement reseravationSelectStatement = reservationSelect.build();

For this query, call QueryBuilder.selectFrom() to create a Select statement. You use the Select.all() operation to select all columns, although you could also have used the column() operation to select specific columns. Add a CQL WHERE clause via the Select.whereColumn() operation, to which you pass the name of the column and then add an equality check for the confirmation number uwing the isEqualTo() operation.

This sample demonstrates how you can use the QueryBuilder to create a PreparedStatement instead of a SimpleStatement, using the concept of a bind marker as a placeholder for a value to be specified when the PreparedStatement is bound:

Select reservationSelect = selectFrom("reservation", "reservations_by_confirmation")
  .all()
  .whereColumn("confirmation_number").isEqualTo(bindMarker());
PreparedStatement reservationSelectPrepared = cqlSession.prepare(reservationSelect.build());

// later
SimpleStatement reservationSelectStatement = reservationSelectPrepared.bind("RS2G0Z");

For a complete code sample using the QueryBuilder, see the query-builder-solution branch of the Reservation Service repository.

Object Mapper

We’ve explored several techniques for creating and executing query statements with the driver. There is one final technique to look at that provides a bit more abstraction. The Java driver provides an object mapper that allows you to focus on developing and interacting with domain models (or data types used on APIs). The object mapper works off of annotations in source code that are used to map Java classes to tables or user-defined types (UDTs). The object mapper is a useful tool for abstracting some of the details of interacting with Cassandra, especially if you have an existing domain model.

The mapper is provided in two separate libraries for use at compile time and runtime, so you will need to include additional additional Maven dependencies in order to use Mapper in your project. You’ll add the following dependency to the compile path of your application:

<dependency>
  <groupId>com.datastax.oss</groupId>
  <artifactId>java-driver-mapper-processor</artifactId>
  <version>${driver.version}</version>
</dependency>

You’ll also add the runtime library as a runtime dependency:

<dependency>
  <groupId>com.datastax.oss</groupId>
  <artifactId>java-driver-mapper-runtime</artifactId>
  <version>${driver.version}</version>
</dependency>

The mapper API is based on standard design patterns for data access, including entity classes and data access objects (DAOs). You create an entity class to represent each table in your design, a DAO interface to specify queries on entities, and a mapper interface that helps generate DAO instances. The mapper generates code based on the classes and interfaces you provide.

For a complete example of using the mapper, you’ll want to look at the mapper-solution branch of the Reservation Service repository. We’ll share some of the highlights here. Let’s begin by creating a ReservationsByConfirmation entity class which will represent rows in the reservations_by_confirmation table:

import com.datastax.oss.driver.api.mapper.annotations.Entity;
import com.datastax.oss.driver.api.mapper.annotations.PartitionKey;
import com.datastax.oss.driver.api.mapper.annotations.NamingStrategy;
import static com.datastax.oss.driver.api.mapper.entity.naming.NamingConvention.SNAKE_CASE_INSENSITIVE;

@Entity
@NamingStrategy(convention = SNAKE_CASE_INSENSITIVE)
public class ReservationsByConfirmation {

    @PartitionKey
    private String confirmationNumber;

    private String hotelId;
    private LocalDate startDate;
    private LocalDate endDate;
    private short roomNumber;
    private UUID guestId;

    // constructors, get/set methods, hashcode, equals
}

There are several annotations used in this example. The class is denoted as an @Entity, and also as having a @NamingStrategy, which is a way of specifying how the mapper should correlate Java identifiers to CQL. For example, you can specify a SNAKE_CASE_INSENSITIVE convention as above, which means that the mapper will convert Java-style class and member names to lowercase, with underscores separating words, which is the recommended CQL naming style. Thus the class name ReservationsByConfirmation will be mapped to the reservations_by_confirmation table, the confirmationNumber member will be mapped to the confirmation_number column, and so on.

The Reservation Service uses an additional entity class ReservationsByHotelDate that is used with the reservations_by_hotel_date table. Its implementation is quite similar, so we won’t reproduce it here.

You can also create entity classes corresponding to User Defined Types (UDTs). If your domain model contains classes that reference other classes, you can annotate the referenced classes as user-defined types with the @Entity annotation. The Object Mapper processes objects recursively using your annotated types.

Next, you’ll create a DAO interface to represent queries on these entity classes:

import com.datastax.oss.driver.api.core.PagingIterable;
import com.datastax.oss.driver.api.mapper.annotations.*;

@Dao
public interface ReservationDao {

    @Select
    ReservationsByConfirmation findByConfirmationNumber(String confirmationNumber);

    @Query("SELECT * FROM ${tableId}")
    PagingIterable<ReservationsByConfirmation> findAll();

    @Insert
    void save(ReservationsByConfirmation reservationsByConfirmation);

    @Delete
    void delete(ReservationsByConfirmation reservationsByConfirmation);

    @Select (customWhereClause = "hotel_id = :hotelId AND start_date = :date")
    PagingIterable<ReservationsByHotelDate> findByHotelDate(
            @CqlName("hotel_id") String hotelId,
            @CqlName("start_date") LocalDate date);

    @Insert
    void save(ReservationsByHotelDate reservationsByHotelDate);

    @Delete
    void delete(ReservationsByHotelDate reservationsByHotelDate);
}

The ReservationDao interface is annotated as a @Dao, and the various queries are marked with annotations such as @Select, @Insert, @Delete, and @Query.

The next step is to create a Mapper interface that can be used to obtain DAO instances:

import com.datastax.oss.driver.api.mapper.annotations.DaoFactory;
import com.datastax.oss.driver.api.mapper.annotations.Mapper;

@Mapper
public interface ReservationMapper {

    @DaoFactory
    ReservationDao reservationDao();

}

Annotate the interface with @Mapper and each operation that returns a DAO with @DaoFactory. When you compile the application, the object mapper interprets your annotations to create a ReservationMapperBuilder class that you can invoke to obtain an implementation of ReservationMapper interface that wraps the CqlSession, and from there obtain an object implementing the ReservationDao interface:

ReservationMapper reservationMapper = new ReservationMapperBuilder(cqlSession).build();
ReservationDao reservationDao = reservationMapper.reservationDao();

Since the mapper and DAO objects are using your CqlSession, you should reuse them just as you do the CqlSession.

Now you can use the ReservationDao to perform queries using your entity classes. Create a ReservationsByConfirmation object using a simple constructor that you can save using the DAO:

ReservationsByConfirmation reservation = new ReservationsByConfirmation(
  "RS2G0Z", "NY456", "2020-06-08", "2020-06-10", 111,
  UUID.fromString("1b4d86f4-ccff-4256-a63d-45c905df2677"));
reservationDao.save(reservation);

You can use the java.util.UUID.fromString() operation here for convenience; in most applications, the value would have been passed in via a remote invocation.

The Mapper.save() operation is all you need to execute to perform a CQL INSERT or UPDATE, as these are really the same operation to Cassandra. The ReservationDao builds and executes the statement on your behalf.

To retrieve a specific reservation, use the ReservationDao.findByConfirmationNumber() operation, passing in an argument list that matches the the partition key:

ReservationsByConfirmation reservation = reservationDao.findByConfirmation Number("RS2G0Z");

Deleting a reservation is also straightforward:

reservationDao.delete(reservation);

The Object Mapper documentation describes more advanced features, including DAO methods that execute asynchronously, the ability to configure CQL statement options such as TTL or consistency level, and customizing how the mapper handles annotations.

Asynchronous Execution

The CqlSession.execute() operation is synchronous, which means that it blocks until a result is obtained or an error occurs, such as a network timeout. The driver also provides the asynchronous executeAsync() operation to support non-blocking interactions with Cassandra. These non-blocking requests can make it simpler to send multiple queries in parallel to speed performance of your client application.

You could take any of the Statements from the examples above and execute it asynchronously:

CompletionStage<AsyncResultSet> resultStage =  cqlSession.executeAsync(statement);

The result is of the type CompletionStage type introduced in Java 8. The CompletionStage

A Future is a Java generic type used to capture the result of an asynchronous operation. Each Future can be checked to see whether the operation has completed, and then queried for the result of the operation according to the bound type. There are also blocking wait() operations to wait for the result. A Future can be cancelled if the caller is no longer interested in the result of the operation. The Future class is a useful tool for implementing asynchronous programming patterns, but requires either blocking or polling to wait for the operation to complete.

To address this drawback, the Java driver leverages the ListenableFuture interface from Google’s Guava framework. The ListenableFuture interface extends Future, and adds an addListener() operation that allows the client to register a callback method that is invoked when the Future completes. The callback method is invoked in a thread managed by the driver, so it is important that the method complete quick ly to avoid tying up driver resources. The ResultSetFuture is bound to the ResultSet type.

Driver Configuration

We’ve already looked at a few of the available options for configuring the driver, but now let’s take a step back and look at its overall configuration approach.

datastax-java-driver {
  basic {
    contact-points = [ "127.0.0.1:9042", "127.0.0.2:9042" ]
    session-keyspace = reservation
  }
}

advanced.speculative-execution-policy {
  class = ConstantSpeculativeExecutionPolicy
  max-executions = 3
  delay = 100 milliseconds
}

datastax-java-driver {
  profiles {
    long_request {
      basic.request.timeout = 3 seconds
      basic.request.consistency = QUORUM
    }
}

statement.setExecutionProfileName("long_request");

Metadata

To access the cluster metadata, invoke the CqlSession.getMetadata() method, which returns an object implementing the com.datastax.oss.driver.api.core.metadata.Metadata interface. This object provides information about the cluster at a snapshot in time, including the nodes in the cluster, the tokens assigned to each node, and the schema including keyspaces and tables.

The driver provides a notification mechanism for clients to learn about schema changes by registering a ++com.datastax.oss.driver.api.core.metadata.schema.SchemaChangeListener++ with the ++CqlSession++ as it is built using the ++withSchemaChangeListener()++ operation on the builder, or via the ++advanced.schema-change-listener++ configuration option.

import static com.datastax.oss.driver.api.querybuilder.SchemaBuilder.createTable;
import com.datastax.oss.driver.api.core.type.DataTypes;

cqlSession.execute(createTable("reservation", "reservations_by_confirmation")
  .ifNotExists()
  .withPartitionKey("confirmation_number, DataTypes.TEXT)
  .withColumn("hotel_id", DataTypes.TEXT)
  .withColumn("start_date", DataTypes.DATE)
  .withColumn("end_date", DataTypes.DATE)
  .withColumn("room_number", DataTypes.SMALLINT)
  .withColumn("guest_id", DataTypes.UUID)
  .build());

Debugging and Monitoring

The driver provides features for monitoring and debugging your client’s use of Cassandra, including facilities for logging and metrics. There are also capabilities for query tracing and tracking slow queries, which you’ll learn about in Chapter 13.

<configuration>
  <!-- other appenders and loggers -->
  <logger name="com.datastax.oss.driver" level="INFO"/>
</configuration>