Class InstanceAdminClient

public class InstanceAdminClient implements BackgroundResource

Service Description: Cloud Spanner Instance Admin API

The Cloud Spanner Instance Admin API can be used to create, delete, modify and list instances. Instances are dedicated Cloud Spanner serving and storage resources to be used by Cloud Spanner databases.

Each instance has a "configuration", which dictates where the serving resources for the Cloud Spanner instance are located (e.g., US-central, Europe). Configurations are created by Google based on resource availability.

Cloud Spanner billing is based on the instances that exist and their sizes. After an instance exists, there are no additional per-database or per-operation charges for use of the instance (though there may be additional network bandwidth charges). Instances offer isolation: problems with databases in one instance will not affect other instances. However, within an instance databases can affect each other. For example, if one database in an instance receives a lot of requests and consumes most of the instance resources, fewer resources are available for other databases in that instance, and their performance may suffer.

This class provides the ability to make remote calls to the backing service through method calls that map to API methods. Sample code to get started:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   InstanceConfigName name = InstanceConfigName.of("[PROJECT]", "[INSTANCE_CONFIG]");
   InstanceConfig response = instanceAdminClient.getInstanceConfig(name);
 }

Note: close() needs to be called on the InstanceAdminClient object to clean up resources such as threads. In the example above, try-with-resources is used, which automatically calls close().

The surface of this class includes several types of Java methods for each of the API's methods:

A "flattened" method. With this type of method, the fields of the request type have been converted into function parameters. It may be the case that not all fields are available as parameters, and not every API method will have a flattened method entry point.
A "request object" method. This type of method only takes one parameter, a request object, which must be constructed before the call. Not every API method will have a request object method.
A "callable" method. This type of method takes no parameters and returns an immutable API callable object, which can be used to initiate calls to the service.

See the individual methods for example code.

Many parameters require resource names to be formatted in a particular way. To assist with these names, this class includes a format method for each type of name, and additionally a parse method to extract the individual identifiers contained within names that are returned.

This class can be customized by passing in a custom instance of InstanceAdminSettings to create(). For example:

To customize credentials:


 InstanceAdminSettings instanceAdminSettings =
     InstanceAdminSettings.newBuilder()
         .setCredentialsProvider(FixedCredentialsProvider.create(myCredentials))
         .build();
 InstanceAdminClient instanceAdminClient = InstanceAdminClient.create(instanceAdminSettings);

To customize the endpoint:


 InstanceAdminSettings instanceAdminSettings =
     InstanceAdminSettings.newBuilder().setEndpoint(myEndpoint).build();
 InstanceAdminClient instanceAdminClient = InstanceAdminClient.create(instanceAdminSettings);

Please refer to the GitHub repository's samples for more quickstart code snippets.

Inheritance

java.lang.Object > InstanceAdminClient

Implements

BackgroundResource

Inherited Members

Object.clone()

Object.equals(Object)

Object.finalize()

Object.getClass()

Object.hashCode()

Object.notify()

Object.notifyAll()

Object.toString()

Object.wait()

Object.wait(long)

Object.wait(long,int)

Static Methods

create()

public static final InstanceAdminClient create()

Constructs an instance of InstanceAdminClient with default settings.

Returns

Type	Description
InstanceAdminClient

Exceptions

Type	Description
IOException

create(InstanceAdminSettings settings)

public static final InstanceAdminClient create(InstanceAdminSettings settings)

Constructs an instance of InstanceAdminClient, using the given settings. The channels are created based on the settings passed in, or defaults for any settings that are not set.

Parameter

Name	Description
settings	`InstanceAdminSettings`

Returns

Type	Description
InstanceAdminClient

Exceptions

Type	Description
IOException

create(InstanceAdminStub stub)

public static final InstanceAdminClient create(InstanceAdminStub stub)

Constructs an instance of InstanceAdminClient, using the given stub for making calls. This is for advanced usage - prefer using create(InstanceAdminSettings).

Parameter

Name	Description
stub	`InstanceAdminStub`

Returns

Type	Description
InstanceAdminClient

Constructors

InstanceAdminClient(InstanceAdminSettings settings)

protected InstanceAdminClient(InstanceAdminSettings settings)

Constructs an instance of InstanceAdminClient, using the given settings. This is protected so that it is easy to make a subclass, but otherwise, the static factory methods should be preferred.

Parameter

Name	Description
settings	`InstanceAdminSettings`

InstanceAdminClient(InstanceAdminStub stub)

protected InstanceAdminClient(InstanceAdminStub stub)

Parameter

Name	Description
stub	`InstanceAdminStub`

Methods

awaitTermination(long duration, TimeUnit unit)

public boolean awaitTermination(long duration, TimeUnit unit)

Parameters

Name	Description
duration	`long`
unit	`TimeUnit`

Returns

