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