001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.databind.io.xml;
007
008import java.io.IOException;
009import java.util.Collection;
010
011import javax.xml.stream.events.Attribute;
012import javax.xml.stream.events.StartElement;
013
014import dev.metaschema.core.model.IBoundObject;
015import dev.metaschema.databind.io.IProblemHandler;
016import dev.metaschema.databind.io.ValidationContext;
017import dev.metaschema.databind.model.IBoundDefinitionModelAssembly;
018import dev.metaschema.databind.model.IBoundDefinitionModelComplex;
019import dev.metaschema.databind.model.IBoundInstanceFlag;
020import dev.metaschema.databind.model.IBoundInstanceModel;
021import edu.umd.cs.findbugs.annotations.NonNull;
022import edu.umd.cs.findbugs.annotations.Nullable;
023
024/**
025 * Handles problems encountered during XML parsing, such as unknown attributes
026 * or elements.
027 */
028@FunctionalInterface
029public interface IXmlProblemHandler extends IProblemHandler {
030  /**
031   * Callback used to handle an attribute that is unknown to the model being
032   * parsed.
033   *
034   * @param parentDefinition
035   *          the bound class currently describing the data being parsed
036   * @param targetObject
037   *          the Java object for the {@code parentDefinition}
038   * @param attribute
039   *          the unknown attribute
040   * @param parsingContext
041   *          the XML parsing context used for parsing
042   * @return {@code true} if the attribute was handled by this method, or
043   *         {@code false} otherwise
044   * @throws IOException
045   *           if an error occurred while handling the unrecognized data
046   */
047  default boolean handleUnknownAttribute(
048      @NonNull IBoundDefinitionModelComplex parentDefinition,
049      @NonNull IBoundObject targetObject,
050      @NonNull Attribute attribute,
051      @NonNull IXmlParsingContext parsingContext) throws IOException {
052    return false;
053  }
054
055  /**
056   * Callback used to handle an element that is unknown to the model being parsed.
057   *
058   * @param parentDefinition
059   *          the bound assembly class on which the missing instances are found
060   * @param targetObject
061   *          the Java object for the {@code parentDefinition}
062   * @param start
063   *          the parsed XML start element
064   * @param parsingContext
065   *          the XML parsing context used for parsing
066   * @return {@code true} if the element was handled by this method, or
067   *         {@code false} otherwise
068   * @throws IOException
069   *           if an error occurred while handling the unrecognized data
070   */
071  default boolean handleUnknownElement(
072      @NonNull IBoundDefinitionModelAssembly parentDefinition,
073      @NonNull IBoundObject targetObject,
074      @NonNull StartElement start,
075      @NonNull IXmlParsingContext parsingContext) throws IOException {
076    return false;
077  }
078
079  /**
080   * A callback used to handle bound flag instances for which no data was found
081   * when the content was parsed.
082   * <p>
083   * This can be used to supply default or prescribed values based on application
084   * logic.
085   *
086   * @param parentDefinition
087   *          the bound assembly class on which the missing instances are found
088   * @param targetObject
089   *          the Java object for the {@code parentDefinition}
090   * @param unhandledInstances
091   *          the set of instances that had no data to parse
092   * @throws IOException
093   *           if an error occurred while handling the missing instances
094   */
095  default void handleMissingFlagInstances(
096      @NonNull IBoundDefinitionModelComplex parentDefinition,
097      @NonNull IBoundObject targetObject,
098      @NonNull Collection<IBoundInstanceFlag> unhandledInstances)
099      throws IOException {
100    handleMissingInstances(parentDefinition, targetObject, unhandledInstances);
101  }
102
103  /**
104   * A callback used to handle bound flag instances for which no data was found
105   * when the content was parsed, with additional validation context.
106   * <p>
107   * This can be used to supply default or prescribed values based on application
108   * logic.
109   *
110   * @param parentDefinition
111   *          the bound assembly class on which the missing instances are found
112   * @param targetObject
113   *          the Java object for the {@code parentDefinition}
114   * @param unhandledInstances
115   *          the set of instances that had no data to parse
116   * @param context
117   *          the validation context with location and path information, may be
118   *          null for backward compatibility
119   * @throws IOException
120   *           if an error occurred while handling the missing instances
121   */
122  default void handleMissingFlagInstances(
123      @NonNull IBoundDefinitionModelComplex parentDefinition,
124      @NonNull IBoundObject targetObject,
125      @NonNull Collection<IBoundInstanceFlag> unhandledInstances,
126      @Nullable ValidationContext context)
127      throws IOException {
128    handleMissingInstances(parentDefinition, targetObject, unhandledInstances, context);
129  }
130
131  /**
132   * A callback used to handle bound model instances for which no data was found
133   * when the content was parsed.
134   * <p>
135   * This can be used to supply default or prescribed values based on application
136   * logic.
137   *
138   * @param parentDefinition
139   *          the bound assembly class on which the missing instances are found
140   * @param targetObject
141   *          the Java object for the {@code parentDefinition}
142   * @param unhandledInstances
143   *          the set of instances that had no data to parse
144   * @throws IOException
145   *           if an error occurred while handling the missing instances
146   */
147  default void handleMissingModelInstances(
148      @NonNull IBoundDefinitionModelAssembly parentDefinition,
149      @NonNull IBoundObject targetObject,
150      @NonNull Collection<? extends IBoundInstanceModel<?>> unhandledInstances)
151      throws IOException {
152    handleMissingInstances(parentDefinition, targetObject, unhandledInstances);
153  }
154
155  /**
156   * A callback used to handle bound model instances for which no data was found
157   * when the content was parsed, with additional validation context.
158   * <p>
159   * This can be used to supply default or prescribed values based on application
160   * logic.
161   *
162   * @param parentDefinition
163   *          the bound assembly class on which the missing instances are found
164   * @param targetObject
165   *          the Java object for the {@code parentDefinition}
166   * @param unhandledInstances
167   *          the set of instances that had no data to parse
168   * @param context
169   *          the validation context with location and path information, may be
170   *          null for backward compatibility
171   * @throws IOException
172   *           if an error occurred while handling the missing instances
173   */
174  default void handleMissingModelInstances(
175      @NonNull IBoundDefinitionModelAssembly parentDefinition,
176      @NonNull IBoundObject targetObject,
177      @NonNull Collection<? extends IBoundInstanceModel<?>> unhandledInstances,
178      @Nullable ValidationContext context)
179      throws IOException {
180    handleMissingInstances(parentDefinition, targetObject, unhandledInstances, context);
181  }
182}