001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.databind.model.info;
007
008import java.io.IOException;
009
010import dev.metaschema.core.model.IBoundObject;
011import dev.metaschema.databind.model.IBoundDefinitionModelAssembly;
012import dev.metaschema.databind.model.IBoundDefinitionModelFieldComplex;
013import dev.metaschema.databind.model.IBoundFieldValue;
014import dev.metaschema.databind.model.IBoundInstanceFlag;
015import dev.metaschema.databind.model.IBoundInstanceModelAssembly;
016import dev.metaschema.databind.model.IBoundInstanceModelChoiceGroup;
017import dev.metaschema.databind.model.IBoundInstanceModelFieldComplex;
018import dev.metaschema.databind.model.IBoundInstanceModelFieldScalar;
019import dev.metaschema.databind.model.IBoundInstanceModelGroupedAssembly;
020import dev.metaschema.databind.model.IBoundInstanceModelGroupedField;
021import edu.umd.cs.findbugs.annotations.NonNull;
022import edu.umd.cs.findbugs.annotations.Nullable;
023
024/**
025 * Handler interface for reading bound items during deserialization.
026 * <p>
027 * Implementations of this interface handle the reading of different types of
028 * model items (flags, fields, assemblies, choice groups).
029 */
030public interface IItemReadHandler {
031  /**
032   * Parse and return an item.
033   *
034   * @param parent
035   *          the parent Java object to use for serialization callbacks
036   * @param instance
037   *          the flag instance
038   * @return the Java object representing the parsed item
039   * @throws IOException
040   *           if an error occurred while parsing
041   */
042  @NonNull
043  Object readItemFlag(
044      @NonNull IBoundObject parent,
045      @NonNull IBoundInstanceFlag instance) throws IOException;
046
047  /**
048   * Parse and return an item.
049   *
050   * @param parent
051   *          the parent Java object to use for serialization callbacks
052   * @param instance
053   *          the field instance
054   * @return the Java object representing the parsed item
055   * @throws IOException
056   *           if an error occurred while parsing
057   */
058  @Nullable
059  Object readItemField(
060      @NonNull IBoundObject parent,
061      @NonNull IBoundInstanceModelFieldScalar instance) throws IOException;
062
063  /**
064   * Parse and return an item.
065   *
066   * @param parent
067   *          the parent Java object to use for serialization callbacks
068   * @param instance
069   *          the field instance
070   * @return the Java object representing the parsed item
071   * @throws IOException
072   *           if an error occurred while parsing
073   */
074  @NonNull
075  IBoundObject readItemField(
076      @NonNull IBoundObject parent,
077      @NonNull IBoundInstanceModelFieldComplex instance) throws IOException;
078
079  /**
080   * Parse and return an item.
081   *
082   * @param parent
083   *          the parent Java object to use for serialization callbacks
084   * @param instance
085   *          the field instance
086   * @return the Java object representing the parsed item
087   * @throws IOException
088   *           if an error occurred while parsing
089   */
090  @NonNull
091  IBoundObject readItemField(
092      @NonNull IBoundObject parent,
093      @NonNull IBoundInstanceModelGroupedField instance) throws IOException;
094
095  /**
096   * Parse and return an item.
097   *
098   * @param parent
099   *          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}