1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.databind.io;
7   
8   import java.io.IOException;
9   import java.util.Collection;
10  
11  import dev.metaschema.core.model.IBoundObject;
12  import dev.metaschema.databind.model.IBoundDefinitionModelComplex;
13  import dev.metaschema.databind.model.IBoundProperty;
14  import edu.umd.cs.findbugs.annotations.NonNull;
15  import edu.umd.cs.findbugs.annotations.Nullable;
16  
17  /**
18   * Implementations support handling common parsing issues.
19   */
20  @FunctionalInterface
21  public interface IProblemHandler {
22    /**
23     * A callback used to handle bound properties for which no data was found when
24     * the content was parsed.
25     * <p>
26     * This can be used to supply default or prescribed values based on application
27     * logic.
28     *
29     * @param parentDefinition
30     *          the bound class on which the missing properties are found
31     * @param targetObject
32     *          the Java object for the {@code parentDefinition}
33     * @param unhandledInstances
34     *          the set of instances that had no data to parse
35     * @throws IOException
36     *           if an error occurred while handling the missing instances
37     */
38    void handleMissingInstances(
39        @NonNull IBoundDefinitionModelComplex parentDefinition,
40        @NonNull IBoundObject targetObject,
41        @NonNull Collection<? extends IBoundProperty<?>> unhandledInstances)
42        throws IOException;
43  
44    /**
45     * A callback used to handle bound properties for which no data was found when
46     * the content was parsed, with additional validation context.
47     * <p>
48     * This method provides richer context information for error messages including
49     * source location, document path, and format-specific details.
50     * <p>
51     * The default implementation delegates to
52     * {@link #handleMissingInstances(IBoundDefinitionModelComplex, IBoundObject, Collection)}
53     * for backward compatibility.
54     *
55     * @param parentDefinition
56     *          the bound class on which the missing properties are found
57     * @param targetObject
58     *          the Java object for the {@code parentDefinition}
59     * @param unhandledInstances
60     *          the set of instances that had no data to parse
61     * @param context
62     *          the validation context with location and path information, may be
63     *          null for backward compatibility
64     * @throws IOException
65     *           if an error occurred while handling the missing instances
66     */
67    default void handleMissingInstances(
68        @NonNull IBoundDefinitionModelComplex parentDefinition,
69        @NonNull IBoundObject targetObject,
70        @NonNull Collection<? extends IBoundProperty<?>> unhandledInstances,
71        @Nullable ValidationContext context)
72        throws IOException {
73      // Default implementation ignores context for backward compatibility
74      handleMissingInstances(parentDefinition, targetObject, unhandledInstances);
75    }
76  }