diff --git a/SUPPORTING_NEW_SERVICES.md b/SUPPORTING_NEW_SERVICES.md index b7d24be1acba..22c7c1327bcc 100644 --- a/SUPPORTING_NEW_SERVICES.md +++ b/SUPPORTING_NEW_SERVICES.md @@ -25,7 +25,7 @@ The library should contain: * Classes representing model objects and request-related options. Model objects that correspond to service resources should have a subclass that provides functions related to that resource. For example, see [`BlobInfo`](https://github.com/GoogleCloudPlatform/google-cloud-java/blob/master/google-cloud-storage/src/main/java/com/google/cloud/storage/BlobInfo.java) (the metadata class) and [`Blob`](https://github.com/GoogleCloudPlatform/google-cloud-java/blob/master/google-cloud-storage/src/main/java/com/google/cloud/storage/Blob.java) (the functional class). The builders for both objects should implement a common interface or abstract class, and the functional subclass builder should delegate to the metadata class builder. * Request-related options classes. Operations should accept these options as varargs when appropriate. Supplying options as varargs allows for supporting more advanced use cases without affecting the method signature. The options classes should provide static methods to create instances with specific options settings. A common option is to request that only specific fields of a model object should be included in a response. Typically such an option is created via a `fields(...)` method which accepts a vararg of type `Field` enum. The enum should implement the [FieldSelector](https://github.com/GoogleCloudPlatform/google-cloud-java/blob/master/google-cloud-core/src/main/java/com/google/cloud/FieldSelector.java) interface. -In general, make classes immutable whenever possible, providing builders as necessary. Make model object classes `java.util.Serializable`. Prefer making classes final, with the following exceptions: (1) functional objects and (2) classes in which the user cannot set all attributes. If a class cannot be made final, then `hashCode` or `equals` overrides should be made final if possible. +In general, make classes immutable whenever possible, providing builders as necessary. Make model object classes `java.io.Serializable`. Prefer making classes final, with the following exceptions: (1) functional objects and (2) classes in which the user cannot set all attributes. If a class cannot be made final, then `hashCode` or `equals` overrides should be made final if possible. `google-cloud-core` provides functionality for code patterns used across `google-cloud` libraries. The following are some important core concepts: * Paging: Google Cloud services often expose page-based listing using page tokens. The [`Page`](https://github.com/GoogleCloudPlatform/google-cloud-java/blob/master/google-cloud-core/src/main/java/com/google/cloud/Page.java) interface should be used for page-based listing. A `Page` contains an iterator over results in that page, as well as methods to get the next page and all results in future pages. `Page` requires a `NextPageFetcher` implementation (see the `NextPageFetcher` interface in [`PageImpl`](https://github.com/GoogleCloudPlatform/google-cloud-java/blob/master/google-cloud-core/src/main/java/com/google/cloud/PageImpl.java)). This implementation should delegate constructing request options to the `nextRequestOptions` method in `PageImpl`.