stevedlawrence commented on a change in pull request #436:
URL: https://github.com/apache/incubator-daffodil/pull/436#discussion_r509381752
##########
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.
Review comment:
Not sure mentioning the coroutine here adds anything since that's purely
an implementation details. People using this, which is what this doc is
intended for, dont' really care too much about that fact that we use a
coroutine behind the scenes.
----------------------------------------------------------------
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]
