HIVE-29713 : maintain properties package, update JEXL dependency to JEXL 3.7.0

standalone-metastore/metastore-common/src/main/java/org/apache/hadoop/hive/metastore/properties/HMSPropertyManager.java

@@ -25,14 +25,20 @@
 import java.util.TreeMap;
 
 /**
- * A property manager tailored for the HiveMetaStore.
+ * A property manager tailored for the HiveMetaStore operating on Iceberg tables.
  * It describes properties for cluster, database and table based on declared schemas.
  * A property is of the form:
  * <ul>
  *   <li>name : when it refers to a cluster property named 'name'</li>
  *   <li>db.name : when it refers to a database property named 'name' for the database 'db'</li>
  *   <li>db.table.name : when it refers to a table property named 'name' for the table 'table' in the database 'db'</li>
  * </ul>
+ * <p>
+ *   This is meant as the base of a property manager that could be used to manage properties in the HiveMetaStore
+ *   for Iceberg table maintenance operations.
+ *   It is not meant to be a complete implementation, but rather a starting point for further development.
+ *   A potential extension would be to add maintenance operation properties at the cluster and database levels to the schema
+ *   so they could act as default values for table properties used by maintenance operations.
  */
 public class HMSPropertyManager extends PropertyManager {
   private static final  String CLUSTER_PREFIX = "cluster";
@@ -45,14 +51,13 @@
 
   /** Table maintenance operation type. */
   public enum MaintenanceOpType {
-    COMPACTION,
-    SNAPSHOT_EXPIRY,
-    STATS_REBUILD,
-    MV_BUILD,
-    MV_REFRESH,
-    SHUFFLE_TO_NEW_PART,
-    RECOMPRESS,
-    REORG
+    EXPIRE_SNAPSHOT,
+    REWRITE_DATA_FILES,
+    COMPRESS_DATA_FILES,
+    REWRITE_MANIFEST,
+    DELETE_ORPHAN_FILES,
+    REWRITE_POSITION_DELETE,
+    COMPUTE_TABLE_STATS
   }
 
   /**
@@ -73,12 +78,7 @@
 
   /** Table maintenance operation status. */
   public enum MaintenanceOpStatus {
-    MAINTENANCE_NEEDED,
-    SCHEDULED,
-    IN_PROGRESS,
-    DONE,
-    CLEANUP_NEEDED,
-    FAILED
+    INIT, CANCELED, SUBMITTED, COMPLETED, FAILED
   }
 
   /** The map from ordinal to OpStatus. */
@@ -101,14 +101,14 @@
    */
   public static final PropertyType<MaintenanceOpType> MAINTENANCE_OPERATION = new PropertyType<MaintenanceOpType>("MaintenanceOperation"){
     @Override public MaintenanceOpType cast(Object value) {
-      if (value instanceof MaintenanceOpType) {
-        return (MaintenanceOpType) value;
+      if (value instanceof MaintenanceOpType op) {
+        return op;
       }
       if (value == null) {
         return null;
       }
-      if (value instanceof Number) {
-        return findOpType(((Number) value).intValue());
+      if (value instanceof Number n) {
+        return findOpType(n.intValue());
       }
       return parse(value.toString());
     }
@@ -121,8 +121,8 @@
     }
 
     @Override public String format(Object value) {
-      if (value instanceof MaintenanceOpType) {
-        return value.toString();
+      if (value instanceof MaintenanceOpType op) {
+        return op.toString();
       }
       return null;
     }
@@ -133,14 +133,14 @@
    */
   public static final PropertyType<MaintenanceOpStatus> MAINTENANCE_STATUS = new PropertyType<MaintenanceOpStatus>("MaintenanceStatus"){
     @Override public MaintenanceOpStatus cast(Object value) {
-      if (value instanceof MaintenanceOpStatus) {
-        return (MaintenanceOpStatus) value;
+      if (value instanceof MaintenanceOpStatus op) {
+        return op;
       }
       if (value == null) {
         return null;
       }
-      if (value instanceof Number) {
-        return findOpStatus(((Number) value).intValue());
+      if (value instanceof Number n) {
+        return findOpStatus(n.intValue());
       }
       return parse(value.toString());
     }
@@ -153,8 +153,8 @@
     }
 
     @Override public String format(Object value) {
-      if (value instanceof MaintenanceOpStatus) {
-        return value.toString();
+      if (value instanceof MaintenanceOpStatus op) {
+        return op.toString();
       }
       return null;
     }
@@ -247,12 +247,12 @@
    */
   @Override
   public PropertySchema getSchema(String schemaName) {
-    switch(schemaName) {
-      case CLUSTER_PREFIX: return CLUSTER_SCHEMA;
-      case DATABASE_PREFIX: return DATABASE_SCHEMA;
-      case TABLE_PREFIX: return TABLE_SCHEMA;
-      default: return null;
-    }
+    return switch (schemaName) {
+      case CLUSTER_PREFIX -> CLUSTER_SCHEMA;
+      case DATABASE_PREFIX -> DATABASE_SCHEMA;
+      case TABLE_PREFIX -> TABLE_SCHEMA;
+      default -> null;
+    };
   }
 
   /**

standalone-metastore/metastore-common/src/main/java/org/apache/hadoop/hive/metastore/properties/PropertyManager.java

@@ -75,14 +75,14 @@ public abstract class PropertyManager {
   /** A Jexl engine for convenience. */
   static final JexlEngine JEXL;
   static {
-    JexlFeatures features = new JexlFeatures()
+    JexlFeatures features = JexlFeatures.createDefault()
         .sideEffect(false)
         .sideEffectGlobal(false);
-    JexlPermissions p = JexlPermissions.RESTRICTED
+    JexlPermissions permissions = JexlPermissions.RESTRICTED
         .compose("org.apache.hadoop.hive.metastore.properties.*");
     JEXL = new JexlBuilder()
         .features(features)
-        .permissions(p)
+        .permissions(permissions)
         .create();
   }
 

standalone-metastore/metastore-common/src/main/java/org/apache/hadoop/hive/metastore/properties/PropertyMap.java

@@ -135,7 +135,7 @@ public PropertyMap(PropertyMap src, Map<String, Object> input) {
 
   /**
    * Deserialization ctor.
-   * <p>Used through deserializtion through reflection by the serialization proxy.</p>
+   * <p>Used through deserialization through reflection by the serialization proxy.</p>
    * @param input the input stream
    * @throws IOException if IO fail
    */

standalone-metastore/metastore-common/src/main/java/org/apache/hadoop/hive/metastore/properties/PropertyStore.java

@@ -25,7 +25,7 @@
 
 /**
  * The PropertyStore is the persistent container of property maps.
- * Maps are addressed in the store by their key -  their name prepended by their manager"s namespace.
+ * Maps are addressed in the store by their key - their name prepended by their manager"s namespace.
  */
 
 public abstract class PropertyStore {

standalone-metastore/metastore-common/src/main/java/org/apache/hadoop/hive/metastore/properties/PropertyType.java

@@ -182,8 +182,8 @@ public String parse(String str) {
 
     @Nullable
     @Override public String format(Object value) {
-      if (value instanceof Boolean) {
-        return ((Boolean) value) ? "true" : "false";
+      if (value instanceof Boolean b) {
+        return b.toString();
       }
       return null;
     }
@@ -201,8 +201,8 @@ public Boolean read(DataInput in) throws IOException {
 
   public static final PropertyType<Integer> INTEGER = new PropertyType<Integer>("integer") {
     @Override public Integer cast(Object value) {
-      if (value instanceof Number) {
-        return ((Number) value).intValue();
+      if (value instanceof Number n) {
+        return n.intValue();
       }
       if (value == null) {
         return null;
@@ -241,8 +241,8 @@ public Integer read(DataInput in) throws IOException {
 
   public static final PropertyType<Long> LONG = new PropertyType<Long>("long"){
     @Override public Long cast(Object value) {
-      if (value instanceof Number) {
-        return ((Number) value).longValue();
+      if (value instanceof Number n) {
+        return n.longValue();
       }
       if (value == null) {
         return null;
@@ -281,11 +281,11 @@ public Long read(DataInput in) throws IOException {
 
   public static final PropertyType<Date> DATETIME = new PropertyType<Date>("date"){
     @Override public Date cast(Object value) {
-      if (value instanceof Number) {
-        return new Date(((Number) value).longValue());
+      if (value instanceof Number n) {
+        return new Date(n.longValue());
       }
-      if (value instanceof Date) {
-        return (Date) value;
+      if (value instanceof Date d) {
+        return d;
       }
       if (value == null) {
         return null;
@@ -322,8 +322,8 @@ public Long read(DataInput in) throws IOException {
 
   public static final PropertyType<Double> DOUBLE = new PropertyType<Double>("double"){
     @Override public Double cast(Object value) {
-      if (value instanceof Number) {
-        return ((Number) value).doubleValue();
+      if (value instanceof Number n) {
+        return n.doubleValue();
       }
       if (value == null) {
         return null;

standalone-metastore/metastore-common/src/main/java/org/apache/hadoop/hive/metastore/properties/SerializationProxy.java

@@ -33,6 +33,7 @@
 import java.io.ObjectOutput;
 import java.io.ObjectOutputStream;
 import java.io.OutputStream;
+import java.io.Serial;
 import java.io.Serializable;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.Executable;
@@ -75,6 +76,7 @@
  */
 public class SerializationProxy<T extends Serializable> implements Externalizable {
   /** Serial version. */
+  @Serial
   private static final long serialVersionUID = 202212281757L;
   /** The logger. */
   public static final Logger LOGGER = LoggerFactory.getLogger(SerializationProxy.class);

standalone-metastore/metastore-common/src/main/java/org/apache/hadoop/hive/metastore/properties/package-info.java

@@ -0,0 +1,83 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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
+ *
+ *     http://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.
+ */
+
+/**
+ * Type-safe, schema-driven property management for Hive metastore objects (clusters, databases, tables).
+ *
+ * <p>This package allows declaring, validating, and persisting custom properties with runtime type
+ * checking and serialization support.</p>
+ *
+ * <h2>Core Components</h2>
+ *
+ * <h3>{@link org.apache.hadoop.hive.metastore.properties.PropertySchema}</h3>
+ * <p>Defines the blueprint for what properties can be set on a metastore object.</p>
+ * <ul>
+ *   <li>Declares allowed properties and their types (STRING, INTEGER, BOOLEAN, DATE, JSON, etc.)</li>
+ *   <li>Manages default values for properties</li>
+ *   <li>Tracks schema version — incremented when properties are added or removed</li>
+ *   <li>Generates a digest (UUID) for schema identity and caching</li>
+ * </ul>
+ *
+ * <h3>{@link org.apache.hadoop.hive.metastore.properties.PropertyType}</h3>
+ * <p>Abstract type system for property values with parsing, formatting, and binary serialization.
+ * Built-in types: {@code STRING}, {@code BOOLEAN}, {@code INTEGER}, {@code LONG}, {@code DOUBLE},
+ * {@code DATETIME} (ISO8601/UTC), {@code JSON} (Gson-backed). Custom types can be registered via
+ * {@link org.apache.hadoop.hive.metastore.properties.PropertyType#register(PropertyType)}.</p>
+ *
+ * <h3>{@link org.apache.hadoop.hive.metastore.properties.PropertyMap}</h3>
+ * <p>Holds the actual property values for a specific metastore object instance, validated against
+ * a {@code PropertySchema}. Uses copy-on-write semantics gated by a dirty flag for thread-safe,
+ * efficient sharing.</p>
+ *
+ * <h3>{@link org.apache.hadoop.hive.metastore.properties.PropertyManager}</h3>
+ * <p>High-level per-session manager that ties schemas into one namespace and drives transactional
+ * reads and writes. Tracks dirty maps to batch persistence store updates. Integrates with JEXL
+ * for dynamic property expressions.</p>
+ *
+ * <h3>{@link org.apache.hadoop.hive.metastore.properties.PropertyStore}</h3>
+ * <p>Persistence layer for loading and saving property maps to the metastore database.
+ * Can be wrapped by {@link org.apache.hadoop.hive.metastore.properties.CachingPropertyStore}
+ * for performance.</p>
+ *
+ * <h2>Workflow Example</h2>
+ * <pre>{@code
+ * // Define a schema (typically done at startup)
+ * PropertySchema tableSchema = new PropertySchema("table-schema", 1, new TreeMap<>());
+ * tableSchema.declareProperty("owner", PropertyType.STRING, "admin");
+ * tableSchema.declareProperty("is_external", PropertyType.BOOLEAN, false);
+ * tableSchema.declareProperty("created_time", PropertyType.DATETIME);
+ *
+ * // Create a property map for an object, set values, and persist
+ * PropertyMap tableProps = manager.newPropertyMap(tableSchema);
+ * tableProps.put("owner", "alice");
+ * tableProps.put("is_external", true);
+ * manager.persistProperties(tableProps);
+ * }</pre>
+ *
+ * <h2>Design Patterns</h2>
+ * <ul>
+ *   <li><b>Thread safety</b>: schemas use {@code AtomicInteger} version counters; maps use
+ *       copy-on-write with dirty flags; digest computation is double-checked locked.</li>
+ *   <li><b>Serialization</b>: a custom {@link org.apache.hadoop.hive.metastore.properties.SerializationProxy}
+ *       handles transient fields safely; both {@code DataInput}/{@code DataOutput} and Java object
+ *       serialization are supported.</li>
+ *   <li><b>Schema versioning</b>: version and digest UUID allow detecting schema changes and
+ *       support schema evolution without breaking existing data.</li>
+ * </ul>
+ */
+package org.apache.hadoop.hive.metastore.properties;