Type	Description
boolean

Exceptions

Type	Description
InterruptedException

close()

public final void close()

createInstanceAsync(CreateInstanceRequest request)

public final OperationFuture<Instance,CreateInstanceMetadata> createInstanceAsync(CreateInstanceRequest request)

Creates an instance and begins preparing it to begin serving. The returned long-running 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, CreateInstance returns ALREADY_EXISTS.

Immediately upon completion of this request:

* The instance is readable via the API, with all requested attributes but no allocated resources. Its state is 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 API. * The instance's state becomes READY.

The returned long-running operation will have a name of the format <instance_name>/operations/<operation_id> and can be used to track creation of the instance. The metadata field type is CreateInstanceMetadata. The response field type is Instance, if successful.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   CreateInstanceRequest request =
       CreateInstanceRequest.newBuilder()
           .setParent(ProjectName.of("[PROJECT]").toString())
           .setInstanceId("instanceId902024336")
           .setInstance(Instance.newBuilder().build())
           .build();
   Instance response = instanceAdminClient.createInstanceAsync(request).get();
 }

Parameter

Name	Description
request	`CreateInstanceRequest` The request object containing all of the parameters for the API call.

Returns

Type	Description
OperationFuture<Instance,CreateInstanceMetadata>

createInstanceAsync(ProjectName parent, String instanceId, Instance instance)

public final OperationFuture<Instance,CreateInstanceMetadata> createInstanceAsync(ProjectName parent, String instanceId, Instance instance)

Immediately upon completion of this request:

* The instance is readable via the API, with all requested attributes but no allocated resources. Its state is 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:

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   ProjectName parent = ProjectName.of("[PROJECT]");
   String instanceId = "instanceId902024336";
   Instance instance = Instance.newBuilder().build();
   Instance response =
       instanceAdminClient.createInstanceAsync(parent, instanceId, instance).get();
 }

Parameters

Name	Description
parent	`ProjectName` Required. The name of the project in which to create the instance. Values are of the form `projects/<project>`.
instanceId	`String` Required. The ID of the instance to create. Valid identifiers are of the form `a-z*[a-z0-9]` and must be between 2 and 64 characters in length.
instance	`Instance` Required. The instance to create. The name may be omitted, but if specified must be `<parent>/instances/<instance_id>`.

Returns

Type	Description
OperationFuture<Instance,CreateInstanceMetadata>

createInstanceAsync(String parent, String instanceId, Instance instance)

public final OperationFuture<Instance,CreateInstanceMetadata> createInstanceAsync(String parent, String instanceId, Instance instance)

Immediately upon completion of this request:

* The instance is readable via the API, with all requested attributes but no allocated resources. Its state is 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:

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   String parent = ProjectName.of("[PROJECT]").toString();
   String instanceId = "instanceId902024336";
   Instance instance = Instance.newBuilder().build();
   Instance response =
       instanceAdminClient.createInstanceAsync(parent, instanceId, instance).get();
 }

Parameters

Name	Description
parent	`String` Required. The name of the project in which to create the instance. Values are of the form `projects/<project>`.
instanceId	`String` Required. The ID of the instance to create. Valid identifiers are of the form `a-z*[a-z0-9]` and must be between 2 and 64 characters in length.
instance	`Instance` Required. The instance to create. The name may be omitted, but if specified must be `<parent>/instances/<instance_id>`.

Returns

Type	Description
OperationFuture<Instance,CreateInstanceMetadata>

createInstanceCallable()

public final UnaryCallable<CreateInstanceRequest,Operation> createInstanceCallable()

Immediately upon completion of this request:

* The instance is readable via the API, with all requested attributes but no allocated resources. Its state is 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:

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   CreateInstanceRequest request =
       CreateInstanceRequest.newBuilder()
           .setParent(ProjectName.of("[PROJECT]").toString())
           .setInstanceId("instanceId902024336")
           .setInstance(Instance.newBuilder().build())
           .build();
   ApiFuture<Operation> future =
       instanceAdminClient.createInstanceCallable().futureCall(request);
   // Do something.
   Operation response = future.get();
 }

Returns

Type	Description
UnaryCallable<CreateInstanceRequest,Operation>

createInstanceOperationCallable()

public final OperationCallable<CreateInstanceRequest,Instance,CreateInstanceMetadata> createInstanceOperationCallable()

Immediately upon completion of this request:

* The instance is readable via the API, with all requested attributes but no allocated resources. Its state is 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:

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   CreateInstanceRequest request =
       CreateInstanceRequest.newBuilder()
           .setParent(ProjectName.of("[PROJECT]").toString())
           .setInstanceId("instanceId902024336")
           .setInstance(Instance.newBuilder().build())
           .build();
   OperationFuture<Instance, CreateInstanceMetadata> future =
       instanceAdminClient.createInstanceOperationCallable().futureCall(request);
   // Do something.
   Instance response = future.get();
 }

