Skip to content

Commit 71733ab

Browse files
igorbernstein2igorbernstein2
authored
Bigtable: clean up the public surface (#5034)
* Bigtable: clean up the public surface * Exclude autogenerated files that aren't used * Internal implementation details are now package private * Internal implementation details that are needed by other pacakges are now @internalapi (ie. pagination wrappers in Client) * package-info.java not document the public surface instead of the autogen one * EnhancedBigtableStubSetting are now public api * synth.py is responsible for the transformations * exclude gradle build files * fix whitespace * Fix tests by making things InternalApi instead of package-private. Mockito can't mock classes which have package-private parents * add todo to simplify synth.py * Add tests to make sure that the gapic api is @InternalOnly * Keep @autogenerated annotations
1 parent af0334b commit 71733ab

31 files changed

Lines changed: 328 additions & 1905 deletions

‎google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/BaseBigtableInstanceAdminClient.java‎

Lines changed: 3 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
import com.google.api.core.ApiFuture;
2020
import com.google.api.core.ApiFutures;
2121
import com.google.api.core.BetaApi;
22+
import com.google.api.core.InternalApi;
2223
import com.google.api.gax.core.BackgroundResource;
2324
import com.google.api.gax.longrunning.OperationFuture;
2425
import com.google.api.gax.paging.AbstractFixedSizeCollection;
@@ -75,76 +76,9 @@
7576
import javax.annotation.Generated;
7677

7778
// AUTO-GENERATED DOCUMENTATION AND SERVICE
78-
/**
79-
* Service Description: Service for creating, configuring, and deleting Cloud Bigtable Instances and
80-
* Clusters. Provides access to the Instance and Cluster schemas only, not the tables' metadata or
81-
* data stored in those tables.
82-
*
83-
* <p>This class provides the ability to make remote calls to the backing service through method
84-
* calls that map to API methods. Sample code to get started:
85-
*
86-
* <pre>
87-
* <code>
88-
* try (BaseBigtableInstanceAdminClient baseBigtableInstanceAdminClient = BaseBigtableInstanceAdminClient.create()) {
89-
* InstanceName name = InstanceName.of("[PROJECT]", "[INSTANCE]");
90-
* Instance response = baseBigtableInstanceAdminClient.getInstance(name);
91-
* }
92-
* </code>
93-
* </pre>
94-
*
95-
* <p>Note: close() needs to be called on the baseBigtableInstanceAdminClient object to clean up
96-
* resources such as threads. In the example above, try-with-resources is used, which automatically
97-
* calls close().
98-
*
99-
* <p>The surface of this class includes several types of Java methods for each of the API's
100-
* methods:
101-
*
102-
* <ol>
103-
* <li>A "flattened" method. With this type of method, the fields of the request type have been
104-
* converted into function parameters. It may be the case that not all fields are available as
105-
* parameters, and not every API method will have a flattened method entry point.
106-
* <li>A "request object" method. This type of method only takes one parameter, a request object,
107-
* which must be constructed before the call. Not every API method will have a request object
108-
* method.
109-
* <li>A "callable" method. This type of method takes no parameters and returns an immutable API
110-
* callable object, which can be used to initiate calls to the service.
111-
* </ol>
112-
*
113-
* <p>See the individual methods for example code.
114-
*
115-
* <p>Many parameters require resource names to be formatted in a particular way. To assist with
116-
* these names, this class includes a format method for each type of name, and additionally a parse
117-
* method to extract the individual identifiers contained within names that are returned.
118-
*
119-
* <p>This class can be customized by passing in a custom instance of
120-
* BaseBigtableInstanceAdminSettings to create(). For example:
121-
*
122-
* <p>To customize credentials:
123-
*
124-
* <pre>
125-
* <code>
126-
* BaseBigtableInstanceAdminSettings baseBigtableInstanceAdminSettings =
127-
* BaseBigtableInstanceAdminSettings.newBuilder()
128-
* .setCredentialsProvider(FixedCredentialsProvider.create(myCredentials))
129-
* .build();
130-
* BaseBigtableInstanceAdminClient baseBigtableInstanceAdminClient =
131-
* BaseBigtableInstanceAdminClient.create(baseBigtableInstanceAdminSettings);
132-
* </code>
133-
* </pre>
134-
*
135-
* To customize the endpoint:
136-
*
137-
* <pre>
138-
* <code>
139-
* BaseBigtableInstanceAdminSettings baseBigtableInstanceAdminSettings =
140-
* BaseBigtableInstanceAdminSettings.newBuilder().setEndpoint(myEndpoint).build();
141-
* BaseBigtableInstanceAdminClient baseBigtableInstanceAdminClient =
142-
* BaseBigtableInstanceAdminClient.create(baseBigtableInstanceAdminSettings);
143-
* </code>
144-
* </pre>
145-
*/
79+
/** For internal use only. */
14680
@Generated("by gapic-generator")
147-
@BetaApi
81+
@InternalApi
14882
public class BaseBigtableInstanceAdminClient implements BackgroundResource {
14983
private final BaseBigtableInstanceAdminSettings settings;
15084
private final BigtableInstanceAdminStub stub;

‎google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/BaseBigtableInstanceAdminSettings.java‎

Lines changed: 3 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919

2020
import com.google.api.core.ApiFunction;
2121
import com.google.api.core.BetaApi;
22+
import com.google.api.core.InternalApi;
2223
import com.google.api.gax.core.GoogleCredentialsProvider;
2324
import com.google.api.gax.core.InstantiatingExecutorProvider;
2425
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
@@ -67,33 +68,9 @@
6768
import javax.annotation.Generated;
6869

6970
// AUTO-GENERATED DOCUMENTATION AND CLASS
70-
/**
71-
* Settings class to configure an instance of {@link BaseBigtableInstanceAdminClient}.
72-
*
73-
* <p>The default instance has everything set to sensible defaults:
74-
*
75-
* <ul>
76-
* <li>The default service address (bigtableadmin.googleapis.com) and default port (443) are used.
77-
* <li>Credentials are acquired automatically through Application Default Credentials.
78-
* <li>Retries are configured for idempotent methods but not for non-idempotent methods.
79-
* </ul>
80-
*
81-
* <p>The builder of this class is recursive, so contained classes are themselves builders. When
82-
* build() is called, the tree of builders is called to create the complete settings object. For
83-
* example, to set the total timeout of getInstance to 30 seconds:
84-
*
85-
* <pre>
86-
* <code>
87-
* BaseBigtableInstanceAdminSettings.Builder baseBigtableInstanceAdminSettingsBuilder =
88-
* BaseBigtableInstanceAdminSettings.newBuilder();
89-
* baseBigtableInstanceAdminSettingsBuilder.getInstanceSettings().getRetrySettings().toBuilder()
90-
* .setTotalTimeout(Duration.ofSeconds(30));
91-
* BaseBigtableInstanceAdminSettings baseBigtableInstanceAdminSettings = baseBigtableInstanceAdminSettingsBuilder.build();
92-
* </code>
93-
* </pre>
94-
*/
71+
/** For internal use only. */
9572
@Generated("by gapic-generator")
96-
@BetaApi
73+
@InternalApi
9774
public class BaseBigtableInstanceAdminSettings
9875
extends ClientSettings<BaseBigtableInstanceAdminSettings> {
9976
/** Returns the object with the settings used for calls to createInstance. */

‎google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/BaseBigtableTableAdminClient.java‎

Lines changed: 3 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
import com.google.api.core.ApiFuture;
2020
import com.google.api.core.ApiFutures;
2121
import com.google.api.core.BetaApi;
22+
import com.google.api.core.InternalApi;
2223
import com.google.api.gax.core.BackgroundResource;
2324
import com.google.api.gax.longrunning.OperationFuture;
2425
import com.google.api.gax.paging.AbstractFixedSizeCollection;
@@ -64,78 +65,9 @@
6465
import javax.annotation.Generated;
6566

6667
// AUTO-GENERATED DOCUMENTATION AND SERVICE
67-
/**
68-
* Service Description: Service for creating, configuring, and deleting Cloud Bigtable tables.
69-
*
70-
* <p>Provides access to the table schemas only, not the data stored within the tables.
71-
*
72-
* <p>This class provides the ability to make remote calls to the backing service through method
73-
* calls that map to API methods. Sample code to get started:
74-
*
75-
* <pre>
76-
* <code>
77-
* try (BaseBigtableTableAdminClient baseBigtableTableAdminClient = BaseBigtableTableAdminClient.create()) {
78-
* InstanceName parent = InstanceName.of("[PROJECT]", "[INSTANCE]");
79-
* String tableId = "";
80-
* Table table = Table.newBuilder().build();
81-
* Table response = baseBigtableTableAdminClient.createTable(parent, tableId, table);
82-
* }
83-
* </code>
84-
* </pre>
85-
*
86-
* <p>Note: close() needs to be called on the baseBigtableTableAdminClient object to clean up
87-
* resources such as threads. In the example above, try-with-resources is used, which automatically
88-
* calls close().
89-
*
90-
* <p>The surface of this class includes several types of Java methods for each of the API's
91-
* methods:
92-
*
93-
* <ol>
94-
* <li>A "flattened" method. With this type of method, the fields of the request type have been
95-
* converted into function parameters. It may be the case that not all fields are available as
96-
* parameters, and not every API method will have a flattened method entry point.
97-
* <li>A "request object" method. This type of method only takes one parameter, a request object,
98-
* which must be constructed before the call. Not every API method will have a request object
99-
* method.
100-
* <li>A "callable" method. This type of method takes no parameters and returns an immutable API
101-
* callable object, which can be used to initiate calls to the service.
102-
* </ol>
103-
*
104-
* <p>See the individual methods for example code.
105-
*
106-
* <p>Many parameters require resource names to be formatted in a particular way. To assist with
107-
* these names, this class includes a format method for each type of name, and additionally a parse
108-
* method to extract the individual identifiers contained within names that are returned.
109-
*
110-
* <p>This class can be customized by passing in a custom instance of BaseBigtableTableAdminSettings
111-
* to create(). For example:
112-
*
113-
* <p>To customize credentials:
114-
*
115-
* <pre>
116-
* <code>
117-
* BaseBigtableTableAdminSettings baseBigtableTableAdminSettings =
118-
* BaseBigtableTableAdminSettings.newBuilder()
119-
* .setCredentialsProvider(FixedCredentialsProvider.create(myCredentials))
120-
* .build();
121-
* BaseBigtableTableAdminClient baseBigtableTableAdminClient =
122-
* BaseBigtableTableAdminClient.create(baseBigtableTableAdminSettings);
123-
* </code>
124-
* </pre>
125-
*
126-
* To customize the endpoint:
127-
*
128-
* <pre>
129-
* <code>
130-
* BaseBigtableTableAdminSettings baseBigtableTableAdminSettings =
131-
* BaseBigtableTableAdminSettings.newBuilder().setEndpoint(myEndpoint).build();
132-
* BaseBigtableTableAdminClient baseBigtableTableAdminClient =
133-
* BaseBigtableTableAdminClient.create(baseBigtableTableAdminSettings);
134-
* </code>
135-
* </pre>
136-
*/
68+
/** For internal use only. */
13769
@Generated("by gapic-generator")
138-
@BetaApi
70+
@InternalApi
13971
public class BaseBigtableTableAdminClient implements BackgroundResource {
14072
private final BaseBigtableTableAdminSettings settings;
14173
private final BigtableTableAdminStub stub;

‎google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/BaseBigtableTableAdminSettings.java‎

Lines changed: 3 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020

2121
import com.google.api.core.ApiFunction;
2222
import com.google.api.core.BetaApi;
23+
import com.google.api.core.InternalApi;
2324
import com.google.api.gax.core.GoogleCredentialsProvider;
2425
import com.google.api.gax.core.InstantiatingExecutorProvider;
2526
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
@@ -59,33 +60,9 @@
5960
import javax.annotation.Generated;
6061

6162
// AUTO-GENERATED DOCUMENTATION AND CLASS
62-
/**
63-
* Settings class to configure an instance of {@link BaseBigtableTableAdminClient}.
64-
*
65-
* <p>The default instance has everything set to sensible defaults:
66-
*
67-
* <ul>
68-
* <li>The default service address (bigtableadmin.googleapis.com) and default port (443) are used.
69-
* <li>Credentials are acquired automatically through Application Default Credentials.
70-
* <li>Retries are configured for idempotent methods but not for non-idempotent methods.
71-
* </ul>
72-
*
73-
* <p>The builder of this class is recursive, so contained classes are themselves builders. When
74-
* build() is called, the tree of builders is called to create the complete settings object. For
75-
* example, to set the total timeout of createTable to 30 seconds:
76-
*
77-
* <pre>
78-
* <code>
79-
* BaseBigtableTableAdminSettings.Builder baseBigtableTableAdminSettingsBuilder =
80-
* BaseBigtableTableAdminSettings.newBuilder();
81-
* baseBigtableTableAdminSettingsBuilder.createTableSettings().getRetrySettings().toBuilder()
82-
* .setTotalTimeout(Duration.ofSeconds(30));
83-
* BaseBigtableTableAdminSettings baseBigtableTableAdminSettings = baseBigtableTableAdminSettingsBuilder.build();
84-
* </code>
85-
* </pre>
86-
*/
63+
/** For internal use only. */
8764
@Generated("by gapic-generator")
88-
@BetaApi
65+
@InternalApi
8966
public class BaseBigtableTableAdminSettings extends ClientSettings<BaseBigtableTableAdminSettings> {
9067
/** Returns the object with the settings used for calls to createTable. */
9168
public UnaryCallSettings<CreateTableRequest, Table> createTableSettings() {

‎google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/package-info.java‎

Lines changed: 4 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -15,45 +15,11 @@
1515
*/
1616

1717
/**
18-
* A client to Cloud Bigtable Admin API.
18+
* Clients for the Cloud Bigtable admin API.
1919
*
20-
* <p>The interfaces provided are listed below, along with usage samples.
20+
* <p>These APIs allow callers to create and manage Cloud Bigtable resources.
2121
*
22-
* <p>=============================== BaseBigtableInstanceAdminClient
23-
* ===============================
24-
*
25-
* <p>Service Description: Service for creating, configuring, and deleting Cloud Bigtable Instances
26-
* and Clusters. Provides access to the Instance and Cluster schemas only, not the tables' metadata
27-
* or data stored in those tables.
28-
*
29-
* <p>Sample for BaseBigtableInstanceAdminClient:
30-
*
31-
* <pre>
32-
* <code>
33-
* try (BaseBigtableInstanceAdminClient baseBigtableInstanceAdminClient = BaseBigtableInstanceAdminClient.create()) {
34-
* InstanceName name = InstanceName.of("[PROJECT]", "[INSTANCE]");
35-
* Instance response = baseBigtableInstanceAdminClient.getInstance(name);
36-
* }
37-
* </code>
38-
* </pre>
39-
*
40-
* ============================ BaseBigtableTableAdminClient ============================
41-
*
42-
* <p>Service Description: Service for creating, configuring, and deleting Cloud Bigtable tables.
43-
*
44-
* <p>Provides access to the table schemas only, not the data stored within the tables.
45-
*
46-
* <p>Sample for BaseBigtableTableAdminClient:
47-
*
48-
* <pre>
49-
* <code>
50-
* try (BaseBigtableTableAdminClient baseBigtableTableAdminClient = BaseBigtableTableAdminClient.create()) {
51-
* InstanceName parent = InstanceName.of("[PROJECT]", "[INSTANCE]");
52-
* String tableId = "";
53-
* Table table = Table.newBuilder().build();
54-
* Table response = baseBigtableTableAdminClient.createTable(parent, tableId, table);
55-
* }
56-
* </code>
57-
* </pre>
22+
* @see com.google.cloud.bigtable.admin.v2.BigtableInstanceAdminClient for instance level API.
23+
* @see com.google.cloud.bigtable.admin.v2.BigtableTableAdminClient for table level API.
5824
*/
5925
package com.google.cloud.bigtable.admin.v2;

‎google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/stub/BigtableInstanceAdminStub.java‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
import static com.google.cloud.bigtable.admin.v2.BaseBigtableInstanceAdminClient.ListAppProfilesPagedResponse;
1919

2020
import com.google.api.core.BetaApi;
21+
import com.google.api.core.InternalApi;
2122
import com.google.api.gax.core.BackgroundResource;
2223
import com.google.api.gax.rpc.OperationCallable;
2324
import com.google.api.gax.rpc.UnaryCallable;
@@ -57,13 +58,9 @@
5758
import javax.annotation.Generated;
5859

5960
// AUTO-GENERATED DOCUMENTATION AND CLASS
60-
/**
61-
* Base stub class for Cloud Bigtable Admin API.
62-
*
63-
* <p>This class is for advanced usage and reflects the underlying API directly.
64-
*/
61+
/** For internal use only. */
6562
@Generated("by gapic-generator")
66-
@BetaApi("A restructuring of stub classes is planned, so this may break in the future")
63+
@InternalApi
6764
public abstract class BigtableInstanceAdminStub implements BackgroundResource {
6865

6966
@BetaApi("The surface for use by generated code is not stable yet and may change in the future.")

‎google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/stub/BigtableTableAdminStub.java‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
import static com.google.cloud.bigtable.admin.v2.BaseBigtableTableAdminClient.ListTablesPagedResponse;
2020

2121
import com.google.api.core.BetaApi;
22+
import com.google.api.core.InternalApi;
2223
import com.google.api.gax.core.BackgroundResource;
2324
import com.google.api.gax.rpc.OperationCallable;
2425
import com.google.api.gax.rpc.UnaryCallable;
@@ -49,13 +50,9 @@
4950
import javax.annotation.Generated;
5051

5152
// AUTO-GENERATED DOCUMENTATION AND CLASS
52-
/**
53-
* Base stub class for Cloud Bigtable Admin API.
54-
*
55-
* <p>This class is for advanced usage and reflects the underlying API directly.
56-
*/
53+
/** For internal use only. */
5754
@Generated("by gapic-generator")
58-
@BetaApi("A restructuring of stub classes is planned, so this may break in the future")
55+
@InternalApi
5956
public abstract class BigtableTableAdminStub implements BackgroundResource {
6057

6158
@BetaApi("The surface for use by generated code is not stable yet and may change in the future.")

‎google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/stub/GrpcBigtableInstanceAdminCallableFactory.java‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
package com.google.cloud.bigtable.admin.v2.stub;
1717

1818
import com.google.api.core.BetaApi;
19+
import com.google.api.core.InternalApi;
1920
import com.google.api.gax.grpc.GrpcCallSettings;
2021
import com.google.api.gax.grpc.GrpcCallableFactory;
2122
import com.google.api.gax.grpc.GrpcStubCallableFactory;
@@ -35,13 +36,9 @@
3536
import javax.annotation.Generated;
3637

3738
// AUTO-GENERATED DOCUMENTATION AND CLASS
38-
/**
39-
* gRPC callable factory implementation for Cloud Bigtable Admin API.
40-
*
41-
* <p>This class is for advanced usage.
42-
*/
39+
/** For internal use only. */
4340
@Generated("by gapic-generator")
44-
@BetaApi("The surface for use by generated code is not stable yet and may change in the future.")
41+
@InternalApi
4542
public class GrpcBigtableInstanceAdminCallableFactory implements GrpcStubCallableFactory {
4643
@Override
4744
public <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createUnaryCallable(

0 commit comments

Comments
 (0)