What's New in the OSS ASN.1 Tools for Java

What's New in ASN.1/Java 8.0

New Features

The ASN.1 compiler now supports X.680 Amendment 1, which relaxes the IMPORTS clause to allow symbols to be imported from the latest module version, as indicated by the object identifier. The IMPORTS clause can now include WITH SUCCESSORS and WITH DESCENDANTS as the SelectionOption.

The ASN.1 compiler now supports the new -enablePartialDecode and -partialDecodeOnly command line options. These options are available when the -toed option is specified or implied by default. The options instruct the compiler to generate code that makes the new coder.decodePartial() TOED runtime API method available to the user. In contrast to the decode() method, the new method does not return the decoded PDU value. Instead, it invokes a user-defined callback method when decoding each field that is marked by the new OSS.DataCallback (or OSS.InfoCallback) compiler directive and optionally passes the decoded field value to it. The partial decode feature enables the user to

• Extract data without writing code to access deeply nested fields of complex PDUs.
• Reduce the memory footprint of applications that contain minimal information in their PDUs.

The feature is available for the PER, UPER, CPER, CUPER, OER, and COER encoding rules.

A new encoder option has been implemented for the JSON encoder. This option selects the alternate form of encoding for a BIT STRING or OCTET STRING with a contents constraint that does not include an ENCODED BY clause. The option is configured with the following JSONCoder methods:
     public void encodeContainedValuesAsText();
     public void encodeContainedValuesAsHex();

The new -userConstraintPDUs | -noUserConstraintPDUs command line options have been implemented. These options tell the compiler whether or not (the default) to generate Java classes for type parameters of the CONSTRAINED BY constraint when such types are defined inline.

The ASN.1 compiler now supports a special type of absolute reference notation that applies to the OSS compiler directives. The notation allows you to access ASN.1 types located within WITH COMPONENTS and WITH COMPONENT(inner subtype) clauses and consists of two dollar signs '$$' followed by an index number that indicates a particular WITH COMPONENTS or WITH COMPONENT clause.
The notation can be used to assign user-defined names within CONSTRAINED BY clauses that are present within an inner subtype or a compiler-generated structure (the ASN.1 compiler creates compiler-generated structures when a contents constraint is applied within an inner subtype). The rules that apply to the new notation are similar to the ones that apply to the absolute reference notation for the CONSTRAINED BY syntax.

A new encoder option that permits customization of the JSON encoder output has been implemented. The option is enabled via the new enableJSONCoderInterface() method of the JSONCoder class. To customize the JSON encoder output, the user must subclass the generated Java class using the OSS.UserClass compiler directive and implement the JSONCoderInterface in the subclass. Then, after enableJSONCoderInterface() is called, the JSON encoder will invoke the JSONCoderInterface that is implemented by the subclass to obtain customized JSON tokens that represent the value being encoded. This encoder option is currently supported only by the SOED runtime.

New samples

New samples have been created for the following:

• The DIN EN 15722 Intelligent transport systems - ESafety - ECall minimum set of data standard. The sample demonstrates how an ECallMessage message can be created and serialized to UPER bits using the API of generated Java classes.
• The eUICC Profile Package standard. The sample demonstrates how a eUICC Profile Package can be constructed and saved to the disk file using the API of generated Java classes.
• The GSMA Remote SIM Provisioning standard. The sample demonstrates the invocation of the GetBoundProfilePackage function of the ES9+ interface at the SM-DP+ using the API of generated Java classes.
• Release 15 of the UMTS RRC protocol: TS 25.331 (UMTS RRC) 15.3.0 (2018-06).
• The Bilateral Transfer protocol (BTP): ILP-RFC 0023 Draft 4. The sample demonstrates communication between BTP peers that involves the Prepare, Fulfill, and Reject requests.

New samples for 5G NGAP, XnAP, E1AP, and F1AP protocols for 3GPP Release 15 have been created. The samples for the LTE S1AP, X2AP, M2AP, M3AP, RRC, LCSAP, LPPa, SBcAP, and XwAP protocols have been updated to 3GPP Release 15.

New samples in the advanced category have been created to explain the use of the partial decode feature:
     partial
     s1ap_pd (uses 3GPP S1AP V15.3.0 specification)