Returns

Type	Description
OperationCallable<CreateInstanceRequest,Instance,CreateInstanceMetadata>

deleteInstance(DeleteInstanceRequest request)

public final void deleteInstance(DeleteInstanceRequest request)

Deletes an instance.

Immediately upon completion of the request:

* Billing ceases for all of the instance's reserved resources.

Soon afterward:

* The instance and *all of its databases* immediately and irrevocably disappear from the API. All data in the databases is permanently deleted.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   DeleteInstanceRequest request =
       DeleteInstanceRequest.newBuilder()
           .setName(InstanceName.of("[PROJECT]", "[INSTANCE]").toString())
           .build();
   instanceAdminClient.deleteInstance(request);
 }

Parameter

Name	Description
request	`DeleteInstanceRequest` The request object containing all of the parameters for the API call.

deleteInstance(InstanceName name)

public final void deleteInstance(InstanceName name)

Deletes an instance.

Immediately upon completion of the request:

* Billing ceases for all of the instance's reserved resources.

Soon afterward:

* The instance and *all of its databases* immediately and irrevocably disappear from the API. All data in the databases is permanently deleted.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   InstanceName name = InstanceName.of("[PROJECT]", "[INSTANCE]");
   instanceAdminClient.deleteInstance(name);
 }

Parameter

Name	Description
name	`InstanceName` Required. The name of the instance to be deleted. Values are of the form `projects/<project>/instances/<instance>`

deleteInstance(String name)

public final void deleteInstance(String name)

Deletes an instance.

Immediately upon completion of the request:

* Billing ceases for all of the instance's reserved resources.

Soon afterward:

* The instance and *all of its databases* immediately and irrevocably disappear from the API. All data in the databases is permanently deleted.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   String name = InstanceName.of("[PROJECT]", "[INSTANCE]").toString();
   instanceAdminClient.deleteInstance(name);
 }

Parameter

Name	Description
name	`String` Required. The name of the instance to be deleted. Values are of the form `projects/<project>/instances/<instance>`

deleteInstanceCallable()

public final UnaryCallable<DeleteInstanceRequest,Empty> deleteInstanceCallable()

Deletes an instance.

Immediately upon completion of the request:

* Billing ceases for all of the instance's reserved resources.

Soon afterward:

* The instance and *all of its databases* immediately and irrevocably disappear from the API. All data in the databases is permanently deleted.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   DeleteInstanceRequest request =
       DeleteInstanceRequest.newBuilder()
           .setName(InstanceName.of("[PROJECT]", "[INSTANCE]").toString())
           .build();
   ApiFuture<Empty> future = instanceAdminClient.deleteInstanceCallable().futureCall(request);
   // Do something.
   future.get();
 }

Returns

Type	Description
UnaryCallable<DeleteInstanceRequest,Empty>

getIamPolicy(ResourceName resource)

public final Policy getIamPolicy(ResourceName resource)

Gets the access control policy for an instance resource. Returns an empty policy if an instance exists but does not have a policy set.

Authorization requires spanner.instances.getIamPolicy on resource.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   ResourceName resource = ProjectName.of("[PROJECT]");
   Policy response = instanceAdminClient.getIamPolicy(resource);
 }

Parameter

Name	Description
resource	`com.google.api.resourcenames.ResourceName` REQUIRED: The resource for which the policy is being requested. See the operation documentation for the appropriate value for this field.

Returns

Type	Description
com.google.iam.v1.Policy

getIamPolicy(GetIamPolicyRequest request)

public final Policy getIamPolicy(GetIamPolicyRequest request)

Gets the access control policy for an instance resource. Returns an empty policy if an instance exists but does not have a policy set.

Authorization requires spanner.instances.getIamPolicy on resource.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   GetIamPolicyRequest request =
       GetIamPolicyRequest.newBuilder()
           .setResource(ProjectName.of("[PROJECT]").toString())
           .setOptions(GetPolicyOptions.newBuilder().build())
           .build();
   Policy response = instanceAdminClient.getIamPolicy(request);
 }

Parameter

Name	Description
request	`com.google.iam.v1.GetIamPolicyRequest` The request object containing all of the parameters for the API call.

Returns

Type	Description
com.google.iam.v1.Policy

getIamPolicy(String resource)

public final Policy getIamPolicy(String resource)

Gets the access control policy for an instance resource. Returns an empty policy if an instance exists but does not have a policy set.

Authorization requires spanner.instances.getIamPolicy on resource.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   String resource = ProjectName.of("[PROJECT]").toString();
   Policy response = instanceAdminClient.getIamPolicy(resource);
 }

Parameter

Name	Description
resource	`String` REQUIRED: The resource for which the policy is being requested. See the operation documentation for the appropriate value for this field.

