gt javadoc

Author: snazy

persistence/nosql/persistence/metastore/src/main/java/org/apache/polaris/persistence/nosql/metastore/privs/GrantTriplet.java

@@ -21,12 +21,58 @@
 import static com.google.common.base.Preconditions.checkArgument;
 
 import org.apache.polaris.core.entity.PolarisEntityCore;
+import org.apache.polaris.core.entity.PolarisEntityType;
+import org.apache.polaris.persistence.nosql.api.index.IndexKey;
+import org.apache.polaris.persistence.nosql.coretypes.ObjBase;
+import org.apache.polaris.persistence.nosql.coretypes.acl.GrantsObj;
 
 /**
  * Represents the triplet of catalog-ID, entity-ID and type-code plus a reverse-or-key marker.
- * String representations of this type are used as ACL names and "role" names.
+ *
+ * <p>This is intended to construct {@link IndexKey}s for {@link GrantsObj#acls}, which contain the
+ * "reversed" and "directed" mappings.
+ *
+ * <ul>
+ *   <li>"Reversed" ({@code reverseOrKey == true}, role encoding {@code 'r'}) means <em>from</em> a
+ *       grantee or securable.
+ *   <li>"Directed" ({@code reverseOrKey == false}, role encoding {@code 'd'}) means <em>to</em> a
+ *       grantee (no use case for <em>to</em> securable).
+ * </ul>
+ *
+ * <p>String representations of this type are used as ACL names and "role" names.
+ *
+ * @param reverseOrKey
+ * @param catalogId catalog id
+ * @param id entity id (aka {@link ObjBase#stableId()}
+ * @param typeCode {@link PolarisEntityType#getCode() entity type code}
  */
 public record GrantTriplet(boolean reverseOrKey, long catalogId, long id, int typeCode) {
+
+  /**
+   * Constructs a new {@link GrantTriplet} instance for the given entity, with {@link
+   * #reverseOrKey()} set to {@code true}.
+   */
+  public static GrantTriplet forEntity(PolarisEntityCore entity) {
+    return new GrantTriplet(true, entity.getCatalogId(), entity.getId(), entity.getTypeCode());
+  }
+
+  /** Convert to a "directed" grant-triplet, having {@link #reverseOrKey()} set to {@code false}. */
+  public GrantTriplet asDirected() {
+    return new GrantTriplet(false, catalogId, id, typeCode);
+  }
+
+  /**
+   * Constructs the role name, the encoded string representation, for this triplet in the pattern
+   * {@code [r|d] "/" catalogId "/" id "/" typeCode}
+   */
+  public String toRoleName() {
+    return (reverseOrKey ? "r/" : "d/") + catalogId + "/" + id + "/" + typeCode;
+  }
+
+  /**
+   * Parses a {@link GrantTriplet#toRoleName()}, expecting exactly the pattern {@code [r|d] "/"
+   * catalogId "/" id "/" typeCode}.
+   */
   public static GrantTriplet fromRoleName(String roleName) {
     var c0 = roleName.charAt(0);
     checkArgument(roleName.charAt(1) == '/' && (c0 == 'r' || c0 == 'd'));
@@ -42,16 +88,4 @@ public static GrantTriplet fromRoleName(String roleName) {
 
     return new GrantTriplet(reversed, catalogId, id, typeCode);
   }
-
-  public static GrantTriplet forEntity(PolarisEntityCore entity) {
-    return new GrantTriplet(true, entity.getCatalogId(), entity.getId(), entity.getTypeCode());
-  }
-
-  public GrantTriplet asDirected() {
-    return new GrantTriplet(false, catalogId, id, typeCode);
-  }
-
-  public String toRoleName() {
-    return (reverseOrKey ? "r/" : "d/") + catalogId + "/" + id + "/" + typeCode;
-  }
 }