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  @FunctionalInterface
24  public interface IXmlProblemHandler extends IProblemHandler {
25    /**
26     * Callback used to handle an attribute that is unknown to the model being
27     * parsed.
28     *
29     * @param parentDefinition
30     *          the bound class currently describing the data being parsed
31     * @param targetObject
32     *          the Java object for the {@code parentDefinition}
33     * @param attribute
34     *          the unknown attribute
35     * @param parsingContext
36     *          the XML parsing context used for parsing
37     * @return {@code true} if the attribute was handled by this method, or
38     *         {@code false} otherwise
39     * @throws IOException
40     *           if an error occurred while handling the unrecognized data
41     */
42    default boolean handleUnknownAttribute(
43        @NonNull IBoundDefinitionModelComplex parentDefinition,
44        @NonNull IBoundObject targetObject,
45        @NonNull Attribute attribute,
46        @NonNull IXmlParsingContext parsingContext) throws IOException {
47      return false;
48    }
49  
50    /**
51     * Callback used to handle an element that is unknown to the model being parsed.
52     *
53     * @param parentDefinition
54     *          the bound assembly class on which the missing instances are found
55     * @param targetObject
56     *          the Java object for the {@code parentDefinition}
57     * @param start
58     *          the parsed XML start element
59     * @param parsingContext
60     *          the XML parsing context used for parsing
61     * @return {@code true} if the element was handled by this method, or
62     *         {@code false} otherwise
63     * @throws IOException
64     *           if an error occurred while handling the unrecognized data
65     */
66    default boolean handleUnknownElement(
67        @NonNull IBoundDefinitionModelAssembly parentDefinition,
68        @NonNull IBoundObject targetObject,
69        @NonNull StartElement start,
70        @NonNull IXmlParsingContext parsingContext) throws IOException {
71      return false;
72    }
73  
74    /**
75     * A callback used to handle bound flag instances for which no data was found
76     * when the content was parsed.
77     * <p>
78     * This can be used to supply default or prescribed values based on application
79     * logic.
80     *
81     * @param parentDefinition
82     *          the bound assembly class on which the missing instances are found
83     * @param targetObject
84     *          the Java object for the {@code parentDefinition}
85     * @param unhandledInstances
86     *          the set of instances that had no data to parse
87     * @throws IOException
88     *           if an error occurred while handling the missing instances
89     */
90    default void handleMissingFlagInstances(
91        @NonNull IBoundDefinitionModelComplex parentDefinition,
92        @NonNull IBoundObject targetObject,
93        @NonNull Collection<IBoundInstanceFlag> unhandledInstances)
94        throws IOException {
95      handleMissingInstances(parentDefinition, targetObject, unhandledInstances);
96    }
97  
98    /**
99     * A callback used to handle bound model instances for which no data was found
100    * when the content was parsed.
101    * <p>
102    * This can be used to supply default or prescribed values based on application
103    * logic.
104    *
105    * @param parentDefinition
106    *          the bound assembly class on which the missing instances are found
107    * @param targetObject
108    *          the Java object for the {@code parentDefinition}
109    * @param unhandledInstances
110    *          the set of instances that had no data to parse
111    * @throws IOException
112    *           if an error occurred while handling the missing instances
113    */
114   default void handleMissingModelInstances(
115       @NonNull IBoundDefinitionModelAssembly parentDefinition,
116       @NonNull IBoundObject targetObject,
117       @NonNull Collection<? extends IBoundInstanceModel<?>> unhandledInstances)
118       throws IOException {
119     handleMissingInstances(parentDefinition, targetObject, unhandledInstances);
120   }
121 }