Returns

Type	Description
com.google.iam.v1.Policy

getIamPolicyCallable()

public final UnaryCallable<GetIamPolicyRequest,Policy> getIamPolicyCallable()

Gets the access control policy for an instance resource. Returns an empty policy if an instance exists but does not have a policy set.

Authorization requires spanner.instances.getIamPolicy on resource.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   GetIamPolicyRequest request =
       GetIamPolicyRequest.newBuilder()
           .setResource(ProjectName.of("[PROJECT]").toString())
           .setOptions(GetPolicyOptions.newBuilder().build())
           .build();
   ApiFuture<Policy> future = instanceAdminClient.getIamPolicyCallable().futureCall(request);
   // Do something.
   Policy response = future.get();
 }

Returns

Type	Description
UnaryCallable<com.google.iam.v1.GetIamPolicyRequest,com.google.iam.v1.Policy>

getInstance(GetInstanceRequest request)

public final Instance getInstance(GetInstanceRequest request)

Gets information about a particular instance.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   GetInstanceRequest request =
       GetInstanceRequest.newBuilder()
           .setName(InstanceName.of("[PROJECT]", "[INSTANCE]").toString())
           .setFieldMask(FieldMask.newBuilder().build())
           .build();
   Instance response = instanceAdminClient.getInstance(request);
 }

Parameter

Name	Description
request	`GetInstanceRequest` The request object containing all of the parameters for the API call.

Returns

Type	Description
Instance

getInstance(InstanceName name)

public final Instance getInstance(InstanceName name)

Gets information about a particular instance.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   InstanceName name = InstanceName.of("[PROJECT]", "[INSTANCE]");
   Instance response = instanceAdminClient.getInstance(name);
 }

Parameter

Name	Description
name	`InstanceName` Required. The name of the requested instance. Values are of the form `projects/<project>/instances/<instance>`.

Returns

Type	Description
Instance

getInstance(String name)

public final Instance getInstance(String name)

Gets information about a particular instance.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   String name = InstanceName.of("[PROJECT]", "[INSTANCE]").toString();
   Instance response = instanceAdminClient.getInstance(name);
 }

Parameter

Name	Description
name	`String` Required. The name of the requested instance. Values are of the form `projects/<project>/instances/<instance>`.

Returns

Type	Description
Instance

getInstanceCallable()

public final UnaryCallable<GetInstanceRequest,Instance> getInstanceCallable()

Gets information about a particular instance.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   GetInstanceRequest request =
       GetInstanceRequest.newBuilder()
           .setName(InstanceName.of("[PROJECT]", "[INSTANCE]").toString())
           .setFieldMask(FieldMask.newBuilder().build())
           .build();
   ApiFuture<Instance> future = instanceAdminClient.getInstanceCallable().futureCall(request);
   // Do something.
   Instance response = future.get();
 }

Returns

Type	Description
UnaryCallable<GetInstanceRequest,Instance>

getInstanceConfig(GetInstanceConfigRequest request)

public final InstanceConfig getInstanceConfig(GetInstanceConfigRequest request)

Gets information about a particular instance configuration.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   GetInstanceConfigRequest request =
       GetInstanceConfigRequest.newBuilder()
           .setName(InstanceConfigName.of("[PROJECT]", "[INSTANCE_CONFIG]").toString())
           .build();
   InstanceConfig response = instanceAdminClient.getInstanceConfig(request);
 }

Parameter

Name	Description
request	`GetInstanceConfigRequest` The request object containing all of the parameters for the API call.

Returns

Type	Description
InstanceConfig

getInstanceConfig(InstanceConfigName name)

public final InstanceConfig getInstanceConfig(InstanceConfigName name)

Gets information about a particular instance configuration.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   InstanceConfigName name = InstanceConfigName.of("[PROJECT]", "[INSTANCE_CONFIG]");
   InstanceConfig response = instanceAdminClient.getInstanceConfig(name);
 }

Parameter

Name	Description
name	`InstanceConfigName` Required. The name of the requested instance configuration. Values are of the form `projects/<project>/instanceConfigs/<config>`.

Returns

Type	Description
InstanceConfig

getInstanceConfig(String name)

public final InstanceConfig getInstanceConfig(String name)

Gets information about a particular instance configuration.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   String name = InstanceConfigName.of("[PROJECT]", "[INSTANCE_CONFIG]").toString();
   InstanceConfig response = instanceAdminClient.getInstanceConfig(name);
 }

Parameter

Name	Description
name	`String` Required. The name of the requested instance configuration. Values are of the form `projects/<project>/instanceConfigs/<config>`.

Returns

Type	Description
InstanceConfig

getInstanceConfigCallable()

public final UnaryCallable<GetInstanceConfigRequest,InstanceConfig> getInstanceConfigCallable()

