refactor: flattened path processing - metadata-driven VI detection

Replace runtime heuristics in the flush pipeline with pre-computed segment classification cached at mapping load time.

Author: m-dzianishchyts

cayenne/src/main/java/org/apache/cayenne/access/flush/ArcValuesCreationHandler.java

@@ -51,9 +51,9 @@ public void nodePropertyChanged(Object nodeId, String property, Object oldValue,
         DbEntity dbEntity = entity.getDbEntity();
 
         if(attribute.isFlattened()) {
-            // get target row ID
-            FlattenedPathProcessingResult result
-                    = processFlattenedPath(id, null, dbEntity, attribute.getDbAttributePath(), newValue != null);
+            // get target row ID - use cached FlattenedPathInfo if available
+            FlattenedPathProcessingResult result = processFlattenedAttributePath(id, dbEntity,
+                    attribute.getDbAttributePath(), newValue != null);
             if(result.isProcessed()) {
                 id = result.getId();
             }

cayenne/src/main/java/org/apache/cayenne/access/flush/ValuesCreationHandler.java

@@ -0,0 +1,138 @@
+/*****************************************************************
+ *   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
+ *
+ *    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.apache.cayenne.map;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Analyzes a flattened {@link ObjRelationship}'s {@link DbRelationship} path
+ * and classifies each segment as one of the {@link FlattenedPathSegmentType} values.
+ * <p>
+ * This classification is performed once per relationship and cached in
+ * {@link ObjRelationship} as a {@link FlattenedPathInfo}, so that downstream
+ * consumers never need to re-derive the nature of each segment from raw
+ * join metadata.
+ * </p>
+ *
+ * @since 5.0
+ */
+public class FlattenedPathAnalyzer {
+
+    /**
+     * Analyzes the given flattened relationship and returns a {@link FlattenedPathInfo}
+     * with each segment classified.
+     *
+     * @param relationship a flattened ObjRelationship (must have more than one DbRelationship)
+     * @return classified path info
+     * @throws IllegalArgumentException if the relationship is not flattened
+     */
+    public static FlattenedPathInfo analyze(ObjRelationship relationship) {
+        List<DbRelationship> dbRels = relationship.getDbRelationships();
+        if (dbRels.size() < 2) {
+            throw new IllegalArgumentException(
+                    "FlattenedPathAnalyzer requires a flattened relationship (>1 DbRelationship), got: "
+                            + relationship.getName());
+        }
+
+        List<FlattenedPathInfo.AnnotatedSegment> segments = new ArrayList<>(dbRels.size());
+        for (DbRelationship dbRel : dbRels) {
+            FlattenedPathSegmentType type = classifySegment(dbRel);
+            segments.add(new FlattenedPathInfo.AnnotatedSegment(dbRel, type));
+        }
+
+        return new FlattenedPathInfo(segments);
+    }
+
+    /**
+     * Classifies a single {@link DbRelationship} segment.
+     *
+     * <p>Classification rules:</p>
+     * <ol>
+     *     <li><b>VI_TO_CHILD</b>: the relationship is toDependentPK, toOne,
+     *         and has all-PK joins (parent → child in vertical inheritance).</li>
+     *     <li><b>VI_TO_PARENT</b>: the reverse relationship is toDependentPK, and
+     *         this relationship is toOne with all-PK joins (child → parent in vertical inheritance).</li>
+     *     <li><b>JOIN_TABLE</b>: the target entity has multiple incoming toDependentPK
+     *         relationships, indicating a many-to-many join table.</li>
+     *     <li><b>REGULAR</b>: everything else.</li>
+     * </ol>
+     */
+    public static FlattenedPathSegmentType classifySegment(DbRelationship dbRel) {
+        if (dbRel.isToMany()) {
+            // toMany can point to a join table
+            if (isJoinTableTarget(dbRel.getTargetEntity())) {
+                return FlattenedPathSegmentType.JOIN_TABLE;
+            }
+            return FlattenedPathSegmentType.REGULAR;
+        }
+
+        // toOne: check for VI patterns
+        if (dbRel.isToDependentPK() && hasAllPkJoins(dbRel)) {
+            // parent - child (toDependentPK, all PK-to-PK joins)
+            if (isJoinTableTarget(dbRel.getTargetEntity())) {
+                return FlattenedPathSegmentType.JOIN_TABLE;
+            }
+            return FlattenedPathSegmentType.VI_TO_CHILD;
+        }
+
+        DbRelationship reverseRel = dbRel.getReverseRelationship();
+        if (reverseRel != null && reverseRel.isToDependentPK() && hasAllPkJoins(dbRel)) {
+            // child - parent (reverse is toDependentPK, all PK-to-PK joins)
+            return FlattenedPathSegmentType.VI_TO_PARENT;
+        }
+
+        return FlattenedPathSegmentType.REGULAR;
+    }
+
+    /**
+     * Returns {@code true} if all joins in the relationship map PK columns on both sides.
+     */
+    private static boolean hasAllPkJoins(DbRelationship dbRel) {
+        for (DbJoin join : dbRel.getJoins()) {
+            if (!join.getSource().isPrimaryKey() || !join.getTarget().isPrimaryKey()) {
+                return false;
+            }
+        }
+        return !dbRel.getJoins().isEmpty();
+    }
+
+    /**
+     * Returns {@code true} if the target entity is a join table, i.e. it has
+     * more than one incoming toDependentPK relationship from other entities.
+     * <p>
+     * In vertical inheritance, a child table has exactly one incoming toDependentPK
+     * (from the parent). A join table has two or more (from both sides of a many-to-many).
+     * </p>
+     */
+    private static boolean isJoinTableTarget(DbEntity target) {
+        int toDependentPKCount = 0;
+        for (DbRelationship rel : target.getRelationships()) {
+            DbRelationship reverseRel = rel.getReverseRelationship();
+            if (reverseRel != null && reverseRel.isToDependentPK()) {
+                toDependentPKCount++;
+                if (toDependentPKCount > 1) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+}

cayenne/src/main/java/org/apache/cayenne/map/FlattenedPathAnalyzer.java

@@ -0,0 +1,122 @@
+/*****************************************************************
+ *   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
+ *
+ *    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.apache.cayenne.map;
+
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Pre-computed classification of a flattened {@link ObjRelationship}'s
+ * {@link DbRelationship} path. Each segment in the path is annotated with a
+ * {@link FlattenedPathSegmentType} that tells downstream consumers
+ * (flush pipeline, prefetch routing, column extraction, etc.)
+ * what kind of link they are dealing with — without re-discovering it
+ * from raw join metadata every time.
+ * <p>
+ * Instances are <b>immutable</b> and created lazily by
+ * {@link FlattenedPathAnalyzer#analyze(ObjRelationship)}.
+ * </p>
+ *
+ * @since 5.0
+ * @see FlattenedPathSegmentType
+ * @see AnnotatedSegment
+ */
+public class FlattenedPathInfo {
+
+    private final List<AnnotatedSegment> segments;
+    private final boolean fkThroughInheritance;
+
+    public FlattenedPathInfo(List<AnnotatedSegment> segments) {
+        this.segments = Collections.unmodifiableList(segments);
+
+        boolean fkThroughVI = false;
+
+        if (segments.size() >= 2) {
+            // FK through inheritance: all preceding segments are VI_TO_CHILD,
+            // and the last segment is a regular FK-to-PK relationship
+            boolean allPrecedingAreVI = true;
+            for (int i = 0; i < segments.size() - 1; i++) {
+                if (segments.get(i).getType() != FlattenedPathSegmentType.VI_TO_CHILD) {
+                    allPrecedingAreVI = false;
+                    break;
+                }
+            }
+            if (allPrecedingAreVI) {
+                FlattenedPathSegmentType lastType = segments.get(segments.size() - 1).getType();
+                if (lastType == FlattenedPathSegmentType.REGULAR) {
+                    DbRelationship lastRel = segments.get(segments.size() - 1).getRelationship();
+                    fkThroughVI = lastRel.isToPK();
+                }
+            }
+        }
+
+        this.fkThroughInheritance = fkThroughVI;
+    }
+
+    /**
+     * Returns the annotated segments of this flattened path, in order.
+     */
+    public List<AnnotatedSegment> getSegments() {
+        return segments;
+    }
+
+    /**
+     * Returns {@code true} if the FK is accessed through a vertical inheritance chain:
+     * one or more {@link FlattenedPathSegmentType#VI_TO_CHILD} segments followed by
+     * a {@link FlattenedPathSegmentType#REGULAR} FK-to-PK segment.
+     */
+    public boolean isFkThroughInheritance() {
+        return fkThroughInheritance;
+    }
+
+    /**
+     * A single segment of a flattened path, pairing a {@link DbRelationship}
+     * with its classified {@link FlattenedPathSegmentType}.
+     *
+     * @since 5.0
+     */
+    public static class AnnotatedSegment {
+
+        private final DbRelationship relationship;
+        private final FlattenedPathSegmentType type;
+
+        public AnnotatedSegment(DbRelationship relationship, FlattenedPathSegmentType type) {
+            this.relationship = relationship;
+            this.type = type;
+        }
+
+        public DbRelationship getRelationship() {
+            return relationship;
+        }
+
+        public FlattenedPathSegmentType getType() {
+            return type;
+        }
+
+        public boolean isVerticalInheritance() {
+            return type.isVerticalInheritance();
+        }
+
+        @Override
+        public String toString() {
+            return relationship.getName() + " [" + type + "]";
+        }
+    }
+}

cayenne/src/main/java/org/apache/cayenne/map/FlattenedPathInfo.java

@@ -0,0 +1,67 @@
+/*****************************************************************
+ *   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
+ *
+ *    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.apache.cayenne.map;
+
+/**
+ * Classifies a {@link DbRelationship} segment within a flattened path
+ * according to its role in the data model.
+ *
+ * <ul>
+ *     <li>{@link #VI_TO_CHILD} — vertical inheritance: parent table → child table (toDependentPK, toOne)</li>
+ *     <li>{@link #VI_TO_PARENT} — vertical inheritance: child table → parent table (reverse of toDependentPK)</li>
+ *     <li>{@link #JOIN_TABLE} — many-to-many join table (target has multiple incoming toDependentPK)</li>
+ *     <li>{@link #REGULAR} — any other relationship (standard FK-to-PK, etc.)</li>
+ * </ul>
+ *
+ * @since 5.0
+ */
+public enum FlattenedPathSegmentType {
+
+    /**
+     * Vertical inheritance from parent to child table.
+     * The relationship is toDependentPK, toOne, and the target entity
+     * is a child in a vertical inheritance hierarchy sharing the parent's PK.
+     */
+    VI_TO_CHILD,
+
+    /**
+     * Vertical inheritance from child to parent table.
+     * The reverse relationship is toDependentPK.
+     */
+    VI_TO_PARENT,
+
+    /**
+     * Relationship targeting a many-to-many join table.
+     * The target entity has multiple incoming toDependentPK relationships.
+     */
+    JOIN_TABLE,
+
+    /**
+     * Any relationship that doesn't fall into the other categories.
+     */
+    REGULAR;
+
+    /**
+     * Returns {@code true} if this segment type represents a vertical inheritance link.
+     */
+    public boolean isVerticalInheritance() {
+        return this == VI_TO_CHILD || this == VI_TO_PARENT;
+    }
+}