Fix #11127: enforce non-null keys for InputLocation lookups and document behavior (master)

src/mdo/java/InputLocation.java

@@ -99,6 +99,7 @@ public InputSource getSource() {
 
     @Override
     public InputLocation getLocation(Object key) {
+        Objects.requireNonNull(key, "key");
         return locations != null ? locations.get(key) : null;
     }
 

src/mdo/java/InputLocationTracker.java

@@ -18,7 +18,23 @@
  */
 package ${package};
 
+/**
+ * Tracks input source locations for model fields.
+ * <p>
+ * Implementations provide a mapping from keys (typically field names or indices) to
+ * {@link InputLocation} instances to support precise error reporting and diagnostics.
+ * Keys must be non-null.
+ *
+ * @since 4.0.0
+ */
 public interface InputLocationTracker {
+    /**
+     * Gets the location of the specified field in the input source.
+     *
+     * @param field the key of the field, must not be {@code null}
+     * @return the location of the field in the input source or {@code null} if unknown
+     * @throws NullPointerException if {@code field} is {@code null}
+     */
     InputLocation getLocation(Object field);
 
     /**

src/mdo/model.vm

@@ -240,8 +240,13 @@ public class ${class.name}
     #if ( $locationTracking && !$class.superClass )
     /**
      * Gets the location of the specified field in the input source.
+     *
+     * @param key the key of the field, must not be {@code null}
+     * @return the location of the field in the input source or {@code null} if unknown
+     * @throws NullPointerException if {@code key} is {@code null}
      */
     public InputLocation getLocation(Object key) {
+        Objects.requireNonNull(key, "key");
         return locations.get(key);
     }