com.google.cloud.spring.data.spanner.core

Interface SpannerOperations

All Known Implementing Classes:

SpannerTemplate

public interface SpannerOperations

Defines operations available to use with Spanner.

Since:

1.1

Author:

Ray Tsang, Chengyuan Zhao

Method Summary

Modifier and Type	Method and Description
<T> long	count(Class<T> entityClass) Count how many objects are stored of the given type.
<T> void	delete(Class<T> entityClass, Key key) Deletes an object based on a key.
<T> void	delete(Class<T> entityClass, KeySet keys) Deletes objects given a set of keys.
void	delete(Object object) Deletes an object from storage.
void	deleteAll(Iterable<?> objects) Deletes objects from storage in a batch.
long	executeDmlStatement(Statement statement) Execute a DML statement on Cloud Spanner.
long	executePartitionedDmlStatement(Statement statement) Execute a DML statement in partitioned mode.
<T> boolean	existsById(Class<T> entityClass, Key key) Returns whether an entity with the given id exists.
void	insert(Object object) Insert an object into storage.
void	insertAll(Iterable<?> objects) Insert objects into storage in batch.
<T> T	performReadOnlyTransaction(Function<SpannerTemplate,T> operations, SpannerReadOptions readOptions) Performs multiple read-only operations in a single transaction.
<T> T	performReadWriteTransaction(Function<SpannerTemplate,T> operations) Performs multiple read and write operations in a single transaction.
<T> List<T>	query(Class<T> entityClass, Statement statement, SpannerQueryOptions options) Finds objects by using an SQL statement.
<A> List<A>	query(Function<Struct,A> rowFunc, Statement statement, SpannerQueryOptions options) Executes a given query string with tags and parameters and applies a given function to each row of the result.
<T> List<T>	queryAll(Class<T> entityClass, SpannerPageableQueryOptions options) Finds all objects of the given type.
<T> T	read(Class<T> entityClass, Key key) Finds a single stored object using a key.
<T> List<T>	read(Class<T> entityClass, KeySet keys) Finds objects stored from their keys.
<T> List<T>	read(Class<T> entityClass, KeySet keys, SpannerReadOptions options) Finds objects stored from their keys.
<T> T	read(Class<T> entityClass, Key key, SpannerReadOptions options) Finds a single stored object using a key.
<T> List<T>	readAll(Class<T> entityClass) Finds all objects of the given type.
<T> List<T>	readAll(Class<T> entityClass, SpannerReadOptions options) Finds all objects of the given type.
void	update(Object object) Update an object already in storage.
void	update(Object object, Set<String> includeProperties) Update an object in storage.
void	update(Object object, String... includeProperties) Update an object in storage.
void	updateAll(Iterable<?> objects) Update objects in batch.
void	upsert(Object object) Update or insert an object into storage.
void	upsert(Object object, Set<String> includeProperties) Update or insert an object into storage.
void	upsert(Object object, String... includeProperties) Update or insert an object into storage.
void	upsertAll(Iterable<?> objects) Update or insert objects into storage in batch.

Method Detail

executeDmlStatement

long executeDmlStatement(Statement statement)

Execute a DML statement on Cloud Spanner. This must always be done in a transaction and one will be started if needed. See executePartitionedDmlStatement(Statement) for executing partitioned DML without a transaction.

Parameters:

statement - the DML statement to execute.

Returns:

the number of rows affected.

executePartitionedDmlStatement

long executePartitionedDmlStatement(Statement statement)

Execute a DML statement in partitioned mode. This is not available inside of transactions.

Parameters:

statement - the DML statement to execute.

Returns:

the lower-bound of number of rows affected.

read

<T> T read(Class<T> entityClass,
           Key key)

Finds a single stored object using a key.

Type Parameters:

T - the type of the object to retrieve.

Parameters:

entityClass - the type of the object to retrieve.

key - the key of the object.

Returns:

