olabusayoT commented on a change in pull request #436:
URL: https://github.com/apache/incubator-daffodil/pull/436#discussion_r511935951
##########
File path:
daffodil-japi/src/main/java/org/apache/daffodil/japi/package-info.java
##########
@@ -217,6 +227,52 @@
* 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.DaffodilUnparseContentHandler} 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.
Review comment:
The caller has to set the namespaces feature, since it is called on the
XMLReader, and that is outside of the Daffodil unparse work. The places you'll
see Daffodil doing this is from the CLI and tests, but we don't set it for the
caller. As far as if there are bad things that could happen, i would say no
primarily because the namespaces feature should be set to true on default by
the XMLReader, but also because we have support for when the namespaces feature
isn't true.
According to the [docs](http://www.saxproject.org/namespaces.html), when the
namespaces feature is set to true, the XMLReader should send the
namespace/prefix mappings to the ContentHandler and include the uri and
localName when calling start/endElement. If it is false, then the
namespaces-feature has to be true, otherwise it is an illegal state. When the
latter feature is true, the namespace/prefix mappings are sent only through
startElement, and its AttributeImpl param (namespaces are treated like
attributes). The good news is we have support for extracting the
namespace/prefix mappings through either of these routes, so I'll update the
documentation to make it more generic and say "as long as they have XML
Namespace support."
The rest of the information should only matter for the parse side, once
[DAFFODIL-2422](https://issues.apache.org/jira/browse/DAFFODIL-2422) is
completed
----------------------------------------------------------------
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]
