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