an object of the requested type. Returns null if no object could be found stored with the given key.

existsById

<T> boolean existsById(Class<T> entityClass,
                       Key key)

Returns whether an entity with the given id exists.

Type Parameters:

T - the type of the object to check.

Parameters:

entityClass - the type of the entity

key - the key of the object

Returns:

true if an entity with the given key exists, false otherwise.

Throws:

IllegalArgumentException - if id is null.

read

<T> T read(Class<T> entityClass,
           Key key,
           SpannerReadOptions options)

Finds a single stored object using a key.

Type Parameters:

T - the type of the object to retrieve.

Parameters:

entityClass - the type of the object to retrieve.

key - the key of the object.

options - the Cloud Spanner read options with which to conduct the read operation.

Returns:

an object of the requested type. Returns null if no object could be found stored with the given key.

read

<T> List<T> read(Class<T> entityClass,
                 KeySet keys,
                 SpannerReadOptions options)
          throws IllegalArgumentException

Finds objects stored from their keys. When the entity has a Where class annotation or any of the properties is eagerly interleaved, the SQL query will be performed instead of the ReadContext.read(java.lang.String, com.google.cloud.spanner.KeySet, java.lang.Iterable<java.lang.String>, com.google.cloud.spanner.Options.ReadOption...) to fetch such properties and satisfy the sql where condition.

Type Parameters:

T - the type of the object to retrieve.

Parameters:

entityClass - the type of the object to retrieve.

keys - the keys of the objects to retrieve.

options - the Cloud Spanner read options with which to conduct the read operation.

Returns:

a list of objects that could be found using the given keys. If no keys could be found the list will be empty.

Throws:

IllegalArgumentException - when a combination of provided parameters and annotations does not allow to take unambiguous decision about the way to perform the operation. Such algorithm is used:

• no need for "eager" or "Where" - we call ReadContext.read(java.lang.String, com.google.cloud.spanner.KeySet, java.lang.Iterable<java.lang.String>, com.google.cloud.spanner.Options.ReadOption...)
• we need "eager" or "Where", options and keys are compatible with SpannerQueryOptions - in this case we execute an SQL query
• otherwise an exception will be thrown

read

<T> List<T> read(Class<T> entityClass,
                 KeySet keys)

Finds objects stored from their keys.

Type Parameters:

T - the type of the object to retrieve.

Parameters:

entityClass - the type of the object to retrieve.

keys - the keys of the objects to retrieve.

Returns:

a list of objects that could be found using the given keys. If no keys could be found the list will be empty.

query

<A> List<A> query(Function<Struct,A> rowFunc,
                  Statement statement,
                  SpannerQueryOptions options)

Executes a given query string with tags and parameters and applies a given function to each row of the result.

Type Parameters:

A - the type to convert each row Struct into.

Parameters:

rowFunc - the function to apply to each row of the result.

statement - the SQL statement used to select the objects.

options - the options with which to run this query.

Returns:

a list of the rows each transformed with the given function.

query

<T> List<T> query(Class<T> entityClass,
                  Statement statement,
                  SpannerQueryOptions options)

Finds objects by using an SQL statement.

Type Parameters:

T - the type of object to retrieve.

Parameters:

entityClass - the type of object to retrieve.

statement - the SQL statement used to select the objects.

options - the Cloud Spanner read options with which to conduct the read operation.

Returns:

a list of the objects found. If no keys could be found the list will be empty.

readAll

<T> List<T> readAll(Class<T> entityClass,
                    SpannerReadOptions options)

Finds all objects of the given type.

Type Parameters:

T - the type of the object to retrieve.

Parameters:

entityClass - the type of the object to retrieve.

options - the Cloud Spanner read options with which to conduct the read operation.

Returns:

a list of all objects stored of the given type. If there are no objects an empty list is returned.

readAll

<T> List<T> readAll(Class<T> entityClass)

Finds all objects of the given type.

