package sapi
Provides the classes necessary to compile DFDL schemas, parse and unparse files using the compiled objects, and retrieve results and parsing diagnostics
Overview
The Daffodil object is a factory object to create a Compiler. The Compiler provides a method to compils a provided DFDL schema into a ProcessorFactory, which creates a DataProcessor:
val c = Daffodil.compiler() val pf = c.compileFile(file) val dp = pf.onPath("/")
The DataProcessor provides the necessary functions to parse and unparse data, returning a ParseResult or UnparseResult, respectively. These contain information about the parse/unparse, such as whether or not the processing succeeded any diagnostic information.
Parse
The DataProcessor.parse method accepts input data to parse in the form of a InputSourceDataInputStream and an InfosetOutputter to determine the output representation of the infoset (e.g. Scala XML Nodes, JDOM2 Documents, etc.):
val scalaOutputter = new ScalaXMLInfosetOutputter() val is = new InputSourceDataInputStream(data) val pr = dp.parse(is, scalaOutputter) val node = scalaOutputter.getResult
The DataProcessor.parse method is thread-safe and may be called multiple times without the need to create other data processors. However, InfosetOutputter's are not thread safe, requiring a unique instance per thread. An InfosetOutputter should call InfosetOutputter.reset before reuse (or a new one should be allocated). For example:
val scalaOutputter = new ScalaXMLInfosetOutputter() files.foreach { f => { outputter.reset val is = new InputSourceDataInputStream(new FileInputStream(f)) val pr = dp.parse(is, scalaOutputter) val node = scalaOutputter.getResult }
One can repeat calls to parse() using the same InputSourceDataInputStream to continue parsing where the previous parse ended. For example:
val is = new InputSourceDataInputStream(dataStream) val scalaOutputter = new ScalaXMLInfosetOutputter() val keepParsing = true while (keepParsing) { scalaOutputter.reset() val pr = dp.parse(is, jdomOutputter) ... keepParsing = !pr.location().isAtEnd() && !pr.isError() }
Unparse
The same DataProcessor used for parse can be used to unparse an infoset via the DataProcessor.unparse method. An InfosetInputter provides the infoset to unparse, with the unparsed data written to the provided java.nio.channels.WritableByteChannel. For example:
val inputter = new ScalaXMLInfosetInputter(node) val ur = dp.unparse(inputter, wbc)
Failures and Diagnostics
It is possible that failures could occur during the creation of the ProcessorFactory, DataProcessor, or ParseResult. However, rather than throwing an exception on error (e.g. invalid DFDL schema, parse error, etc), these classes extend WithDiagnostics, which is used to determine if an error occurred, and any diagnostic information (see Diagnostic) related to the step. Thus, before continuing, one must check WithDiagnostics.isError. For example:
val pf = c.compile(file) if (pf.isError()) { val diags = pf.getDiagnostics() diags.foreach { d => System.out.println(d.toString()) } return -1; }
Saving and Reloading Parsers
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 DataProcessor:
val dp = pf.onPath("/") dp.save(saveFile);
And to restore a saved DataProcessor:
val dp = Daffodil.reload(saveFile); val pr = dp.parse(data, inputter);
- Alphabetic
- By Inheritance
- sapi
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
Type Members
-
class
Compiler extends AnyRef
Compile DFDL schemas into ProcessorFactory's or reload saved parsers into DataProcessor's.
-
class
DataLocation extends AnyRef
Information related to a location in data
-
class
DataProcessor extends WithDiagnostics with Serializable
Compiled version of a DFDL Schema, used to parse data and get the DFDL infoset
-
class
Diagnostic extends AnyRef
Class containing diagnostic information
-
class
InvalidParserException extends Exception
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.
-
class
InvalidUsageException extends Exception
This exception will be thrown as a result of an invalid usage of the Daffodil API
-
class
LocationInSchemaFile extends AnyRef
Information related to locations in DFDL schema files
-
class
ParseResult extends WithDiagnostics
Result of calling DataProcessor.parse, containing any diagnostic information, and the final data location
-
class
ProcessorFactory extends WithDiagnostics
Factory to create DataProcessor's, used for parsing data
-
class
UnparseResult extends WithDiagnostics
Result of calling DataProcessor.unparse, containing diagnostic information
-
abstract
class
WithDiagnostics extends Serializable
Abstract class that adds diagnostic information to classes that extend it.
Abstract class that adds diagnostic information to classes that extend it.
When a function returns a class that extend this, one should call WithDiagnostics.isError on that class before performing any further actions. If an error exists, any use of that class, aside from those functions in WithDiagnostics, is invalid and will result in an Exception.
Value Members
-
object
Daffodil
Factory object to create a Compiler and set global configurations
-
object
ValidationMode extends Enumeration
Validation modes for validating the resulting infoset against the DFDL schema
Apache Daffodil (incubating) Scala API
Packages
org.apache.daffodil.sapi - Provides the classes necessary to compile DFDL schemas, parse and unparse files using the compiled objects, and retrieve results and parsing diagnostics
org.apache.daffodil.sapi.logger - Provides the classes necessary to receive logging messages from Daffodil.
org.apache.daffodil.sapi.debugger - Provides the classes necessary to perform parse tracing or create a custom debugger