Converts an input ASN.1 specification to obtain the Data Reader Input XML Specification (DRIX) and Data Reader Output XML Specification (DROX).
This can then be used within the Data360 Analyze Data Reader in order to parse a file which is described by the ASN.1 specification.
For cases where multiple ASN.1 modules are to be used, and reference each other via IMPORTS, EXPORTS statements, the Convert MultiModule ASN1 node should be used.
In order to use this node, either paste an ASN.1 specification into the ASN1 Specification property, or specify the name of a file containing the ASN.1 specification in the ASN1 Specification Filename field.
The Library, Version, Namespace and DrixFilename properties all need to be set in order to construct a correct DRIX file with the corresponding tags setup. In order for the DRIX produced to be used as in an "include" tag by a subsequent Data Reader node, the "DrixFilename" property must specify a filename that has the form <Directory>/{{^Library^}}[optAdditional].drix Where: "optAdditional" can be any additional characters that form part of a valid filename, but does not contain any directory separator ("/", "\") characters.
The TopLevelType property specifies the top level type in the ASN.1 specification file, and the generated DRIX will have the primaryField hit this type.
If a subsequent Data Reader node is to use the types created by this node, then the library should be referenced in an include tag, and declare a field to be of the top level type. In this manner, if the ASN.1 data is blocked, or wrapped in some header/trailer information, it is simple to nest the field that references the top level type in other DRIX constructs.
This version of the converter can only handle data encoding using the ASN.1 Basic Encoding Rules (BER) - and by extension CER & DER.Not all of the keywords & constructs available in the ASN.1 language are supported in this version of the converter.
Properties
EncodingRules
Optionally specify the ASN.1 Encoding Rules to use. Chose from:
- BER
- CER
- DER
The default value is BER.
Asn1SpecificationFilename
Optionally specify the absolute name of the ASN.1 specification.
Cannot be used in conjunction with the ASN1 Specification property.
Asn1Specification
Optionally specify the ASN.1 Specification. The specification must be written using the standard Abstract Syntax Notation, and is simply pasted into the text field.
Cannot be used in conjunction with the ASN1SpecificationFilename property.
Library
Specify the name of the library for the generated ASN.1 DRIX file.
A value is required for this property.
Version
Specify the version number for the generated ASN.1 DRIX file.
A value is required for this property.
Namespace
Specify the namespace under which all of the types will be defined in the generated ASN.1 DRIX file.
A value is required for this property.
TopLevelType
Specify the type within the ASN.1 specification which is the top level type. This type defines how to read the data file.
A value is required for this property.
DrixFilename
Specify the type within the ASN.1 specification which is the top level type. This type defines how to read the data file.
A value is required for this property.
DroxFilename
Specify the absolute path where the generated DROX file is to be created.
A value is required for this property.
LibrarySearchPaths
Optionally specify the absolute path of the directories containing any referenced DRIX files. Each path entry must be on a new line.
All search paths must exist at a location on the file system where the Data360 Analyze server is located.
Example: {{nil.brain.home}}/lib/ldr/commonTypes
{{nil.brain.home}}/lib/ldr/converters/asn1
DroxGenerator
Optionally specify the Data Reader Output XML (DROX) Specification to be used by the converter. This DROX is basically a "generator" DROX, which should contain a dumper and at least one dump tag. The dump tag tells the ASN.1 Converter how to construct the DROX file which can subsequently be used with the generated DRIX to read the ASN.1 file.
By default this simply outputs all of the fields under the top level type. If the top level type contains a choice between different record types, it may be preferable to create separate dump tags for each of these record types.
For instance, if the top level type was specified as :
MyTopLevelType ::= CHOICE { recType1 [0] RecordType1, recType2 [1] RecordType2 }
Then it may be desirable to create a droxGenerator that looks like:
<drox> <dumper name="Asn1Dumper" javaClass="com.lavastorm.ldr.converters.asn1.output.Asn1OutputDefinitionGenerator"/> <dump name="Asn1Dumper"> <include> <fields> <pattern pattern="{{^TopLevelType^}}.recType1"/> </fields> </include> </dump> <dump name="Asn1Dumper"> <include> <fields> <pattern pattern="{{^TopLevelType^}}.recType2"/> </fields> </include> </dump> </drox>
Classpaths
Optionally specify entries that are to be added to the classpath used by the node. Any external jars required by the node should be placed in this parameter. Each entry must be placed on a newline.
DefaultMaxIntegerSize
Optionally specify the data size to use for the decoded values for all INTEGER & ENUM types which do not have any value or size constraints. Choose from:
- -1 - no Maximum
- 4 - 4 Byte Maximum
- 8 - 8 Byte Maximum
Since there is no fixed restriction on the default sizing of ASN.1 INTEGER encoding, this could be of an arbitrary length. Therefore, by default, this property should be set to -1 and BigInteger types are used to read in the data.
However, this can lead to poor performance. Therefore, if it is known in advance that all INTEGER fields will never be greater than 4 or 8 bytes, then this property can be set accordingly. Changes to this property affect the output metadata.
In the case of 4, data will be output with an "int" type. In the case of 8, data will be output with a "long" type. In the case of -1, the property BigToString must also be set to True, and the data will be output with a "String" type.
In cases using "4 Bytes" or "8 Bytes", when more than 4 or 8 bytes of encoded data are present, but the value of the data can be encoded in 4 bytes or 8 bytes respectively, there is no problem. An example of this would be a 10 byte encoding of the value 0, as 0x00 00 00 00 00 00 00 00 00 01. This can be packed into an int, or long type with no overflow.
However, in cases where the value is too large to be encoded, then the dependant on the setting of the overflowErrorLevel property, the following will happen:
overflowErrorLevel Behaviour
IGNORE Overflow never checked. Data is simply packed into the specified number of bytes, with possibility of unreported overflow
WARNING Logs a WARNING message in the log, data is treated as BAD and will be output as null.
RECOVERABLE_ERROR Logs a RECOVERABLE_ERROR message in the log, data is treated as BAD and will be output as null.
FATAL_ERROR FATAL_ERROR thrown when overflow is encountered.
OctetStringToHexString
Optionally specify whether OCTET STRING types will be output as Hex Strings. If set to False, these are handled as byte arrays, and the output metadata is dependant on the property ByteArrayToBase64 in the Data Reader node using the DRIX. If set to True, then these are simple decoded using a .binary.Int8ArrayToHexString type, and output as a String value. e.g. the value 0x010203 would be output as the String "010203".
The default value is False.
BigToString
Optionally specify whether java.lang.BigInteger and java.lang.BigDecimal fields should be converted to Strings and output as such. The internal BRD formats numeric types (double, long) cannot handle numeric values greater than 8 bytes long. If these types are not converted to String, then they must be output as byte array data.
The default value is True.
StringToUnicode
Optionally specify whether or not all java Strings should be output as Unicode in the output records
The default value is False.
ByteArrayToBase64
Optionally specify whether or not byte arrays can be output as Base64 encoded strings. When this is set to False, byte arrays cannot be output by this node.
The default value is False.
DeprecatedErrorLevel
Specify the error level to use for all deprecation errors.
The default value is warning.
Inputs and outputs
Inputs: multiple optional.
Outputs: multiple optional.