Gets information about a particular instance configuration.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   GetInstanceConfigRequest request =
       GetInstanceConfigRequest.newBuilder()
           .setName(InstanceConfigName.of("[PROJECT]", "[INSTANCE_CONFIG]").toString())
           .build();
   ApiFuture<InstanceConfig> future =
       instanceAdminClient.getInstanceConfigCallable().futureCall(request);
   // Do something.
   InstanceConfig response = future.get();
 }

Returns

Type	Description
UnaryCallable<GetInstanceConfigRequest,InstanceConfig>

getOperationsClient()

public final OperationsClient getOperationsClient()

Returns the OperationsClient that can be used to query the status of a long-running operation returned by another API method call.

Returns

Type	Description
OperationsClient

getSettings()

public final InstanceAdminSettings getSettings()

Returns

Type	Description
InstanceAdminSettings

getStub()

public InstanceAdminStub getStub()

Returns

Type	Description
InstanceAdminStub

isShutdown()

public boolean isShutdown()

Returns

Type	Description
boolean

isTerminated()

public boolean isTerminated()

Returns

Type	Description
boolean

listInstanceConfigs(ListInstanceConfigsRequest request)

public final InstanceAdminClient.ListInstanceConfigsPagedResponse listInstanceConfigs(ListInstanceConfigsRequest request)

Lists the supported instance configurations for a given project.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   ListInstanceConfigsRequest request =
       ListInstanceConfigsRequest.newBuilder()
           .setParent(ProjectName.of("[PROJECT]").toString())
           .setPageSize(883849137)
           .setPageToken("pageToken873572522")
           .build();
   for (InstanceConfig element : instanceAdminClient.listInstanceConfigs(request).iterateAll()) {
     // doThingsWith(element);
   }
 }

Parameter

Name	Description
request	`ListInstanceConfigsRequest` The request object containing all of the parameters for the API call.

Returns

Type	Description
InstanceAdminClient.ListInstanceConfigsPagedResponse

listInstanceConfigs(ProjectName parent)

public final InstanceAdminClient.ListInstanceConfigsPagedResponse listInstanceConfigs(ProjectName parent)

Lists the supported instance configurations for a given project.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   ProjectName parent = ProjectName.of("[PROJECT]");
   for (InstanceConfig element : instanceAdminClient.listInstanceConfigs(parent).iterateAll()) {
     // doThingsWith(element);
   }
 }

Parameter

Name	Description
parent	`ProjectName` Required. The name of the project for which a list of supported instance configurations is requested. Values are of the form `projects/<project>`.

Returns

Type	Description
InstanceAdminClient.ListInstanceConfigsPagedResponse

listInstanceConfigs(String parent)

public final InstanceAdminClient.ListInstanceConfigsPagedResponse listInstanceConfigs(String parent)

Lists the supported instance configurations for a given project.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   String parent = ProjectName.of("[PROJECT]").toString();
   for (InstanceConfig element : instanceAdminClient.listInstanceConfigs(parent).iterateAll()) {
     // doThingsWith(element);
   }
 }

Parameter

Name	Description
parent	`String` Required. The name of the project for which a list of supported instance configurations is requested. Values are of the form `projects/<project>`.

Returns

Type	Description
InstanceAdminClient.ListInstanceConfigsPagedResponse

listInstanceConfigsCallable()

public final UnaryCallable<ListInstanceConfigsRequest,ListInstanceConfigsResponse> listInstanceConfigsCallable()

Lists the supported instance configurations for a given project.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   ListInstanceConfigsRequest request =
       ListInstanceConfigsRequest.newBuilder()
           .setParent(ProjectName.of("[PROJECT]").toString())
           .setPageSize(883849137)
           .setPageToken("pageToken873572522")
           .build();
   while (true) {
     ListInstanceConfigsResponse response =
         instanceAdminClient.listInstanceConfigsCallable().call(request);
     for (InstanceConfig element : response.getResponsesList()) {
       // doThingsWith(element);
     }
     String nextPageToken = response.getNextPageToken();
     if (!Strings.isNullOrEmpty(nextPageToken)) {
       request = request.toBuilder().setPageToken(nextPageToken).build();
     } else {
       break;
     }
   }
 }

Returns

Type	Description
UnaryCallable<ListInstanceConfigsRequest,ListInstanceConfigsResponse>

listInstanceConfigsPagedCallable()

public final UnaryCallable<ListInstanceConfigsRequest,InstanceAdminClient.ListInstanceConfigsPagedResponse> listInstanceConfigsPagedCallable()

Lists the supported instance configurations for a given project.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   ListInstanceConfigsRequest request =
       ListInstanceConfigsRequest.newBuilder()
           .setParent(ProjectName.of("[PROJECT]").toString())
           .setPageSize(883849137)
           .setPageToken("pageToken873572522")
           .build();
   ApiFuture<InstanceConfig> future =
       instanceAdminClient.listInstanceConfigsPagedCallable().futureCall(request);
   // Do something.
   for (InstanceConfig element : future.get().iterateAll()) {
     // doThingsWith(element);
   }
 }

