feat: Add GcRuleBuilder for safe GC rule construction

Author: jinseopkim0

google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/models/GcRuleBuilder.java

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.bigtable.admin.v2.models;
+
+import com.google.bigtable.admin.v2.GcRule;
+import com.google.protobuf.util.Durations;
+import org.threeten.bp.Duration;
+
+/**
+ * Factory for creating safe GcRule protos.
+ *
+ * <p>Use this class to construct GcRules instead of the raw proto builder to avoid
+ * common pitfalls with "oneof" fields (e.g. accidentally overwriting max age with max versions).
+ */
+public final class GcRuleBuilder {
+  private GcRuleBuilder() {} // Static utility
+
+  // Entry points for composite rules
+
+  /** Starts building an Intersection (AND) rule. */
+  public static IntersectionRuleBuilder intersection() {
+    return new IntersectionRuleBuilder();
+  }
+
+  /** Starts building a Union (OR) rule. */
+  public static UnionRuleBuilder union() {
+    return new UnionRuleBuilder();
+  }
+
+  // Entry points for simple rules (return the Proto directly)
+
+  /** Creates a Max Age rule. */
+  public static GcRule maxAge(Duration age) {
+    long seconds = age.getSeconds();
+    int nanos = age.getNano();
+    return GcRule.newBuilder()
+        .setMaxAge(Durations.fromNanos(seconds * 1_000_000_000L + nanos))
+        .build();
+  }
+
+  /** Creates a Max Versions rule. */
+  public static GcRule maxVersions(int versions) {
+    return GcRule.newBuilder().setMaxNumVersions(versions).build();
+  }
+}

google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/models/IntersectionRuleBuilder.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.bigtable.admin.v2.models;
+
+import com.google.bigtable.admin.v2.GcRule;
+import com.google.bigtable.admin.v2.GcRule.Intersection;
+
+/**
+ * Builder for creating an Intersection (AND) GC Rule.
+ *
+ * <p>This class ensures type safety when constructing composite rules, preventing
+ * the misuse of the standard builder's ambiguous setters.
+ */
+public final class IntersectionRuleBuilder {
+  private final Intersection.Builder intersectionBuilder = Intersection.newBuilder();
+
+  /** Adds a rule to the intersection. */
+  public IntersectionRuleBuilder add(GcRule rule) {
+    intersectionBuilder.addRules(rule);
+    return this;
+  }
+
+  /** Builds the final GcRule proto. */
+  public GcRule build() {
+    return GcRule.newBuilder().setIntersection(intersectionBuilder).build();
+  }
+}

google-cloud-bigtable/src/main/java/com/google/cloud/bigtable/admin/v2/models/UnionRuleBuilder.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.bigtable.admin.v2.models;
+
+import com.google.bigtable.admin.v2.GcRule;
+import com.google.bigtable.admin.v2.GcRule.Union;
+
+/**
+ * Builder for creating a Union (OR) GC Rule.
+ *
+ * <p>This class ensures type safety when constructing composite rules, preventing
+ * the misuse of the standard builder's ambiguous setters.
+ */
+public final class UnionRuleBuilder {
+  private final Union.Builder unionBuilder = Union.newBuilder();
+
+  /** Adds a rule to the union. */
+  public UnionRuleBuilder add(GcRule rule) {
+    unionBuilder.addRules(rule);
+    return this;
+  }
+
+  /** Builds the final GcRule proto. */
+  public GcRule build() {
+    return GcRule.newBuilder().setUnion(unionBuilder).build();
+  }
+}

google-cloud-bigtable/src/test/java/com/google/cloud/bigtable/admin/v2/models/GcRuleBuilderTest.java

@@ -0,0 +1,97 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.bigtable.admin.v2.models;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import com.google.bigtable.admin.v2.GcRule;
+import com.google.protobuf.util.Durations;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+import org.threeten.bp.Duration;
+
+@RunWith(JUnit4.class)
+public class GcRuleBuilderTest {
+
+  @Test
+  public void maxAge_createsCorrectProto() {
+    GcRule rule = GcRuleBuilder.maxAge(Duration.ofHours(1));
+    
+    assertThat(rule.hasMaxAge()).isTrue();
+    assertThat(rule.getMaxAge()).isEqualTo(Durations.fromHours(1));
+  }
+
+  @Test
+  public void maxVersions_createsCorrectProto() {
+    GcRule rule = GcRuleBuilder.maxVersions(5);
+    
+    assertThat(rule.hasMaxNumVersions()).isTrue();
+    assertThat(rule.getMaxNumVersions()).isEqualTo(5);
+  }
+
+  @Test
+  public void intersection_buildsNestedRules() {
+    // Expected Proto structure
+    GcRule expected = GcRule.newBuilder()
+        .setIntersection(GcRule.Intersection.newBuilder()
+            .addRules(GcRule.newBuilder().setMaxNumVersions(1).build())
+            .addRules(GcRule.newBuilder().setMaxAge(Durations.fromHours(2)).build()))
+        .build();
+
+    // Using the new Builder
+    GcRule actual = GcRuleBuilder.intersection()
+        .add(GcRuleBuilder.maxVersions(1))
+        .add(GcRuleBuilder.maxAge(Duration.ofHours(2)))
+        .build();
+
+    assertThat(actual).isEqualTo(expected);
+  }
+
+  @Test
+  public void union_buildsNestedRules() {
+    // Expected Proto structure
+    GcRule expected = GcRule.newBuilder()
+        .setUnion(GcRule.Union.newBuilder()
+            .addRules(GcRule.newBuilder().setMaxNumVersions(10).build())
+            .addRules(GcRule.newBuilder().setMaxAge(Durations.fromDays(5)).build()))
+        .build();
+
+    // Using the new Builder
+    GcRule actual = GcRuleBuilder.union()
+        .add(GcRuleBuilder.maxVersions(10))
+        .add(GcRuleBuilder.maxAge(Duration.ofDays(5)))
+        .build();
+
+    assertThat(actual).isEqualTo(expected);
+  }
+  
+  @Test
+  public void nestedComplexRules_workCorrectly() {
+    // Union of (Version(1) OR Intersection(Age(1h) AND Version(5)))
+    GcRule actual = GcRuleBuilder.union()
+        .add(GcRuleBuilder.maxVersions(1))
+        .add(GcRuleBuilder.intersection()
+            .add(GcRuleBuilder.maxAge(Duration.ofHours(1)))
+            .add(GcRuleBuilder.maxVersions(5))
+            .build())
+        .build();
+
+    assertThat(actual.getUnion().getRulesCount()).isEqualTo(2);
+    assertThat(actual.getUnion().getRules(1).getIntersection().getRulesCount()).isEqualTo(2);
+  }
+}