com.google.cloud.spanner.watcher

Class SpannerTableChangeSetPoller

java.lang.Object

com.google.api.core.AbstractApiService

com.google.cloud.spanner.watcher.SpannerTableChangeSetPoller

All Implemented Interfaces:

com.google.api.core.ApiService, SpannerTableChangeWatcher

public class SpannerTableChangeSetPoller
extends com.google.api.core.AbstractApiService
implements SpannerTableChangeWatcher

Implementation of the SpannerTableChangeWatcher interface that continuously polls a change set table for new rows, and then polls an actual data table 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).

Usage:

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

 Spanner spanner = SpannerOptions.getDefaultInstance().getService();
 TableId tableId =
     TableId.of(DatabaseId.of(SpannerOptions.getDefaultProjectId(), instance, database), table);
 SpannerTableChangeSetPoller watcher = SpannerTableChangeSetPoller.newBuilder(spanner, tableId).build();
 watcher.addCallback(
     new RowChangeCallback() {

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SpannerTableChangeSetPoller.Builder Builder for a SpannerTableChangeSetPoller.

Nested classes/interfaces inherited from interface com.google.cloud.spanner.watcher.SpannerTableChangeWatcher

SpannerTableChangeWatcher.Row, SpannerTableChangeWatcher.RowChangeCallback

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 SpannerTableChangeWatcher.
protected void	doStart()
protected void	doStop()
TableId	getTable() Returns the id of the table that is monitored by this watcher.
static SpannerTableChangeSetPoller.Builder	newBuilder(com.google.cloud.spanner.Spanner spanner, TableId table) Creates a new SpannerTableChangeSetPoller.Builder for the given table.
static SpannerTableChangeSetPoller.Builder	newBuilder(com.google.cloud.spanner.Spanner spanner, TableId changeSetTable, TableId table) Creates a new SpannerTableChangeSetPoller.Builder for the given table and using the specified change set table.

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 SpannerTableChangeSetPoller.Builder newBuilder(com.google.cloud.spanner.Spanner spanner,
                                                             TableId table)

Creates a new SpannerTableChangeSetPoller.Builder for the given table. The poller will assume that all change sets are stored in a table called CHANGE_SETS.

newBuilder

public static SpannerTableChangeSetPoller.Builder newBuilder(com.google.cloud.spanner.Spanner spanner,
                                                             TableId changeSetTable,
                                                             TableId table)

Creates a new SpannerTableChangeSetPoller.Builder for the given table and using the specified change set table.

getTable

public TableId getTable()

Description copied from interface: SpannerTableChangeWatcher

Returns the id of the table that is monitored by this watcher.

Specified by:

getTable in interface SpannerTableChangeWatcher

addCallback

public void addCallback(SpannerTableChangeWatcher.RowChangeCallback callback)

Description copied from interface: SpannerTableChangeWatcher

Adds a SpannerTableChangeWatcher.RowChangeCallback for this SpannerTableChangeWatcher. Callbacks may only be added when the ApiService.state() of this SpannerTableChangeWatcher is State#NEW. Callbacks should be lightweight and non-blocking. The callback should hand off any heavy computations or blocking operations to a non-blocking executor or buffer.

The SpannerTableChangeWatcher guarantees that at most one SpannerTableChangeWatcher.RowChangeCallback will be active at any given time, and all callbacks will receive all changes in order of commit timestamp. There is no guarantee as to the order of which callback is called first if a SpannerTableChangeWatcher has registered multiple callbacks.

Specified by:

addCallback in interface SpannerTableChangeWatcher

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