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.IProblemHandler;
010import gov.nist.secauto.metaschema.databind.model.IBoundDefinitionModelAssembly;
011import gov.nist.secauto.metaschema.databind.model.IBoundDefinitionModelComplex;
012import gov.nist.secauto.metaschema.databind.model.IBoundInstanceFlag;
013import gov.nist.secauto.metaschema.databind.model.IBoundInstanceModel;
014
015import java.io.IOException;
016import java.util.Collection;
017
018import javax.xml.stream.events.Attribute;
019import javax.xml.stream.events.StartElement;
020
021import edu.umd.cs.findbugs.annotations.NonNull;
022
023@FunctionalInterface
024public interface IXmlProblemHandler extends IProblemHandler {
025  /**
026   * Callback used to handle an attribute that is unknown to the model being
027   * parsed.
028   *
029   * @param parentDefinition
030   *          the bound class currently describing the data being parsed
031   * @param targetObject
032   *          the Java object for the {@code parentDefinition}
033   * @param attribute
034   *          the unknown attribute
035   * @param parsingContext
036   *          the XML parsing context used for parsing
037   * @return {@code true} if the attribute was handled by this method, or
038   *         {@code false} otherwise
039   * @throws IOException
040   *           if an error occurred while handling the unrecognized data
041   */
042  default boolean handleUnknownAttribute(
043      @NonNull IBoundDefinitionModelComplex parentDefinition,
044      @NonNull IBoundObject targetObject,
045      @NonNull Attribute attribute,
046      @NonNull IXmlParsingContext parsingContext) throws IOException {
047    return false;
048  }
049
050  /**
051   * Callback used to handle an element that is unknown to the model being parsed.
052   *
053   * @param parentDefinition
054   *          the bound assembly class on which the missing instances are found
055   * @param targetObject
056   *          the Java object for the {@code parentDefinition}
057   * @param start
058   *          the parsed XML start element
059   * @param parsingContext
060   *          the XML parsing context used for parsing
061   * @return {@code true} if the element was handled by this method, or
062   *         {@code false} otherwise
063   * @throws IOException
064   *           if an error occurred while handling the unrecognized data
065   */
066  default boolean handleUnknownElement(
067      @NonNull IBoundDefinitionModelAssembly parentDefinition,
068      @NonNull IBoundObject targetObject,
069      @NonNull StartElement start,
070      @NonNull IXmlParsingContext parsingContext) throws IOException {
071    return false;
072  }
073
074  /**
075   * A callback used to handle bound flag instances for which no data was found
076   * when the content was parsed.
077   * <p>
078   * This can be used to supply default or prescribed values based on application
079   * logic.
080   *
081   * @param parentDefinition
082   *          the bound assembly class on which the missing instances are found
083   * @param targetObject
084   *          the Java object for the {@code parentDefinition}
085   * @param unhandledInstances
086   *          the set of instances that had no data to parse
087   * @throws IOException
088   *           if an error occurred while handling the missing instances
089   */
090  default void handleMissingFlagInstances(
091      @NonNull IBoundDefinitionModelComplex parentDefinition,
092      @NonNull IBoundObject targetObject,
093      @NonNull Collection<IBoundInstanceFlag> unhandledInstances)
094      throws IOException {
095    handleMissingInstances(parentDefinition, targetObject, unhandledInstances);
096  }
097
098  /**
099   * A callback used to handle bound model instances for which no data was found
100   * when the content was parsed.
101   * <p>
102   * This can be used to supply default or prescribed values based on application
103   * logic.
104   *
105   * @param parentDefinition
106   *          the bound assembly class on which the missing instances are found
107   * @param targetObject
108   *          the Java object for the {@code parentDefinition}
109   * @param unhandledInstances
110   *          the set of instances that had no data to parse
111   * @throws IOException
112   *           if an error occurred while handling the missing instances
113   */
114  default void handleMissingModelInstances(
115      @NonNull IBoundDefinitionModelAssembly parentDefinition,
116      @NonNull IBoundObject targetObject,
117      @NonNull Collection<? extends IBoundInstanceModel<?>> unhandledInstances)
118      throws IOException {
119    handleMissingInstances(parentDefinition, targetObject, unhandledInstances);
120  }
121}