1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.databind.io.xml;
7   
8   import java.io.IOException;
9   import java.util.Collection;
10  
11  import javax.xml.stream.events.Attribute;
12  import javax.xml.stream.events.StartElement;
13  
14  import dev.metaschema.core.model.IBoundObject;
15  import dev.metaschema.databind.io.IProblemHandler;
16  import dev.metaschema.databind.io.ValidationContext;
17  import dev.metaschema.databind.model.IBoundDefinitionModelAssembly;
18  import dev.metaschema.databind.model.IBoundDefinitionModelComplex;
19  import dev.metaschema.databind.model.IBoundInstanceFlag;
20  import dev.metaschema.databind.model.IBoundInstanceModel;
21  import edu.umd.cs.findbugs.annotations.NonNull;
22  import edu.umd.cs.findbugs.annotations.Nullable;
23  
24  /**
25   * Handles problems encountered during XML parsing, such as unknown attributes
26   * or elements.
27   */
28  @FunctionalInterface
29  public interface IXmlProblemHandler extends IProblemHandler {
30    /**
31     * Callback used to handle an attribute that is unknown to the model being
32     * parsed.
33     *
34     * @param parentDefinition
35     *          the bound class currently describing the data being parsed
36     * @param targetObject
37     *          the Java object for the {@code parentDefinition}
38     * @param attribute
39     *          the unknown attribute
40     * @param parsingContext
41     *          the XML parsing context used for parsing
42     * @return {@code true} if the attribute was handled by this method, or
43     *         {@code false} otherwise
44     * @throws IOException
45     *           if an error occurred while handling the unrecognized data
46     */
47    default boolean handleUnknownAttribute(
48        @NonNull IBoundDefinitionModelComplex parentDefinition,
49        @NonNull IBoundObject targetObject,
50        @NonNull Attribute attribute,
51        @NonNull IXmlParsingContext parsingContext) throws IOException {
52      return false;
53    }
54  
55    /**
56     * Callback used to handle an element that is unknown to the model being parsed.
57     *
58     * @param parentDefinition
59     *          the bound assembly class on which the missing instances are found
60     * @param targetObject
61     *          the Java object for the {@code parentDefinition}
62     * @param start
63     *          the parsed XML start element
64     * @param parsingContext
65     *          the XML parsing context used for parsing
66     * @return {@code true} if the element was handled by this method, or
67     *         {@code false} otherwise
68     * @throws IOException
69     *           if an error occurred while handling the unrecognized data
70     */
71    default boolean handleUnknownElement(
72        @NonNull IBoundDefinitionModelAssembly parentDefinition,
73        @NonNull IBoundObject targetObject,
74        @NonNull StartElement start,
75        @NonNull IXmlParsingContext parsingContext) throws IOException {
76      return false;
77    }
78  
79    /**
80     * A callback used to handle bound flag instances for which no data was found
81     * when the content was parsed.
82     * <p>
83     * This can be used to supply default or prescribed values based on application
84     * logic.
85     *
86     * @param parentDefinition
87     *          the bound assembly class on which the missing instances are found
88     * @param targetObject
89     *          the Java object for the {@code parentDefinition}
90     * @param unhandledInstances
91     *          the set of instances that had no data to parse
92     * @throws IOException
93     *           if an error occurred while handling the missing instances
94     */
95    default void handleMissingFlagInstances(
96        @NonNull IBoundDefinitionModelComplex parentDefinition,
97        @NonNull IBoundObject targetObject,
98        @NonNull Collection<IBoundInstanceFlag> unhandledInstances)
99        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 }