Returns

Type	Description
UnaryCallable<ListInstanceConfigsRequest,ListInstanceConfigsPagedResponse>

listInstances(ListInstancesRequest request)

public final InstanceAdminClient.ListInstancesPagedResponse listInstances(ListInstancesRequest request)

Lists all instances in the given project.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   ListInstancesRequest request =
       ListInstancesRequest.newBuilder()
           .setParent(ProjectName.of("[PROJECT]").toString())
           .setPageSize(883849137)
           .setPageToken("pageToken873572522")
           .setFilter("filter-1274492040")
           .build();
   for (Instance element : instanceAdminClient.listInstances(request).iterateAll()) {
     // doThingsWith(element);
   }
 }

Parameter

Name	Description
request	`ListInstancesRequest` The request object containing all of the parameters for the API call.

Returns

Type	Description
InstanceAdminClient.ListInstancesPagedResponse

listInstances(ProjectName parent)

public final InstanceAdminClient.ListInstancesPagedResponse listInstances(ProjectName parent)

Lists all instances in the given project.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   ProjectName parent = ProjectName.of("[PROJECT]");
   for (Instance element : instanceAdminClient.listInstances(parent).iterateAll()) {
     // doThingsWith(element);
   }
 }

Parameter

Name	Description
parent	`ProjectName` Required. The name of the project for which a list of instances is requested. Values are of the form `projects/<project>`.

Returns

Type	Description
InstanceAdminClient.ListInstancesPagedResponse

listInstances(String parent)

public final InstanceAdminClient.ListInstancesPagedResponse listInstances(String parent)

Lists all instances in the given project.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   String parent = ProjectName.of("[PROJECT]").toString();
   for (Instance element : instanceAdminClient.listInstances(parent).iterateAll()) {
     // doThingsWith(element);
   }
 }

Parameter

Name	Description
parent	`String` Required. The name of the project for which a list of instances is requested. Values are of the form `projects/<project>`.

Returns

Type	Description
InstanceAdminClient.ListInstancesPagedResponse

listInstancesCallable()

public final UnaryCallable<ListInstancesRequest,ListInstancesResponse> listInstancesCallable()

Lists all instances in the given project.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   ListInstancesRequest request =
       ListInstancesRequest.newBuilder()
           .setParent(ProjectName.of("[PROJECT]").toString())
           .setPageSize(883849137)
           .setPageToken("pageToken873572522")
           .setFilter("filter-1274492040")
           .build();
   while (true) {
     ListInstancesResponse response = instanceAdminClient.listInstancesCallable().call(request);
     for (Instance element : response.getResponsesList()) {
       // doThingsWith(element);
     }
     String nextPageToken = response.getNextPageToken();
     if (!Strings.isNullOrEmpty(nextPageToken)) {
       request = request.toBuilder().setPageToken(nextPageToken).build();
     } else {
       break;
     }
   }
 }

Returns

Type	Description
UnaryCallable<ListInstancesRequest,ListInstancesResponse>

listInstancesPagedCallable()

public final UnaryCallable<ListInstancesRequest,InstanceAdminClient.ListInstancesPagedResponse> listInstancesPagedCallable()

Lists all instances in the given project.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   ListInstancesRequest request =
       ListInstancesRequest.newBuilder()
           .setParent(ProjectName.of("[PROJECT]").toString())
           .setPageSize(883849137)
           .setPageToken("pageToken873572522")
           .setFilter("filter-1274492040")
           .build();
   ApiFuture<Instance> future =
       instanceAdminClient.listInstancesPagedCallable().futureCall(request);
   // Do something.
   for (Instance element : future.get().iterateAll()) {
     // doThingsWith(element);
   }
 }

Returns

Type	Description
UnaryCallable<ListInstancesRequest,ListInstancesPagedResponse>

setIamPolicy(ResourceName resource, Policy policy)

public final Policy setIamPolicy(ResourceName resource, Policy policy)

Sets the access control policy on an instance resource. Replaces any existing policy.

Authorization requires spanner.instances.setIamPolicy on resource.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   ResourceName resource = ProjectName.of("[PROJECT]");
   Policy policy = Policy.newBuilder().build();
   Policy response = instanceAdminClient.setIamPolicy(resource, policy);
 }

Parameters

Name	Description
resource	`com.google.api.resourcenames.ResourceName` REQUIRED: The resource for which the policy is being specified. See the operation documentation for the appropriate value for this field.
policy	`com.google.iam.v1.Policy` REQUIRED: The complete policy to be applied to the `resource`. The size of the policy is limited to a few 10s of KB. An empty policy is a valid policy but certain Cloud Platform services (such as Projects) might reject them.

