Add more comments and reorganize the structure

Author: XJDKC

polaris-core/src/main/java/org/apache/polaris/core/connection/ConnectionConfigInfoDpo.java

@@ -18,7 +18,11 @@
  */
 package org.apache.polaris.core.connection;
 
-import com.fasterxml.jackson.annotation.*;
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonSubTypes;
+import com.fasterxml.jackson.annotation.JsonTypeInfo;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.DeserializationFeature;
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -195,7 +199,7 @@ public static ConnectionConfigInfoDpo fromConnectionConfigInfoModelWithSecrets(
   }
 
   public abstract ConnectionConfigInfoDpo withServiceIdentity(
-      ServiceIdentityInfoDpo serviceIdentityInfo);
+      @Nonnull ServiceIdentityInfoDpo serviceIdentityInfo);
 
   /**
    * Produces the correponding API-model ConnectionConfigInfo for this persistence object; many

polaris-core/src/main/java/org/apache/polaris/core/connection/SigV4AuthenticationParametersDpo.java

@@ -39,18 +39,24 @@
  */
 public class SigV4AuthenticationParametersDpo extends AuthenticationParametersDpo {
 
+  // The aws IAM role arn assumed by polaris userArn when signing requests
   @JsonProperty(value = "roleArn")
   private final String roleArn;
 
+  // The session name used when assuming the role
   @JsonProperty(value = "roleSessionName")
   private final String roleSessionName;
 
+  // An optional external id used to establish a trust relationship with AWS in the trust policy
   @JsonProperty(value = "externalId")
   private final String externalId;
 
+  // Region to be used by the SigV4 protocol for signing requests
   @JsonProperty(value = "signingRegion")
   private final String signingRegion;
 
+  // The service name to be used by the SigV4 protocol for signing requests, the default signing
+  // name is "execute-api" is if not provided
   @JsonProperty(value = "signingName")
   private final String signingName;
 

polaris-core/src/main/java/org/apache/polaris/core/connection/hadoop/HadoopConnectionConfigInfoDpo.java

@@ -65,6 +65,7 @@ public String toString() {
         .add("uri", getUri())
         .add("warehouse", getWarehouse())
         .add("authenticationParameters", getAuthenticationParameters().toString())
+        .add("serviceIdentity", getServiceIdentity())
         .toString();
   }
 

polaris-core/src/main/java/org/apache/polaris/core/connection/iceberg/IcebergRestConnectionConfigInfoDpo.java

@@ -80,7 +80,8 @@ public String getRemoteCatalogName() {
   }
 
   @Override
-  public ConnectionConfigInfoDpo withServiceIdentity(ServiceIdentityInfoDpo serviceIdentityInfo) {
+  public ConnectionConfigInfoDpo withServiceIdentity(
+      @Nonnull ServiceIdentityInfoDpo serviceIdentityInfo) {
     return new IcebergRestConnectionConfigInfoDpo(
         getUri(), getAuthenticationParameters(), serviceIdentityInfo, getRemoteCatalogName());
   }

polaris-core/src/main/java/org/apache/polaris/core/credentials/DefaultPolarisCredentialManager.java

@@ -20,6 +20,7 @@
 package org.apache.polaris.core.credentials;
 
 import com.google.common.annotations.VisibleForTesting;
+import jakarta.annotation.Nonnull;
 import java.util.EnumMap;
 import java.util.Optional;
 import org.apache.polaris.core.connection.AuthenticationParametersDpo;
@@ -35,6 +36,17 @@
 import software.amazon.awssdk.services.sts.model.AssumeRoleRequest;
 import software.amazon.awssdk.services.sts.model.AssumeRoleResponse;
 
+/**
+ * Default implementation of {@link PolarisCredentialManager} responsible for retrieving credentials
+ * used by Polaris to access external systems such as remote catalogs or cloud storage.
+ *
+ * <p>It resolves a {@link ServiceIdentityInfoDpo} into a {@link ResolvedServiceIdentity} using the
+ * {@link ServiceIdentityRegistry}, then uses the provided authentication parameters to generate
+ * temporary access credentials (e.g., via AWS STS AssumeRole).
+ *
+ * <p>This implementation currently supports AWS IAM service identities and can be extended to
+ * support other identity types or external services beyond catalogs, such as cloud storage.
+ */
 public class DefaultPolarisCredentialManager implements PolarisCredentialManager {
   private final ServiceIdentityRegistry serviceIdentityRegistry;
 
@@ -43,7 +55,7 @@ public DefaultPolarisCredentialManager(ServiceIdentityRegistry serviceIdentityRe
   }
 
   @Override
-  public EnumMap<ConnectionCredentialProperty, String> getConnectionCredentials(
+  public @Nonnull EnumMap<ConnectionCredentialProperty, String> getConnectionCredentials(
       ServiceIdentityInfoDpo serviceIdentity,
       AuthenticationParametersDpo authenticationParameters) {
     EnumMap<ConnectionCredentialProperty, String> credentialMap =

polaris-core/src/main/java/org/apache/polaris/core/credentials/PolarisCredentialManager.java

@@ -19,14 +19,36 @@
 
 package org.apache.polaris.core.credentials;
 
+import jakarta.annotation.Nonnull;
 import java.util.EnumMap;
 import org.apache.polaris.core.connection.AuthenticationParametersDpo;
 import org.apache.polaris.core.credentials.connection.ConnectionCredentialProperty;
 import org.apache.polaris.core.credentials.connection.PolarisConnectionCredsVendor;
 import org.apache.polaris.core.identity.dpo.ServiceIdentityInfoDpo;
 
+/**
+ * PolarisCredentialManager is responsible for retrieving the credentials Polaris needs to access
+ * remote services such as federated catalogs or cloud storage.
+ *
+ * <p>It combines service-managed identity information (e.g., an IAM user Polaris uses) with
+ * user-defined authentication parameters (e.g., roleArn) to generate the credentials required for
+ * authentication with external systems.
+ *
+ * <p>Typical flow:
+ *
+ * <ol>
+ *   <li>Resolve the service identity and locate its associated credential (e.g., from a secret
+ *       manager via the service identity registry).
+ *   <li>Use the resolved identity together with the authentication parameters to obtain the final
+ *       access credentials.
+ * </ol>
+ *
+ * <p>This design supports both SaaS and self-managed deployments, ensuring a clear separation
+ * between user-provided configuration and Polaris-managed identity.
+ */
 public interface PolarisCredentialManager extends PolarisConnectionCredsVendor {
   @Override
+  @Nonnull
   EnumMap<ConnectionCredentialProperty, String> getConnectionCredentials(
       ServiceIdentityInfoDpo serviceIdentity, AuthenticationParametersDpo authenticationParameters);
 }

polaris-core/src/main/java/org/apache/polaris/core/credentials/connection/ConnectionCredentialProperty.java

@@ -21,6 +21,12 @@
 
 import org.apache.iceberg.aws.AwsProperties;
 
+/**
+ * A subset of Iceberg catalog properties recognized by Polaris.
+ *
+ * <p>Most of these properties are meant to initialize Catalog objects for accessing the remote
+ * Catalog service.
+ */
 public enum ConnectionCredentialProperty {
   AWS_ACCESS_KEY_ID(String.class, AwsProperties.REST_ACCESS_KEY_ID, "the aws access key id"),
   AWS_SECRET_ACCESS_KEY(

polaris-core/src/main/java/org/apache/polaris/core/credentials/connection/PolarisConnectionCredsVendor.java

@@ -19,11 +19,39 @@
 
 package org.apache.polaris.core.credentials.connection;
 
+import jakarta.annotation.Nonnull;
 import java.util.EnumMap;
 import org.apache.polaris.core.connection.AuthenticationParametersDpo;
 import org.apache.polaris.core.identity.dpo.ServiceIdentityInfoDpo;
 
+/**
+ * Generates credentials Polaris uses to connect to external catalog services such as AWS Glue or
+ * other federated endpoints. Implementations combine service-managed identity metadata (such as an
+ * IAM user or role, defined in {@link ServiceIdentityInfoDpo}) with user-provided authentication
+ * parameters (such as a role ARN or external ID, defined in {@link AuthenticationParametersDpo}) to
+ * construct a credential map consumable by Polaris.
+ *
+ * <p>This interface allows pluggable behavior for different authentication mechanisms and service
+ * vendors. Implementations can support service-specific credential provisioning or caching
+ * strategies as needed.
+ */
 public interface PolarisConnectionCredsVendor {
+
+  /**
+   * Retrieve credential values required to authenticate a remote connection.
+   *
+   * <p>The returned credentials are derived using the combination of Polaris-managed service
+   * identity and user-specified connection authentication parameters. Implementations may look up
+   * the service identity credential from a secret store or local config, and use it in conjunction
+   * with user-supplied data to produce scoped credentials for accessing remote services.
+   *
+   * @param serviceIdentity Polaris-managed identity metadata, including a reference to the backing
+   *     credential (e.g., a secret ARN or ID)
+   * @param authenticationParameters Authentication configuration supplied by the Polaris user
+   * @return A map from {@link ConnectionCredentialProperty} to the resolved credential value, used
+   *     by downstream systems to establish the connection
+   */
+  @Nonnull
   EnumMap<ConnectionCredentialProperty, String> getConnectionCredentials(
       ServiceIdentityInfoDpo serviceIdentity, AuthenticationParametersDpo authenticationParameters);
 }

polaris-core/src/main/java/org/apache/polaris/core/identity/dpo/AwsIamServiceIdentityInfoDpo.java

@@ -30,6 +30,17 @@
 import org.apache.polaris.core.identity.ServiceIdentityType;
 import org.apache.polaris.core.secrets.ServiceSecretReference;
 
+/**
+ * Persistence-layer representation of an AWS IAM service identity used by Polaris.
+ *
+ * <p>This class models an AWS IAM identity (either a user or role) and extends {@link
+ * ServiceIdentityInfoDpo}. It is typically used internally to store both the identity metadata
+ * (such as the IAM ARN) and a reference to the actual credential (e.g., via {@link
+ * ServiceSecretReference}).
+ *
+ * <p>Instances of this class are convertible to the public API model {@link
+ * AwsIamServiceIdentityInfo}.
+ */
 public class AwsIamServiceIdentityInfoDpo extends ServiceIdentityInfoDpo {
 
   // Technically, it should be ^arn:(aws|aws-cn|aws-us-gov):iam::(\d{12}):(user|role)/.+$,

polaris-core/src/main/java/org/apache/polaris/core/identity/dpo/ServiceIdentityInfoDpo.java

@@ -68,6 +68,10 @@ public ServiceSecretReference getIdentityInfoReference() {
     return identityInfoReference;
   }
 
+  /**
+   * Converts this persistence object to the corresponding API model. During the conversion, some
+   * fields will be dropped, e.g. the reference to the service identity's credential
+   */
   public abstract @Nonnull ServiceIdentityInfo asServiceIdentityInfoModel();
 
   @Override

polaris-core/src/main/java/org/apache/polaris/core/identity/mutation/EntityMutationEngine.java

@@ -21,6 +21,21 @@
 
 import org.apache.polaris.core.entity.PolarisBaseEntity;
 
+/**
+ * Engine responsible for applying a sequence of {@link EntityMutator} transformations to a {@link
+ * PolarisBaseEntity}.
+ *
+ * <p>This abstraction allows Polaris to customize or enrich entities during runtime or persistence,
+ * based on configured or contextual logic (e.g., injecting service identity info, computing derived
+ * fields).
+ */
 public interface EntityMutationEngine {
+  /**
+   * Applies all registered entity mutators to the provided entity, in order.
+   *
+   * @param entity The original Polaris entity to mutate.
+   * @return A new or modified instance of {@link PolarisBaseEntity} after all mutations are
+   *     applied.
+   */
   PolarisBaseEntity applyMutations(PolarisBaseEntity entity);
 }

service/common/src/main/java/org/apache/polaris/service/identity/mutation/EntityMutator.java renamed to polaris-core/src/main/java/org/apache/polaris/core/identity/mutation/EntityMutator.java

@@ -17,10 +17,23 @@
  * under the License.
  */
 
-package org.apache.polaris.service.identity.mutation;
+package org.apache.polaris.core.identity.mutation;
 
 import org.apache.polaris.core.entity.PolarisBaseEntity;
 
+/**
+ * A transformation hook that mutates a Polaris entity.
+ *
+ * <p>Implementations of this interface apply custom logic to modify or enrich a {@link
+ * PolarisBaseEntity}.
+ */
 public interface EntityMutator {
+
+  /**
+   * Applies the mutation logic to the given entity.
+   *
+   * @param entity the entity to mutate
+   * @return the mutated entity
+   */
   PolarisBaseEntity apply(PolarisBaseEntity entity);
 }

polaris-core/src/main/java/org/apache/polaris/core/identity/registry/DefaultServiceIdentityRegistry.java

@@ -27,9 +27,27 @@
 import org.apache.polaris.core.identity.dpo.ServiceIdentityInfoDpo;
 import org.apache.polaris.core.identity.resolved.ResolvedServiceIdentity;
 
+/**
+ * Default implementation of {@link ServiceIdentityRegistry} that resolves service identities from
+ * statically configured values (typically defined via Quarkus server configuration).
+ *
+ * <p>This implementation supports both multi-tenant (e.g., SaaS) and self-managed (single-tenant)
+ * Polaris deployments:
+ *
+ * <ul>
+ *   <li>In multi-tenant mode, each tenant (realm) can have its own set of service identities
+ *       defined in the configuration. The same identity will consistently be assigned for each
+ *       {@link ServiceIdentityType} within a given tenant.
+ *   <li>In single-tenant or self-managed deployments, a single set of service identities can be
+ *       defined and used system-wide.
+ * </ul>
+ */
 public class DefaultServiceIdentityRegistry implements ServiceIdentityRegistry {
 
+  /** Map of service identity types to their resolved identities. */
   private final EnumMap<ServiceIdentityType, ResolvedServiceIdentity> resolvedServiceIdentities;
+
+  /** Map of identity info references (URNs) to their resolved service identities. */
   private final Map<String, ResolvedServiceIdentity> referenceToResolvedServiceIdentity;
 
   public DefaultServiceIdentityRegistry(

polaris-core/src/main/java/org/apache/polaris/core/identity/registry/ServiceIdentityRegistry.java

@@ -23,14 +23,34 @@
 import org.apache.polaris.core.identity.dpo.ServiceIdentityInfoDpo;
 import org.apache.polaris.core.identity.resolved.ResolvedServiceIdentity;
 
+/**
+ * A registry interface for managing and resolving service identities in Polaris.
+ *
+ * <p>In a multi-tenant Polaris deployment, each catalog or tenant may be associated with a distinct
+ * service identity that represents the Polaris service itself when accessing external systems
+ * (e.g., cloud services like AWS or GCP). This registry provides a central mechanism to manage
+ * those identities and resolve them at runtime.
+ *
+ * <p>The registry helps abstract the configuration and retrieval of service-managed credentials
+ * from the logic that uses them. It ensures a consistent and secure way to handle identity
+ * resolution across different deployment models, including SaaS and self-managed environments.
+ */
 public interface ServiceIdentityRegistry {
+  /**
+   * Assigns a new {@link ServiceIdentityInfoDpo} for the given service identity type. Typically
+   * used during entity creation to associate a default or generated identity.
+   *
+   * @param serviceIdentityType The type of service identity (e.g., AWS_IAM).
+   * @return A new {@link ServiceIdentityInfoDpo} representing the assigned service identity.
+   */
   ServiceIdentityInfoDpo assignServiceIdentity(ServiceIdentityType serviceIdentityType);
 
   /**
-   * Resolves the service identity based on the provided service identity information.
+   * Resolves the given service identity by retrieving the actual credential or secret referenced by
+   * it, typically from a secret manager or internal credential store.
    *
-   * @param serviceIdentityInfo The service identity information to resolve.
-   * @return The resolved service identity.
+   * @param serviceIdentityInfo The service identity metadata to resolve.
+   * @return A {@link ResolvedServiceIdentity} including credentials and other resolved data.
    */
   ResolvedServiceIdentity resolveServiceIdentity(ServiceIdentityInfoDpo serviceIdentityInfo);
 }

polaris-core/src/main/java/org/apache/polaris/core/identity/registry/ServiceIdentityRegistryFactory.java

@@ -21,6 +21,12 @@
 
 import org.apache.polaris.core.context.RealmContext;
 
+/**
+ * Factory for creating {@link ServiceIdentityRegistry} instances.
+ *
+ * <p>Each {@link ServiceIdentityRegistry} instance is associated with a {@link RealmContext} and is
+ * responsible for managing the service identities for the user in that realm.
+ */
 public interface ServiceIdentityRegistryFactory {
   ServiceIdentityRegistry getOrCreateServiceIdentityRegistry(RealmContext realmContext);
 }

polaris-core/src/main/java/org/apache/polaris/core/identity/resolved/ResolvedAwsIamServiceIdentity.java

@@ -31,10 +31,29 @@
 import software.amazon.awssdk.services.sts.StsClient;
 import software.amazon.awssdk.services.sts.StsClientBuilder;
 
+/**
+ * Represents a fully resolved AWS IAM service identity, including the associated IAM ARN and
+ * credentials. This class is used internally by Polaris to access AWS services on behalf of a
+ * configured service identity.
+ *
+ * <p>It contains AWS credentials (access key, secret, and optional session token) and provides a
+ * lazily initialized {@link StsClient} for performing role assumptions or identity verification.
+ *
+ * <p>The resolved identity can be converted back into its persisted DPO form using {@link
+ * #asServiceIdentityInfoDpo()}.
+ */
 public class ResolvedAwsIamServiceIdentity extends ResolvedServiceIdentity {
+
+  /** IAM role or user ARN representing the Polaris service identity. */
   private final String iamArn;
+
+  /** AWS access key ID of the AWS credential associated with the identity. */
   private final String accessKeyId;
+
+  /** AWS secret access key of the AWS credential associated with the identity. */
   private final String secretAccessKey;
+
+  /** The AWS session token of the AWS credential associated with the identity. */
   private final String sessionToken;
 
   public ResolvedAwsIamServiceIdentity(
@@ -77,6 +96,7 @@ public ServiceIdentityInfoDpo asServiceIdentityInfoDpo() {
     return new AwsIamServiceIdentityInfoDpo(getIdentityInfoReference(), getIamArn());
   }
 
+  /** Returns a memoized supplier for creating an STS client using the resolved credentials. */
   public Supplier<StsClient> stsClientSupplier() {
     return Suppliers.memoize(
         () -> {

polaris-core/src/main/java/org/apache/polaris/core/identity/resolved/ResolvedServiceIdentity.java

@@ -57,5 +57,6 @@ public void setIdentityInfoReference(@NotNull ServiceSecretReference identityInf
     this.identityInfoReference = identityInfoReference;
   }
 
+  /** Converts this resolved identity into its corresponding persisted form (DPO). */
   public abstract @Nonnull ServiceIdentityInfoDpo asServiceIdentityInfoDpo();
 }