nl.topicus.jdbc.shaded.com.google.cloud.spanner.spi.v1.SpannerRpc Maven / Gradle / Ivy
/*
* Copyright 2017 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package nl.topicus.jdbc.shaded.com.google.cloud.spanner.spi.v1;
import nl.topicus.jdbc.shaded.com.google.cloud.ServiceRpc;
import nl.topicus.jdbc.shaded.com.google.cloud.spanner.SpannerException;
import nl.topicus.jdbc.shaded.com.google.common.collect.ImmutableList;
import nl.topicus.jdbc.shaded.com.google.longrunning.Operation;
import nl.topicus.jdbc.shaded.com.google.protobuf.FieldMask;
import nl.topicus.jdbc.shaded.com.google.spanner.admin.database.v1.Database;
import nl.topicus.jdbc.shaded.com.google.spanner.admin.instance.v1.Instance;
import nl.topicus.jdbc.shaded.com.google.spanner.admin.instance.v1.InstanceConfig;
import nl.topicus.jdbc.shaded.com.google.spanner.v1.BeginTransactionRequest;
import nl.topicus.jdbc.shaded.com.google.spanner.v1.CommitRequest;
import nl.topicus.jdbc.shaded.com.google.spanner.v1.CommitResponse;
import nl.topicus.jdbc.shaded.com.google.spanner.v1.ExecuteSqlRequest;
import nl.topicus.jdbc.shaded.com.google.spanner.v1.PartialResultSet;
import nl.topicus.jdbc.shaded.com.google.spanner.v1.ReadRequest;
import nl.topicus.jdbc.shaded.com.google.spanner.v1.RollbackRequest;
import nl.topicus.jdbc.shaded.com.google.spanner.v1.Session;
import nl.topicus.jdbc.shaded.com.google.spanner.v1.Transaction;
import java.util.List;
import java.util.Map;
import nl.topicus.jdbc.shaded.javax.annotation.Nullable;
/**
* Abstracts remote calls to the Cloud Spanner service. Typically end-consumer code will never use
* this interface; it's main purpose is to abstract the implementation of the public Cloud Spanner
* API from the underlying transport mechanism.
*
* Each {@code SpannerRPC} instance is bound to a particular project and set of authorization
* credentials.
*
*
The interface is currently defined in terms of the generated HTTP client model classes. This
* is purely for expedience; a future version of this interface is likely to be independent of
* transport to allow switching between gRPC and HTTP.
*/
public interface SpannerRpc extends ServiceRpc {
/** Options passed in {@link SpannerRpc} methods to control how an RPC is issued. */
enum Option {
CHANNEL_HINT("Channel Hint");
private final String value;
Option(String value) {
this.value = value;
}
@SuppressWarnings("unchecked")
T get(@Nullable Map options) {
if (options == null) {
return null;
}
return (T) options.get(this);
}
Long getLong(@Nullable Map options) {
return get(options);
}
@Override
public String toString() {
return value;
}
}
/**
* Represents results from paginated RPCs, i.e., those where up to a maximum number of items is
* returned from each call and a followup call must be made to fetch more.
*
* @param the type of result
*/
public static final class Paginated {
private final Iterable results;
private final String nextPageToken;
/**
* Creates a new page of results.
*
* @param results the result, or null for no results.
* @param nextPageToken the token for the next page of results, or null if no more pages exist
*/
public Paginated(@Nullable Iterable results, @Nullable String nextPageToken) {
// The generated HTTP client has null members when no results are present, rather than an
// empty list. Implicitly convert to an empty list to minimize the risk of NPEs.
this.results = (results == null) ? ImmutableList.of() : results;
this.nextPageToken =
(nextPageToken == null || nextPageToken.isEmpty()) ? null : nextPageToken;
}
/**
* Returns the current page of results. Always returns non-null; if a null "results" was passed
* to the constructor, a default empty {@code Iterable} will be returned.
*/
public Iterable getResults() {
return results;
}
/**
* Returns the token to use in the request for the next page, or null if this is the last page.
*/
@Nullable
public String getNextPageToken() {
return nextPageToken;
}
}
/** Consumer for the results produced by a streaming read or query call. */
interface ResultStreamConsumer {
void onPartialResultSet(PartialResultSet results);
void onCompleted();
void onError(SpannerException e);
}
/** Handle for cancellation of a streaming read or query call. */
interface StreamingCall {
/**
* Requests more messages from the stream. We disable the auto flow control mechanisam in grpc,
* so we need to request messages ourself. This gives us more control over how much buffer we
* maintain in the client. Grpc will request 1 initial message automatically so we don't need to
* call this at the beginning. After that it should be called whenever there is a flow control
* window available based on the flow control setting configured by the client. Currently we do
* not have any flow control so this is called automatically when a message is received.
*/
void request(int numMessages);
/**
* Cancels the call.
*
* @param message a message to use in the final status of any underlying RPC
*/
void cancel(@Nullable String message);
}
// Instance admin APIs.
Paginated listInstanceConfigs(int pageSize, @Nullable String pageToken)
throws SpannerException;
InstanceConfig getInstanceConfig(String instanceConfigName) throws SpannerException;
Paginated listInstances(
int pageSize, @Nullable String pageToken, @Nullable String filter) throws SpannerException;
Operation createInstance(String parent, String instanceId, Instance instance)
throws SpannerException;
Operation updateInstance(Instance instance, FieldMask fieldMask) throws SpannerException;
Instance getInstance(String instanceName) throws SpannerException;
void deleteInstance(String instanceName) throws SpannerException;
// Database admin APIs.
Paginated listDatabases(String instanceName, int pageSize, @Nullable String pageToken)
throws SpannerException;
Operation createDatabase(
String instanceName, String createDatabaseStatement, Iterable additionalStatements)
throws SpannerException;
Operation updateDatabaseDdl(
String databaseName, Iterable updateDatabaseStatements, @Nullable String updateId)
throws SpannerException;
void dropDatabase(String databaseName) throws SpannerException;
Database getDatabase(String databaseName) throws SpannerException;
List getDatabaseDdl(String databaseName) throws SpannerException;
/** Retrieves a long running operation. */
Operation getOperation(String name) throws SpannerException;
Session createSession(String databaseName, @Nullable Map labels, @Nullable Map options)
throws SpannerException;
void deleteSession(String sessionName, @Nullable Map options) throws SpannerException;
StreamingCall read(
ReadRequest request, ResultStreamConsumer consumer, @Nullable Map options);
StreamingCall executeQuery(
ExecuteSqlRequest request, ResultStreamConsumer consumer, @Nullable Map options);
Transaction beginTransaction(BeginTransactionRequest request, @Nullable Map options)
throws SpannerException;
CommitResponse commit(CommitRequest commitRequest, @Nullable Map options)
throws SpannerException;
void rollback(RollbackRequest request, @Nullable Map options) throws SpannerException;
}