feat: Add support for optional embeddable classes (#1409)

Author: nakamura-to

doma-core/src/main/java/org/seasar/doma/internal/jdbc/entity/FieldWrapper.java

@@ -0,0 +1,63 @@
+/*
+ * 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.entity;
+
+import org.seasar.doma.internal.WrapException;
+
+/**
+ * A wrapper interface for accessing and manipulating object fields.
+ *
+ * <p>This interface provides a unified way to get and set field values on objects, abstracting the
+ * underlying reflection operations. It handles different types of fields including regular fields
+ * and optional fields, providing type-safe access patterns.
+ *
+ * <p>Implementations of this interface are typically created by {@link PropertyPathSegment}
+ * implementations to handle field access for specific property path segments.
+ *
+ * <p>This interface is used internally by the Doma framework for property mapping and should not be
+ * used directly by application code.
+ *
+ * @see PropertyPathSegment
+ * @see PropertyPath
+ */
+public interface FieldWrapper {
+  /**
+   * Retrieves the value of this field from the specified object.
+   *
+   * @param obj the object from which to retrieve the field value
+   * @return the field value, which may be null
+   * @throws WrapException if an error occurs during field access
+   */
+  Object get(Object obj) throws WrapException;
+
+  /**
+   * Sets the value of this field on the specified object.
+   *
+   * @param obj the object on which to set the field value
+   * @param value the value to set, which may be null
+   * @throws WrapException if an error occurs during field access
+   */
+  void set(Object obj, Object value) throws WrapException;
+
+  /**
+   * Returns the type of this field.
+   *
+   * <p>For optional fields, this returns the element type rather than the Optional type itself.
+   *
+   * @return the field type
+   */
+  Class<?> getType();
+}

doma-core/src/main/java/org/seasar/doma/internal/jdbc/entity/PropertyField.java

@@ -19,7 +19,6 @@
 import java.util.LinkedList;
 import org.seasar.doma.internal.WrapException;
 import org.seasar.doma.internal.util.AssertionUtil;
-import org.seasar.doma.internal.util.FieldUtil;
 import org.seasar.doma.jdbc.entity.EntityPropertyAccessException;
 import org.seasar.doma.jdbc.entity.EntityPropertyNotFoundException;
 
@@ -29,35 +28,36 @@ public class PropertyField<ENTITY> {
 
   protected final Class<ENTITY> entityClass;
 
-  protected final LinkedList<Field> fields = new LinkedList<>();
+  protected final LinkedList<FieldWrapper> fields = new LinkedList<>();
 
   public PropertyField(String path, Class<ENTITY> entityClass) {
+    this(PropertyPath.of(path), entityClass);
+  }
+
+  public PropertyField(PropertyPath path, Class<ENTITY> entityClass) {
     AssertionUtil.assertNotNull(path, entityClass);
-    this.path = path;
+    this.path = path.name();
     this.entityClass = entityClass;
-    String[] segments = path.split("\\.");
     Class<?> clazz = entityClass;
-    for (String segment : segments) {
-      Field field = getField(clazz, segment);
+    for (PropertyPathSegment segment : path.segments()) {
+      FieldWrapper field = getField(clazz, segment);
       fields.add(field);
       clazz = field.getType();
     }
     AssertionUtil.assertTrue(fields.size() > 0);
   }
 
-  private Field getField(Class<?> clazz, String name) {
-    Field field = findField(clazz, name);
+  private FieldWrapper getField(Class<?> clazz, PropertyPathSegment segment) {
+    Field field = findField(clazz, segment.name());
     if (field == null) {
-      throw new EntityPropertyNotFoundException(clazz.getName(), name);
+      throw new EntityPropertyNotFoundException(clazz.getName(), segment.name());
     }
-    if (!FieldUtil.isPublic(field)) {
-      try {
-        FieldUtil.setAccessible(field, true);
-      } catch (WrapException wrapException) {
-        throw new EntityPropertyAccessException(wrapException.getCause(), clazz.getName(), name);
-      }
+    try {
+      return segment.wrapField(field);
+    } catch (WrapException wrapException) {
+      throw new EntityPropertyAccessException(
+          wrapException.getCause(), clazz.getName(), segment.name());
     }
-    return field;
   }
 
   private Field findField(Class<?> clazz, String name) {
@@ -73,7 +73,7 @@ private Field findField(Class<?> clazz, String name) {
   public Object getValue(ENTITY entity) {
     AssertionUtil.assertNotNull(entity);
     Object value = entity;
-    for (Field field : fields) {
+    for (FieldWrapper field : fields) {
       if (value == null) {
         break;
       }
@@ -82,9 +82,9 @@ public Object getValue(ENTITY entity) {
     return value;
   }
 
-  private Object getFieldValue(Field field, Object target) {
+  private Object getFieldValue(FieldWrapper field, Object target) {
     try {
-      return FieldUtil.get(field, target);
+      return field.get(target);
     } catch (WrapException wrapException) {
       throw new EntityPropertyAccessException(
           wrapException.getCause(), entityClass.getName(), path);
@@ -99,17 +99,17 @@ public void setValue(ENTITY entity, Object value) {
     setFieldValue(fields.getFirst(), entity, value);
   }
 
-  private void setFieldValue(Field field, ENTITY entity, Object value) {
+  private void setFieldValue(FieldWrapper field, ENTITY entity, Object value) {
     try {
-      FieldUtil.set(field, entity, value);
+      field.set(entity, value);
     } catch (WrapException wrapException) {
       throw new EntityPropertyAccessException(
           wrapException.getCause(), entityClass.getName(), path);
     }
   }
 
   public boolean isPrimitive() {
-    Field field = fields.getLast();
+    FieldWrapper field = fields.getLast();
     return field.getType().isPrimitive();
   }
 }

doma-core/src/main/java/org/seasar/doma/internal/jdbc/entity/PropertyPath.java

@@ -0,0 +1,108 @@
+/*
+ * 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.entity;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Objects;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+/**
+ * Represents a path to a property within an object graph, composed of one or more segments.
+ *
+ * <p>A property path is used to navigate through object hierarchies, particularly when dealing with
+ * embeddable objects that may be nested within entities. Each segment of the path represents a step
+ * in the navigation from one object to another.
+ *
+ * <p>For example, a property path like "address.street" would consist of two segments: one for
+ * "address" and another for "street", allowing navigation from an entity to its embedded address
+ * object and then to the street field within that address.
+ *
+ * <p>This record is immutable and provides factory methods for creating and combining paths.
+ *
+ * <p>This class is used internally by the Doma framework for property mapping and should not be
+ * used directly by application code.
+ *
+ * @param segments the list of path segments that make up this property path, must not be empty
+ * @see PropertyPathSegment
+ * @see PropertyField
+ */
+public record PropertyPath(List<? extends PropertyPathSegment> segments) {
+  public PropertyPath {
+    if (segments.isEmpty()) {
+      throw new IllegalArgumentException("segments");
+    }
+  }
+
+  /**
+   * Returns the full name of this property path as a dot-separated string.
+   *
+   * <p>For example, if this path has segments "address" and "street", this method would return
+   * "address.street".
+   *
+   * @return the full property path name with segments joined by dots
+   */
+  public String name() {
+    return segments.stream().map(PropertyPathSegment::name).collect(Collectors.joining("."));
+  }
+
+  /**
+   * Creates a new property path by combining an existing path with an additional segment.
+   *
+   * <p>This method allows for building longer property paths by appending segments to existing
+   * paths. The original path is not modified; a new immutable path is returned.
+   *
+   * @param path the existing property path to extend
+   * @param segment the segment to append to the path
+   * @return a new property path containing all segments from the original path plus the new segment
+   * @throws NullPointerException if either path or segment is null
+   */
+  public static PropertyPath combine(PropertyPath path, PropertyPathSegment segment) {
+    Objects.requireNonNull(path);
+    Objects.requireNonNull(segment);
+    var segments = Stream.concat(path.segments.stream(), Stream.of(segment)).toList();
+    return new PropertyPath(segments);
+  }
+
+  /**
+   * Creates a property path from a dot-separated string representation.
+   *
+   * <p>This factory method parses a string like "address.street" into a property path with
+   * appropriate segments. Each segment is created as a default property path segment.
+   *
+   * @param path the dot-separated string representation of the property path
+   * @return a new property path with segments parsed from the string
+   * @throws NullPointerException if path is null
+   */
+  public static PropertyPath of(String path) {
+    Objects.requireNonNull(path);
+    var segments = Arrays.stream(path.split("\\.")).map(PropertyPathSegment.Default::new).toList();
+    return new PropertyPath(segments);
+  }
+
+  /**
+   * Returns the string representation of this property path.
+   *
+   * <p>This is equivalent to calling {@link #name()}.
+   *
+   * @return the full property path name with segments joined by dots
+   */
+  @Override
+  public String toString() {
+    return name();
+  }
+}