Skip to content

Commit

Permalink
docs: Add comments to GCS gRPC API proto spec to describe how naming …
Browse files Browse the repository at this point in the history 
…work (#1139)

* docs: Add comments to GCS gRPC API proto spec to describe how naming works

PiperOrigin-RevId: 408352508

Source-Author: Google APIs <noreply@google.com>
Source-Date: Mon Nov 8 08:42:59 2021 -0800
Source-Repo: googleapis/googleapis
Source-Sha: be4be3dde73955e934eb6daddbab68e793e1c1e5
Source-Link: googleapis/googleapis@be4be3d

* chore: update Java and Python dependencies

PiperOrigin-RevId: 408420890

Source-Author: Google APIs <noreply@google.com>
Source-Date: Mon Nov 8 13:03:45 2021 -0800
Source-Repo: googleapis/googleapis
Source-Sha: 2921f9fb3bfbd16f6b2da0104373e2b47a80a65e
Source-Link: googleapis/googleapis@2921f9f
  • Loading branch information
@yoshi-automation
yoshi-automation committed Nov 15, 2021
1 parent af62e23 commit 417c525
Show file tree
Hide file tree
Showing 11 changed files with 145 additions and 101 deletions.
16 changes: 15 additions & 1 deletion gapic-google-cloud-storage-v2/src/main/java/com/google/storage/v2/StorageClient.java
View file
Expand Up @@ -29,7 +29,21 @@

// AUTO-GENERATED DOCUMENTATION AND CLASS.
/**
* Service Description: Manages Google Cloud Storage resources.
* Service Description: ## API Overview and Naming Syntax
*
* <p>The GCS gRPC API allows applications to read and write data through the abstractions of
* buckets and objects. For a description of these abstractions please see
* https://cloud.google.com/storage/docs.
*
* <p>Resources are named as follows: - Projects are referred to as they are defined by the Resource
* Manager API, using strings like `projects/123456` or `projects/my-string-id`. - Buckets are named
* using string names of the form: `projects/{project}/buckets/{bucket}` For globally unique
* buckets, `_` may be substituted for the project. - Objects are uniquely identified by their name
* along with the name of the bucket they belong to, as separate strings in this API. For example:
*
* <p>ReadObjectRequest { bucket: 'projects/_/buckets/my-bucket' object: 'my-object' } Note that
* object names can contain `/` characters, which are treated as any other character (no special
* directory semantics).
*
* <p>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:
Expand Down
16 changes: 15 additions & 1 deletion gapic-google-cloud-storage-v2/src/main/java/com/google/storage/v2/package-info.java
View file
Expand Up @@ -19,7 +19,21 @@
*
* <p>======================= StorageClient =======================
*
* <p>Service Description: Manages Google Cloud Storage resources.
* <p>Service Description: ## API Overview and Naming Syntax
*
* <p>The GCS gRPC API allows applications to read and write data through the abstractions of
* buckets and objects. For a description of these abstractions please see
* https://cloud.google.com/storage/docs.
*
* <p>Resources are named as follows: - Projects are referred to as they are defined by the Resource
* Manager API, using strings like `projects/123456` or `projects/my-string-id`. - Buckets are named
* using string names of the form: `projects/{project}/buckets/{bucket}` For globally unique
* buckets, `_` may be substituted for the project. - Objects are uniquely identified by their name
* along with the name of the bucket they belong to, as separate strings in this API. For example:
*
* <p>ReadObjectRequest { bucket: 'projects/_/buckets/my-bucket' object: 'my-object' } Note that
* object names can contain `/` characters, which are treated as any other character (no special
* directory semantics).
*
* <p>Sample for StorageClient:
*
Expand Down
96 changes: 91 additions & 5 deletions grpc-google-cloud-storage-v2/src/main/java/com/google/storage/v2/StorageGrpc.java
View file
Expand Up @@ -21,12 +21,30 @@
*
*
* <pre>
* Manages Google Cloud Storage resources.
* ## API Overview and Naming Syntax
* The GCS gRPC API allows applications to read and write data through the
* abstractions of buckets and objects. For a description of these abstractions
* please see https://cloud.google.com/storage/docs.
* Resources are named as follows:
* - Projects are referred to as they are defined by the Resource Manager API,
* using strings like `projects/123456` or `projects/my-string-id`.
* - Buckets are named using string names of the form:
* `projects/{project}/buckets/{bucket}`
* For globally unique buckets, `_` may be substituted for the project.
* - Objects are uniquely identified by their name along with the name of the
* bucket they belong to, as separate strings in this API. For example:
* ReadObjectRequest {
* bucket: 'projects/_/buckets/my-bucket'
* object: 'my-object'
* }
* Note that object names can contain `/` characters, which are treated as
* any other character (no special directory semantics).
* </pre>
*/
@javax.annotation.Generated(
value = "by gRPC proto compiler",
comments = "Source: google/storage/v2/storage.proto")
@io.grpc.stub.annotations.GrpcGenerated
public final class StorageGrpc {

private StorageGrpc() {}
Expand Down Expand Up @@ -252,7 +270,24 @@ public StorageFutureStub newStub(
*
*
* <pre>
* Manages Google Cloud Storage resources.
* ## API Overview and Naming Syntax
* The GCS gRPC API allows applications to read and write data through the
* abstractions of buckets and objects. For a description of these abstractions
* please see https://cloud.google.com/storage/docs.
* Resources are named as follows:
* - Projects are referred to as they are defined by the Resource Manager API,
* using strings like `projects/123456` or `projects/my-string-id`.
* - Buckets are named using string names of the form:
* `projects/{project}/buckets/{bucket}`
* For globally unique buckets, `_` may be substituted for the project.
* - Objects are uniquely identified by their name along with the name of the
* bucket they belong to, as separate strings in this API. For example:
* ReadObjectRequest {
* bucket: 'projects/_/buckets/my-bucket'
* object: 'my-object'
* }
* Note that object names can contain `/` characters, which are treated as
* any other character (no special directory semantics).
* </pre>
*/
public abstract static class StorageImplBase implements io.grpc.BindableService {
Expand Down Expand Up @@ -382,7 +417,24 @@ public final io.grpc.ServerServiceDefinition bindService() {
*
*
* <pre>
* Manages Google Cloud Storage resources.
* ## API Overview and Naming Syntax
* The GCS gRPC API allows applications to read and write data through the
* abstractions of buckets and objects. For a description of these abstractions
* please see https://cloud.google.com/storage/docs.
* Resources are named as follows:
* - Projects are referred to as they are defined by the Resource Manager API,
* using strings like `projects/123456` or `projects/my-string-id`.
* - Buckets are named using string names of the form:
* `projects/{project}/buckets/{bucket}`
* For globally unique buckets, `_` may be substituted for the project.
* - Objects are uniquely identified by their name along with the name of the
* bucket they belong to, as separate strings in this API. For example:
* ReadObjectRequest {
* bucket: 'projects/_/buckets/my-bucket'
* object: 'my-object'
* }
* Note that object names can contain `/` characters, which are treated as
* any other character (no special directory semantics).
* </pre>
*/
public static final class StorageStub extends io.grpc.stub.AbstractAsyncStub<StorageStub> {
Expand Down Expand Up @@ -493,7 +545,24 @@ public void queryWriteStatus(
*
*
* <pre>
* Manages Google Cloud Storage resources.
* ## API Overview and Naming Syntax
* The GCS gRPC API allows applications to read and write data through the
* abstractions of buckets and objects. For a description of these abstractions
* please see https://cloud.google.com/storage/docs.
* Resources are named as follows:
* - Projects are referred to as they are defined by the Resource Manager API,
* using strings like `projects/123456` or `projects/my-string-id`.
* - Buckets are named using string names of the form:
* `projects/{project}/buckets/{bucket}`
* For globally unique buckets, `_` may be substituted for the project.
* - Objects are uniquely identified by their name along with the name of the
* bucket they belong to, as separate strings in this API. For example:
* ReadObjectRequest {
* bucket: 'projects/_/buckets/my-bucket'
* object: 'my-object'
* }
* Note that object names can contain `/` characters, which are treated as
* any other character (no special directory semantics).
* </pre>
*/
public static final class StorageBlockingStub
Expand Down Expand Up @@ -563,7 +632,24 @@ public com.google.storage.v2.QueryWriteStatusResponse queryWriteStatus(
*
*
* <pre>
* Manages Google Cloud Storage resources.
* ## API Overview and Naming Syntax
* The GCS gRPC API allows applications to read and write data through the
* abstractions of buckets and objects. For a description of these abstractions
* please see https://cloud.google.com/storage/docs.
* Resources are named as follows:
* - Projects are referred to as they are defined by the Resource Manager API,
* using strings like `projects/123456` or `projects/my-string-id`.
* - Buckets are named using string names of the form:
* `projects/{project}/buckets/{bucket}`
* For globally unique buckets, `_` may be substituted for the project.
* - Objects are uniquely identified by their name along with the name of the
* bucket they belong to, as separate strings in this API. For example:
* ReadObjectRequest {
* bucket: 'projects/_/buckets/my-bucket'
* object: 'my-object'
* }
* Note that object names can contain `/` characters, which are treated as
* any other character (no special directory semantics).
* </pre>
*/
public static final class StorageFutureStub
Expand Down
49 changes: 0 additions & 49 deletions proto-google-cloud-storage-v2/src/main/java/com/google/storage/v2/Bucket.java
View file
Expand Up @@ -14384,11 +14384,6 @@ public com.google.storage.v2.Bucket.Website getDefaultInstanceForType() {
*
* <pre>
* Immutable. The name of the bucket.
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
* Other sorts of buckets in the future are not guaranteed to follow this
* pattern.
* For globally unique bucket names, a `_` may be substituted for the project
* ID.
* </pre>
*
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
Expand All @@ -14412,11 +14407,6 @@ public java.lang.String getName() {
*
* <pre>
* Immutable. The name of the bucket.
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
* Other sorts of buckets in the future are not guaranteed to follow this
* pattern.
* For globally unique bucket names, a `_` may be substituted for the project
* ID.
* </pre>
*
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
Expand Down Expand Up @@ -14496,8 +14486,6 @@ public com.google.protobuf.ByteString getBucketIdBytes() {
*
* <pre>
* Immutable. The project which owns this bucket.
* Format: projects/{project_number}
* Example: `projects/123456`.
* </pre>
*
* <code>
Expand All @@ -14523,8 +14511,6 @@ public java.lang.String getProject() {
*
* <pre>
* Immutable. The project which owns this bucket.
* Format: projects/{project_number}
* Example: `projects/123456`.
* </pre>
*
* <code>
Expand Down Expand Up @@ -16767,11 +16753,6 @@ public Builder mergeFrom(
*
* <pre>
* Immutable. The name of the bucket.
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
* Other sorts of buckets in the future are not guaranteed to follow this
* pattern.
* For globally unique bucket names, a `_` may be substituted for the project
* ID.
* </pre>
*
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
Expand All @@ -16794,11 +16775,6 @@ public java.lang.String getName() {
*
* <pre>
* Immutable. The name of the bucket.
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
* Other sorts of buckets in the future are not guaranteed to follow this
* pattern.
* For globally unique bucket names, a `_` may be substituted for the project
* ID.
* </pre>
*
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
Expand All @@ -16821,11 +16797,6 @@ public com.google.protobuf.ByteString getNameBytes() {
*
* <pre>
* Immutable. The name of the bucket.
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
* Other sorts of buckets in the future are not guaranteed to follow this
* pattern.
* For globally unique bucket names, a `_` may be substituted for the project
* ID.
* </pre>
*
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
Expand All @@ -16847,11 +16818,6 @@ public Builder setName(java.lang.String value) {
*
* <pre>
* Immutable. The name of the bucket.
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
* Other sorts of buckets in the future are not guaranteed to follow this
* pattern.
* For globally unique bucket names, a `_` may be substituted for the project
* ID.
* </pre>
*
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
Expand All @@ -16869,11 +16835,6 @@ public Builder clearName() {
*
* <pre>
* Immutable. The name of the bucket.
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
* Other sorts of buckets in the future are not guaranteed to follow this
* pattern.
* For globally unique bucket names, a `_` may be substituted for the project
* ID.
* </pre>
*
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
Expand Down Expand Up @@ -17014,8 +16975,6 @@ public Builder setBucketIdBytes(com.google.protobuf.ByteString value) {
*
* <pre>
* Immutable. The project which owns this bucket.
* Format: projects/{project_number}
* Example: `projects/123456`.
* </pre>
*
* <code>
Expand All @@ -17040,8 +16999,6 @@ public java.lang.String getProject() {
*
* <pre>
* Immutable. The project which owns this bucket.
* Format: projects/{project_number}
* Example: `projects/123456`.
* </pre>
*
* <code>
Expand All @@ -17066,8 +17023,6 @@ public com.google.protobuf.ByteString getProjectBytes() {
*
* <pre>
* Immutable. The project which owns this bucket.
* Format: projects/{project_number}
* Example: `projects/123456`.
* </pre>
*
* <code>
Expand All @@ -17091,8 +17046,6 @@ public Builder setProject(java.lang.String value) {
*
* <pre>
* Immutable. The project which owns this bucket.
* Format: projects/{project_number}
* Example: `projects/123456`.
* </pre>
*
* <code>
Expand All @@ -17112,8 +17065,6 @@ public Builder clearProject() {
*
* <pre>
* Immutable. The project which owns this bucket.
* Format: projects/{project_number}
* Example: `projects/123456`.
* </pre>
*
* <code>
Expand Down
14 changes: 0 additions & 14 deletions proto-google-cloud-storage-v2/src/main/java/com/google/storage/v2/BucketOrBuilder.java
View file
Expand Up @@ -28,11 +28,6 @@ public interface BucketOrBuilder
*
* <pre>
* Immutable. The name of the bucket.
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
* Other sorts of buckets in the future are not guaranteed to follow this
* pattern.
* For globally unique bucket names, a `_` may be substituted for the project
* ID.
* </pre>
*
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
Expand All @@ -45,11 +40,6 @@ public interface BucketOrBuilder
*
* <pre>
* Immutable. The name of the bucket.
* Global buckets will be of the format `projects/{project}/buckets/{bucket}`.
* Other sorts of buckets in the future are not guaranteed to follow this
* pattern.
* For globally unique bucket names, a `_` may be substituted for the project
* ID.
* </pre>
*
* <code>string name = 1 [(.google.api.field_behavior) = IMMUTABLE];</code>
Expand Down Expand Up @@ -92,8 +82,6 @@ public interface BucketOrBuilder
*
* <pre>
* Immutable. The project which owns this bucket.
* Format: projects/{project_number}
* Example: `projects/123456`.
* </pre>
*
* <code>
Expand All @@ -108,8 +96,6 @@ public interface BucketOrBuilder
*
* <pre>
* Immutable. The project which owns this bucket.
* Format: projects/{project_number}
* Example: `projects/123456`.
* </pre>
*
* <code>
Expand Down

0 comments on commit 417c525

Please sign in to comment.