001/*
002 * Portions of this software was developed by employees of the National Institute
003 * of Standards and Technology (NIST), an agency of the Federal Government and is
004 * being made available as a public service. Pursuant to title 17 United States
005 * Code Section 105, works of NIST employees are not subject to copyright
006 * protection in the United States. This software may be subject to foreign
007 * copyright. Permission in the United States and in foreign countries, to the
008 * extent that NIST may hold copyright, to use, copy, modify, create derivative
009 * works, and distribute this software and its documentation without fee is hereby
010 * granted on a non-exclusive basis, provided that this notice and disclaimer
011 * of warranty appears in all copies.
012 *
013 * THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, EITHER
014 * EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY
015 * THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF
016 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND FREEDOM FROM
017 * INFRINGEMENT, AND ANY WARRANTY THAT THE DOCUMENTATION WILL CONFORM TO THE
018 * SOFTWARE, OR ANY WARRANTY THAT THE SOFTWARE WILL BE ERROR FREE.  IN NO EVENT
019 * SHALL NIST BE LIABLE FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT,
020 * INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM,
021 * OR IN ANY WAY CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY,
022 * CONTRACT, TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PERSONS OR
023 * PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED FROM, OR AROSE OUT
024 * OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR SERVICES PROVIDED HEREUNDER.
025 */
026
027package gov.nist.secauto.metaschema.databind.io.xml;
028
029import gov.nist.secauto.metaschema.core.model.IFlagContainer;
030import gov.nist.secauto.metaschema.databind.io.IProblemHandler;
031import gov.nist.secauto.metaschema.databind.model.IAssemblyClassBinding;
032import gov.nist.secauto.metaschema.databind.model.IBoundFlagInstance;
033import gov.nist.secauto.metaschema.databind.model.IBoundNamedModelInstance;
034import gov.nist.secauto.metaschema.databind.model.IClassBinding;
035
036import java.io.IOException;
037import java.util.Collection;
038
039import javax.xml.stream.events.Attribute;
040import javax.xml.stream.events.StartElement;
041
042import edu.umd.cs.findbugs.annotations.NonNull;
043
044public interface IXmlProblemHandler extends IProblemHandler {
045  /**
046   * Callback used to handle an attribute that is unknown to the model being
047   * parsed.
048   *
049   * @param parentDefinition
050   *          the bound class currently describing the data being parsed
051   * @param targetObject
052   *          the Java object for the {@code parentDefinition}
053   * @param attribute
054   *          the unknown attribute
055   * @param parsingContext
056   *          the XML parsing context used for parsing
057   * @return {@code true} if the attribute was handled by this method, or
058   *         {@code false} otherwise
059   * @throws IOException
060   *           if an error occurred while handling the unrecognized data
061   */
062  default boolean handleUnknownAttribute(
063      @NonNull IFlagContainer parentDefinition,
064      @NonNull Object targetObject,
065      @NonNull Attribute attribute,
066      @NonNull IXmlParsingContext parsingContext) throws IOException {
067    return false;
068  }
069
070  /**
071   * Callback used to handle an element that is unknown to the model being parsed.
072   *
073   * @param parentDefinition
074   *          the bound assembly class on which the missing instances are found
075   * @param targetObject
076   *          the Java object for the {@code parentDefinition}
077   * @param start
078   *          the parsed XML start element
079   * @param parsingContext
080   *          the XML parsing context used for parsing
081   * @return {@code true} if the element was handled by this method, or
082   *         {@code false} otherwise
083   * @throws IOException
084   *           if an error occurred while handling the unrecognized data
085   */
086  default boolean handleUnknownElement(
087      @NonNull IAssemblyClassBinding parentDefinition,
088      @NonNull Object targetObject,
089      @NonNull StartElement start,
090      @NonNull IXmlParsingContext parsingContext) throws IOException {
091    return false;
092  }
093
094  /**
095   * A callback used to handle bound flag instances for which no data was found
096   * when the content was parsed.
097   * <p>
098   * This can be used to supply default or prescribed values based on application
099   * logic.
100   *
101   * @param parentDefinition
102   *          the bound assembly class on which the missing instances are found
103   * @param targetObject
104   *          the Java object for the {@code parentDefinition}
105   * @param unhandledInstances
106   *          the set of instances that had no data to parse
107   * @throws IOException
108   *           if an error occurred while handling the missing instances
109   */
110  default void handleMissingFlagInstances(
111      @NonNull IClassBinding parentDefinition,
112      @NonNull Object targetObject,
113      @NonNull Collection<IBoundFlagInstance> unhandledInstances)
114      throws IOException {
115    handleMissingInstances(parentDefinition, targetObject, unhandledInstances);
116  }
117
118  /**
119   * A callback used to handle bound model instances for which no data was found
120   * when the content was parsed.
121   * <p>
122   * This can be used to supply default or prescribed values based on application
123   * logic.
124   *
125   * @param parentDefinition
126   *          the bound assembly class on which the missing instances are found
127   * @param targetObject
128   *          the Java object for the {@code parentDefinition}
129   * @param unhandledInstances
130   *          the set of instances that had no data to parse
131   * @throws IOException
132   *           if an error occurred while handling the missing instances
133   */
134  default void handleMissingModelInstances(
135      @NonNull IAssemblyClassBinding parentDefinition,
136      @NonNull Object targetObject,
137      @NonNull Collection<IBoundNamedModelInstance> unhandledInstances)
138      throws IOException {
139    handleMissingInstances(parentDefinition, targetObject, unhandledInstances);
140
141  }
142}