com.google.cloud.spanner.watcher

Class SpannerDatabaseChangeSetPoller

java.lang.Object

com.google.api.core.AbstractApiService

com.google.cloud.spanner.watcher.SpannerDatabaseChangeSetPoller

All Implemented Interfaces:

com.google.api.core.ApiService, SpannerDatabaseChangeWatcher

public class SpannerDatabaseChangeSetPoller
extends com.google.api.core.AbstractApiService
implements SpannerDatabaseChangeWatcher

Implementation of the SpannerDatabaseChangeWatcher interface that continuously polls a change set table for new rows, and then polls the actual data tables for any changes that was part of the last seen change set. This requires all client applications to insert a new row to a CHANGE_SETS table for each read/write transaction that is executed. While this does add an extra write operation to each read/write transaction, it has two advantages:

1. It does not require each data table to have a column that stores the last commit timestamp. Commit timestamp columns that are filled using DML will prevent the same transaction from reading anything from the same table for the remainder of the transaction. See https://cloud.google.com/spanner/docs/commit-timestamp#dml.
2. Instead of having a commit timestamp column in each data table, the data tables contain a CHANGE_SET_ID column. This column can be of any type and can contain a random value. This makes the column easier to index than a commit timestamp column, as an index on a truly random id will not suffer from hotspots (https://cloud.google.com/spanner/docs/schema-design#primary-key-prevent-hotspots).

Example usage for watching all tables in a database:

{@code
 String instance = "my-instance";
 String database = "my-database";

 Spanner spanner = SpannerOptions.getDefaultInstance().getService();
 DatabaseId databaseId = DatabaseId.of(SpannerOptions.getDefaultProjectId(), instance, database);
 SpannerDatabaseChangeWatcher watcher =
     SpannerDatabaseChangeSetPoller.newBuilder(spanner, databaseId).allTables().build();
 watcher.addCallback(
     new RowChangeCallback() {

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	SpannerDatabaseChangeSetPoller.Builder Builder for a SpannerDatabaseChangeSetPoller.

Nested classes/interfaces inherited from interface com.google.api.core.ApiService

com.google.api.core.ApiService.Listener, com.google.api.core.ApiService.State

Method Summary

Modifier and Type	Method and Description
void	addCallback(SpannerTableChangeWatcher.RowChangeCallback callback) Adds a SpannerTableChangeWatcher.RowChangeCallback for this SpannerDatabaseChangeWatcher.
protected void	doStart()
protected void	doStop()
com.google.cloud.spanner.DatabaseId	getDatabaseId() Returns the id of the database that is being monitored for changes.
List<TableId>	getTables() Returns the ids of the tables that are monitored by this watcher.
static SpannerDatabaseChangeSetPoller.Builder.TableSelecter	newBuilder(com.google.cloud.spanner.Spanner spanner, com.google.cloud.spanner.DatabaseId databaseId) Creates a builder for a SpannerDatabaseChangeSetPoller.
static SpannerDatabaseChangeSetPoller.Builder.TableSelecter	newBuilder(com.google.cloud.spanner.Spanner spanner, com.google.cloud.spanner.DatabaseId databaseId, TableId changeSetTable) Creates a builder for a SpannerDatabaseChangeSetPoller.

Methods inherited from class com.google.api.core.AbstractApiService

addListener, awaitRunning, awaitRunning, awaitTerminated, awaitTerminated, failureCause, isRunning, notifyFailed, notifyStarted, notifyStopped, startAsync, state, stopAsync

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.google.api.core.ApiService

addListener, awaitRunning, awaitRunning, awaitTerminated, awaitTerminated, failureCause, isRunning, startAsync, state, stopAsync

Method Detail

newBuilder

public static SpannerDatabaseChangeSetPoller.Builder.TableSelecter newBuilder(com.google.cloud.spanner.Spanner spanner,
                                                                              com.google.cloud.spanner.DatabaseId databaseId)

Creates a builder for a SpannerDatabaseChangeSetPoller.

newBuilder

public static SpannerDatabaseChangeSetPoller.Builder.TableSelecter newBuilder(com.google.cloud.spanner.Spanner spanner,
                                                                              com.google.cloud.spanner.DatabaseId databaseId,
                                                                              TableId changeSetTable)

Creates a builder for a SpannerDatabaseChangeSetPoller.

addCallback

public void addCallback(SpannerTableChangeWatcher.RowChangeCallback callback)

Description copied from interface: SpannerDatabaseChangeWatcher

Adds a SpannerTableChangeWatcher.RowChangeCallback for this SpannerDatabaseChangeWatcher. Callbacks may only be added when the ApiService.state() of this SpannerDatabaseChangeWatcher is ApiService.State.NEW. Callbacks for one table will always be in order of commit timestamp, and only one callback will be active at any time for a table. Callbacks for different tables may be called in parallel, and there is no guarantee to the ordering of callbacks over multiple tables.

Specified by:

addCallback in interface SpannerDatabaseChangeWatcher

doStart

protected void doStart()

Specified by:

doStart in class com.google.api.core.AbstractApiService

doStop

protected void doStop()

Specified by:

doStop in class com.google.api.core.AbstractApiService

getDatabaseId

public com.google.cloud.spanner.DatabaseId getDatabaseId()

Description copied from interface: SpannerDatabaseChangeWatcher

Returns the id of the database that is being monitored for changes.

Specified by:

getDatabaseId in interface SpannerDatabaseChangeWatcher

getTables

public List<TableId> getTables()

Description copied from interface: SpannerDatabaseChangeWatcher

Returns the ids of the tables that are monitored by this watcher. This call can require the SpannerDatabaseChangeWatcher to make a round-trip to the database to determine the actual tables that are being monitored.

Specified by:

getTables in interface SpannerDatabaseChangeWatcher