001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.databind.io;
007
008import java.io.IOException;
009import java.util.Collection;
010
011import dev.metaschema.core.model.IBoundObject;
012import dev.metaschema.databind.model.IBoundDefinitionModelComplex;
013import dev.metaschema.databind.model.IBoundProperty;
014import edu.umd.cs.findbugs.annotations.NonNull;
015import edu.umd.cs.findbugs.annotations.Nullable;
016
017/**
018 * Implementations support handling common parsing issues.
019 */
020@FunctionalInterface
021public interface IProblemHandler {
022  /**
023   * A callback used to handle bound properties for which no data was found when
024   * the content was parsed.
025   * <p>
026   * This can be used to supply default or prescribed values based on application
027   * logic.
028   *
029   * @param parentDefinition
030   *          the bound class on which the missing properties are found
031   * @param targetObject
032   *          the Java object for the {@code parentDefinition}
033   * @param unhandledInstances
034   *          the set of instances that had no data to parse
035   * @throws IOException
036   *           if an error occurred while handling the missing instances
037   */
038  void handleMissingInstances(
039      @NonNull IBoundDefinitionModelComplex parentDefinition,
040      @NonNull IBoundObject targetObject,
041      @NonNull Collection<? extends IBoundProperty<?>> unhandledInstances)
042      throws IOException;
043
044  /**
045   * A callback used to handle bound properties for which no data was found when
046   * the content was parsed, with additional validation context.
047   * <p>
048   * This method provides richer context information for error messages including
049   * source location, document path, and format-specific details.
050   * <p>
051   * The default implementation delegates to
052   * {@link #handleMissingInstances(IBoundDefinitionModelComplex, IBoundObject, Collection)}
053   * for backward compatibility.
054   *
055   * @param parentDefinition
056   *          the bound class on which the missing properties are found
057   * @param targetObject
058   *          the Java object for the {@code parentDefinition}
059   * @param unhandledInstances
060   *          the set of instances that had no data to parse
061   * @param context
062   *          the validation context with location and path information, may be
063   *          null for backward compatibility
064   * @throws IOException
065   *           if an error occurred while handling the missing instances
066   */
067  default void handleMissingInstances(
068      @NonNull IBoundDefinitionModelComplex parentDefinition,
069      @NonNull IBoundObject targetObject,
070      @NonNull Collection<? extends IBoundProperty<?>> unhandledInstances,
071      @Nullable ValidationContext context)
072      throws IOException {
073    // Default implementation ignores context for backward compatibility
074    handleMissingInstances(parentDefinition, targetObject, unhandledInstances);
075  }
076}