Document the behavior of customMetadataLocation

Author: liamzwbao

integration-tests/src/main/java/org/apache/polaris/service/it/test/PolarisRestCatalogViewIntegrationBase.java

@@ -52,7 +52,6 @@
 import org.junit.jupiter.api.Assumptions;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestInfo;
 import org.junit.jupiter.api.extension.ExtendWith;
@@ -179,10 +178,8 @@ protected boolean overridesRequestedLocation() {
     return true;
   }
 
-  /** TODO: Unblock this test, see: https://github.com/apache/polaris/issues/1273 */
   @Override
   @Test
-  @Disabled
   public void createViewWithCustomMetadataLocation() {
     Assertions.assertThatThrownBy(super::createViewWithCustomMetadataLocation)
         .isInstanceOf(ForbiddenException.class)
@@ -209,6 +206,8 @@ public void createViewWithCustomMetadataLocationUsingPolaris(@TempDir Path tempD
 
     assertThat(catalog().viewExists(identifier)).as("View should not exist").isFalse();
 
+    // CAN create a view with a custom metadata location `baseLocation/customLocation`,
+    // as long as the location is within the parent namespace's `write.metadata.path=baseLocation`
     View view =
         catalog()
             .buildView(identifier)
@@ -228,6 +227,9 @@ public void createViewWithCustomMetadataLocationUsingPolaris(@TempDir Path tempD
         .isNotNull()
         .startsWith(customLocation);
 
+    // CANNOT update the view with a new metadata location `baseLocation/customLocation2`,
+    // even though the new location is still under the parent namespace's
+    // `write.metadata.path=baseLocation`.
     Assertions.assertThatThrownBy(
             () ->
                 catalog()
@@ -240,15 +242,19 @@ public void createViewWithCustomMetadataLocationUsingPolaris(@TempDir Path tempD
         .isInstanceOf(ForbiddenException.class)
         .hasMessageContaining("Forbidden: Invalid locations");
 
-    catalog()
-        .loadView(identifier)
-        .updateProperties()
-        .set(IcebergTableLikeEntity.USER_SPECIFIED_WRITE_METADATA_LOCATION_KEY, customLocationChild)
-        .commit();
-    View childView = catalog().loadView(identifier);
-    assertThat(childView.properties()).containsEntry("write.metadata.path", customLocationChild);
-    assertThat(((BaseView) childView).operations().current().metadataFileLocation())
-        .isNotNull()
-        .startsWith(customLocationChild);
+    // CANNOT update the view with a child metadata location `baseLocation/customLocation/child`,
+    // even though it is a subpath of the original view's
+    // `write.metadata.path=baseLocation/customLocation`.
+    Assertions.assertThatThrownBy(
+            () ->
+                catalog()
+                    .loadView(identifier)
+                    .updateProperties()
+                    .set(
+                        IcebergTableLikeEntity.USER_SPECIFIED_WRITE_METADATA_LOCATION_KEY,
+                        customLocationChild)
+                    .commit())
+        .isInstanceOf(ForbiddenException.class)
+        .hasMessageContaining("Forbidden: Invalid locations");
   }
 }

polaris-core/src/main/java/org/apache/polaris/core/storage/PolarisStorageConfigurationInfo.java

@@ -181,6 +181,7 @@ public static Optional<PolarisStorageConfigurationInfo> forEntityPath(
                     "Allowing unstructured table location for entity: {}",
                     entityPathReversed.get(0).getName());
 
+                // TODO: figure out the purpose of adding `userSpecifiedWriteLocations`
                 List<String> locs =
                     userSpecifiedWriteLocations(entityPathReversed.get(0).getPropertiesAsMap());
                 return new StorageConfigurationOverride(