Merge branch 'release/1.1.0' into master

Release: com.io7m.blackthorne 1.1.0
Change: Allow content handlers to throw raw exceptions (Ticket: #2)

README-CHANGES.xml

@@ -1,9 +1,18 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <c:changelog project="com.io7m.blackthorne" xmlns:c="urn:com.io7m.changelog:4.0">
   <c:releases>
-    <c:release date="2020-10-15T14:07:35+00:00" ticket-system="com.github.io7m.blackthorne" version="1.0.0">
+    <c:release date="2020-10-15T00:00:00+00:00" ticket-system="com.github.io7m.blackthorne" version="1.0.0">
       <c:changes/>
     </c:release>
+    <c:release date="2020-10-24T20:32:34+00:00" ticket-system="com.github.io7m.blackthorne" version="1.1.0">
+      <c:changes>
+        <c:change date="2020-10-24T20:32:34+00:00" summary="Allow content handlers to throw raw exceptions">
+          <c:tickets>
+            <c:ticket id="2"/>
+          </c:tickets>
+        </c:change>
+      </c:changes>
+    </c:release>
   </c:releases>
   <c:ticket-systems>
     <c:ticket-system default="true" id="com.github.io7m.blackthorne" url="https://www.github.com/io7m/blackthorne/issues/"/>

com.io7m.blackthorne.api/pom.xml

@@ -8,7 +8,7 @@
   <parent>
     <artifactId>com.io7m.blackthorne</artifactId>
     <groupId>com.io7m.blackthorne</groupId>
-    <version>1.0.0</version>
+    <version>1.1.0</version>
   </parent>
 
   <artifactId>com.io7m.blackthorne.api</artifactId>

com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/BTAttributesHandlerType.java

@@ -18,7 +18,6 @@
 package com.io7m.blackthorne.api;
 
 import org.xml.sax.Attributes;
-import org.xml.sax.SAXException;
 
 /**
  * A function that, given a set of attributes, returns a {@code T}.
@@ -36,11 +35,11 @@ public interface BTAttributesHandlerType<T>
    *
    * @return A value of {@code T}
    *
-   * @throws SAXException On errors
+   * @throws Exception On errors
    */
 
   T parse(
     BTElementParsingContextType context,
     Attributes attributes)
-    throws SAXException;
+    throws Exception;
 }

com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/BTCharacterHandlerType.java

@@ -17,8 +17,6 @@
 
 package com.io7m.blackthorne.api;
 
-import org.xml.sax.SAXException;
-
 /**
  * A function that, given a string, returns a {@code T}.
  *
@@ -37,13 +35,13 @@ public interface BTCharacterHandlerType<T>
    *
    * @return A value of {@code T}
    *
-   * @throws SAXException On errors
+   * @throws Exception On errors
    */
 
   T parse(
     BTElementParsingContextType context,
     char[] characters,
     int offset,
     int length)
-    throws SAXException;
+    throws Exception;
 }

com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/BTContentHandler.java

@@ -17,19 +17,20 @@
 package com.io7m.blackthorne.api;
 
 import com.io7m.jlexing.core.LexicalPosition;
-import java.net.URI;
-import java.util.HashMap;
-import java.util.Map;
-import java.util.Objects;
-import java.util.Optional;
-import java.util.function.Consumer;
 import org.xml.sax.Attributes;
 import org.xml.sax.Locator;
 import org.xml.sax.SAXException;
 import org.xml.sax.SAXParseException;
 import org.xml.sax.ext.DefaultHandler2;
 import org.xml.sax.ext.Locator2;
 