Returns

Type	Description
com.google.iam.v1.Policy

setIamPolicy(SetIamPolicyRequest request)

public final Policy setIamPolicy(SetIamPolicyRequest request)

Sets the access control policy on an instance resource. Replaces any existing policy.

Authorization requires spanner.instances.setIamPolicy on resource.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   SetIamPolicyRequest request =
       SetIamPolicyRequest.newBuilder()
           .setResource(ProjectName.of("[PROJECT]").toString())
           .setPolicy(Policy.newBuilder().build())
           .build();
   Policy response = instanceAdminClient.setIamPolicy(request);
 }

Parameter

Name	Description
request	`com.google.iam.v1.SetIamPolicyRequest` The request object containing all of the parameters for the API call.

Returns

Type	Description
com.google.iam.v1.Policy

setIamPolicy(String resource, Policy policy)

public final Policy setIamPolicy(String resource, Policy policy)

Sets the access control policy on an instance resource. Replaces any existing policy.

Authorization requires spanner.instances.setIamPolicy on resource.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   String resource = ProjectName.of("[PROJECT]").toString();
   Policy policy = Policy.newBuilder().build();
   Policy response = instanceAdminClient.setIamPolicy(resource, policy);
 }

Parameters

Name	Description
resource	`String` REQUIRED: The resource for which the policy is being specified. See the operation documentation for the appropriate value for this field.
policy	`com.google.iam.v1.Policy` REQUIRED: The complete policy to be applied to the `resource`. The size of the policy is limited to a few 10s of KB. An empty policy is a valid policy but certain Cloud Platform services (such as Projects) might reject them.

Returns

Type	Description
com.google.iam.v1.Policy

setIamPolicyCallable()

public final UnaryCallable<SetIamPolicyRequest,Policy> setIamPolicyCallable()

Sets the access control policy on an instance resource. Replaces any existing policy.

Authorization requires spanner.instances.setIamPolicy on resource.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   SetIamPolicyRequest request =
       SetIamPolicyRequest.newBuilder()
           .setResource(ProjectName.of("[PROJECT]").toString())
           .setPolicy(Policy.newBuilder().build())
           .build();
   ApiFuture<Policy> future = instanceAdminClient.setIamPolicyCallable().futureCall(request);
   // Do something.
   Policy response = future.get();
 }

Returns

Type	Description
UnaryCallable<com.google.iam.v1.SetIamPolicyRequest,com.google.iam.v1.Policy>

shutdown()

public void shutdown()

shutdownNow()

public void shutdownNow()

testIamPermissions(ResourceName resource, List<String> permissions)

public final TestIamPermissionsResponse testIamPermissions(ResourceName resource, List<String> permissions)

Returns permissions that the caller has on the specified instance resource.

Attempting this RPC on a non-existent Cloud Spanner instance resource will result in a NOT_FOUND error if the user has spanner.instances.list permission on the containing Google Cloud Project. Otherwise returns an empty set of permissions.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   ResourceName resource = ProjectName.of("[PROJECT]");
   List<String> permissions = new ArrayList<>();
   TestIamPermissionsResponse response =
       instanceAdminClient.testIamPermissions(resource, permissions);
 }

Parameters

Name	Description
resource	`com.google.api.resourcenames.ResourceName` REQUIRED: The resource for which the policy detail is being requested. See the operation documentation for the appropriate value for this field.
permissions	`List<String>` The set of permissions to check for the `resource`. Permissions with wildcards (such as '' or 'storage.') are not allowed. For more information see IAM Overview.

Returns

Type	Description
com.google.iam.v1.TestIamPermissionsResponse

testIamPermissions(TestIamPermissionsRequest request)

public final TestIamPermissionsResponse testIamPermissions(TestIamPermissionsRequest request)

Returns permissions that the caller has on the specified instance resource.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   TestIamPermissionsRequest request =
       TestIamPermissionsRequest.newBuilder()
           .setResource(ProjectName.of("[PROJECT]").toString())
           .addAllPermissions(new ArrayList<String>())
           .build();
   TestIamPermissionsResponse response = instanceAdminClient.testIamPermissions(request);
 }

Parameter

Name	Description
request	`com.google.iam.v1.TestIamPermissionsRequest` The request object containing all of the parameters for the API call.

Returns

Type	Description
com.google.iam.v1.TestIamPermissionsResponse

testIamPermissions(String resource, List<String> permissions)

public final TestIamPermissionsResponse testIamPermissions(String resource, List<String> permissions)

Returns permissions that the caller has on the specified instance resource.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   String resource = ProjectName.of("[PROJECT]").toString();
   List<String> permissions = new ArrayList<>();
   TestIamPermissionsResponse response =
       instanceAdminClient.testIamPermissions(resource, permissions);
 }

