Package org.apache.daffodil.api.layers

package org.apache.daffodil.api.layers

Daffodil Layers API Package

This package provides base classes for creating Layers, which provide a means of algorithmic operations on the data stream that cannot be expressed using regular DFDL properties.

There are two kinds of layers:

  • transforming layers - such as a base64 decoder/encoder for parts of a textual format
  • checksum layers - such as computing CRC32 over a message header
Both run an algorithm over a part of the data stream.

Layers are implemented in Scala or Java as small (usually) Jar files that are dynamically loaded from the CLASSPATH in response to a DFDL schema that uses that layer via the dfdlx:layer property.

See the Layer Usage Documentation for how a layer is used from a Daffodil DFDL schema.

This API documentation is focused on the programming required to create a new layer implementation as a custom plug-in for Daffodil.

Layer is the general abstract base class used to define any layer, but most commonly it is used for transforming layers.

ChecksumLayer is an abstract base class derived from Layer, and further specialized for defining checksum layers.

About Testing

The Daffodil test code base includes tests for many ways that an API user can goof up the definition of a layer class. For example, there are tests for calling processingError, runtimeSchemaDefinitionError, and throwing an Exception from every place a custom-defined Layer could cause these. Processing errors cause the parser to backtrack in all sensible cases. That is to say that if a layer is parsing data, and the data it encounters is not a match for that layer, then a properly written layer will issue a processing error, and the parser will backtrack, allowing the format to try other alternatives for parsing that data.

Custom Plug-In Layers

Custom Plug-in layers must extend the Layer class, and be referenced in a META-INF/services file with the same class reference as the name. This path has changed in Daffodil 4.0.0.

Compatibility with Daffodil 3.7.0 and prior versions of Apache Daffodil

This new Layer API is entirely incompatible with schemas or layer code from Daffodil 3.7.0 and all prior versions of Daffodil.

The layer feature was just an experimental feature in earlier versions of Daffodil, so we reserved the right to change it, and for Daffodil 3.8.0 it has changed radically based on what we learned from the earlier experimentation.

It is our intention that this Layer API (introduced in Daffodil 3.8.0) will prove to be stable and supportable long term.

  • Classes
    Class
    Description
    ChecksumLayer
    A checksum layer computes a numeric value from a region of the data stream.
    Layer
    This is the primary API class for writing layers.