1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.databind.io.xml;
7   
8   import org.codehaus.stax2.XMLEventReader2;
9   
10  import java.io.IOException;
11  
12  import javax.xml.stream.XMLStreamConstants;
13  
14  import dev.metaschema.core.model.IBoundObject;
15  import dev.metaschema.databind.io.IParsingContext;
16  import dev.metaschema.databind.model.IBoundDefinitionModelComplex;
17  import dev.metaschema.databind.model.IBoundInstanceModel;
18  import edu.umd.cs.findbugs.annotations.NonNull;
19  
20  /**
21   * Provides the context for parsing XML content into bound objects.
22   */
23  public interface IXmlParsingContext extends IParsingContext<XMLEventReader2, IXmlProblemHandler> {
24  
25    /**
26     * Parses XML into a bound object based on the provided {@code definition}.
27     * <p>
28     * Parses the {@link XMLStreamConstants#START_DOCUMENT}, any processing
29     * instructions, and the element.
30     *
31     * @param <CLASS>
32     *          the returned object type
33     * @param definition
34     *          the definition describing the element data to read
35     * @return the parsed object
36     * @throws IOException
37     *           if an error occurred while parsing the input
38     */
39    <CLASS> CLASS read(@NonNull IBoundDefinitionModelComplex definition) throws IOException;
40  
41    /**
42     * Read the data associated with the {@code instance} and apply it to the
43     * provided {@code parentObject}.
44     *
45     * @param <T>
46     *          the item Java type
47     * @param instance
48     *          the instance to parse data for
49     * @param parentObject
50     *          the Java object that data parsed by this method will be stored in
51     * @param parseGrouping
52     *          if {@code true} parse the instance's grouping element or
53     *          {@code false} otherwise
54     * @return {@code true} if the instance was parsed, or {@code false} if the data
55     *         did not contain information for this instance
56     * @throws IOException
57     *           if an error occurred while parsing the input
58     *
59     */
60    <T> boolean readItems(
61        @NonNull IBoundInstanceModel<T> instance,
62        @NonNull IBoundObject parentObject,
63        boolean parseGrouping) throws IOException;
64  }