Parameters

Name	Description
resource	`String` REQUIRED: The resource for which the policy detail is being requested. See the operation documentation for the appropriate value for this field.
permissions	`List<String>` The set of permissions to check for the `resource`. Permissions with wildcards (such as '' or 'storage.') are not allowed. For more information see IAM Overview.

Returns

Type	Description
com.google.iam.v1.TestIamPermissionsResponse

testIamPermissionsCallable()

public final UnaryCallable<TestIamPermissionsRequest,TestIamPermissionsResponse> testIamPermissionsCallable()

Returns permissions that the caller has on the specified instance resource.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   TestIamPermissionsRequest request =
       TestIamPermissionsRequest.newBuilder()
           .setResource(ProjectName.of("[PROJECT]").toString())
           .addAllPermissions(new ArrayList<String>())
           .build();
   ApiFuture<TestIamPermissionsResponse> future =
       instanceAdminClient.testIamPermissionsCallable().futureCall(request);
   // Do something.
   TestIamPermissionsResponse response = future.get();
 }

Returns

Type	Description
UnaryCallable<com.google.iam.v1.TestIamPermissionsRequest,com.google.iam.v1.TestIamPermissionsResponse>

updateInstanceAsync(Instance instance, FieldMask fieldMask)

public final OperationFuture<Instance,UpdateInstanceMetadata> updateInstanceAsync(Instance instance, FieldMask fieldMask)

Updates an instance, and begins allocating or releasing resources as requested. The returned long-running operation can be used to track the progress of updating the instance. If the named instance does not exist, returns NOT_FOUND.

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, 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.

The returned long-running operation will have a name of the format <instance_name>/operations/<operation_id> and can be used to track the instance modification. The metadata field type is UpdateInstanceMetadata. The response field type is Instance, if successful.

Authorization requires spanner.instances.update permission on resource name.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   Instance instance = Instance.newBuilder().build();
   FieldMask fieldMask = FieldMask.newBuilder().build();
   Instance response = instanceAdminClient.updateInstanceAsync(instance, fieldMask).get();
 }

Parameters

Name	Description
instance	`Instance` Required. The instance to update, which must always include the instance name. Otherwise, only fields mentioned in field_mask need be included.
fieldMask	`FieldMask` Required. A mask specifying which fields in Instance should be updated. The field mask must always be specified; this prevents any future fields in Instance from being erased accidentally by clients that do not know about them.

Returns

Type	Description
OperationFuture<Instance,UpdateInstanceMetadata>

updateInstanceAsync(UpdateInstanceRequest request)

public final OperationFuture<Instance,UpdateInstanceMetadata> updateInstanceAsync(UpdateInstanceRequest request)

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:

Upon completion of the returned operation:

Authorization requires spanner.instances.update permission on resource name.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   UpdateInstanceRequest request =
       UpdateInstanceRequest.newBuilder()
           .setInstance(Instance.newBuilder().build())
           .setFieldMask(FieldMask.newBuilder().build())
           .build();
   Instance response = instanceAdminClient.updateInstanceAsync(request).get();
 }

Parameter

Name	Description
request	`UpdateInstanceRequest` The request object containing all of the parameters for the API call.

Returns

Type	Description
OperationFuture<Instance,UpdateInstanceMetadata>

updateInstanceCallable()

public final UnaryCallable<UpdateInstanceRequest,Operation> updateInstanceCallable()

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:

Upon completion of the returned operation:

Authorization requires spanner.instances.update permission on resource name.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   UpdateInstanceRequest request =
       UpdateInstanceRequest.newBuilder()
           .setInstance(Instance.newBuilder().build())
           .setFieldMask(FieldMask.newBuilder().build())
           .build();
   ApiFuture<Operation> future =
       instanceAdminClient.updateInstanceCallable().futureCall(request);
   // Do something.
   Operation response = future.get();
 }

Returns

Type	Description
UnaryCallable<UpdateInstanceRequest,Operation>

updateInstanceOperationCallable()

public final OperationCallable<UpdateInstanceRequest,Instance,UpdateInstanceMetadata> updateInstanceOperationCallable()

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:

Upon completion of the returned operation:

Authorization requires spanner.instances.update permission on resource name.

Sample code:


 try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
   UpdateInstanceRequest request =
       UpdateInstanceRequest.newBuilder()
           .setInstance(Instance.newBuilder().build())
           .setFieldMask(FieldMask.newBuilder().build())
           .build();
   OperationFuture<Instance, UpdateInstanceMetadata> future =
       instanceAdminClient.updateInstanceOperationCallable().futureCall(request);
   // Do something.
   Instance response = future.get();
 }

Returns

Type	Description
OperationCallable<UpdateInstanceRequest,Instance,UpdateInstanceMetadata>