Version 3.0 enhancements
This chapter presents the new services and the improvements added to the TCE-Java v2.0 release.
The TCE-JAVA Compiler and runtimes are now compliant with the 2002 release of the ASN.1 standards.
It supports the following new features:
The new RELATIVE-OID type and the new floating-point syntax, MINUS-ZERO value and NOT-A-NUMBER value for REAL values were already supported by the TCE-Java v2.0 version.
- New SEQUENCE OF NamedType and SET OF NamedType syntax,
- New CONTAINING and ENCODED BY constraints on OCTET STRING and BIT STRING types,
- New PATTERN constraint for restricted character string types,
- New exception marker for ENUMERATED types,
- New version number for extensions,
- New possibilities for the @ notation in ComponentRelationConstraint,
- New hexadecimal encoding possibility for open types in XER,
- New block comment,
- Come-back of the object identifier predefined arc "iso(1) registration-authority(1)",
The ASN.1:2002 XML value notation is not supported.
DEFAULT values management
Up to the previous release, the encoders handle the fields of SEQUENCE and SET types with a default value the same way as optional fields. The encoder puts the value in the encoded message if and only if the value is present on the API.
The new release provides a new feature for ASN.1 default values processing. In order to give the user the maximum flexibility in the design of his application, our ASN.1 runtime offers the ability to select the behavior of the encoding:
The encoding can be changed with a new method on the asnContext object:
- The most compact encodings that is the systematic deletion of ASN.1 default values.
- Minimum processing on default value to be compliant with the ASN.1 standard (default behaviour).
If enabled, all values given on the API equal to their ASN.1 default values are absent in the encoded message.
Note that this flag does not change the behaviour of the encoder when CXER and DER canonical encoding rules are used (the encoder has not the freedom to follow the user preferences).
Concerning decoding, up to the previous release, the decoders handle the fields of SEQUENCE and SET types with a default value the same way as optional fields. The decoder puts the value on the API if and only if the value is present in the decoded message.
The new release provides a new feature where the decoder puts the default value on the API if the value is absent from the decoded message. It can be enabled with a new method on the asnContext object:
New error trace
Errors during encoding, decoding and constraint check can now be traced in the trace stream.
This new debug feature is enabled by default when a trace stream is defined. It can be disabled by calling the setErrorTrace(false) method on the Context object.
The error trace gives in XML format several useful debug data:
- The description of the error,
- The nature of the error (the class name of the exception),
- When decoding, the offset where the decoder stopped in the decoded message,
- The full path of the field containing the error in the decoded value.
Example of error trace:
<description>Expected true or fals</description>
New SAX API
A new SAX-like decoding API package fr.marben.asnsdk.japi.sax is available. It allows decoding a value step by step. The decoded value is not instantiated and an application can get the decoded fields by implementing a content handler which is called for each decoding step.
A new specific compilation option is available to use this interface: api sax.
New generic api feature
Methods to access directly the API values from root values have been added.
Direct access methods provide three ways to identify a field in a value:
The Java String representations are provided by the Compiler thanks to the -apiIds option. A file asnids.txt containing the identifiers is generated.
- a Java String representing the textual identification,
- a Java String representing the numeric identification and
- an integer array containing type indexes of the numerical identification.
New graphical user interface
The graphical user interface of the compiler has been totally redesigned:
A project file created by a previous version of the GUI can be used with the new version of the GUI.
- The new GUI is user-friendly and easy-to-use.
- A file navigator is now included in the interface.
- The text editor supports now several file encodings (US-ASCII, ISO-LATIN-1, UTF-8, ...).
- A project is mandatory to perform the compilation.
The new GUI of the compiler requires Java 1.4 at least.
With Java 1.2 or Java 1.3, the compiler can only be used in command-line mode.
Boolean True value
Up to the previous release, BER encoding of the true boolean value was the DER canonical encoding 0xFF.
This new feature allows users to parameterize the BER true value thanks to setEncodingBerTrueValue and getEncodingBerTrueValue methods.
ASN.1 syntax compatibility
Some new rules of the 2002 version of the ASN.1 standards could cause compatibility problems on the ASN.1 description:
For the three first points, a simple work-around is the removal of the offending syntax.
- The SIZE and FROM constraints are no longer allowed on UTCTime and GeneralizedTime types,
- A COMPONENTS OF can no longer reference a SEQUENCE or SET type with an empty root part,
- The UNIQUE keyword is now incompatible with the DEFAULT keyword in the definition of a field of an information object class,
- The SIZE or FROM constraints are no longer allowed inside a FROM constraint,
- The definition of an information object class with no finite representation for its objects is now forbidden,
- A recursive information object definition is no longer allowed,
- The syntax object.&variableTypeValueSetField is now forbidden.
For the fourth point, a simple work-around is the removal of the enclosing FROM constraint.
The other points are very improbable cases that need a case per case study. Contact email@example.com if you encounter these cases.
Extensible permitted Alphabet constraint in PER
The PER encoding rules have been clarified for a restricted character string type with a FROM constraint followed by an extensible constraint.
Until the previous version, a FROM constraint followed by an extensible constraint was ignored when computing constraints for PER. This is no longer the case.
- With the v2.0 version, this type was equivalent to:
- With the v3.0 version, this type is now equivalent to:
This change impacts the PER encoding of restricted character string types (IA5String, NumericString, PrintableString, VisibleString, ISO646String, BMPString and UniversalString) with such a combination of constraints.
With this release, the -compat 1927 compiler option can be used to obtain the behaviour of the previous release.
Extensible SET type encoding in DER
The encoding of a SET type in DER is now ordered by tag. The named types are encoded smaller tags first, whether they are in the roots, the known extensions or unknown extensions.
File name unicity
The previous version of the compiler was not aware of systems that do not distinguish the case in file names, such as Microsoft Windows systems
For example, if an ASN.1 module contains two types named Ta and TA, the previous version of the compiler produced two classes named Ta and TA in files named Ta.java and TA.java that were confused by the system.
To avoid this problem, the new version of the compiler adds a suffix to class names of the same Java package when the type names differ only by their case. In a similar way, it also adds a suffix to ASN.1 module names to produce different Java package names.
For example, if an ASN.1 module contains two types named Ta and TA, the new version of the compiler produces two classes named Ta_80 and TA_C0 in files named Ta_80.java and TA_C0.java.
Because the addition of this suffix in case of a conflict does not depend on the system running the compiler, it can introduce an API change for users of others systems, such as UNIX-like systems.
Error trace enabled by default
When a trace stream is defined, the new debug feature is enabled by default. Thus, each error returned by the runtime to the user application appears now in the trace stream.
To obtain the same behaviour as in the previous release, call the setErrorTrace(false) method on the Context object.
Changes in the XML semantic tree
The element RestrictedCharacterStringValue in the XML Semantic Tree (produced with the -tree compiler option) has been modified:
In order to be in compliance with the ASN.1:2002 standard, the elements ContaingBitString and ContaingOctetString have been added in the XML Semantic Tree.
The element SequenceOf in the XML Semantic Tree has been modified:
- The representation of values of type BMPString, resp.UniversalString, in the hexBerValue attribute have been changed from the hexadecimal representation of 16 bits, resp. 32 bits, characters to the hexadecimal representation of UTF-8 encoded characters.
- An attribute charCount has been added to give the number of characters contained in the hexBerValue attribute.
- A subelement SetSeqOfNamedType representing the sequence of named type has been added.
Local time no longer allowed for UTCTime
The runtime does no longer allow an UTCTime value expressed in local time. Only values expressed in coordinated universal time (values ending with the letter Z) or with a time differential (values ending with +hhmm or -hhmm) are allowed.
The previous versions of the runtime did not enforce this rule of [X.680].
The new version of the runtime returns an exception with error code 19 if such a value is used to set an UTCTime value.