001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.databind.io.xml;
007
008import org.codehaus.stax2.XMLEventReader2;
009
010import java.io.IOException;
011
012import javax.xml.stream.XMLStreamConstants;
013
014import dev.metaschema.core.model.IBoundObject;
015import dev.metaschema.databind.io.IParsingContext;
016import dev.metaschema.databind.model.IBoundDefinitionModelComplex;
017import dev.metaschema.databind.model.IBoundInstanceModel;
018import edu.umd.cs.findbugs.annotations.NonNull;
019
020/**
021 * Provides the context for parsing XML content into bound objects.
022 */
023public interface IXmlParsingContext extends IParsingContext<XMLEventReader2, IXmlProblemHandler> {
024
025  /**
026   * Parses XML into a bound object based on the provided {@code definition}.
027   * <p>
028   * Parses the {@link XMLStreamConstants#START_DOCUMENT}, any processing
029   * instructions, and the element.
030   *
031   * @param <CLASS>
032   *          the returned object type
033   * @param definition
034   *          the definition describing the element data to read
035   * @return the parsed object
036   * @throws IOException
037   *           if an error occurred while parsing the input
038   */
039  <CLASS> CLASS read(@NonNull IBoundDefinitionModelComplex definition) throws IOException;
040
041  /**
042   * Read the data associated with the {@code instance} and apply it to the
043   * provided {@code parentObject}.
044   *
045   * @param <T>
046   *          the item Java type
047   * @param instance
048   *          the instance to parse data for
049   * @param parentObject
050   *          the Java object that data parsed by this method will be stored in
051   * @param parseGrouping
052   *          if {@code true} parse the instance's grouping element or
053   *          {@code false} otherwise
054   * @return {@code true} if the instance was parsed, or {@code false} if the data
055   *         did not contain information for this instance
056   * @throws IOException
057   *           if an error occurred while parsing the input
058   *
059   */
060  <T> boolean readItems(
061      @NonNull IBoundInstanceModel<T> instance,
062      @NonNull IBoundObject parentObject,
063      boolean parseGrouping) throws IOException;
064}