stevedlawrence commented on a change in pull request #436:
URL: https://github.com/apache/incubator-daffodil/pull/436#discussion_r509382080
##########
File path:
daffodil-japi/src/main/java/org/apache/daffodil/japi/package-info.java
##########
@@ -217,6 +228,49 @@
* UnparseResult ur = dp.unparse(jdomInputter, wbc)
* }</pre>
*
+ * <h5>SAX Unparse</h5>
+ *
+ * In order to kick off an unparse via the SAX API, one must register the
+ * {@link org.apache.daffodil.japi.DaffodilInputContentHandler} as the
contentHandler for an XMLReader
+ * implementation. The call to the
+ * {@link
org.apache.daffodil.japi.DataProcessor#newContentHandlerInstance(java.nio.channels.WritableByteChannel)}
method must be provided with the {@link java.nio.channels.WritableByteChannel},
+ * where the unparsed data ought to be written to. Any XMLReader
implementation is permissible, as
+ * long as they allow support for the namespace and namespace-prefixes
features of XMLReader. The
+ * namespaces feature MUST be set to true, and namespace-prefixes is only
optional if the former is true.
+ *
+ * <pre>
+ * {@code
+ * ByteArrayInputStream is = new ByteArrayInputStream(data);
+ * DaffodilInputContentHandler inputContentHandler =
dp.newContentHandlerInstance(wbc);
+ * try {
+ * XMLReader xmlReader =
SAXParserFactory.newInstance().newSAXParser().getXMLReader();
+ * xmlReader.setContentHandler(inputContentHandler)
+ * } catch (ParserConfigurationException | SAXException e) {
+ * ...
+ * `}
+ * }
+ * </pre>
+ *
+ * The call to the XMLReader.parse method must be wrapped in a try/catch, as
+ * {@link org.apache.daffodil.japi.DaffodilInputContentHandler} relies on
throwing an exception to
+ * stop the coroutine and the XMLReader.parse in the case of any
errors/failures.
+ * There are two kinds of errors to expect
+ * {@link org.apache.daffodil.japi.DaffodilUnparseErrorSAXException}, for the
case when the
+ * {@link org.apache.daffodil.japi.UnparseResult#isError()}, and
+ * {@link org.apache.daffodil.japi.DaffodilUnparseErrorSAXException}, for any
other errors.
+ *
+ * <pre>
+ * {@code
+ * try {
+ * xmlReader.parse(new InputSource(is));
+ * } catch (DaffodilUnparseErrorSAXException | DaffodilUnhandledSAXException
e) {
+ * ...
+ * }
+ * UnparseResult ur = inputContHandler.getUnparseResult();
Review comment:
If we get a UnhandledSAXException, then what does getUnparseResult
return? Can it be null?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
