site/docs/3.2.0/javadoc/org/apache/daffodil/japi/package-summary.html - daffodil-site - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <!-- NewPage -->
 <html lang="en">
 <head>
 <!-- Generated by javadoc -->
 <title>org.apache.daffodil.japi (Apache Daffodil 3.2.0 Java API)</title>
 <link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style">
 <script type="text/javascript" src="../../../../script.js"></script>
 </head>
 <body>
 <script type="text/javascript"><!--
     try {
         if (location.href.indexOf('is-external=true') == -1) {
             parent.document.title="org.apache.daffodil.japi (Apache Daffodil 3.2.0 Java API)";
         }
     }
     catch(err) {
     }
 //-->
 </script>
 <noscript>
 <div>JavaScript is disabled on your browser.</div>
 </noscript>
 <!-- ========= START OF TOP NAVBAR ======= -->
 <div class="topNav"><a name="navbar.top">
 <!--   -->
 </a>
 <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
 <a name="navbar.top.firstrow">
 <!--   -->
 </a>
 <ul class="navList" title="Navigation">
 <li><a href="../../../../overview-summary.html">Overview</a></li>
 <li class="navBarCell1Rev">Package</li>
 <li>Class</li>
 <li><a href="package-tree.html">Tree</a></li>
 <li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../help-doc.html">Help</a></li>
 </ul>
 </div>
 <div class="subNav">
 <ul class="navList">
 <li>Prev&nbsp;Package</li>
 <li><a href="../../../../org/apache/daffodil/japi/debugger/package-summary.html">Next&nbsp;Package</a></li>
 </ul>
 <ul class="navList">
 <li><a href="../../../../index.html?org/apache/daffodil/japi/package-summary.html" target="_top">Frames</a></li>
 <li><a href="package-summary.html" target="_top">No&nbsp;Frames</a></li>
 </ul>
 <ul class="navList" id="allclasses_navbar_top">
 <li><a href="../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
 </ul>
 <div>
 <script type="text/javascript"><!--
   allClassesLink = document.getElementById("allclasses_navbar_top");
   if(window==top) {
     allClassesLink.style.display = "block";
   }
   else {
     allClassesLink.style.display = "none";
   }
   //-->
 </script>
 </div>
 <a name="skip.navbar.top">
 <!--   -->
 </a></div>
 <!-- ========= END OF TOP NAVBAR ========= -->
 <div class="header">
 <h1 title="Package" class="title">Package&nbsp;org.apache.daffodil.japi</h1>
 <div class="docSummary">
 <div class="block">Provides the classes necessary to compile DFDL schemas, parse and
  unparse files using the compiled objects, and retrieve results and
  parsing diagnostics</div>
 </div>
 <p>See:&nbsp;<a href="#package.description">Description</a></p>
 </div>
 <div class="contentContainer">
 <ul class="blockList">
 <li class="blockList">
 <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation">
 <caption><span>Class Summary</span><span class="tabEnd">&nbsp;</span></caption>
 <tr>
 <th class="colFirst" scope="col">Class</th>
 <th class="colLast" scope="col">Description</th>
 </tr>
 <tbody>
 <tr class="altColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/Compiler.html" title="class in org.apache.daffodil.japi">Compiler</a></td>
 <td class="colLast">
 <div class="block">Compile DFDL schemas into <a href="../../../../org/apache/daffodil/japi/ProcessorFactory.html" title="class in org.apache.daffodil.japi"><code>ProcessorFactory</code></a>'s or reload saved parsers into <a href="../../../../org/apache/daffodil/japi/DataProcessor.html" title="class in org.apache.daffodil.japi"><code>DataProcessor</code></a>'s.</div>
 </td>
 </tr>
 <tr class="rowColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/Daffodil.html" title="class in org.apache.daffodil.japi">Daffodil</a></td>
 <td class="colLast">
 <div class="block">API Suitable for Java programmers to use.</div>
 </td>
 </tr>
 <tr class="altColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/DaffodilParseXMLReader.html" title="class in org.apache.daffodil.japi">DaffodilParseXMLReader</a></td>
 <td class="colLast">
 <div class="block">SAX method of parsing schema and getting the DFDL Infoset via some
  org.xml.sax.ContentHandler, based on the org.xml.sax.XMLReader interface</div>
 </td>
 </tr>
 <tr class="rowColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/DaffodilUnparseContentHandler.html" title="class in org.apache.daffodil.japi">DaffodilUnparseContentHandler</a></td>
 <td class="colLast">
 <div class="block">Accepts SAX callback events from any SAX XMLReader for unparsing</div>
 </td>
 </tr>
 <tr class="altColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/DataLocation.html" title="class in org.apache.daffodil.japi">DataLocation</a></td>
 <td class="colLast">
 <div class="block">Information related to a location in data</div>
 </td>
 </tr>
 <tr class="rowColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/DataProcessor.html" title="class in org.apache.daffodil.japi">DataProcessor</a></td>
 <td class="colLast">
 <div class="block">Compiled version of a DFDL Schema, used to parse data and get the DFDL infoset</div>
 </td>
 </tr>
 <tr class="altColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/Diagnostic.html" title="class in org.apache.daffodil.japi">Diagnostic</a></td>
 <td class="colLast">
 <div class="block">Class containing diagnostic information</div>
 </td>
 </tr>
 <tr class="rowColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/LocationInSchemaFile.html" title="class in org.apache.daffodil.japi">LocationInSchemaFile</a></td>
 <td class="colLast">
 <div class="block">Information related to locations in DFDL schema files</div>
 </td>
 </tr>
 <tr class="altColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/ParseResult.html" title="class in org.apache.daffodil.japi">ParseResult</a></td>
 <td class="colLast">
 <div class="block">Result of calling <a href="../../../../org/apache/daffodil/japi/DataProcessor.html#parse-java.nio.channels.ReadableByteChannel-org.apache.daffodil.japi.infoset.InfosetOutputter-long-"><code>DataProcessor.parse(java.nio.channels.ReadableByteChannel, InfosetOutputter, long)</code></a>, containing
  the diagnostic information, and the final data location</div>
 </td>
 </tr>
 <tr class="rowColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/ProcessorFactory.html" title="class in org.apache.daffodil.japi">ProcessorFactory</a></td>
 <td class="colLast">
 <div class="block">Factory to create <a href="../../../../org/apache/daffodil/japi/DataProcessor.html" title="class in org.apache.daffodil.japi"><code>DataProcessor</code></a>'s, used for parsing data</div>
 </td>
 </tr>
 <tr class="rowColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/UnparseResult.html" title="class in org.apache.daffodil.japi">UnparseResult</a></td>
 <td class="colLast">
 <div class="block">Result of calling <a href="../../../../org/apache/daffodil/japi/DataProcessor.html#unparse-org.apache.daffodil.japi.infoset.InfosetInputter-java.nio.channels.WritableByteChannel-"><code>DataProcessor.unparse(InfosetInputter, java.nio.channels.WritableByteChannel)</code></a>,
  containing diagnostic information</div>
 </td>
 </tr>
 <tr class="altColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/WithDiagnostics.html" title="class in org.apache.daffodil.japi">WithDiagnostics</a></td>
 <td class="colLast">
 <div class="block">Abstract class that adds diagnostic information to classes that extend it.</div>
 </td>
 </tr>
 </tbody>
 </table>
 </li>
 <li class="blockList">
 <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Enum Summary table, listing enums, and an explanation">
 <caption><span>Enum Summary</span><span class="tabEnd">&nbsp;</span></caption>
 <tr>
 <th class="colFirst" scope="col">Enum</th>
 <th class="colLast" scope="col">Description</th>
 </tr>
 <tbody>
 <tr class="altColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/ValidationMode.html" title="enum in org.apache.daffodil.japi">ValidationMode</a></td>
 <td class="colLast">
 <div class="block">Validation modes for validating the resulting infoset against the DFDL schema</div>
 </td>
 </tr>
 </tbody>
 </table>
 </li>
 <li class="blockList">
 <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Exception Summary table, listing exceptions, and an explanation">
 <caption><span>Exception Summary</span><span class="tabEnd">&nbsp;</span></caption>
 <tr>
 <th class="colFirst" scope="col">Exception</th>
 <th class="colLast" scope="col">Description</th>
 </tr>
 <tbody>
 <tr class="altColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/DaffodilUnhandledSAXException.html" title="class in org.apache.daffodil.japi">DaffodilUnhandledSAXException</a></td>
 <td class="colLast">
 <div class="block">This exception will be thrown when an unexpected error occurs during the SAX unparse</div>
 </td>
 </tr>
 <tr class="rowColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/DaffodilUnparseErrorSAXException.html" title="class in org.apache.daffodil.japi">DaffodilUnparseErrorSAXException</a></td>
 <td class="colLast">
 <div class="block">This exception will be thrown when unparseResult.isError returns true during a SAX Unparse</div>
 </td>
 </tr>
 <tr class="altColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/ExternalVariableException.html" title="class in org.apache.daffodil.japi">ExternalVariableException</a></td>
 <td class="colLast">
 <div class="block">This exception will be thrown if an error occurs when setting an external variable.</div>
 </td>
 </tr>
 <tr class="rowColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/InvalidParserException.html" title="class in org.apache.daffodil.japi">InvalidParserException</a></td>
 <td class="colLast">
 <div class="block">This exception will be thrown as a result of attempting to reload a saved parser
  that is invalid (not a parser file, corrupt, etc.) or
  is not in the GZIP format.</div>
 </td>
 </tr>
 <tr class="altColor">
 <td class="colFirst"><a href="../../../../org/apache/daffodil/japi/InvalidUsageException.html" title="class in org.apache.daffodil.japi">InvalidUsageException</a></td>
 <td class="colLast">
 <div class="block">This exception will be thrown as a result of an invalid usage of the Daffodil API</div>
 </td>
 </tr>
 </tbody>
 </table>
 </li>
 </ul>
 <a name="package.description">
 <!--   -->
 </a>
 <h2 title="Package org.apache.daffodil.japi Description">Package org.apache.daffodil.japi Description</h2>
 <div class="block">Provides the classes necessary to compile DFDL schemas, parse and
  unparse files using the compiled objects, and retrieve results and
  parsing diagnostics

  <h2>Overview</h2>

  The <a href="../../../../org/apache/daffodil/japi/Daffodil.html" title="class in org.apache.daffodil.japi"><code>Daffodil</code></a> object is a factory object to create a
  <a href="../../../../org/apache/daffodil/japi/Compiler.html" title="class in org.apache.daffodil.japi"><code>Compiler</code></a>. The <a href="../../../../org/apache/daffodil/japi/Compiler.html" title="class in org.apache.daffodil.japi"><code>Compiler</code></a> provides
  a method to compile a provided DFDL schema into a <a href="../../../../org/apache/daffodil/japi/ProcessorFactory.html" title="class in org.apache.daffodil.japi"><code>ProcessorFactory</code></a>,
  which creates a <a href="../../../../org/apache/daffodil/japi/DataProcessor.html" title="class in org.apache.daffodil.japi"><code>DataProcessor</code></a>:

  <pre>
  <code>
  Compiler c = Daffodil.compiler();
  ProcessorFactory pf = c.compileFile(file);
  DataProcessor dp = pf.onPath("/");
  </code></pre>

  The <a href="../../../../org/apache/daffodil/japi/DataProcessor.html" title="class in org.apache.daffodil.japi"><code>DataProcessor</code></a> provides the necessary functions to parse and
  unparse data, returning a <a href="../../../../org/apache/daffodil/japi/ParseResult.html" title="class in org.apache.daffodil.japi"><code>ParseResult</code></a> or
  <a href="../../../../org/apache/daffodil/japi/UnparseResult.html" title="class in org.apache.daffodil.japi"><code>UnparseResult</code></a>, respectively. These contain information about the
  parse/unparse, such as whether or not the processing succeeded with any diagnostic information.

  The <a href="../../../../org/apache/daffodil/japi/DataProcessor.html" title="class in org.apache.daffodil.japi"><code>DataProcessor</code></a> also provides two functions that can be used to
  perform parsing/unparsing via the SAX API. The first creates a
  <a href="../../../../org/apache/daffodil/japi/DaffodilParseXMLReader.html" title="class in org.apache.daffodil.japi"><code>DaffodilParseXMLReader</code></a> which is used for parsing, and the
  second creates a <a href="../../../../org/apache/daffodil/japi/DaffodilUnparseContentHandler.html" title="class in org.apache.daffodil.japi"><code>DaffodilUnparseContentHandler</code></a> which is used for
  unparsing.

  <pre>
  <code>
  DaffodilParseXMLReader xmlReader = dp.newXMLReaderInstance();
  DaffodilUnparseContentHandler unparseContentHandler = dp.newContentHandlerInstance(output);
  </code></pre>

  The <a href="../../../../org/apache/daffodil/japi/DaffodilParseXMLReader.html" title="class in org.apache.daffodil.japi"><code>DaffodilParseXMLReader</code></a> has several methods that allow one to
  set properties and handlers (such as ContentHandlers or ErrorHandlers) for the reader. One can
  use any contentHandler/errorHandler as long as they extend the
  <code>ContentHandler</code> and <code>ErrorHandler</code> interfaces
  respectively. One can also set properties for the <a href="../../../../org/apache/daffodil/japi/DaffodilParseXMLReader.html" title="class in org.apache.daffodil.japi"><code>DaffodilParseXMLReader</code></a>
  using <a href="../../../../org/apache/daffodil/japi/DaffodilParseXMLReader.html#setProperty-java.lang.String-java.lang.Object-"><code>DaffodilParseXMLReader.setProperty(java.lang.String,
  java.lang.Object)</code></a>.

  The following properties can be set as follows:

  <p><i>The constants below have literal values starting with
  "urn:ogf:dfdl:2013:imp:daffodil.apache.org:2018:sax:" and ending with "BlobDirectory",
  "BlobPrefix" and "BlobSuffix" respectively.</i></p>

  <pre>
  <code>
  xmlReader.setProperty(DaffodilParseXMLReader.DAFFODIL_SAX_URN_BLOBDIRECTORY(),
   Paths.get(System.getProperty("java.io.tmpdir"))); // value type: java.nio.file.Paths
  xmlReader.setProperty(DaffodilParseXMLReader.DAFFODIL_SAX_URN_BLOBPREFIX(), "daffodil-sax-"); // value type String
  xmlReader.setProperty(DaffodilParseXMLReader.DAFFODIL_SAX_URN_BLOBSUFFIX(), ".bin"); // value type String
  </code>
  </pre>

  The properties can be retrieved using the same variables with
  <a href="../../../../org/apache/daffodil/japi/DaffodilParseXMLReader.html#getProperty-java.lang.String-"><code>DaffodilParseXMLReader.getProperty(java.lang.String)</code></a> and casting
  to the appropriate type as listed above.

  The following handlers can be set as follows:
  <pre>
  <code>
  xmlReader.setContentHandler(contentHandler);
  xmlReader.setErrorHandler(errorHandler);
  </code>
  </pre>

  The handlers above must implement the following interfaces respectively:
  <pre>
  <code>
  org.xml.sax.ContentHandler
  org.xml.sax.ErrorHandler
  </code>
  </pre>

  The <a href="../../../../org/apache/daffodil/japi/ParseResult.html" title="class in org.apache.daffodil.japi"><code>ParseResult</code></a> can be found as a property within the
  <a href="../../../../org/apache/daffodil/japi/DaffodilParseXMLReader.html" title="class in org.apache.daffodil.japi"><code>DaffodilParseXMLReader</code></a> using this uri:
  "urn:ogf:dfdl:2013:imp:daffodil.apache.org:2018:sax:ParseResult" or
  <a href="../../../../org/apache/daffodil/japi/DaffodilParseXMLReader.html#DAFFODIL_SAX_URN_PARSERESULT--"><code>DaffodilParseXMLReader.DAFFODIL_SAX_URN_PARSERESULT()</code></a>.

  In order for a successful unparse to happen, the SAX API requires the
  unparse to be kicked off by a parse call to any <code>XMLReader</code> implementation that
  has the <a href="../../../../org/apache/daffodil/japi/DaffodilUnparseContentHandler.html" title="class in org.apache.daffodil.japi"><code>DaffodilUnparseContentHandler</code></a> registered as its content
  handler. To retrieve the <a href="../../../../org/apache/daffodil/japi/UnparseResult.html" title="class in org.apache.daffodil.japi"><code>UnparseResult</code></a>, one can use
  <a href="../../../../org/apache/daffodil/japi/DaffodilUnparseContentHandler.html#getUnparseResult--"><code>DaffodilUnparseContentHandler.getUnparseResult()</code></a> once the
  XMLReader.parse run is complete.

  <h3>Parse</h3>

  <h4>Dataprocessor Parse</h4>

  The <a href="../../../../org/apache/daffodil/japi/DataProcessor.html#parse-org.apache.daffodil.japi.io.InputSourceDataInputStream-org.apache.daffodil.japi.infoset.InfosetOutputter-"><code>DataProcessor.parse(org.apache.daffodil.japi.io.InputSourceDataInputStream,
  org.apache.daffodil.japi.infoset.InfosetOutputter)</code></a> method accepts input data to parse in the form
  of a <a href="../../../../org/apache/daffodil/japi/io/InputSourceDataInputStream.html" title="class in org.apache.daffodil.japi.io"><code>InputSourceDataInputStream</code></a> and an
  <a href="../../../../org/apache/daffodil/japi/infoset/InfosetOutputter.html" title="class in org.apache.daffodil.japi.infoset"><code>InfosetOutputter</code></a> to determine the output representation
  of the infoset (e.g. Scala XML Nodes, JDOM2 Documents, etc.):

  <pre>
  <code>
  JDOMInfosetOutputter jdomOutputter= new JDOMInfosetOutputter();
  InputSourceDataInputStream is = new InputSourceDataInputStream(data);
  ParseResult pr = dp.parse(is, jdomOutputter);
  Document doc = jdomOutputter.getResult();
  </code></pre>

  The <a href="../../../../org/apache/daffodil/japi/DataProcessor.html#parse-org.apache.daffodil.japi.io.InputSourceDataInputStream-org.apache.daffodil.japi.infoset.InfosetOutputter-"><code>DataProcessor.parse(org.apache.daffodil.japi.io.InputSourceDataInputStream,
  org.apache.daffodil.japi.infoset.InfosetOutputter)</code></a> method is thread-safe and may be called multiple
  times without the need to create other data processors. However,
  <a href="../../../../org/apache/daffodil/japi/infoset/InfosetOutputter.html" title="class in org.apache.daffodil.japi.infoset"><code>InfosetOutputter</code></a>'s are not thread safe, requiring a
  unique instance per thread. An <a href="../../../../org/apache/daffodil/japi/infoset/InfosetOutputter.html" title="class in org.apache.daffodil.japi.infoset"><code>InfosetOutputter</code></a> should
  call <a href="../../../../org/apache/daffodil/japi/infoset/InfosetOutputter.html#reset--"><code>InfosetOutputter.reset()</code></a> before reuse (or a new one
  should be allocated). For example:

  <pre>
  <code>
  JDOMInfosetOutputter jdomOutputter = new JDOMInfosetOutputter();
  for (File f : inputFiles) {
    jdomOutputter.reset();
    InputSourceDataInputStream is = new InputSourceDataInputStream(new FileInputStream(f)));
    ParseResult pr = dp.parse(is, jdomOutputter);
    Document doc = jdomOutputter.getResult();
  }
  </code></pre>

  One can repeat calls to parse() using the same InputSourceDataInputStream to continue parsing
  where the previous parse ended. For example:

  <pre>
  <code>
  InputSourceDataInputStream is = new InputSourceDataInputStream(dataStream);
  JDOMInfosetOutputter jdomOutputter = new JDOMInfosetOutputter();
  boolean keepParsing = true;
  while (keepParsing &amp;&amp; is.hasData()) {
    jdomOutputter.reset();
    ParseResult pr = dp.parse(is, jdomOutputter);
    ...
    keepParsing = !pr.isError();
  }
  </code></pre>

  <h4>SAX Parse</h4>
  The <a href="../../../../org/apache/daffodil/japi/DaffodilParseXMLReader.html#parse-org.apache.daffodil.japi.io.InputSourceDataInputStream-"><code>DaffodilParseXMLReader.parse(
  org.apache.daffodil.japi.io.InputSourceDataInputStream)</code></a> method accepts input data to parse in
  the form of a <a href="../../../../org/apache/daffodil/japi/io/InputSourceDataInputStream.html" title="class in org.apache.daffodil.japi.io"><code>InputSourceDataInputStream</code></a>. The output
  representation of the infoset, as well as how parse errors are handled, are dependent on the
  content handler and the error handler provided to the <a href="../../../../org/apache/daffodil/japi/DaffodilParseXMLReader.html" title="class in org.apache.daffodil.japi"><code>DaffodilParseXMLReader</code></a>.
  For example the <code>SAXHandler</code> provides a JDOM representation, whereas
  other ContentHandlers may output directly to a <code>OutputStream</code> or <code>Writer</code>.

  <pre>
  <code>
  SAXHandler contentHandler = new SAXHandler();
  xmlReader.setContentHandler(contentHandler);
  InputSourceDataInputStream is = new InputSourceDataInputStream(data);
  xmlReader.parse(is);
  ParseResult pr = (ParseResult) xmlReader.getProperty(DaffodilParseXMLReader.DAFFODIL_SAX_URN_PARSERESULT());
  Document doc = saxHandler.getDocument();
  </code></pre>

  The The <a href="../../../../org/apache/daffodil/japi/DaffodilParseXMLReader.html#parse-org.apache.daffodil.japi.io.InputSourceDataInputStream-"><code>DaffodilParseXMLReader.parse(
  org.apache.daffodil.japi.io.InputSourceDataInputStream)</code></a> method is not thread-safe and may
  only be called again/reused once a parse operation is completed. This can be done multiple
  times without the need to create new DaffodilParseXMLReaders, ContentHandlers or ErrorHandlers.
  It might be necessary to reset whatever ContentHandler is used (or allocate a new one). A
  thread-safe implementation would require unique instances of the DaffodilParseXMLReader and its
  components. For example:

  <pre>
  <code>
  SAXHandler contentHandler = new SAXHandler();
  xmlReader.setContentHandler(contentHandler);
  for (File f : inputFiles) {
    contentHandler.reset();
    InputSourceDataInputStream is = new InputSourceDataInputStream(new FileInputStream(f));
    xmlReader.parse(is);
    ParseResult pr = (ParseResult) xmlReader.getProperty(DaffodilParseXMLReader.DAFFODIL_SAX_URN_PARSERESULT());
    Document doc = saxHandler.getDocument();
  }
  </code>
  </pre>

  The value of the supported features cannot be changed during a parse, and the parse will run
  with the value of the features as they were when the parse was kicked off. To run a parse with
  different feature values, one must wait until the running parse finishes, set the feature values
  using the XMLReader's setFeature and run the parse again.

  One can repeat calls to parse() using the same InputSourceDataInputStream to continue parsing
  where the previous parse ended. For example:

  <pre>
  <code>
  InputSourceDataInputStream is = new InputSourceDataInputStream(dataStream);
  SAXHandler contentHandler = new SAXHandler();
  xmlReader.setContentHandler(contentHandler);
  Boolean keepParsing = true;
  while (keepParsing &amp;&amp; is.hasData()) {
    contentHandler.reset();
    xmlReader.parse(is);
    val pr = xmlReader.getProperty(DaffodilParseXMLReader.DAFFODIL_SAX_URN_PARSERESULT());
    ...
    keepParsing = !pr.isError();
  }
  </code>
  </pre>

  <h3>Unparse</h3>

  <h4>Dataprocessor Unparse</h4>

  The same <a href="../../../../org/apache/daffodil/japi/DataProcessor.html" title="class in org.apache.daffodil.japi"><code>DataProcessor</code></a> used for parse can be used to unparse an
  infoset via the <a href="../../../../org/apache/daffodil/japi/DataProcessor.html#unparse-org.apache.daffodil.japi.infoset.InfosetInputter-java.nio.channels.WritableByteChannel-"><code>DataProcessor.unparse(org.apache.daffodil.japi.infoset.InfosetInputter,
  java.nio.channels.WritableByteChannel)</code></a> method. An <a href="../../../../org/apache/daffodil/japi/infoset/InfosetInputter.html" title="class in org.apache.daffodil.japi.infoset"><code>InfosetInputter</code></a>
  provides the infoset to unparse, with the unparsed data written to the
  provided <code>WritableByteChannel</code>. For example:

  <pre>
  <code>
  JDOMInfosetInputter jdomInputter = new JDOMInfosetInputter(doc);
  UnparseResult ur = dp.unparse(jdomInputter, wbc)
  </code></pre>

  <h4>SAX Unparse</h4>

  In order to kick off an unparse via the SAX API, one must register the
  <a href="../../../../org/apache/daffodil/japi/DaffodilUnparseContentHandler.html" title="class in org.apache.daffodil.japi"><code>DaffodilUnparseContentHandler</code></a> as the contentHandler for an
  XMLReader implementation. The call to the
  <a href="../../../../org/apache/daffodil/japi/DataProcessor.html#newContentHandlerInstance-java.nio.channels.WritableByteChannel-"><code>DataProcessor.newContentHandlerInstance(java.nio.channels.WritableByteChannel)</code></a>
  method must be provided with the <code>WritableByteChannel</code>, where the unparsed
  data ought to be written to. Any XMLReader implementation is permissible, as long as they have
  XML Namespace support.

  <pre>
  <code>
   ByteArrayInputStream is = new ByteArrayInputStream(data);
   ByteArrayOutputStream os = new ByteArrayOutputStream();
   WritableByteChannel wbc = java.nio.channels.Channels.newChannel(os);
   DaffodilUnparseContentHandler unparseContentHandler = dp.newContentHandlerInstance(wbc);
   try {
    XMLReader xmlReader = SAXParserFactory.newInstance().newSAXParser().getXMLReader();
    xmlReader.setContentHandler(unparseContentHandler)
    xmlReader.parse(is)
   } catch (ParserConfigurationException | SAXException e) {
    ...
  `} catch catch (DaffodilUnparseErrorSAXException | DaffodilUnhandledSAXException e) {
    ...
   }
  </code>
  </pre>

  The call to the XMLReader.parse method must be wrapped in a try/catch, as
  <a href="../../../../org/apache/daffodil/japi/DaffodilUnparseContentHandler.html" title="class in org.apache.daffodil.japi"><code>DaffodilUnparseContentHandler</code></a> relies on throwing an exception to
  end processing in the case of any errors/failures.
  There are two kinds of errors to expect
  <a href="../../../../org/apache/daffodil/japi/DaffodilUnparseErrorSAXException.html" title="class in org.apache.daffodil.japi"><code>DaffodilUnparseErrorSAXException</code></a>, for the case when the
  <a href="../../../../org/apache/daffodil/japi/WithDiagnostics.html#isError--"><code>WithDiagnostics.isError()</code></a>, and
  <a href="../../../../org/apache/daffodil/japi/DaffodilUnparseErrorSAXException.html" title="class in org.apache.daffodil.japi"><code>DaffodilUnparseErrorSAXException</code></a>, for any other errors.

  In the case of an <a href="../../../../org/apache/daffodil/japi/DaffodilUnhandledSAXException.html" title="class in org.apache.daffodil.japi"><code>DaffodilUnhandledSAXException</code></a>,
  <a href="../../../../org/apache/daffodil/japi/DaffodilUnparseContentHandler.html#getUnparseResult--"><code>DaffodilUnparseContentHandler.getUnparseResult()</code></a> will return null.

  <pre>
  <code>
   try {
     xmlReader.parse(new InputSource(is));
   } catch (DaffodilUnparseErrorSAXException | DaffodilUnhandledSAXException e) {
     ...
   }
   UnparseResult ur = unparseContentHandler.getUnparseResult();
  </code>
  </pre>


  <h3>Failures and Diagnostics</h3>

  It is possible that failures could occur during the creation of the
  <a href="../../../../org/apache/daffodil/japi/ProcessorFactory.html" title="class in org.apache.daffodil.japi"><code>ProcessorFactory</code></a>, <a href="../../../../org/apache/daffodil/japi/DataProcessor.html" title="class in org.apache.daffodil.japi"><code>DataProcessor</code></a>,
  or <a href="../../../../org/apache/daffodil/japi/ParseResult.html" title="class in org.apache.daffodil.japi"><code>ParseResult</code></a>. However, rather than throwing an exception on
  error (e.g. invalid DFDL schema, parse error, etc), these classes extend
  <a href="../../../../org/apache/daffodil/japi/WithDiagnostics.html" title="class in org.apache.daffodil.japi"><code>WithDiagnostics</code></a>, which is used to determine if an error occurred,
  and any diagnostic information (see <a href="../../../../org/apache/daffodil/japi/Diagnostic.html" title="class in org.apache.daffodil.japi"><code>Diagnostic</code></a>) related to the step.
  Thus, before continuing, one must check <a href="../../../../org/apache/daffodil/japi/WithDiagnostics.html#isError--"><code>WithDiagnostics.isError()</code></a>.
  For example:

  <pre>
  <code>
  ProcessorFactor pf = c.compile(files);
  if (pf.isError()) {
    java.util.List&lt;Diagnostic&gt; diags = pf.getDiagnostics();
    foreach (Diagnostic d : diags) {
      System.out.println(d.toString());
    }
    return -1;
  }
  </code></pre>

  <h3>Saving and Reloading Parsers</h3>

  In some cases, it may be beneficial to save a parser and reload it.
  For example, when starting up, it may be quicker to reload an
  already compiled parser than to compile it from scratch. To save a
  <a href="../../../../org/apache/daffodil/japi/DataProcessor.html" title="class in org.apache.daffodil.japi"><code>DataProcessor</code></a>:

  <pre>
  <code>
  DataProcessor dp = pf.onPath("/");
  dp.save(saveFile);
  </code></pre>

  And to restore a saved <a href="../../../../org/apache/daffodil/japi/DataProcessor.html" title="class in org.apache.daffodil.japi"><code>DataProcessor</code></a>:

  <pre>
  <code>
  DataProcessor dp = Daffodil.reload(saveFile);
  ParseResult pr = dp.parse(data);
  </code></pre>

  And use like below:
  <pre>
  <code>
  ParseResult pr = dp.parse(data);
  </code></pre>

  or

  <pre>
  <code>
  DaffodilParseXMLReader xmlReader = dp.newXMLReaderInstance();
  ... // setting appropriate handlers
  xmlReader.parse(data);
  ParseResult pr = xmlReader.getProperty("...ParseResult");
  </code></pre></div>
 </div>
 <!-- ======= START OF BOTTOM NAVBAR ====== -->
 <div class="bottomNav"><a name="navbar.bottom">
 <!--   -->
 </a>
 <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
 <a name="navbar.bottom.firstrow">
 <!--   -->
 </a>
 <ul class="navList" title="Navigation">
 <li><a href="../../../../overview-summary.html">Overview</a></li>
 <li class="navBarCell1Rev">Package</li>
 <li>Class</li>
 <li><a href="package-tree.html">Tree</a></li>
 <li><a href="../../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../../index-all.html">Index</a></li>
 <li><a href="../../../../help-doc.html">Help</a></li>
 </ul>
 </div>
 <div class="subNav">
 <ul class="navList">
 <li>Prev&nbsp;Package</li>
 <li><a href="../../../../org/apache/daffodil/japi/debugger/package-summary.html">Next&nbsp;Package</a></li>
 </ul>
 <ul class="navList">
 <li><a href="../../../../index.html?org/apache/daffodil/japi/package-summary.html" target="_top">Frames</a></li>
 <li><a href="package-summary.html" target="_top">No&nbsp;Frames</a></li>
 </ul>
 <ul class="navList" id="allclasses_navbar_bottom">
 <li><a href="../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
 </ul>
 <div>
 <script type="text/javascript"><!--
   allClassesLink = document.getElementById("allclasses_navbar_bottom");
   if(window==top) {
     allClassesLink.style.display = "block";
   }
   else {
     allClassesLink.style.display = "none";
   }
   //-->
 </script>
 </div>
 <a name="skip.navbar.bottom">
 <!--   -->
 </a></div>
 <!-- ======== END OF BOTTOM NAVBAR ======= -->
 </body>
 </html>