Improvements

The ASN.1 compiler has been changed to generate Java classes compatible with the TOED runtime by default. Previously, when neither -toed nor -soed was specified on the ASN.1/Java command-line, Java classes compatible with the SOED runtime were generated.

The -paramtypesuperclass option is now supported with both the SOED and TOED. Before this change it was not available with the TOED and was ignored when specified along with the -toed option.

The ASN.1 compiler and TOED runtime have been enhanced to support the DeferDecoding directive for the BER and DER encoding rules. For other encoding rules (PER, OER, XER, and JSON), the compiler generates encoders and decoders that ignore the directive and encodes or decodes the value in a single pass.

---

What's New in ASN.1/Java 7.2

New Features

The OSS ASN.1 Tools has been enhanced to support the Canonical Packed Encoding Rules (ALIGNED and UNALIGNED), as specified by ITU-T Recommendation X.691 (08/2015) | ISO/IEC 8825-2:2015.

Both the compiler and runtime have been enhanced to support the Java Platform Module System (JPMS), which was introduced in Java 9. The compiler now supports the '-javamodule <name>' option that packages the generated classes into the Java module with the specified <name>. The software distribution now includes an extra set of runtime libraries that are packaged as Java 9 modules. These new libraries are available in the mlib/ directory of the ASN.1/Java installation and can be used only with JDK 9.

The ASN.1 compiler now supports the UPPERCAMELCASED and LOWERCAMELCASED keywords in the NAME and TEXT JER encoding instructions. You can now describe a wider range of JSON data in an ASN.1 schema.

The public API of the JIAAPI value parser will now parse concatenated values and value assignments from an arbitrary java.io.Reader object. A relaxed parsing mode is now implemented: non-critical deviations from the expected syntax are ignored.

New samples

A new sample that demonstrates processing of 3GPP CDR files (TS 32.297) has been created. 3GPP CDR files contain a non-ASN.1 file header and non-ASN.1 record headers, while record bodies are encoded by one of the ASN.1 encoding rules (BER, PER unaligned, PER aligned, or XER). The sample shows how one can skip over non-ASN.1 content, feed ASN.1 data to the ASN.1/Java API, and convert CDR records to Java objects.

New samples have been created for release 14 of the LTE protocols and existing samples for release 12 and 13 have been updated to the most recent versions of the available ASN.1 schemas:

• TS 29.171 (LCSAP) V13.3.0 (2017-06)
• TS 29.171 (LCSAP) V14.1.0 (2017-06)
• TS 36.455 (LPPA) V14.3.0 (2017-09)
• TS 36.443 (M2AP) V13.3.0 (2016-03)
• TS 36.443 (M2AP) V14.0.1 (2017-09)
• TS 36.444 (M3AP) V13.2.0 (2016-03)
• TS 36.444 (M3AP) V14.1.0 (2017-06)
• TS 36.331 (RRC CV2X) V14.4.0 (2017-09)
• TS 36.331 (RRC NB IOT) V13.7.1 (2017-09)
• TS 36.331 (RRC NB IOT) V14.4.0 (2017-09)
• TS 36.331 (RRC) V12.15.1 (2017-09)
• TS 36.331 (RRC) V13.7.1 (2017-09)
• TS 36.331 (RRC) V14.4.0 (2017-09)
• TS 36.413 (S1AP NB IOT) V13.6.0 (2017-06)
• TS 36.413 (S1AP NB IOT) V14.4.0 (2017-10)
• TS 36.413 (S1AP) V12.7.0 (2016-03)
• TS 36.413 (S1AP) V13.6.0 (2017-06)
• TS 36.413 (S1AP) V14.4.0 (2017-10)
• TS 29.169 (SBCAP) V12.10.0 (2017-09)
• TS 29.169 (SBCAP) V13.3.0 (2017-09)
• TS 29.169 (SBCAP) V14.1.0 (2017-09)
• TS 36.423 (X2AP NB IOT) V13.7.0 (2017-06)
• TS 36.423 (X2AP NB IOT) V14.4.0 (2017-09)
• TS 36.423 (X2AP) V12.9.0 (2016-07)
• TS 36.423 (X2AP) V13.7.0 (2017-06)
• TS 36.423 (X2AP) V14.4.0 (2017-09)
• TS 36.463 (XWAP) V14.2.0 (2017-06)

