Add type-check to PolarisEntity subclass ctors

[XN137]

currently one can freely "cast" any PolarisEntity to a more
specific type via their constructors.

this can lead to subtle bugs like we fixed in
a29f800

by adding type checks we discover a few more places where we need to be
more careful about how we construct new or handle existing entities.

note that we can add a check for PolarisEntitySubType in a followup,
but it requires more fixes currently.

[XN137]

without this change the CatalogFederationIT was failing:

getTableEntity: ns1.test_table -> resolvedPath:[entity:name=test_catalog_external;id=6;parentId=0;entityVersion=1;type=CATALOG;subType=NULL_SUBTYPE;internalProperties={catalogType=EXTERNAL, storage_configuration_info={"@type":"FileStorageConfigurationInfo","allowedLocations":["file:///tmp/warehouse"],"storageType":"FILE","fileIoImplClassName":"org.apache.iceberg.hadoop.HadoopFileIO"}, connection_configuration_info={"uri":"http://localhost:42705/api/catalog","authenticationParameters":{"tokenUri":"http://localhost:42705/api/catalog/v1/oauth/tokens","clientId":"71667f9b548ce462","clientSecretReference":{"urn":"urn:polaris-secret:unsafe-in-memory:6:0","referencePayload":{"ciphertext-hash":"adf96dbbdf0d7b85a4940ff1e5bd912526fab136e9b66896efcd641be8bd3c6c","encryption-key":"hDB047wH0cue+kMm6v28HhJI9cK6JOs63SWqzR39V+o="}},"scopes":["PRINCIPAL_ROLE:ALL"],"authenticationTypeCode":1},"remoteCatalogName":"test_catalog_local","connectionTypeCode":1}};grantRecordsAsGrantee:[];grantRecordsAsSecurable:[PolarisGrantRec{securableCatalogId=0, securableId=6, granteeCatalogId=6, granteeId=7, privilegeCode=2}, PolarisGrantRec{securableCatalogId=0, securableId=6, granteeCatalogId=6, granteeId=7, privilegeCode=21}, PolarisGrantRec{securableCatalogId=0, securableId=6, granteeCatalogId=6, granteeId=7, privilegeCode=31}]] -> name=test_catalog_external;id=6;parentId=0;entityVersion=1;type=CATALOG;subType=NULL_SUBTYPE;internalProperties={catalogType=EXTERNAL, storage_configuration_info={"@type":"FileStorageConfigurationInfo","allowedLocations":["file:///tmp/warehouse"],"storageType":"FILE","fileIoImplClassName":"org.apache.iceberg.hadoop.HadoopFileIO"}, connection_configuration_info={"uri":"http://localhost:42705/api/catalog","authenticationParameters":{"tokenUri":"http://localhost:42705/api/catalog/v1/oauth/tokens","clientId":"71667f9b548ce462","clientSecretReference":{"urn":"urn:polaris-secret:unsafe-in-memory:6:0","referencePayload":{"ciphertext-hash":"adf96dbbdf0d7b85a4940ff1e5bd912526fab136e9b66896efcd641be8bd3c6c","encryption-key":"hDB047wH0cue+kMm6v28HhJI9cK6JOs63SWqzR39V+o="}},"scopes":["PRINCIPAL_ROLE:ALL"],"authenticationTypeCode":1},"remoteCatalogName":"test_catalog_local","connectionTypeCode":1}}
2025-08-25 08:43:48,888 INFO  [org.apa.pol.ser.exc.IcebergExceptionMapper] [,POLARIS] [,,,] (executor-thread-1) Handling runtimeException Invalid entity type: CATALOG
2025-08-25 08:43:48,888 INFO  [org.apa.pol.ser.exc.IcebergExceptionMapper] [,POLARIS] [,,,] (executor-thread-1) Full RuntimeException: java.lang.IllegalStateException: Invalid entity type: CATALOG
	at com.google.common.base.Preconditions.checkState(Preconditions.java:603)
	at org.apache.polaris.core.entity.table.TableLikeEntity.<init>(TableLikeEntity.java:41)
	at org.apache.polaris.core.entity.table.IcebergTableLikeEntity.<init>(IcebergTableLikeEntity.java:49)
	at org.apache.polaris.core.entity.table.IcebergTableLikeEntity.of(IcebergTableLikeEntity.java:54)
	at org.apache.polaris.service.catalog.iceberg.IcebergCatalogHandler.getTableEntity(IcebergCatalogHandler.java:578)
	at org.apache.polaris.service.catalog.iceberg.IcebergCatalogHandler.loadTableIfStale(IcebergCatalogHandler.java:603)
	at org.apache.polaris.service.catalog.iceberg.IcebergCatalogAdapter.lambda$loadTable$10(IcebergCatalogAdapter.java:431)
	at org.apache.polaris.service.catalog.iceberg.IcebergCatalogAdapter.withCatalog(IcebergCatalogAdapter.java:193)
	at org.apache.polaris.service.catalog.iceberg.IcebergCatalogAdapter.loadTable(IcebergCatalogAdapter.java:422)
	at org.apache.polaris.service.catalog.iceberg.IcebergCatalogAdapter_ClientProxy.loadTable(Unknown Source)

[dimas-b]

I wonder how the entity path ends up pointing to a CATALOG when it's a loadTable call 🤔

[XN137]

idk how external catalog integration works under the hood but in the first output line (that i had added) we can see that the PolarisResolvedPathWrapper ends up pointing to the external catalog entity (which is also the leaf element).

so i assumed for external catalogs in general we dont have any actual entity representing the table? but maybe this is just an artifact of an incorrectly written test idk.

the return value of getTableEntity is only used for supporting ETags not for loading the table:

polaris/runtime/service/src/main/java/org/apache/polaris/service/catalog/iceberg/IcebergCatalogHandler.java

Lines 601 to 619 in 3f1dfb3

	if (ifNoneMatch != null) {
	// Perform freshness-aware table loading if caller specified ifNoneMatch.
	IcebergTableLikeEntity tableEntity = getTableEntity(tableIdentifier);
	if (tableEntity == null || tableEntity.getMetadataLocation() == null) {
	LOGGER
	.atWarn()
	.addKeyValue("tableIdentifier", tableIdentifier)
	.addKeyValue("tableEntity", tableEntity)
	.log("Failed to getMetadataLocation to generate ETag when loading table");
	} else {
	// TODO: Refactor null-checking into the helper method once we create a more canonical
	// interface for associate etags with entities.
	String tableEntityTag =
	IcebergHttpUtil.generateETagForMetadataFileLocation(tableEntity.getMetadataLocation());
	if (ifNoneMatch.anyMatch(tableEntityTag)) {
	return Optional.empty();
	}
	}
	}

[dimas-b]

@dennishuo : do you have any insight to share?

[dimas-b]

to be clear: this conversation is interesting, but the changes in this PR still make sense from my POV 🙂

[dimas-b]

The refactoring LGTM 👍