Type Parameters:

T - the type of the object to retrieve.

Parameters:

entityClass - the type of the object to retrieve.

Returns:

a list of all objects stored of the given type. If there are no objects an empty list is returned.

queryAll

<T> List<T> queryAll(Class<T> entityClass,
                     SpannerPageableQueryOptions options)

Finds all objects of the given type.

Type Parameters:

T - the type of the object to retrieve.

Parameters:

entityClass - the type of the object to retrieve.

options - the Cloud Spanner query options with which to conduct the query operation.

Returns:

a list of all objects stored of the given type. If there are no objects an empty list is returned.

delete

<T> void delete(Class<T> entityClass,
                Key key)

Deletes an object based on a key.

Type Parameters:

T - the type of the object to delete.

Parameters:

entityClass - the type of the object to delete.

key - the key of the object to delete from storage.

delete

void delete(Object object)

Deletes an object from storage.

Parameters:

object - the object to delete from storage.

deleteAll

void deleteAll(Iterable<?> objects)

Deletes objects from storage in a batch.

Parameters:

objects - the objects to delete from storage.

delete

<T> void delete(Class<T> entityClass,
                KeySet keys)

Deletes objects given a set of keys.

Type Parameters:

T - the type of the object to delete.

Parameters:

entityClass - the type of object to delete.

keys - the keys of the objects to delete.

insert

void insert(Object object)

Insert an object into storage.

Parameters:

object - the object to insert.

insertAll

void insertAll(Iterable<?> objects)

Insert objects into storage in batch.

Parameters:

objects - the objects to insert.

update

void update(Object object)

Update an object already in storage.

Parameters:

object - the object to update.

updateAll

void updateAll(Iterable<?> objects)

Update objects in batch.

Parameters:

objects - the objects to update.

update

void update(Object object,
            String... includeProperties)

Update an object in storage.

Parameters:

object - the object to update.

includeProperties - the properties to upsert. if none are given then all properties are used

update

void update(Object object,
            Set<String> includeProperties)

Update an object in storage.

Parameters:

object - the object to update.

includeProperties - the properties to update. If null is given, then all properties are used. Note that an empty Set means that no properties will be used.

upsert

void upsert(Object object)

Update or insert an object into storage.

Parameters:

object - the object to update or insert.

upsertAll

void upsertAll(Iterable<?> objects)

Update or insert objects into storage in batch.

Parameters:

objects - the objects to update or insert.

upsert

void upsert(Object object,
            String... includeProperties)

Update or insert an object into storage.

Parameters:

object - the object to update or insert.

includeProperties - the properties to upsert. if none are given then all properties are upserted.

upsert

void upsert(Object object,
            Set<String> includeProperties)

Update or insert an object into storage.

Parameters:

object - the object to update or insert.

includeProperties - the properties to update. If null is given, then all properties are used. Note that an empty Set means that no properties will be used.

count

<T> long count(Class<T> entityClass)

Count how many objects are stored of the given type.

Type Parameters:

T - the type of the object to count.

Parameters:

entityClass - the type of object to count.

Returns:

the number of stored objects.

performReadWriteTransaction

<T> T performReadWriteTransaction(Function<SpannerTemplate,T> operations)

Performs multiple read and write operations in a single transaction.

Type Parameters:

T - the final return type of the operations.

Parameters:

operations - the function representing the operations to perform using a SpannerOperations based on a single transaction.

Returns:

the final result of the transaction.

performReadOnlyTransaction

<T> T performReadOnlyTransaction(Function<SpannerTemplate,T> operations,
                                 SpannerReadOptions readOptions)

Performs multiple read-only operations in a single transaction.

Type Parameters:

T - the final return type of the operations.

Parameters:

operations - the function representing the operations to perform using a SpannerOperations based on a single transaction.

readOptions - allows the user to specify staleness for the read transaction

Returns:

the final result of the transaction.