A new sample for release 14 of the UMTS RRC protocol has been created:

• TS 25.331 (UMTS RRC) 14.4.0 (2017-09)

Improvements

The ASN.1/Java compiler will now automatically turn off the default -relaxedMode option when the -designerWarnings option is specified.

Type-safe getter methods have been added to the EmbeddedPDV.Identification and the External.Encoding universal classes to align the API of these classes with the API generated for CHOICE ASN.1 type:

public Syntaxes getSyntaxes();
public ObjectIdentifier getSyntax();
public INTEGER getPresentation_context_id();
public Context_negotiation getContext_negotiation();
public ObjectIdentifier getTransfer_syntax();
public Null getFixed();

public OpenType getSingle_ASN1_type();
public OctetString getOctet_aligned();
public BitString getArbitrary();

---

What's New in ASN.1/Java 7.1

New Features

JSON

JSON Encoding Rules support in the ASN.1/Java compiler and the SOED, TOED, and LED runtime libraries now conforms to Draft ITU-T Recommendation X.jsoner. The existing -json command-line option now instructs the compiler to enable support for X.jsoner at runtime.

The JSON codec now supports encoding instructions, specified by Draft ITU-T Recommendation X.jsoner in the SOED and TOED. The following encoding instructions are supported:

• JER:ARRAY
• JER:BASE64
• JER:NAME
• JER:OBJECT
• JER:TEXT
• JER:UNWRAPPED

New samples

Samples for the following LTE protocols have been created:

• LTE LCS Application Protocol (LCS-AP) - TS 29.171 V13.2.0 (2016-03)
• LTE Positioning Protocol A (LPPa) - TS 36.455 V13.1.0 (2016-03)
• LTE RRC protocol to demonstrate cV2X features - TS 36.331 V14.2.2 (2017-03)

Improvements

The compiler will no longer issue a false warning for a valid type value constrained by inner subtype constraints. Also, the SOED runtime constraint checker will no longer issue false validation errors for such values.

The TOED compiler now generates a correct constraint checker for a SEQUENCE or SET type where some fields have DEFAULT values. Previously, if the value of the field was not explicitly specified, a NullPointerException could be thrown. Now, the generated code attempts to validate the implied value.

Previously, the SOED runtime constraint checker omitted any validation of a SEQUENCE or SET component when it had a DEFAULT value and the component's value was not explicitly specified. Now, the constraint checker validates such components using their DEFAULT value instead.

The SOED CER encoder will now relay an unknown extension of ENUMERATED and will not issue this confusing error message: E0124S: Unable to relay unknown extension: the extension was decoded by the Canonical Encoding Rules (CER) Coder but is relayed by the Canonical Encoding Rules (CER) Coder.

---

What's New in ASN.1/Java 7.0

New Features

JSON encoding rules in the SOED runtime

Support for the JSON encoding rules has been added to the SOED runtime.

Current limitations of the JSON SOED encoder/decoder:

• The deferred decoding feature is not supported.
• The ValueInFile feature is supported only for SET OF and SEQUENCE OF ASN.1 types.

New command-line options

The -helperAPI <param> and -noHelperAPI <param> command-line options have been added to the ASN.1 Tools for Java. These options tell the compiler to generate optional helper APIs, or not. A parameter is required that can be a single keyword or a comma-separated list of keywords. The keyword specifies the type of helper API; currently, only opentype and pdudecoder are valid.

• The -helperAPI opentype command-line option affects the representation of open type fields that are constrained by a component relation constraint.
• The -helperAPI pdudecoder and -noHelperAPI pdudecoder command-line options tell the compiler whether to generate optional PDU and PDU_ID classes that will be used to auto-detect and decode PDUs of unknown types from bits on the wire.

Contraint validations

Validation of the following constraints has been implemented in the TOED:

1. Element set specification (x.680 clause 50) - EXCEPT and ALL EXCEPT
2. Subtype elements (x.680 clause 51)
   • Permitted alphabet
   • Type constraint
   • Pattern constraint
   • Property settings
   • Duration range
   • Time point range
   • Recurrence range
