Package

org.apache.daffodil

sapi

Permalink

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(input:java\.nio\.channels\.ReadableByteChannel,output:org\.apache\.daffodil\.sapi\.infoset\.InfosetOutputter)* method accepts input data to parse in the form of a java.nio.channels.ReadableByteChannel and an infoset.InfosetOutputter to determine the output representation of the infoset (e.g. Scala XML Nodes, JDOM2 Documents, etc.):

val scalaOutputter = new ScalaXMLInfosetOutputter()
val pr = dp.parse(data, scalaOutputter)
val node = scalaOutputter.getResult

The DataProcessor#parse(input:java\.nio\.channels\.ReadableByteChannel,output:org\.apache\.daffodil\.sapi\.infoset\.InfosetOutputter)* method is thread-safe and may be called multiple times without the need to create other data processors. However, infoset.InfosetOutputter's are not thread safe, requiring a unique instance per thread. An infoset.InfosetOutputter should call infoset.InfosetOutputter#reset before reuse (or a new one should be allocated). For example:

val scalaOutputter = new ScalaXMLInfosetOutputter()
files.foreach { f => {
  outputter.reset
  val pr = dp.parse(f, scalaOutputter)
  val node = scalaOutputter.getResult
}}
Unparse

The same DataProcessor used for parse can be used to unparse an infoset via the DataProcessor#unparse(input* method. An infoset.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);
Linear Supertypes
AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. sapi
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Type Members

  1. class Compiler extends AnyRef

    Permalink

    Compile DFDL schemas into ProcessorFactory's or reload saved parsers into DataProcessor's.

  2. class DataLocation extends AnyRef

    Permalink

    Information related to a location in data

  3. class DataProcessor extends WithDiagnostics

    Permalink

    Compiled version of a DFDL Schema, used to parse data and get the DFDL infoset

  4. class Diagnostic extends AnyRef

    Permalink

    Class containing diagnostic information

  5. class InvalidParserException extends Exception

    Permalink

    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.

  6. class InvalidUsageException extends Exception

    Permalink

    This exception will be thrown as a result of an invalid usage of the Daffodil API

  7. class LocationInSchemaFile extends AnyRef

    Permalink

    Information related to locations in DFDL schema files

  8. class ParseResult extends WithDiagnostics

    Permalink

    Result of calling DataProcessor#parse(input:java\.nio\.channels\.ReadableByteChannel,output:org\.apache\.daffodil\.sapi\.infoset\.InfosetOutputter)*, containing any diagnostic information, and the final data location

  9. class ProcessorFactory extends WithDiagnostics

    Permalink

    Factory to create DataProcessor's, used for parsing data

  10. class UnparseResult extends WithDiagnostics

    Permalink

    Result of calling DataProcessor#unparse(input*, containing diagnostic information

  11. abstract class WithDiagnostics extends AnyRef

    Permalink

    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

  1. object Daffodil

    Permalink

    Factory object to create a Compiler and set global configurations

  2. object ValidationMode extends Enumeration

    Permalink

    Validation modes for validating the resulting infoset against the DFDL schema

  3. package debugger

    Permalink

    Provides the classes necessary to perform parse tracing or create a custom debugger

    Provides the classes necessary to perform parse tracing or create a custom debugger

    Overview

    Daffodil comes with one prebuilt debugger, the TraceDebuggerRunner, which outputs verbose information during the parsing processes, which can be used to aid in debugging a DFDL schema. For example, the TraceDebuggerRunner can be use like so:

    val tdr = new TraceDebuggerRunner()
    Daffodil.setDebugger(tdr)

    Additionally, one may create their own debugger runner by implementing the methods in the DebuggerRunner.

    Once the debugger is set, it must then be turned on, like so:

    Daffodil.setDebugging(true);
  4. package infoset

    Permalink

    Defines various classes used control the representation of the infoset for parse and unparse.

    Defines various classes used control the representation of the infoset for parse and unparse. Classes that extend InfosetOutputter are provided to the DataProcessor#parse(input:java\.nio\.channels\.ReadableByteChannel,output:org\.apache\.daffodil\.sapi\.infoset\.InfosetOutputter)* method to deteremine how to output an infoset. These classes are not guaranteed to be thread-safe. Classes that extend InfosetInputter are provided to the DataProcessor#unparse(input* method to determine how to read in an infoset. A new InfosetOutputter is required for each call to unparse().

  5. package logger

    Permalink

    Provides the classes necessary to recieve logging messages from Daffodil.

    Provides the classes necessary to recieve logging messages from Daffodil.

    Overview

    Daffodil comes with three prebuilt log writers:

    To use one of these log writers, create and instance of it and pass it to Daffodil.setLogWriter. For example, to write all logs to /var/log/daffodil.log:

    val lw = new FileLogWriter(new File("/var/log/daffodil.log"))
    Daffodil.setLogWriter(lw)

    One may also change the log level using Daffodil.setLoggingLevel, which defaults to LogLevel#Info if not set. For example, to change the log level to LogLevel#Warning:

    Daffodil.setLoggingLevel(LogLevel.Warning);

Inherited from AnyRef

Inherited from Any

Ungrouped