+import java.net.URI;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.function.Consumer;
+
 /**
  * A dispatching handler that produces values of type {@code T}. The handler is responsible for
  * instantiating a content handler based on the received document namespace URI.
@@ -95,6 +96,18 @@ public static <U> BTContentHandlerBuilderType<U> builder(
     return new Builder<>();
   }
 
+  private static String messageOrException(
+    final Exception e)
+  {
+    final var messageOrNull = e.getMessage();
+    if (messageOrNull == null) {
+      return String.format(
+        "No error message provided for exception %s",
+        e.getClass().getName());
+    }
+    return messageOrNull;
+  }
+
   @Override
   public void setDocumentLocator(
     final Locator in_locator)
@@ -109,12 +122,13 @@ public void startElement(
     final String localName,
     final String qualifiedName,
     final Attributes attributes)
-    throws SAXException
   {
     try {
       this.stackHandler.onElementStarted(namespaceURI, localName, attributes);
     } catch (final SAXParseException e) {
       this.error(e);
+    } catch (final Exception e) {
+      this.error(this.saxParseExceptionOf(e));
     }
   }
 
@@ -123,12 +137,13 @@ public void endElement(
     final String namespaceURI,
     final String localName,
     final String qualifiedName)
-    throws SAXException
   {
     try {
       this.stackHandler.onElementFinished(namespaceURI, localName);
     } catch (final SAXParseException e) {
       this.error(e);
+    } catch (final Exception e) {
+      this.error(this.saxParseExceptionOf(e));
     }
   }
 
@@ -137,12 +152,13 @@ public void characters(
     final char[] ch,
     final int start,
     final int length)
-    throws SAXException
   {
     try {
       this.stackHandler.onCharacters(ch, start, length);
     } catch (final SAXParseException e) {
       this.error(e);
+    } catch (final Exception e) {
+      this.error(this.saxParseExceptionOf(e));
     }
   }
 
@@ -189,18 +205,6 @@ public void fatalError(
     throw e;
   }
 
-  private static String messageOrException(
-    final Exception e)
-  {
-    final var messageOrNull = e.getMessage();
-    if (messageOrNull == null) {
-      return String.format(
-        "No error message provided for exception %s",
-        e.getClass().getName());
-    }
-    return messageOrNull;
-  }
-
   private LexicalPosition<URI> currentLexical()
   {
     final LexicalPosition<URI> lexicalPosition;
@@ -223,6 +227,12 @@ private LexicalPosition<URI> currentLexical()
     return lexicalPosition;
   }
 
+  private SAXParseException saxParseExceptionOf(
+    final Exception e)
+  {
+    return new SAXParseException(e.getLocalizedMessage(), this.locator, e);
+  }
+
   /**
    * @return The parsed value
    */

com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/BTContentHandlerBuilderType.java

@@ -55,7 +55,9 @@ default BTContentHandlerBuilderType<T> addHandler(
     final String localName,
     final BTElementHandlerConstructorType<?, T> constructor)
   {
-    return this.addHandler(BTQualifiedName.of(namespaceURI, localName), constructor);
+    return this.addHandler(
+      BTQualifiedName.of(namespaceURI, localName),
+      constructor);
   }
 
   /**

com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/BTElementHandlerConstructorType.java

@@ -16,8 +16,6 @@
 
 package com.io7m.blackthorne.api;
 
-import org.xml.sax.SAXException;
-
 /**
  * A content handler constructor that produces handlers that produce values of type {@code A}
  *
@@ -34,11 +32,11 @@ public interface BTElementHandlerConstructorType<CT, RT>
    *
    * @return A new content handler
    *
-   * @throws SAXException If required
+   * @throws Exception If required
    * @see BTElementParsingContextType#parseException(Exception)
    */
 
   BTElementHandlerType<? extends CT, ? extends RT> create(
     BTElementParsingContextType context)
-    throws SAXException;
+    throws Exception;
 }

com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/BTElementHandlerType.java

@@ -18,7 +18,6 @@
 package com.io7m.blackthorne.api;
 
 import org.xml.sax.Attributes;
-import org.xml.sax.SAXException;
 
 import java.util.Map;
 import java.util.function.Function;