3. Other constraints
   • Table constraint
   • Component relation constraint
   • Contents constraint

Improvements

-sampleCode command-line option

The -sampleCode command line option can be specified with both the -soed and the -toed options. Before the change the -sampleCode option was ignored when specified along with the -toed option.

---

What's New in ASN.1/Java 6.3.1

New Features

The OSS ASN.1 Tools for Java now includes ASN.1 Studio 8.0. For a summary of the improvements in ASN.1 Studio 8.0, see the Enhancements History section.

---

What's New in ASN.1/Java 6.3

New Features

The following new features have been added:

Support for constraint checking in TOED

New command-line options

The -splitBigEnums #n command-line option reduces the size of a large JVM internal static initializer method by generating static _initMembers...() methods that split the large initializer into parts, which helps overcome the JVM 64K method size limit.

The -limitBigEnums #n command-line option is used when the amount of code needed to initialize named "static final" class instances that represent ENUMERATED or INTEGER with named numbers exceeds the 64K limit.

Improvements

Java class improvements

The Java classes that are generated to represent INTEGER types with named numbers now contain an inner "public static class Value" that includes a "public static final long" constant for each named number. This feature is useful when named numbers are present in the Java "switch" statement.

Method improvements

The following methods of the com.oss.asn1.Coder class (available for SOED and TOED) are used to control the whitespace generated by the XER, E-XER and JSON encoders:

• public void enableCompact();
• public void disableCompact();

The following methods of the com.oss.asn1.Coder class (available for TOED) are used to control the whitespace generated by the XER and JSON encoders:

• public void setIndentWidth(int width);
• public int getIndentWidth();

---

What's New in ASN.1/Java 6.2

New Features

The following new features have been added:

JSON Encoding Rules Support

The JSON Encoding Rules are currently available with the osstoed.jar runtime library and the -toed runtime option.

OER and COER Encoding Rules Support

The Octet Encoding Rules (OER) and the Canonical Encoding Rules (COER) are now available with the -soed compiler option and the oss.jar SOED runtime library.

New command-line option

The ASN.1/Java TOED compiler now supports the -limitMethodSize <number> compiler option, which enables you to split the generated methods that exceed the 64K size limit into smaller parts. The "number" parameter specifies the number of lines of generated source code.

New methods

New methods have been added to the com.oss.asn1.Coder TOED runtime class. The methods enable or disable the Coder options that affect the JSON encoding of SET or SEQUENCE components that are defined using the OPTIONAL or the DEFAULT keyword:

• enableEncodingOfAbsentComponents()
• disableEncodingOfAbsentComponents()

The following methods have been added to the com.oss.util.ASN1PrintWriter class:

• enablePrintingOfImpliedValues()
• disablePrintingOfImpliedValues()

New Samples

The standards/tap3_bin2xml sample has been created. The sample demonstrates conversion of binary BER-encoded TAP3 records into XML (XER) format.

Improvements

The TOED BER/DER/OER/PER/XER Encoding Rules now support automatic encoding and decoding of values contained in a BIT STRING or OCTET STRING that is encoded by different encoding rules.

The formatted string that is returned by the toString() method of AbstractData can now be customized. An extra overloaded version of this method has been added to the class. Also, the TOED runtime now includes the com.oss.util.ASN1PrintWriter utility class which improves compatibility with the SOED API.

The error messages issued for invalid encodings of an unconstrained length determinant have been changed. The decoder issues more comprehensive error descriptions.

The runtime classes now provide a better implementation of the hashCode() method.

The ASN.1/Java PER SOED coder has been changed to interpret the unspecified lower bound of the length determinant in accordance with the 2015 version of the X.691 document. The -compat oldPERSemiBoundedStrings flag can be used to restore the compatibility with the previous revisions of the X.691 standard.

---

What's New in ASN.1/Java 6.1

New Features

COER, DER, XER, and CXER Support in TOED

New methods

The SOED and TOED runtimes now define the name() method of the Enumerated class, which easily determines the symbolic name of the enumerator.

