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