Add detailed unknown column error handling

Introduced `UnknownColumnAdditionalInfoException` to provide enhanced error details, including a mapping table. Updated `UnknownColumnHandler` to support additional context using a column name map and added `ColumnNameMapFormatter` for formatted table creation. Added related tests to ensure accuracy of the new functionality.

Author: nakamura-to

doma-core/src/main/java/org/seasar/doma/internal/jdbc/command/ColumnNameMapFormatter.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright Doma Authors
+ *
+ * Licensed 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
+ *
+ *     https://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.
+ */
+package org.seasar.doma.internal.jdbc.command;
+
+import java.util.Map;
+import java.util.TreeMap;
+
+public class ColumnNameMapFormatter {
+  public static String format(Map<String, MappingSupport.PropType> columnNameMap) {
+    StringBuilder buf = new StringBuilder();
+    buf.append("------------------------------------------------------\n");
+    buf.append("Lowercase Column Name -> Property Name (Entity Name)\n");
+    buf.append("------------------------------------------------------\n");
+    TreeMap<String, MappingSupport.PropType> sortedMap = new TreeMap<>(columnNameMap);
+    for (Map.Entry<String, MappingSupport.PropType> entry : sortedMap.entrySet()) {
+      String columnName = entry.getKey();
+      MappingSupport.PropType propType = entry.getValue();
+      buf.append(columnName);
+      buf.append(" -> ");
+      buf.append(propType.name());
+      buf.append(" (");
+      buf.append(propType.entityType().getName());
+      buf.append(")\n");
+    }
+    buf.append("------------------------------------------------------");
+    return buf.toString();
+  }
+}

doma-core/src/main/java/org/seasar/doma/internal/jdbc/command/EntityProvider.java

@@ -95,6 +95,7 @@ protected ENTITY build(ResultSet resultSet) throws SQLException {
     return entity;
   }
 
