This method returns an instance of com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient. That interface implements AutoCloseable. That again means that most users will be inclined to put it in a try-with-resources block, or in some other way close it when they are done. If they do that, then the underlying stub that is used by the client will be closed, which again is a shared object, and means that all existing and also future instances that will be returned by this method will use a closed stub.

So we need to make a choice here whether:

1. We document that users should never call close() on the instance that is returned.
2. OR: Create a new stub for each new instance that is returned by this method.
3. OR: Create/use a small wrapper object around the instance that we are returning here that overrides the default close() behavior. The modified behavior could either be to do nothing, or to throw an exception that indicates that this instance is managed by the Spanner instance that created it.

I think that option 3 is the safest option.

Thanks for the catch!

Thinking a bit more on the issue, I think its due to the dependency on the stub making it a shared resource when it should not have been one. Another approach which I explored was to make use of the shared DatabaseAdminStubSettings and InstanceAdminStubSettings objects and creating a new stub objects from these settings by doing something like gapicRpc.getDatabaseAdminStubSettings().createStub() . This will ensure we avoid the coupling and at the same time are able to re-use all the code of GapicSpannerRpc for creating the settings.

Based on offline conversations, we found an additional issue. For ex - refer the below snippet where we would still up see the shared stub behavior.

void doSomeAdminStuff() {
  try (DatabaseAdminClient client = spanner.databaseAdminClient()) {
    client.listDatabases();
    doSomethingElse();
    client.dropDatabase(...);
  }
}

void doSomethingElse() {
  try (DatabaseAdminClient client = spanner.databaseAdminClient()) {
    client.updateDatabase(...);
  }
}

I explored two other approaches based on @olavloite 's suggestion

1. Creating a ManagedDatabaseAdminClient which extends the DatabaseAdminClient class and overrides the close() method. This is not possible to implement since the method is marked as final and hence we cannot override it.
2. Using dynamic proxy classes (reference - https://www.baeldung.com/java-dynamic-proxies#invocation-handler-via-lambda-expressions ). This is not possible since dynamic proxies only work for classes that implement some interface and in this case DatabaseAdminClient does not implement any interface that can supply all its methods.

We are settling for an approach where we return a new instance each time a client object is requested. This makes sure we don't run into any edge cases (like discussed above). At the same time, we have captured in the method documentation that customers may choose to cache the instances based on their application side code.