The useIndefiniteLengthEncoding() method has been added to the com.oss.asn1.Coder class of the TOED API for better compatibility with the SOED API.

An overloaded version of the enableContainedValueDecoding() method has been added to the com.oss.asn1.Coder class:

public void enableContainedValueDecoding(boolean preserveEncoding)

This method enables automatic decoding of contained values, carried within a BIT STRING or OCTET STRING with contents constraints. This feature is supported in the SOED runtime only.

Improvements

The TOED runtime has been enhanced to support OER as defined in "Rec. ITU-T X.696 | ISO/IEC 8825-7", rather than only the subset of ASN.1 types as defined in the "NTCIP 1102:2004 Octet Encoding Rules (OER) Base Protocol" document.

The ASN.1/Java compiler has been changed to generate the type-safe getXXX() method for each alternative of the CHOICE type.

The ASN.1 compiler now informs the user about warnings and errors that were suppressed because relaxed mode is enabled by default.

The compiler now accepts comments within compiler command files. The "--" characters specify the beginning of a comment and can be placed anywhere on the line. The comment continues until either a subsequent "--" is reached or the line ends.

When the same coder object is used to decode from a byte buffer and then from a stream, the second attempt no longer results in a ClassCastException being thrown in the BER TOED coder.

Previously, some invalid encodings could cause the BER TOED decoder to throw an OutOfMemoryError. Since applications typically do not intercept Java errors, this caused the application to crash. Now the decoder will throw a DecodeFailedException with the OUT_MEMORY status code instead.

The BER and DER TOED decoders will now correctly process open types that are nested in constructed types as child components and have unknown extension values of child components of SEQUENCE, SET, or CHOICE types.

An anomaly in the SOED and TOED runtimes that caused performance degradation when a value of the UTF8String type was decoded has been fixed.

The recent Corrigendum (Rec. ITU X.691 Cor 4 | ISO/IEC 8825-2 Cor 4.) to the X.691 standard fixed a defect in Clause 32.6.1. The definition o f the fractional-value field of a DURATION-INTERVAL-ENCODING type is changed from

INTEGER(1..999, ..., 1000..MAX)

to

 INTEGER(0..999, ..., 1000..MAX)

The ASN.1/Java PER encoders/decoders will now behave according to the new definition.

---

What's New in ASN.1/Java 6.0

New Features

New runtime library

A new runtime library, the OSS ASN.1/Java Time-Optimized Encoder/Decoder (TOED), has been implemented.

TOED is optimized for faster encoding and decoding. The new ASN.1/Java TOED runtime, osstoed.jar, uses encoders/decoders generated by the compiler, dramatically speeding up the encoding/decoding process compared to the interpretive ASN.1/Java runtime, oss.jar, which is now referred to as the ASN.1/Java Space-Optimized Encoder/Decoder (SOED).

BER, basic PER (aligned and unaligned), and OER encoding rules are supported. Support for DER, CER and XER is coming soon. Limited constraint checking is available, only to the extent that is required by the corresponding encoding rules (PER, OER).

For more information of the differences between the ASN.1/Java SOED and TOED runtime packages, see the SOED versus TOED section.

OER Support

Support for the Octet Encoding Rules (OER), as specified by the NTCIP 1102:2004 Octet Encoding Rules (OER) Base Protocol document, has been implemented in the ASN.1/Java compiler, the TOED runtime library and ASN.1 Studio. OER messages can generally be encoded/decoded significantly faster compared to BER and PER messages, while being only slightly less compact than PER messages. Support for OER in ASN.1/Java SOED and ASN.1/Java LED will be provided in the next release.

New compiler options

New compiler options, -soed and -toed, have been added. These options instruct the compiler to generate either Java classes that are optimized for a smaller code size (to be used with oss.jar at run time), or Java classes that are optimized for speed (to be used with osstoed.jar at run time). The -soed option is selected by default when neither -soed nor -toed are specified. The -soed and -toed options are mutually exclusive; if specified simultaneously, the option specified last on the command line takes precedence.

New samples

The set of samples provided includes new samples illustrating the use of protocols based on the SAE J2735 Intelligent Transportation standard, as well as the RRC, S1AP, and X2AP LTE protocols based on 3GPP Release 10.

---