+  @SuppressWarnings("removal")
   @Deprecated(forRemoval = true)
   protected HashMap<Integer, EntityPropertyType<ENTITY, ?>> createIndexMap(
       ResultSetMetaData resultSetMeta, EntityType<ENTITY> entityType) throws SQLException {

doma-core/src/main/java/org/seasar/doma/internal/jdbc/command/MappingSupport.java

@@ -98,7 +98,7 @@ public Map<Integer, MappingSupport.PropType> createIndexMap(
         if (ROWNUMBER_COLUMN_NAME.equals(lowerCaseColumnName)) {
           continue;
         }
-        unknownColumnHandler.handle(query, entityType, lowerCaseColumnName);
+        unknownColumnHandler.handle(query, entityType, lowerCaseColumnName, columnNameMap);
       } else {
         unmappedPropertySet.remove(propertyType);
         indexMap.put(i, propertyType);

doma-core/src/main/java/org/seasar/doma/jdbc/UnknownColumnAdditionalInfoException.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright Doma Authors
+ *
+ * Licensed 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
+ *
+ *     https://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.
+ */
+package org.seasar.doma.jdbc;
+
+import java.io.Serial;
+import java.util.Objects;
+import org.seasar.doma.message.Message;
+
+public class UnknownColumnAdditionalInfoException extends UnknownColumnException {
+
+  @Serial private static final long serialVersionUID = 1L;
+
+  private final String additionalInfo;
+
+  public UnknownColumnAdditionalInfoException(
+      SqlLogType logType, UnknownColumnException exception, String additionalInfo) {
+    super(
+        Message.DOMA2238,
+        new Object[] {
+          exception.getColumnName(),
+          exception.getEntityClassName(),
+          exception.getSqlFilePath(),
+          choiceSql(logType, exception.getRawSql(), exception.getFormattedSql()),
+          additionalInfo
+        },
+        exception.getColumnName(),
+        exception.getExpectedPropertyName(),
+        exception.getEntityClassName(),
+        exception.getKind(),
+        exception.getRawSql(),
+        exception.getFormattedSql(),
+        exception.getSqlFilePath());
+    this.additionalInfo = Objects.requireNonNull(additionalInfo);
+  }
+
+  public String getAdditionalInfo() {
+    return additionalInfo;
+  }
+}

doma-core/src/main/java/org/seasar/doma/jdbc/UnknownColumnException.java

@@ -15,12 +15,14 @@
  */
 package org.seasar.doma.jdbc;
 
+import java.io.Serial;
 import org.seasar.doma.message.Message;
+import org.seasar.doma.message.MessageResource;
 
 /** Thrown to indicate that there is the column that is unknown to an entity. */
 public class UnknownColumnException extends JdbcException {
 
-  private static final long serialVersionUID = 1L;
+  @Serial private static final long serialVersionUID = 1L;
 
   protected final String columnName;
 
@@ -45,13 +47,35 @@ public UnknownColumnException(
       String rawSql,
       String formattedSql,
       String sqlFilePath) {
-    super(
+    this(
         Message.DOMA2002,
+        new Object[] {
+          columnName,
+          expectedPropertyName,
+          entityClassName,
+          sqlFilePath,
+          choiceSql(logType, rawSql, formattedSql)
+        },
         columnName,
         expectedPropertyName,
         entityClassName,
-        sqlFilePath,
-        choiceSql(logType, rawSql, formattedSql));
+        kind,
+        rawSql,
+        formattedSql,
+        sqlFilePath);
+  }
+
+  protected UnknownColumnException(
+      MessageResource messageCode,
+      Object[] args,
+      String columnName,
+      String expectedPropertyName,
+      String entityClassName,
+      SqlKind kind,
+      String rawSql,
+      String formattedSql,
+      String sqlFilePath) {
+    super(messageCode, args);
     this.columnName = columnName;
     this.expectedPropertyName = expectedPropertyName;
     this.entityClassName = entityClassName;

doma-core/src/main/java/org/seasar/doma/jdbc/UnknownColumnHandler.java

@@ -15,6 +15,9 @@
  */
 package org.seasar.doma.jdbc;
 
+import java.util.Map;
+import org.seasar.doma.internal.jdbc.command.ColumnNameMapFormatter;
+import org.seasar.doma.internal.jdbc.command.MappingSupport;
 import org.seasar.doma.jdbc.entity.EntityType;
 import org.seasar.doma.jdbc.entity.NamingType;
 import org.seasar.doma.jdbc.query.Query;
@@ -30,6 +33,7 @@ public interface UnknownColumnHandler {
    * @param unknownColumnName the name of the unknown column
    * @throws UnknownColumnException if this handler does not allow the unknown column
    */
+  @Deprecated(forRemoval = true)
   default void handle(Query query, EntityType<?> entityType, String unknownColumnName) {
     Sql<?> sql = query.getSql();
     Naming naming = query.getConfig().getNaming();
@@ -44,4 +48,31 @@ default void handle(Query query, EntityType<?> entityType, String unknownColumnN
         sql.getFormattedSql(),
         sql.getSqlFilePath());
   }
+
+  /**
+   * Handles the unknown column with additional context provided by the column name map.
+   *
+   * @param query the query associated with the operation
+   * @param entityType the entity type description
+   * @param unknownColumnName the name of the unknown column
+   * @param columnNameMap the map containing column names and their corresponding property types
+   * @throws UnknownColumnAdditionalInfoException if handling the unknown column fails with
+   *     additional information
+   */
+  default void handle(
+      Query query,
+      EntityType<?> entityType,
+      String unknownColumnName,
+      Map<String, MappingSupport.PropType> columnNameMap) {
+    try {
+      handle(query, entityType, unknownColumnName);
+    } catch (UnknownColumnException original) {
+      String additionalInfo = ColumnNameMapFormatter.format(columnNameMap);
+      UnknownColumnAdditionalInfoException ex =
+          new UnknownColumnAdditionalInfoException(
+              query.getConfig().getExceptionSqlLogType(), original, additionalInfo);
+      ex.addSuppressed(original);
+      throw ex;
+    }
+  }
 }

doma-core/src/main/java/org/seasar/doma/message/Message.java

@@ -277,6 +277,13 @@ public enum Message implements MessageResource {
   DOMA2237(
       "Duplicate column name \"{0}\" found in ResultSetMetaData. Column names must be unique."
           + "\nPATH=[{1}].\nSQL=[{2}]"),
+  DOMA2238(
+      """
+      While the column "{0}" is in the result set, the corresponding property is not found in the entity class "{1}".
+      Check the following mapping table:
+      {4}
+      PATH=[{2}]
+      SQL=[{3}]"""),
 
   // expression
   DOMA3001(

doma-core/src/test/java/org/seasar/doma/internal/jdbc/command/ColumnNameMapFormatterTest.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright Doma Authors
+ *
+ * Licensed 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
+ *
+ *     https://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.
+ */
+package org.seasar.doma.internal.jdbc.command;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import example.entity._Dept;
+import example.entity._Emp;
+import java.util.HashMap;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+class ColumnNameMapFormatterTest {
+
+  @Test
+  void test_format_withPopulatedMap() {
+    _Emp emp = _Emp.getSingletonInternal();
+    _Dept dept = _Dept.getSingletonInternal();
+
+    Map<String, MappingSupport.PropType> map = new HashMap<>();
+    map.put(
+        emp.version.getColumnName().toLowerCase(),
+        new MappingSupport.PropType(emp, emp.version, ""));
+    map.put(
+        dept.name.getColumnName().toLowerCase(), new MappingSupport.PropType(dept, dept.name, ""));
+    map.put(
+        emp.salary.getColumnName().toLowerCase(), new MappingSupport.PropType(emp, emp.salary, ""));
+
+    String expected =
+        """
+        ------------------------------------------------------
+        Lowercase Column Name -> Property Name (Entity Name)
+        ------------------------------------------------------
+        name -> name (Dept)
+        salary -> salary (Emp)
+        version -> version (Emp)
+        ------------------------------------------------------""";
+
+    String actual = ColumnNameMapFormatter.format(map);
+
+    assertEquals(expected, actual);
+  }
+}

doma-core/src/test/java/org/seasar/doma/internal/jdbc/command/EntityProviderTest.java

@@ -25,6 +25,7 @@
 import java.math.BigDecimal;
 import java.sql.SQLException;
 import java.util.Collections;
+import java.util.Map;
 import org.junit.jupiter.api.Test;
 import org.seasar.doma.FetchType;
 import org.seasar.doma.internal.jdbc.mock.ColumnMetaData;
@@ -249,7 +250,11 @@ public boolean isResultStream() {
 
   protected static class EmptyUnknownColumnHandler implements UnknownColumnHandler {
     @Override
-    public void handle(Query query, EntityType<?> entityType, String unknownColumnName) {}
+    public void handle(
+        Query query,
+        EntityType<?> entityType,
+        String unknownColumnName,
+        Map<String, MappingSupport.PropType> columnNameMap) {}
   }
 
   protected static class EmptyUnknownColumnHandlerConfig extends MockConfig {