public abstract class Layer
extends java.lang.Object
All layers are derived from this class.
This class is used directly as a base class to define transforming layers.
To simplify the
definition of checksum layers, a specialized sub-class
ChecksumLayer
is also available.
Many of the requirements for layers, such as the naming conventions for layer variables,
are described here, but they apply equally to checksum layers.
Derived classes will be dynamically loaded by Java's Service Provider Interface (SPI) system.
The names of concrete classes derived from Layer are listed in
a metadata resource file
named for this class (that is, the file name is the fully-qualified class name of this class:
resources/META-INF/services/org.apache.daffodil.runtime1.layers.api.Layer).
This file contains lines where each line contains one fully qualified class name of a derived
layer class.
More than one line in the file denotes that the Jar file contains the definitions of more than one derived layer
class.
This file is incorporated in the compiled jar file for the derived Layer class
so that the class path can be searched and Jars containing layer classes can be dynamically loaded.
The SPI creates an instance the class by calling a default (no-arg) constructor, which should be the only constructor.
Instances of derived layer classes can be stateful. They are private to threads, and each time a layer is encountered during parse/unparse, an instance is created for that situation.
Layer instances should not share mutable state (such as via singleton objects).
Layer logic may read and write DFDL variables. These variables are associated with the layer implementation class by using Java/Scala reflection to find matches (case-sensitive) between the names of DFDL variables and method names and method arguments of the layer's Java/Scala code. Hence, the layer's DFDL variables must have names suitable for use as Java/Scala identifiers.
The layer namespace is used only for its layer. All DFDL variables defined in that namespace are either used to pass parameters to the layer code, or receive results (such as a checksum) back from the layer code. This is enforced. If a layer namespace contains a DFDL variable and there is no corresponding usage of that variable name in the layer code (following the conventions below), then it is a Schema Definition Error when the layer code is loaded.
A layer that does not define any DFDL variables does
not have to define a DFDL schema that defines the layer's target
namespace, but any layer that uses DFDL variables *must* define a
schema with the layer's namespace as its target namespace, and with the
variables declared in it (using dfdl:defineVariable).
Variables being read must have values before being read by the layer, and this is true for both parsing and unparsing. This happens when the Daffodil processor begins parsing/unparsing the layered sequence. When unparsing, variables being read cannot be forward-referencing to parts of the DFDL infoset that have not yet been unparsed.
A layer that wants to read parameters declares a special setter named
setLayerVariableParameters
which has arguments where each has a name and type that match a corresponding
dfdl:defineVariable in the layer's target namespace.
For example, if the layer logic has a DFDL variable for a parameter named direction
of type xs:string and another DFDL variable for a parameter named wordCount
of type xs:unsignedShort
then the derived Layer class must have a setLayerVariableParameters with
arguments corresponding in name and type to these two variables.
This setter will be called passing the value of the variables immediately after the layer
instance is constructed.
The arguments to setLayerVariableParameters can be in any order:
void setLayerVariableParameters(String direction, int wordCount) {
// usually this setter will assign the values to data members
this.direction = direction;
this.wordCount = wordCount;
}
Beside initializing local members, this setter is also an initializer for the layer class instance.
Any exception thrown becomes a Schema Definition Error.
If there are no parameter variables, then this setter, with no arguments, can be used purely for initialization.
A DFDL variable used to return a result from a layer must be undefined, since variables in DFDL are single-assignment.
Usually this means the use of the layer must be surrounded by a dfdl:newVariableInstance
annotation which creates a new instance of the layer result variable, over a limited scope
of use.
The variable is assigned by the layer, and it is then available for reading by the DFDL schema until
the end of the dfdl:newVariableInstance scope.
To return a value into a DFDL variable, the layer implementation defines a special recognizable
getter method.
The name of the getter is formed from prefixing the DFDL variable name with the string
"getLayerVariableResult_".
The return type of the getter must correspond to the type of the variable.
For example, a result value getter for a DFDL variable named total of type xs:unsignedShort would be:
int getLayerVariableResult_total() {
// returns the value created by the layer's algorithm.
// commonly this returns the value of a data member.
return this.total;
}
Layers could have multiple result variables, but a single variable is most common, generally for returning checksums.
See the ChecksumLayer class, which is designed to facilitate creation of checksum/CRC/hash/digest layers.
The Java types to use for the setter arguments and getter return types correspond to the DFDL variable types according to this table:
| DFDL Schema Type | Java Type |
|---|---|
| xs:byte | byte |
| xs:short | short |
| xs:int | int |
| xs:long | long |
| xs:integer | java.math.BigInteger |
| xs:decimal | java.math.BigDecimal |
| xs:unsignedInt | long |
| xs:unsignedByte | short |
| xs:unsignedShort | int |
| xs:unsignedLong | java.math.BigInteger |
| xs:nonNegativeInteger | java.math.BigInteger |
| xs:double | double |
| xs:float | float |
| xs:hexBinary | byte[] |
| xs:anyURI | java.net.URI |
| xs:boolean | boolean |
| xs:dateTime | com.ibm.icu.util.ICUCalendar |
| xs:date | com.ibm.icu.util.ICUCalendar |
| xs:time | com.ibm.icu.util.ICUCalendar |
The rest of the Layer class implements the layer decode/encode logic.
The actual algorithm of the layer is not implemented in methods of the derived layer class, but rather is
implemented in the layer's input decoder and output encoder.
These extend the java.io.InputStream and java.io.OutputStream base classes to actually handle the
data.
Every layer must implement the wrapLayerInput(java.io.InputStream) and wrapLayerOutput(java.io.OutputStream)
methods, which provide the input decoder and output encoder instances to the Daffodil layer framework.
When parsing/unparsing, the derived Layer class itself is concerned with setup and tear-down of the
layer's input decoder and output encoder, with providing access to/from DFDL variables,
and with reporting errors effectively.
setProcessingErrorException allows the layer to specify that if the layer throws specific
exceptions or runtime exceptions that they are converted into processing errors.
This eliminates most need for layer code to contain try-catches.
For example:
setProcessingErrorException(IOException.class);
informs the DFDL processor that an IOException thrown from the layer is to be treated as a processing error.
Unhandled exceptions thrown by the layer code are treated as fatal errors.
| Constructor and Description |
|---|
Layer(java.lang.String localName,
java.lang.String targetNamespace)
Constructs a new Layer object with the given layer name and namespace URI.
|
| Modifier and Type | Method and Description |
|---|---|
org.apache.daffodil.runtime1.layers.LayerRuntime |
getLayerRuntime()
For framework use.
|
java.util.List<java.lang.Class<? extends java.lang.Exception>> |
getProcessingErrorExceptions()
For framework use.
|
java.lang.String |
localName()
For framework use.
|
java.lang.String |
name()
For framework use.
|
java.lang.String |
namespace()
For framework use.
|
void |
processingError(java.lang.String msg)
Use to report a processing error.
|
void |
processingError(java.lang.Throwable cause)
Use to report a processing error.
|
void |
runtimeSchemaDefinitionError(java.lang.String msg)
Use to report a runtime schema definition error.
|
void |
runtimeSchemaDefinitionError(java.lang.Throwable cause)
Use to report a runtime schema definition error.
|
void |
setLayerRuntime(org.apache.daffodil.runtime1.layers.LayerRuntime lr)
For framework use.
|
void |
setProcessingErrorException(java.lang.Class<? extends java.lang.Exception> e)
Use to add an exception class to the list of exceptions that will be automatically converted
into processing errors.
|
abstract java.io.InputStream |
wrapLayerInput(java.io.InputStream jis)
Wraps a layer input decoder around an input stream.
|
abstract java.io.OutputStream |
wrapLayerOutput(java.io.OutputStream jos)
Wraps a layer output encoder around an output stream.
|
public Layer(java.lang.String localName,
java.lang.String targetNamespace)
localName - the local NCName of the layer. Must be usable as a Java identifier.targetNamespace - the namespace URI of the layer. Must obey URI syntax.java.lang.IllegalArgumentException - if arguments are null or do not obey required syntax.public final java.lang.String name()
This method and the string it returns are required by the SPI loader.
public final java.lang.String localName()
public final java.lang.String namespace()
public final void setLayerRuntime(org.apache.daffodil.runtime1.layers.LayerRuntime lr)
Called by the execution framework to give the context for reporting errors.
lr - runtime data structure used by the frameworkpublic final org.apache.daffodil.runtime1.layers.LayerRuntime getLayerRuntime()
Called by the execution framework to obtain the context for reporting errors.
public void processingError(java.lang.String msg)
When parsing a processing error can cause backtracking so that the parse can often recover from the error.
When unparsing a processing error is fatal.
msg - describes the errorpublic void processingError(java.lang.Throwable cause)
When parsing a processing error can cause backtracking so that the parse can often recover from the error.
When unparsing a processing error is fatal.
cause - a throwable object that describes the errorpublic void runtimeSchemaDefinitionError(java.lang.String msg)
This indicates that the layer is unable to work meaningfully because of the way it is configured. That is, the schema itself is not well defined due to the way the layer is configured.
For example suppose a layer had a DFDL variable for a parameter that is supposed to be an integer between 1 and 10, and this parameter is generally provided as a constant value. If the provided parameter variable value is 0, which is not meaningful, then a Runtime Schema Definition Error is the right error to invoke.
This error type is always fatal whether parsing or unparsing.
msg - describes the errorpublic void runtimeSchemaDefinitionError(java.lang.Throwable cause)
This indicates that the layer is unable to work meaningfully because of the way it is configured. The schema itself is not well defined due to the way the layer is configured.
This error type is always fatal whether parsing or unparsing.
See runtimeSchemaDefinitionError(String) for discussion of situations where
a Runtime Schema Definition Error is appropriate.
cause - a throwable object that describes the errorpublic abstract java.io.InputStream wrapLayerInput(java.io.InputStream jis)
throws java.lang.Exception
This input decoder does the real parser-time work of the layer.
It implements java.io.InputStream, by
reading data from the given argument input stream, and decoding it.
Any exception thrown from this wrap method becomes a Schema Definition Error (fatal).
The input decoder generally uses a reference to this layer instance to report errors.
To have the Daffodil layer framework convert uncaught exceptions
thrown by the input decoder into processing errors automatically,
call the setProcessingErrorException(Class).
Other kinds of input decoder processing errors can be signaled by calling the processingError(String) or
processingError(Throwable) methods.
Input decoder schema definition errors are more rare, but if needed the runtimeSchemaDefinitionError(String) or
runtimeSchemaDefinitionError(Throwable) methods may be called.
jis - The input stream to be wrapped.java.lang.Exceptionpublic abstract java.io.OutputStream wrapLayerOutput(java.io.OutputStream jos)
throws java.lang.Exception
The output encoder does the real unparse-time work of the layer.
It implements java.io.OutputStream by
accepting data via the usual output stream write calls, encoding this
data, and writing the encoded data to the argument output stream.
Any exception thrown from this wrap method becomes a Schema Definition Error (fatal).
The output encoder generally uses a reference to this layer to report errors.
To have the Daffodil layer framework convert uncaught exceptions
thrown by the output encoder into processing errors automatically,
call the setProcessingErrorException(Class).
Other kinds of output encoder processing errors can be signaled by calling the processingError(String) or
processingError(Throwable) methods.
Output encoder schema definition errors are more rare, but if needed the runtimeSchemaDefinitionError(String) or
runtimeSchemaDefinitionError(Throwable) methods may be called.
jos - The output stream to be wrapped.java.lang.Exceptionpublic final void setProcessingErrorException(java.lang.Class<? extends java.lang.Exception> e)
The purpose of this is to allow one to use java/scala libraries that may throw exceptions when encountering bad data. Such exceptions should be translated into processing errors, which will allow the parser to backtrack and try other alternatives which may work for that data. By calling this method the layer framework implements the try-catch logic to capture these exception types and convert them into processing errors. This avoids a great deal of try-catch logic that would otherwise be required in layer methods.
When considering whether a thrown Exception is to be converted to a processing error RuntimeException classes are handled separately from Exception classes. Hence calling
setProcessingErrorException(Exception.class);
will NOT cause all RuntimeExceptions to also be converted into processing errors.
It will, however, cause all classes derived from Exception that are NOT RuntimeExceptions
to be caught and converted into Processing Errors.e - the exception class to be added to the list of processing error exceptionspublic final java.util.List<java.lang.Class<? extends java.lang.Exception>> getProcessingErrorExceptions()