org.apache.daffodil.runtime1.layers.api

Class ChecksumLayer

java.lang.Object

org.apache.daffodil.runtime1.layers.api.Layer

org.apache.daffodil.runtime1.layers.ChecksumLayerBase

org.apache.daffodil.runtime1.layers.api.ChecksumLayer

public abstract class ChecksumLayer
extends org.apache.daffodil.runtime1.layers.ChecksumLayerBase

A checksum layer computes a numeric value from a region of the data stream.

The term checksum is used generically here to subsume all sorts of CRCs, check digits, data hash, and digest calculations.

This abstract base is suitable only for checksums computed over small sections of data. It is not for large data streams or whole large files. The entire region of data the checksum is being computed over will be pulled into a byte buffer in memory.

The resulting checksum is the return value of the compute(boolean, java.nio.ByteBuffer) method.

This result is delivered into a DFDL variable for use by the DFDL schema. This DFDL variable can have any name such as 'crc', 'digest', or 'dataHash'.

The derived implementation class must also define a getter method based on the name of the DFDL variable which will be assigned with the checksum value. For example if the checksum is actually a specific digest/hash calculation and the DFDL variable is named digest, then this getter must be defined:

     int getLayerVariableResult_digest() {
       return this.digest; // usually returns a data member
     }
 
 

This will be called automatically to retrieve the integer value that was returned from the compute method, and the DFDL variable named digest will be assigned that value.

The derived class implementing a checksum layer must call

     setLength(len); // sets the length in bytes
 
 

to specify the length of the data region in bytes. Normally this would be called from the layer's implementation of the setLayerVariableParameters method:

     void setLayerVariableParameters(...) {
         ...
         setLength(len); // len is a constant,
                         // or is computed from a parameter variable
         ...
     }
 

See the documentation of the Layer class for a description of how DFDL variables are passed to the arguments of the setLayerVariableParameters method.

See Layer for more details about layers generally as most of its documentation is relevant to this derived abstract base class as well.

Constructor Summary

Constructors

Constructor and Description
ChecksumLayer(java.lang.String layerName, java.lang.String layerTargetNamespace) Base class constructor

Method Summary

Modifier and Type	Method and Description
abstract int	compute(boolean isUnparse, java.nio.ByteBuffer byteBuffer) Override to compute the checksum of a buffer of data.

Methods inherited from class org.apache.daffodil.runtime1.layers.ChecksumLayerBase

getChecksum, getLength, setChecksum, setLength, wrapLayerInput, wrapLayerOutput

Methods inherited from class org.apache.daffodil.runtime1.layers.api.Layer

getLayerRuntime, getProcessingErrorExceptions, localName, name, namespace, processingError, processingError, runtimeSchemaDefinitionError, runtimeSchemaDefinitionError, setLayerRuntime, setProcessingErrorException

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ChecksumLayer

public ChecksumLayer(java.lang.String layerName,
                     java.lang.String layerTargetNamespace)

Base class constructor

Parameters:

layerName - the name of the layer

layerTargetNamespace - the URI that is the target namespace of the layer

Throws:

java.lang.IllegalArgumentException - if arguments are null or do not obey required syntax.

Method Detail

compute

public abstract int compute(boolean isUnparse,
                            java.nio.ByteBuffer byteBuffer)

Override to compute the checksum of a buffer of data.

Specified by:

compute in class org.apache.daffodil.runtime1.layers.ChecksumLayerBase

Parameters:

isUnparse - true if the direction is unparsing. Used because in some cases the computed checksum must be written into the byte buffer in a specific location.

byteBuffer - the bytes over which the checksum is to be computed. This byte buffer can be modified, (for example so as to embed the computed checksum in the middle of the data somewhere). The resulting modified bytes become the data that is read by the DFDL parsing and written when unparsing.

Returns:

the checksum value as an Int (32-bit signed integer)