Improved parser errors and warnings to include the resource the error was found in. Also improved Javadoc documentation.

Author: David Waltermire

core/src/main/java/gov/nist/secauto/metaschema/core/datatype/AbstractDataTypeAdapter.java

@@ -19,6 +19,7 @@
 import org.codehaus.stax2.evt.XMLEventFactory2;
 
 import java.io.IOException;
+import java.net.URI;
 
 import javax.xml.namespace.QName;
 import javax.xml.stream.XMLEventWriter;
@@ -91,15 +92,14 @@ public boolean isXmlMixed() {
   }
 
   @Override
-  public TYPE parse(XMLEventReader2 eventReader) throws IOException {
+  public TYPE parse(XMLEventReader2 eventReader, URI resource) throws IOException {
     StringBuilder builder = new StringBuilder();
     XMLEvent nextEvent;
     try {
       while (!(nextEvent = eventReader.peek()).isEndElement()) {
         if (!nextEvent.isCharacters()) {
-          throw new IOException(String.format("Invalid content '%s' at %s",
-              XmlEventUtil.toString(nextEvent),
-              XmlEventUtil.toString(nextEvent.getLocation())));
+          throw new IOException(String.format("Invalid content %s",
+              XmlEventUtil.toString(nextEvent, resource)));
         }
         Characters characters = nextEvent.asCharacters();
         builder.append(characters.getData());
@@ -115,7 +115,7 @@ public TYPE parse(XMLEventReader2 eventReader) throws IOException {
         throw new IOException(
             String.format("Malformed data '%s'%s. %s",
                 value,
-                XmlEventUtil.generateLocationMessage(nextEvent),
+                XmlEventUtil.generateLocationMessage(nextEvent, resource),
                 ex.getLocalizedMessage()),
             ex);
       }
@@ -129,12 +129,12 @@ public TYPE parse(XMLEventReader2 eventReader) throws IOException {
    * the string-based parsing method.
    */
   @Override
-  public TYPE parse(JsonParser parser) throws IOException {
+  public TYPE parse(JsonParser parser, URI resource) throws IOException {
     String value = parser.getValueAsString();
     if (value == null) {
       throw new IOException(
           String.format("Unable to get null value as text%s",
-              JsonUtil.generateLocationMessage(parser)));
+              JsonUtil.generateLocationMessage(parser, resource)));
     }
     // skip over value
     parser.nextToken();
@@ -144,7 +144,7 @@ public TYPE parse(JsonParser parser) throws IOException {
       throw new IOException(
           String.format("Malformed data '%s'%s. %s",
               value,
-              JsonUtil.generateLocationMessage(parser),
+              JsonUtil.generateLocationMessage(parser, resource),
               ex.getLocalizedMessage()),
           ex);
     }
@@ -226,7 +226,7 @@ public ITEM_TYPE cast(IAnyAtomicItem item) {
   @NonNull
   protected ITEM_TYPE castInternal(@NonNull IAnyAtomicItem item) {
     // try string based casting as a fallback
-    String itemString = null;
+    String itemString;
     try {
       itemString = item.asString();
       TYPE value = parse(itemString);

core/src/main/java/gov/nist/secauto/metaschema/core/datatype/IDataTypeAdapter.java

@@ -19,8 +19,8 @@
 
 import java.io.IOException;
 import java.lang.reflect.Field;
+import java.net.URI;
 import java.util.List;
-import java.util.function.Supplier;
 
 import javax.xml.namespace.QName;
 import javax.xml.stream.XMLEventWriter;
@@ -201,90 +201,30 @@ default boolean isAtomic() {
    *
    * @param eventReader
    *          the XML parser used to read the parsed value
+   * @param resource
+   *          the resource being parsed
    * @return the parsed value
    * @throws IOException
    *           if a parsing error occurs
    */
   // TODO: migrate code to XML parser implementation.
   @NonNull
-  TYPE parse(@NonNull XMLEventReader2 eventReader) throws IOException;
+  TYPE parse(@NonNull XMLEventReader2 eventReader, @NonNull URI resource) throws IOException;
 
   /**
    * Parses a JSON property value.
    *
    * @param parser
    *          the JSON parser used to read the parsed value
+   * @param resource
+   *          the resource being parsed
    * @return the parsed value
    * @throws IOException
    *           if a parsing error occurs
    */
   // TODO: migrate code to JSON parser implementation.
   @NonNull
-  TYPE parse(@NonNull JsonParser parser) throws IOException;
-
-  /**
-   * Parses a provided string using {@link #parse(String)}.
-   * <p>
-   * This method may pre-parse the data and then return copies, since the data can
-   * only be parsed once, but the supplier might be called multiple times.
-   *
-   * @param value
-   *          the string value to parse
-   * @return a supplier that will provide new instances of the parsed data
-   * @throws IOException
-   *           if an error occurs while parsing
-   * @throws IllegalArgumentException
-   *           if the provided value is invalid based on the data type
-   * @see #parse(String)
-   */
-  @NonNull
-  default Supplier<TYPE> parseAndSupply(@NonNull String value) throws IOException {
-    TYPE retval = parse(value);
-    return () -> copy(retval);
-  }
-
-  /**
-   * Parses a provided string using
-   * {@link IDataTypeAdapter#parse(XMLEventReader2)}.
-   * <p>
-   * This method may pre-parse the data and then return copies, since the data can
-   * only be parsed once, but the supplier might be called multiple times.
-   *
-   * @param eventReader
-   *          the XML parser used to read the parsed value
-   * @return a supplier that will provide new instances of the parsed data
-   * @throws IOException
-   *           if an error occurs while parsing
-   * @see #parse(String)
-   * @see #parse(XMLEventReader2)
-   */
-  // TODO: migrate code to XML parser implementation.
-  @NonNull
-  default Supplier<TYPE> parseAndSupply(@NonNull XMLEventReader2 eventReader) throws IOException {
-    TYPE retval = parse(eventReader);
-    return () -> copy(retval);
-  }
-
-  /**
-   * Parses a provided string using {@link #parse(JsonParser)}.
-   * <p>
-   * This method may pre-parse the data and then return copies, since the data can
-   * only be parsed once, but the supplier might be called multiple times.
-   *
-   * @param parser
-   *          the JSON parser used to read the parsed value
-   * @return a supplier that will provide new instances of the parsed data
-   * @throws IOException
-   *           if an error occurs while parsing
-   * @see #parse(String)
-   * @see #parse(JsonParser)
-   */
-  // TODO: migrate code to JSON parser implementation.
-  @NonNull
-  default Supplier<TYPE> parseAndSupply(@NonNull JsonParser parser) throws IOException {
-    TYPE retval = parse(parser);
-    return () -> copy(retval);
-  }
+  TYPE parse(@NonNull JsonParser parser, @NonNull URI resource) throws IOException;
 
   /**
    * Writes the provided Java class instance data as XML. The parent element
@@ -306,7 +246,10 @@ default Supplier<TYPE> parseAndSupply(@NonNull JsonParser parser) throws IOExcep
    *           if an unexpected error occurred while writing to the output stream
    */
   // TODO: migrate code to XML writer implementation.
-  void writeXmlValue(@NonNull Object instance, @NonNull StartElement parent, @NonNull XMLEventFactory2 eventFactory,
+  void writeXmlValue(
+      @NonNull Object instance,
+      @NonNull StartElement parent,
+      @NonNull XMLEventFactory2 eventFactory,
       @NonNull XMLEventWriter eventWriter)
       throws IOException;
 

core/src/main/java/gov/nist/secauto/metaschema/core/datatype/adapter/BooleanAdapter.java

@@ -19,12 +19,18 @@
 import gov.nist.secauto.metaschema.core.util.ObjectUtils;
 
 import java.io.IOException;
+import java.net.URI;
 import java.util.List;
 
 import javax.xml.namespace.QName;
 
 import edu.umd.cs.findbugs.annotations.NonNull;
 
+/**
+ * Support for the Metaschema <a href=
+ * "https://pages.nist.gov/metaschema/specification/datatypes/#boolean">boolean</a>
+ * data type.
+ */
 public class BooleanAdapter
     extends AbstractDataTypeAdapter<Boolean, IBooleanItem> {
   @NonNull
@@ -52,7 +58,7 @@ public Boolean parse(String value) {
   }
 
   @Override
-  public Boolean parse(JsonParser parser) throws IOException {
+  public Boolean parse(JsonParser parser, URI resource) throws IOException {
     Boolean value = parser.getBooleanValue();
     // skip over value
     parser.nextToken();

core/src/main/java/gov/nist/secauto/metaschema/core/datatype/markup/MarkupLineAdapter.java

@@ -15,13 +15,19 @@
 import org.codehaus.stax2.XMLEventReader2;
 
 import java.io.IOException;
+import java.net.URI;
 import java.util.List;
 
 import javax.xml.namespace.QName;
 import javax.xml.stream.XMLStreamException;
 
 import edu.umd.cs.findbugs.annotations.NonNull;
 
+/**
+ * Support for the Metaschema <a href=
+ * "https://pages.nist.gov/metaschema/specification/datatypes/#markup-line">markup-line</a>
+ * data type.
+ */
 public class MarkupLineAdapter
     extends AbstractMarkupAdapter<MarkupLine> {
   @NonNull
@@ -47,16 +53,16 @@ public MarkupLine parse(String value) {
 
   @SuppressWarnings("null")
   @Override
-  public MarkupLine parse(XMLEventReader2 eventReader) throws IOException {
+  public MarkupLine parse(XMLEventReader2 eventReader, URI resource) throws IOException {
     try {
-      return XmlMarkupParser.instance().parseMarkupline(eventReader);
+      return XmlMarkupParser.instance().parseMarkupline(eventReader, resource);
     } catch (XMLStreamException ex) {
       throw new IOException(ex);
     }
   }
 
   @Override
-  public MarkupLine parse(JsonParser parser) throws IOException {
+  public MarkupLine parse(JsonParser parser, URI resource) throws IOException {
     @SuppressWarnings("null")
     MarkupLine retval = parse(parser.getValueAsString());
     // skip past value

core/src/main/java/gov/nist/secauto/metaschema/core/datatype/markup/MarkupMultilineAdapter.java

@@ -15,13 +15,19 @@
 import org.codehaus.stax2.XMLEventReader2;
 
 import java.io.IOException;
+import java.net.URI;
 import java.util.List;
 
 import javax.xml.namespace.QName;
 import javax.xml.stream.XMLStreamException;
 
 import edu.umd.cs.findbugs.annotations.NonNull;
 
+/**
+ * Support for the Metaschema <a href=
+ * "https://pages.nist.gov/metaschema/specification/datatypes/#markup-line">markup-multiline</a>
+ * data type.
+ */
 public class MarkupMultilineAdapter
     extends AbstractMarkupAdapter<MarkupMultiline> {
   @NonNull
@@ -52,16 +58,16 @@ public MarkupMultiline parse(String value) {
 
   @SuppressWarnings("null")
   @Override
-  public MarkupMultiline parse(XMLEventReader2 eventReader) throws IOException {
+  public MarkupMultiline parse(XMLEventReader2 eventReader, URI resource) throws IOException {
     try {
-      return XmlMarkupParser.instance().parseMarkupMultiline(eventReader);
+      return XmlMarkupParser.instance().parseMarkupMultiline(eventReader, resource);
     } catch (XMLStreamException ex) {
       throw new IOException(ex);
     }
   }
 
   @Override
-  public MarkupMultiline parse(JsonParser parser) throws IOException {
+  public MarkupMultiline parse(JsonParser parser, URI resource) throws IOException {
     @SuppressWarnings("null")
     MarkupMultiline retval = parse(parser.getValueAsString());
     // skip past value