@@ -82,13 +81,13 @@ default BTIgnoreUnrecognizedElements onShouldIgnoreUnrecognizedElements(
    * @param context    The parsing context
    * @param attributes The element's attributes
    *
-   * @throws SAXException On parse errors
+   * @throws Exception On parse errors
    */
 
   default void onElementStart(
     final BTElementParsingContextType context,
     final Attributes attributes)
-    throws SAXException
+    throws Exception
   {
 
   }
@@ -101,25 +100,25 @@ default void onElementStart(
    *
    * @return The value produced by all of the data received up to this point
    *
-   * @throws SAXException On parse errors
+   * @throws Exception On parse errors
    */
 
   RT onElementFinished(BTElementParsingContextType context)
-    throws SAXException;
+    throws Exception;
 
   /**
    * A child element has been parsed successfully and produced a result.
    *
    * @param context The parsing context
    * @param result  The value produced by the child element
    *
-   * @throws SAXException On parse errors
+   * @throws Exception On parse errors
    */
 
   default void onChildValueProduced(
     final BTElementParsingContextType context,
     final CT result)
-    throws SAXException
+    throws Exception
   {
 
   }
@@ -132,15 +131,15 @@ default void onChildValueProduced(
    * @param offset  The start of the data within {@code data}
    * @param length  The length of the data within {@code data}
    *
-   * @throws SAXException On parse errors
+   * @throws Exception On parse errors
    */
 
   default void onCharacters(
     final BTElementParsingContextType context,
     final char[] data,
     final int offset,
     final int length)
-    throws SAXException
+    throws Exception
   {
 
   }

com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/BTException.java

@@ -27,15 +27,6 @@ public final class BTException extends Exception
 {
   private final List<BTParseError> errors;
 
-  /**
-   * @return The parse errors encountered during parsing
-   */
-
-  public List<BTParseError> errors()
-  {
-    return this.errors;
-  }
-
   /**
    * Construct an exception.
    *
@@ -84,4 +75,13 @@ public BTException(
     super(Objects.requireNonNull(inCause, "cause"));
     this.errors = Objects.requireNonNull(inErrors, "errors");
   }
+
+  /**
+   * @return The parse errors encountered during parsing
+   */
+
+  public List<BTParseError> errors()
+  {
+    return this.errors;
+  }
 }

com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/BTFunctorHandler.java

@@ -18,7 +18,6 @@
 package com.io7m.blackthorne.api;
 
 import org.xml.sax.Attributes;
-import org.xml.sax.SAXException;
 
 import java.util.Map;
 import java.util.Objects;
@@ -76,7 +75,7 @@ public BTIgnoreUnrecognizedElements onShouldIgnoreUnrecognizedElements(
   public void onElementStart(
     final BTElementParsingContextType context,
     final Attributes attributes)
-    throws SAXException
+    throws Exception
   {
     this.handler.onElementStart(context, attributes);
   }
@@ -85,7 +84,7 @@ public void onElementStart(
   public void onChildValueProduced(
     final BTElementParsingContextType context,
     final A result)
-    throws SAXException
+    throws Exception
   {
     this.handler.onChildValueProduced(context, result);
   }
@@ -96,14 +95,14 @@ public void onCharacters(
     final char[] data,
     final int offset,
     final int length)
-    throws SAXException
+    throws Exception
   {
     this.handler.onCharacters(context, data, offset, length);
   }
 
   @Override
   public C onElementFinished(final BTElementParsingContextType context)
-    throws SAXException
+    throws Exception
   {
     return this.function.apply(this.handler.onElementFinished(context));
   }

com.io7m.blackthorne.api/src/main/java/com/io7m/blackthorne/api/BTScalarAttributeHandler.java

@@ -18,7 +18,6 @@
 package com.io7m.blackthorne.api;
 
 import org.xml.sax.Attributes;
-import org.xml.sax.SAXException;
 
 import java.util.Objects;
 
@@ -59,7 +58,7 @@ public String name()
   public void onElementStart(
     final BTElementParsingContextType context,
     final Attributes attributes)
-    throws SAXException
+    throws Exception
   {
     this.result = this.handler.parse(context, attributes);
   }