Contents
The following changes have been made to the ASN.1 compiler:
In addition, the ASN.1/Java Tools now includes ASN.1 Studio release 10.5.
The ASN.1 Standards repository now includes ASN.1 specifications for 3GPP Release 17, as follows:
The ASN.1 Basic repository now includes samples for binary to CSV and JSON formats.
The Runtime API documentation has been updated with a version generated by the JDK 17 JavaDoc tool program.
ValueNotationReader parser = Project.getValueNotationReader();Reading a single value or value assignment from a string can be accomplished by invoking the read-methods of the parser. The following methods return an instance of the AbstractData class:
value = parser.readValue(string, new TypeOfTheValue()); or value = parser.readValueAssignment(string);The latter method relies on the PDU type name that is specified in the input string.
We stand with Ukraine 
AbstractData data;
AVNInput input = new AVNInput(reader);
while (data = parser.readValue(input, new Type()) != null)
System.out.println("data " + data);
NOTE: The ASN.1 value notation parser is a chargeable feature in non-evaluation licenses. Contact Sales to obtain pricing information.The compiler will now recognize the new -2021 option. The existing -2015 option is now an alias of the -2021 option. Also, the ASN1.Version compiler directive will now accept '2021' as an argument.
The ASN.1/Java Tools now supports the conversion of Java objects to CSV format.
New utility methods have been added to the com.oss.util.ByteTool class in
the SOED, lean and TOED runtimes:
public static String toTAP3BCD(byte[] tap3Bcd);
public static byte[] parseTAP3BCD(String tap3Bcd);
public static String toTBCD(byte[] tbcd);
public static byte[] parseTBCD(String tbcd);
These new methods enhance the ByteTool to support the TAP3 Binary-Coded
Decimal and Telephony Binary-Coded Decimal encodings.
A new sample has been created for the IEEE 1609.2 specification. This sample demonstrates how to construct, sign, and verify a signed Ieee1609Dot2Data using the java.security API.
A new sample has been created for release 16 of the UMTS RRC protocol:
Samples for releases 14, 15, and 16 of the LTE and 5G protocols have been updated to use the most recent versions of ASN.1 schemas available:
EfcCcc DEFINITIONS AUTOMATIC TAGS ::= BEGIN
IMPORTS LPN FROM EfcDsrcApplication
Get-Response FROM EfcDsrcGeneric;
CCC-DataRetrieval-Response::= Get-Response {BOOLEAN}
VehicleLicensePlateNumber ::= LPN (WITH COMPONENTS {..., licencePlateNumber(SIZE(14))})
END
EfcDsrcApplication DEFINITIONS AUTOMATIC TAGS ::= BEGIN
LPN::= SEQUENCE {
licencePlateNumber OCTET STRING
}
END
EfcDsrcGeneric DEFINITIONS AUTOMATIC TAGS ::= BEGIN
Get-Response{Container}::= SEQUENCE {
eid INTEGER,
iid Container OPTIONAL
}
ENDA {0 2 2} DEFINITIONS ::= BEGIN
i INTEGER ::= 3
END
B {0 2 3 0} DEFINITIONS ::= BEGIN
I ::= INTEGER
END
C DEFINITIONS ::= BEGIN
IMPORTS i FROM A {0 2 2}
I FROM B {0 2 A.i 0};
v I ::= 23
ENDThe OSS ASN.1 Tools for Java now includes ASN.1 Studio 10.1. For a summary of the improvements in ASN.1 Studio 10.1, see the Enhancements History section.
The Java compiler now accepts the [<selector>:]<prefix> syntax as an argument for the -prefix option, where selector can be one of "package", "class" or "var". See the following examples:
The new com.oss.util.BERTool class provides a Type-Length-Value (TLV) Print Utility application and a set of nested utility classes for parsing or printing BER/DER encoded data. The TLV Print Utility application is similar to the previously available "osstlv" native executable. To run the application use the following command:
java -jar <install dir>/bin/osstlv.jarwhere <install dir> is the directory where the OSS ASN.1 Tools for Java is installed.
Refer to the online API documentation for further information on the BERTool class and its nested classes (OSS TOED API, OSS SOED API).
New samples have been created for release 16 of the LTE and 5G protocols:
Samples for releases 14, 15, and 16 of the LTE and 5G protocols have been updated to use the most recent versions of ASN.1 schemas available:
The cam_denm sample has been updated to use the most recent version of the ASN.1 schema:
The OSS.NOENCODE and OSS.NODECODE compiler directives reduce the generated TOED code by excluding the encoding or decoding routines for the directive's operand. Under certain conditions, the generated code can be reduced even further using the new -compactNoDecode compiler option.
The -compactNoDecode compiler option instructs the compiler to generate a compact version of Time-Optimized Decoder code for fields marked by the NODECODE directive.
New samples for release 16 of LTE and 5G protocols have been created:
Samples for releases 13, 14, and 15 of LTE and 5G protocols have been updated to use the most recent versions of ASN.1 schemas available:
The API for UTF8String is now streamlined and made uniform across all available representations of this ASN.1 type. Also, support for supplementary Unicode characters, such as emoji symbols, is enhanced in all representations of UTF8String.
The SOED and TOED compilers now generate an identical set of constructors for all representations of the UTF8String ASN.1 type:
The SOED and TOED runtimes now define an identical set of getter and setter methods for all representations of the UTF8String ASN.1 type:
The confusing behavior of the API with an --<UNBOUNDED>-- representation of UTF8String is eliminated:
The --<BMPSTRING>-- representation is enhanced to support values that contain supplementary Unicode characters. Previously, when the value of a --<BMPSTRING>-- representation included a surrogate pair that represented a supplementary Unicode character, the encoding of such value was not supported.
The JIA_ValueReader class of the JIAAPI add-on is enhanced to support parsing of arbitrary values of open types. Previously, the JIA_ValueReader class was able to parse only open types that carried values of primitive built-in ASN.1 types, such as, INTEGER, BOOLEAN, OBJECT IDENTIFIER, etc.
Mod DEFINITIONS EXTENSIBILITY IMPLIED ::= BEGIN
Enum ::= ENUMERATED { a(1), b(2)}
END
Previously, due to type sharing of similar type definitions for Set and
SetExt, as well as for Choice and ChoiceExt, the implicit extensibility of
SetExt and ChoiceExt was lost:
Mod DEFINITIONS AUTOMATIC TAGS ::= BEGIN
Set ::= SET {a INTEGER, b BOOLEAN}
Choice ::= CHOICE {a INTEGER, b BOOLEAN}
END
ModExt DEFINITIONS AUTOMATIC TAGS EXTENSIBILITY IMPLIED ::= BEGIN
SetExt ::= SET {a INTEGER, b BOOLEAN}
ChoiceExt ::= CHOICE {a INTEGER, b BOOLEAN}
ENDValue ::= SEQUENCE {f1 INTEGER {one(1), two(2)}}
the compiler previously generated the following code:
public class Value extends Sequence {
. . .
public static class F1 extends INTEGER {
. . .
public static final class Value {
public static final long one = 1;
public static final long two = 2;
}
. . .B4468 DEFINITIONS ::= BEGIN
MACAlgorithms ALGORITHM ::= { ... }
MessageAuthenticationCodeAlgorithm ::= AlgorithmIdentifier {MAC-ALGORITHM, {MACAlgorithms}}
AlgorithmIdentifier {ALGORITHM-TYPE, ALGORITHM-TYPE:AlgorithmSet} ::=
SEQUENCE {
algorithm ALGORITHM-TYPE.&id({AlgorithmSet}),
parameters ALGORITHM-TYPE.&Params({AlgorithmSet}{@algorithm})
}
ALGORITHM ::= CLASS {
&id OBJECT IDENTIFIER UNIQUE,
&Params
}
MAC-ALGORITHM ::= CLASS {
&id OBJECT IDENTIFIER UNIQUE,
&Params,
&Other OPTIONAL
}
ENDPartial decoding for BER and DER:
The partial decoding feature is now available with BER, DER, PER, UPER, OER, and
COER.
Note that BER/DER support requires osstoed.jar version 8.1+.
New samples have been created for the following:
The ASN.1/Java TOED compiler no longer generates incorrect code in the validate() method when the constraint expression contains a union of inner subtype constraints. Previously, false validation errors occurred.
The ASN.1/Java SOED compiler no longer generates invalid type information when a type with component relation constraints is defined inline in an information object. This invalid type information caused a error in the constraint checker at run time.
The ASN.1/Java compiler now correctly compares BIT STRING type values with
named bits when one of the values is specified as {}.
Previously, the compiler incorrectly compared such values; consequently, a
false constraint violation could be reported or a real violation could be
missed. For example, a constraint violation was not reported for value y:
Test DEFINITIONS ::= BEGIN
EndEntityType ::= BIT STRING {app(0), enrol(1)} (SIZE (8))(ALL EXCEPT ''H)
y EndEntityType ::= {}
END
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
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 have been created for the following:
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)
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.
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.
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:
A new sample for release 14 of the UMTS RRC protocol has been created:
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();
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:
Samples for the following LTE protocols have been created:
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.
Support for the JSON encoding rules has been added to the SOED runtime.
Current limitations of the JSON SOED encoder/decoder:
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.
Validation of the following constraints has been implemented in the TOED:
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.
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.
The following new features have been added:
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.
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.
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:
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:
The following new features have been added:
The JSON Encoding Rules are currently available with the osstoed.jar runtime library and the -toed runtime option.
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.
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 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:
The following methods have been added to the com.oss.util.ASN1PrintWriter class:
The standards/tap3_bin2xml sample has been created. The sample demonstrates conversion of binary BER-encoded TAP3 records into XML (XER) format.
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.
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.
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.
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.
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, -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.
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.
This documentation applies to the OSS® ASN.1 Tools for Java release 8.7 and later.
Copyright © 2024 OSS Nokalva, Inc. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means electronic, mechanical, photocopying, recording or otherwise, without the prior permission of OSS Nokalva, Inc.
Every distributed copy of the OSS® ASN.1 Tools for Java is associated with a specific license and related unique license number. That license determines, among other things, what functions of the OSS ASN.1 Tools for Java are available to you.