1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.databind.model.info;
7   
8   import java.io.IOException;
9   
10  import dev.metaschema.core.model.IBoundObject;
11  import dev.metaschema.databind.model.IBoundDefinitionModelAssembly;
12  import dev.metaschema.databind.model.IBoundDefinitionModelFieldComplex;
13  import dev.metaschema.databind.model.IBoundFieldValue;
14  import dev.metaschema.databind.model.IBoundInstanceFlag;
15  import dev.metaschema.databind.model.IBoundInstanceModelAssembly;
16  import dev.metaschema.databind.model.IBoundInstanceModelChoiceGroup;
17  import dev.metaschema.databind.model.IBoundInstanceModelFieldComplex;
18  import dev.metaschema.databind.model.IBoundInstanceModelFieldScalar;
19  import dev.metaschema.databind.model.IBoundInstanceModelGroupedAssembly;
20  import dev.metaschema.databind.model.IBoundInstanceModelGroupedField;
21  import edu.umd.cs.findbugs.annotations.NonNull;
22  import edu.umd.cs.findbugs.annotations.Nullable;
23  
24  /**
25   * Handler interface for reading bound items during deserialization.
26   * <p>
27   * Implementations of this interface handle the reading of different types of
28   * model items (flags, fields, assemblies, choice groups).
29   */
30  public interface IItemReadHandler {
31    /**
32     * Parse and return an item.
33     *
34     * @param parent
35     *          the parent Java object to use for serialization callbacks
36     * @param instance
37     *          the flag instance
38     * @return the Java object representing the parsed item
39     * @throws IOException
40     *           if an error occurred while parsing
41     */
42    @NonNull
43    Object readItemFlag(
44        @NonNull IBoundObject parent,
45        @NonNull IBoundInstanceFlag instance) throws IOException;
46  
47    /**
48     * Parse and return an item.
49     *
50     * @param parent
51     *          the parent Java object to use for serialization callbacks
52     * @param instance
53     *          the field instance
54     * @return the Java object representing the parsed item
55     * @throws IOException
56     *           if an error occurred while parsing
57     */
58    @Nullable
59    Object readItemField(
60        @NonNull IBoundObject parent,
61        @NonNull IBoundInstanceModelFieldScalar instance) throws IOException;
62  
63    /**
64     * Parse and return an item.
65     *
66     * @param parent
67     *          the parent Java object to use for serialization callbacks
68     * @param instance
69     *          the field instance
70     * @return the Java object representing the parsed item
71     * @throws IOException
72     *           if an error occurred while parsing
73     */
74    @NonNull
75    IBoundObject readItemField(
76        @NonNull IBoundObject parent,
77        @NonNull IBoundInstanceModelFieldComplex instance) throws IOException;
78  
79    /**
80     * Parse and return an item.
81     *
82     * @param parent
83     *          the parent Java object to use for serialization callbacks
84     * @param instance
85     *          the field instance
86     * @return the Java object representing the parsed item
87     * @throws IOException
88     *           if an error occurred while parsing
89     */
90    @NonNull
91    IBoundObject readItemField(
92        @NonNull IBoundObject parent,
93        @NonNull IBoundInstanceModelGroupedField instance) throws IOException;
94  
95    /**
96     * Parse and return an item.
97     *
98     * @param parent
99     *          the parent Java object to use for serialization callbacks, or
100    *          {@code null} if there is no parent
101    * @param definition
102    *          the field instance
103    * @return the Java object representing the parsed item
104    * @throws IOException
105    *           if an error occurred while parsing
106    */
107   @NonNull
108   IBoundObject readItemField(
109       @Nullable IBoundObject parent,
110       @NonNull IBoundDefinitionModelFieldComplex definition) throws IOException;
111 
112   /**
113    * Parse and return an item.
114    *
115    * @param parent
116    *          the parent Java object to use for serialization callbacks
117    * @param fieldValue
118    *          the field value instance
119    * @return the Java object representing the parsed item
120    * @throws IOException
121    *           if an error occurred while parsing
122    */
123   @Nullable
124   Object readItemFieldValue(
125       @NonNull IBoundObject parent,
126       @NonNull IBoundFieldValue fieldValue) throws IOException;
127 
128   /**
129    * Parse and return an item.
130    *
131    * @param parent
132    *          the parent Java object to use for serialization callbacks
133    * @param instance
134    *          the assembly instance
135    * @return the Java object representing the parsed item
136    * @throws IOException
137    *           if an error occurred while parsing
138    */
139   @NonNull
140   IBoundObject readItemAssembly(
141       @NonNull IBoundObject parent,
142       @NonNull IBoundInstanceModelAssembly instance) throws IOException;
143 
144   /**
145    * Parse and return an item.
146    *
147    * @param parent
148    *          the parent Java object to use for serialization callbacks
149    * @param instance
150    *          the assembly instance
151    * @return the Java object representing the parsed item
152    * @throws IOException
153    *           if an error occurred while parsing
154    */
155   @NonNull
156   IBoundObject readItemAssembly(
157       @NonNull IBoundObject parent,
158       @NonNull IBoundInstanceModelGroupedAssembly instance) throws IOException;
159 
160   /**
161    * Parse and return an item.
162    *
163    * @param parent
164    *          the parent Java object to use for serialization callbacks, or
165    *          {@code null} if there is no parent
166    * @param definition
167    *          the assembly instance
168    * @return the Java object representing the parsed item
169    * @throws IOException
170    *           if an error occurred while parsing
171    */
172   @NonNull
173   IBoundObject readItemAssembly(
174       @Nullable IBoundObject parent,
175       @NonNull IBoundDefinitionModelAssembly definition) throws IOException;
176 
177   /**
178    * Parse and return an item.
179    *
180    * @param parent
181    *          the parent Java object to use for serialization callbacks
182    * @param instance
183    *          the choice group instance
184    * @return the Java object representing the parsed item
185    * @throws IOException
186    *           if an error occurred while parsing
187    */
188   @Nullable
189   IBoundObject readChoiceGroupItem(
190       @NonNull IBoundObject parent,
191       @NonNull IBoundInstanceModelChoiceGroup instance) throws IOException;
192 }