com.google.cloud.spanner.InstanceAdminClient Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of google-cloud-spanner Show documentation
Show all versions of google-cloud-spanner Show documentation
Java idiomatic client for Google Cloud Spanner.
/*
* 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 com.google.cloud.spanner;
import com.google.api.gax.longrunning.OperationFuture;
import com.google.api.gax.paging.Page;
import com.google.cloud.Policy;
import com.google.cloud.spanner.Options.CreateAdminApiOption;
import com.google.cloud.spanner.Options.DeleteAdminApiOption;
import com.google.cloud.spanner.Options.ListOption;
import com.google.cloud.spanner.Options.UpdateAdminApiOption;
import com.google.longrunning.Operation;
import com.google.spanner.admin.instance.v1.CreateInstanceConfigMetadata;
import com.google.spanner.admin.instance.v1.CreateInstanceMetadata;
import com.google.spanner.admin.instance.v1.UpdateInstanceConfigMetadata;
import com.google.spanner.admin.instance.v1.UpdateInstanceMetadata;
/** Client to do admin operations on Cloud Spanner Instance and Instance Configs. */
public interface InstanceAdminClient {
/**
* Creates an instance config and begins preparing it to be used. The returned {@code Operation}
* can be used to track the progress of preparing the new instance config. The instance config
* name is assigned by the caller and must start with the string 'custom'. If the named instance
* config already exists, a SpannerException is thrown.
*
* Immediately after the request returns:
*
*
* - The instance config is readable via the API, with all requested attributes.
*
- The instance config's {@code reconciling} field is set to true. Its state is {@code
* CREATING}.
*
*
* While the operation is pending:
*
*
* - Cancelling the operation renders the instance config immediately unreadable via the API.
*
- Except for deleting the creating resource, all other attempts to modify the instance
* config are rejected.
*
*
* Upon completion of the returned operation:
*
*
* - Instances can be created using the instance configuration.
*
- The instance config's {@code reconciling} field becomes false.
*
- Its state becomes {@code READY}.
*
*
*
*
* {@code
* String projectId = "my-project";
* String baseInstanceConfig = "my-base-config";
* String instanceConfigId = "custom-user-config";
*
* final InstanceConfig baseConfig = instanceAdminClient.getInstanceConfig(baseInstanceConfig);
*
* List readOnlyReplicas = ImmutableList.of(baseConfig.getOptionalReplicas().get(0));
*
* InstanceConfigInfo instanceConfigInfo =
* InstanceConfigInfo.newBuilder(InstanceConfigId.of(projectId, instanceConfigId), baseConfig)
* .setDisplayName(instanceConfigId)
* .addReadOnlyReplicas(readOnlyReplicas)
* .build();
*
* final OperationFuture operation =
* instanceAdminClient.createInstanceConfig(instanceConfigInfo);
*
* InstanceConfig instanceConfig = op.get(5, TimeUnit.MINUTES)
* }
*
*
*/
default OperationFuture createInstanceConfig(
InstanceConfigInfo instanceConfig, CreateAdminApiOption... options) throws SpannerException {
throw new UnsupportedOperationException("Not implemented");
}
/**
* Updates a custom instance config. This can not be used to update a Google managed instance
* config. The returned {@code Operation} can be used to track the progress of updating the
* instance. If the named instance config does not exist, a SpannerException is thrown. The
* request must include at least one field to update.
*
* Only user managed configurations can be updated.
*
*
Immediately after the request returns:
*
*
* - The instance config's {@code reconciling} field is set to true.
*
*
* While the operation is pending:
*
*
* - Cancelling the operation sets its metadata's cancel_time.
*
- The operation is guaranteed to succeed at undoing all changes, after which point it
* terminates with a `CANCELLED` status.
*
- All other attempts to modify the instance config are rejected.
*
- Reading the instance config via the API continues to give the pre-request values.
*
*
* Upon completion of the returned operation:
*
*
* - Creating instances using the instance configuration uses the new values.
*
- The instance config's new values are readable via the API.
*
- The instance config's {@code reconciling} field becomes false.
*
*
*
*
* {@code
* String projectId = "my-project";
* String instanceConfigId = "custom-user-config";
* String displayName = "my-display-name";
*
* InstanceConfigInfo instanceConfigInfo =
* InstanceConfigInfo.newBuilder(InstanceConfigId.of(projectId, instanceConfigId))
* .setDisplayName(displayName)
* .build();
*
* // Only update display name.
* final OperationFuture operation =
* instanceAdminClient.updateInstanceConfig(
* instanceConfigInfo, ImmutableList.of(InstanceConfigField.DISPLAY_NAME));
*
* InstanceConfig instanceConfig = operation.get(5, TimeUnit.MINUTES);
* }
*
*
*/
default OperationFuture updateInstanceConfig(
InstanceConfigInfo instanceConfig,
Iterable fieldsToUpdate,
UpdateAdminApiOption... options)
throws SpannerException {
throw new UnsupportedOperationException("Not implemented");
}
/** Gets an instance config. */
/*
* {@code
* final String configId = my_config_id;
* InstanceConfig instanceConfig = instanceAdminClient.getInstanceConfig(configId);
* }
*
*/
InstanceConfig getInstanceConfig(String configId) throws SpannerException;
/**
* Deletes a custom instance config. Deletion is only allowed for custom instance configs and when
* no instances are using the configuration. If any instances are using the config, a
* SpannerException is thrown.
*
* Only user managed configurations can be deleted.
*
*
*
{@code
* String projectId = "my-project";
* String instanceConfigId = "custom-user-config";
*
* instanceAdminClient.deleteInstanceConfig(instanceConfigId);
* }
*
*
*/
default void deleteInstanceConfig(String instanceConfigId, DeleteAdminApiOption... options)
throws SpannerException {
throw new UnsupportedOperationException("Not implemented");
}
/** Lists the supported instance configs for current project. */
/*
* {@code
* List configs =
* Lists.newArrayList(instanceAdminClient.listInstanceConfigs(Options.pageSize(1)).iterateAll());
* }
*
*/
Page listInstanceConfigs(ListOption... options) throws SpannerException;
/** Lists long-running instance config operations. */
default Page listInstanceConfigOperations(ListOption... options) {
throw new UnsupportedOperationException("Not implemented");
}
/**
* Creates an instance and begins preparing it to begin serving. The returned {@code Operation}
* can be used to track the progress of preparing the new instance. The instance name is assigned
* by the caller. If the named instance already exists, a SpannerException is thrown. Immediately
* upon completion of this request:
*
*
* - The instance is readable via the API, with all requested attributes but no allocated
* resources.
*
- Its state is {@code CREATING}.
*
*
* Until completion of the returned operation:
*
*
* - Cancelling the operation renders the instance immediately unreadable via the API.
*
- The instance can be deleted.
*
- All other attempts to modify the instance are rejected.
*
*
* Upon completion of the returned operation:
*
*
* - Billing for all successfully-allocated resources begins (some types may have lower than
* the requested levels).
*
- Databases can be created in the instance.
*
- The instance's allocated resource levels are readable via the
*
*
*
*
* {@code
* final String instanceId = my_instance_id;
* final String configId = my_config_id;
* final String clientProject = my_client_project;
*
* Operation op =
* instanceAdminClient.createInstance(InstanceInfo
* .newBuilder(InstanceId.of(clientProject, instanceId))
* .setInstanceConfigId(InstanceConfigId.of(clientProject, configId))
* .setDisplayName(instanceId)
* .setNodeCount(1)
* .build());
* op.waitFor();
* }
*
*
*/
OperationFuture createInstance(InstanceInfo instance)
throws SpannerException;
/** Gets an instance. */
/*
* {@code
* final String instanceId = my_instance_id;
* Instance ins = instanceAdminClient.getInstance(instanceId);
* }
*
*/
Instance getInstance(String instanceId) throws SpannerException;
/**
* Lists the instances.
*
* @param options Options to control the instances returned. It also supports {@link
* Options#filter(String)} option. The fields eligible for filtering are:
*
* - name
*
- display_name
*
- labels.key where key is the name of a label
*
*
* {@code
* List instances =
* Lists.newArrayList(
* instanceAdminClient.listInstances(Options.pageSize(1)).iterateAll());
* }
*
*/
Page listInstances(ListOption... options) throws SpannerException;
/** Deletes an instance. */
/*
* {@code
* final String instanceId = my_instance_id;
* instanceAdminClient.deleteInstance(instanceId);
* }
*
*/
void deleteInstance(String instanceId) throws SpannerException;
/**
* Updates an instance, and begins allocating or releasing resources as requested. The returned
* {@code Operation} can be used to track the progress of updating the instance. If the named
* instance does not exist, throws SpannerException.
*
* Immediately upon completion of this request:
*
*
* - For resource types for which a decrease in the instance's allocation has been requested,
* billing is based on the newly-requested level.
*
*
* Until completion of the returned operation:
*
*
* - Cancelling the operation sets its metadata's
* [cancel_time][UpdateInstanceMetadata.cancel_time], and begins restoring resources to
* their pre-request values. The operation is guaranteed to succeed at undoing all resource
* changes, after which point it terminates with a `CANCELLED` status.
*
- All other attempts to modify the instance are rejected.
*
- Reading the instance via the API continues to give the pre-request resource levels.
*
*
* Upon completion of the returned operation:
*
*
* - Billing begins for all successfully-allocated resources (some types may have lower than
* the requested levels).
*
- All newly-reserved resources are available for serving the instance's tables.
*
- The instance's new resource levels are readable via the API.
*
*
*
*
* {@code
* Instance instance = my_instance;
* final String clientProject = my_client_project;
* final String instanceId = my_instance_id;
*
* final String newDisplayName = my_display_name;
*
* InstanceInfo toUpdate =
* InstanceInfo.newBuilder(InstanceId.of(clientProject, instanceId))
* .setDisplayName(newDisplayName)
* .setNodeCount(instance.getNodeCount() + 1)
* .build();
* // Only update display name
* Operation op =
* instanceAdminClient.updateInstance(toUpdate, InstanceInfo.InstanceField.DISPLAY_NAME);
* op.waitFor().getResult();
* }
*
*
*/
OperationFuture updateInstance(
InstanceInfo instance, InstanceInfo.InstanceField... fieldsToUpdate);
/** Returns the IAM policy for the given instance. */
Policy getInstanceIAMPolicy(String instanceId);
/**
* Updates the IAM policy for the given instance and returns the resulting policy. It is highly
* recommended to first get the current policy and base the updated policy on the returned policy.
* See {@link Policy.Builder#setEtag(String)} for information on the recommended read-modify-write
* cycle.
*/
Policy setInstanceIAMPolicy(String instanceId, Policy policy);
/**
* Tests for the given permissions on the specified instance for the caller.
*
* @param instanceId the id of the instance to test.
* @param permissions the permissions to test for. Permissions with wildcards (such as '*',
* 'spanner.*', 'spanner.instances.*') are not allowed.
* @return the subset of the tested permissions that the caller is allowed.
*/
Iterable testInstanceIAMPermissions(String instanceId, Iterable permissions);
/** Returns a builder for {@code Instance} object with the given id. */
Instance.Builder newInstanceBuilder(InstanceId id);
/** Cancels the specified long-running operation. */
void cancelOperation(String name);
/** Gets the specified long-running operation. */
Operation getOperation(String name);
}