[Bigtable] GCRules.GCRule Javadoc fix for createTable (#5066)

rahulKQL · chingor13 · commit 00c8bb1f1942 · 2019-05-13T14:49:09.000-07:00
* GCRules.GCRule sample code on createTable

Added sample code on createTable, createTableAsync for `GCRules.GCRule` usage.

Added note for GCRules regarding database compaction

* Addressing review comments

Updated GCRules note, removed empty params, and updated BigtableTableAdminClient with better example

* Addressing feedback and rearranged gcRule example

* Updated GCRules argument description
diff --git a/google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/BigtableTableAdminClient.java b/google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/BigtableTableAdminClient.java
@@ -29,6 +29,7 @@
 import com.google.cloud.bigtable.admin.v2.BaseBigtableTableAdminClient.ListTablesPagedResponse;
 import com.google.cloud.bigtable.admin.v2.internal.NameUtil;
 import com.google.cloud.bigtable.admin.v2.models.CreateTableRequest;
+import com.google.cloud.bigtable.admin.v2.models.GCRules;
 import com.google.cloud.bigtable.admin.v2.models.ModifyColumnFamiliesRequest;
 import com.google.cloud.bigtable.admin.v2.models.Table;
 import com.google.cloud.bigtable.admin.v2.stub.EnhancedBigtableTableAdminStub;
@@ -177,13 +178,24 @@ public void close() {
    * <p>Sample code:
    *
    * <pre>{@code
+   * // A table with a single column family, which retains only the latest value.
    * Table table = client.createTable(
    *   CreateTableRequest.of("my-table")
-   *     .addFamily("cf2", GCRULES.maxVersions(1)
+   *     .addFamily("cf2", GCRULES.maxVersions(1))
+   * );
+   *
+   * // Another table with more complex garbage collection rules.
+   * Table table = client.createTable(
+   *   CreateTableRequest.of("my-table")
+   *     .addFamily("cf2", GCRULES.union()
+   *       .rule(GCRULES.maxAge(Duration.ofDays(30)))
+   *       .rule(GCRULES.maxVersions(5))
+   *     )
    * );
    * }</pre>
    *
    * @see CreateTableRequest for available options.
+   * @see GCRules for the documentation on available garbage collection rules.
    */
   @SuppressWarnings("WeakerAccess")
   public Table createTable(CreateTableRequest request) {
@@ -196,9 +208,19 @@ public Table createTable(CreateTableRequest request) {
    * <p>Sample code:
    *
    * <pre>{@code
+   * // A table with a single column family, which retains values up to 7 days.
    * ApiFuture<Table> tableFuture = client.createTableAsync(
    *   CreateTableRequest.of("my-table")
-   *     .addFamily("cf", GCRules.GCRULES.maxVersions(1))
+   *     .addFamily("cf", GCRULES.maxAge(Duration.ofDays(7)))
+   * );
+   *
+   * // Another table with more complex garbage collection rules.
+   * ApiFuture<Table> tableFuture = client.createTableAsync(
+   *   CreateTableRequest.of("my-table")
+   *     .addFamily("cf", GCRULES.intersection()
+   *       .rule(GCRULES.maxAge(120, TimeUnit.HOURS))
+   *       .rule(GCRULES.maxVersions(10))
+   *     )
    * );
    *
    * ApiFutures.addCallback(
@@ -217,6 +239,7 @@ public Table createTable(CreateTableRequest request) {
    * }</pre>
    *
    * @see CreateTableRequest for available options.
+   * @see GCRules for the documentation on available garbage collection rules.
    */
   @SuppressWarnings("WeakerAccess")
   public ApiFuture<Table> createTableAsync(CreateTableRequest request) {
diff --git a/google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/models/CreateTableRequest.java b/google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/models/CreateTableRequest.java
@@ -36,28 +36,19 @@
  * </ul>
  */
 public final class CreateTableRequest {
-  // TODO(igorbernstein): rename to requestBuilder
   private final com.google.bigtable.admin.v2.CreateTableRequest.Builder requestBuilder =
       com.google.bigtable.admin.v2.CreateTableRequest.newBuilder();
 
   public static CreateTableRequest of(String tableId) {
     return new CreateTableRequest(tableId);
   }
 
-  /**
-   * Configures table with the specified id
-   *
-   * @param tableId
-   */
+  /** Configures table with the specified id */
   private CreateTableRequest(String tableId) {
     requestBuilder.setTableId(tableId);
   }
 
-  /**
-   * Adds a new columnFamily to the configuration
-   *
-   * @param familyId
-   */
+  /** Adds a new columnFamily to the configuration */
   public CreateTableRequest addFamily(String familyId) {
     Preconditions.checkNotNull(familyId);
     requestBuilder.getTableBuilder().putColumnFamilies(familyId, ColumnFamily.getDefaultInstance());
@@ -68,8 +59,7 @@ public CreateTableRequest addFamily(String familyId) {
    * Adds a new columnFamily with {@link GCRule} to the configuration. Please note that calling this
    * method with the same familyId will overwrite the previous family.
    *
-   * @param familyId
-   * @param gcRule
+   * @see GCRule for available options.
    */
   public CreateTableRequest addFamily(String familyId, GCRule gcRule) {
     Preconditions.checkNotNull(familyId);
@@ -79,11 +69,7 @@ public CreateTableRequest addFamily(String familyId, GCRule gcRule) {
     return this;
   }
 
-  /**
-   * Adds split at the specified key to the configuration
-   *
-   * @param key
-   */
+  /** Adds split at the specified key to the configuration */
   public CreateTableRequest addSplit(ByteString key) {
     Preconditions.checkNotNull(key);
     requestBuilder.addInitialSplitsBuilder().setKey(key);
diff --git a/google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/models/GCRules.java b/google-cloud-clients/google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/models/GCRules.java
@@ -30,7 +30,13 @@
 
 // TODO(igorbernstein2): the distinction between GcRule & GCRule is too subtle, use fully qualified
 // names for the protos.
-/** Wraps {@link GcRule} protocol buffer object and exposes a simpler Fluent DSL model */
+/**
+ * Wraps {@link GcRule} protocol buffer object and exposes a friendly API.
+ *
+ * <p>Note: Garbage collection executes opportunistically in the background, and so it's possible
+ * for reads to return a cell even if it matches the active GC expression for its family. Please use
+ * appropriate filters in your reads to exclude cells which are eligible for garbage collection.
+ */
 @BetaApi
 public final class GCRules {
   /** Factory method to create GCRules - entry point into the DSL. */
@@ -124,11 +130,7 @@ private IntersectionRule() {
       rulesList = new ArrayList<>();
     }
 
-    /**
-     * Adds a new GCRule
-     *
-     * @param rule
-     */
+    /** Adds a new GCRule */
     // TODO(igorbernstein2): consider renaming this to addRule
     public IntersectionRule rule(@Nonnull GCRule rule) {
       rulesList.add(rule);
@@ -189,11 +191,7 @@ private UnionRule() {
       rulesList = new ArrayList<>();
     }
 
-    /**
-     * Adds a new GCRule
-     *
-     * @param rule
-     */
+    /** Adds a new GCRule */
     public UnionRule rule(@Nonnull GCRule rule) {
       rulesList.add(rule);
       return this;
