The following compiler options are sorted alphabetically. For a list of options sorted by category, see ASN.1/Java Compiler Options.
Specifies the version of the standard used in the input ASN.1 specification files.
The -1990 option indicates that the ASN.1 specification should contain only syntax that conforms to the 1990 standard. The compiler provides support for the 1990 version of ASN.1, which includes the following:
The compiler flags any syntax that follows a standard newer than 1990.
The -2021 option indicates that the ASN.1 specification should contain only syntax that conforms to a more modern ASN.1 standard than 1990. The compiler provides support for the 2021 version of ASN.1, which includes the addition of WITH SUCCESSORS and WITH DESCENDANTS to the imports clause. The previous 2015 version of ASN.1 is also supported, which includes the following:
By default, before detecting a particular type of notation, the compiler uses neutral mode. After the compiler detects notation particular to ASN.1:1990 or ASN.1:2021, it switches out of neutral mode and enforces conformance to that standard. One disadvantage of using neutral mode is that often, when creating new ASN.1 specifications, the debugging cycle may take longer than usual to complete.
You can use both versions of the ASN.1 standard for the same specification; however, this behavior is not allowed by the X.680 (2021) ISO/IEC 8824-1:2021 standard, and therefore the compiler will generate warnings.
When using ASN.1:2021 syntax, the compiler issues warnings or errors if:
The -1993, -1994, -1997, -2002, -2008, and -2015 compiler options are equivalents of the -2021 option.
Enables the compiler to retain a previous behavior specified by an argument. Use this option sparingly, only when it is absolutely necessary for a specific task.
The option takes a single argument. If you use multiple compatibility options, it can be specified more than once.
asn1pjav foo.asn -allow BadValues -allow MixedCaseForSomeBuiltInTypesNames
Instructs the compiler to accept mixed case names for certain ASN.1 built-in types, if types with such names are not already defined in the ASN.1 input. The -allow MixedCaseForSomeBuiltInTypesNames is enabled by the default -relaxedMode option.
The following built-in types currently support mixed-case names:
M DEFINITIONS ::= BEGIN Type ::= IA5STRING value Type ::= "abc" END
If -allow MixedCaseForSomeBuiltInTypesNames is not specified, the compiler reports the following errors:
"test.asn", line 3 (M): A0256W: 'IA5STRING' is referenced, but is not defined. "test.asn", line 3 (M): A0052E: 'IA5STRING' is not defined. "test.asn", line 3 (M): A1277W: 'IA5STRING' is assumed to be a misspelling of the built-in type 'IA5String'.
The compiler assumes that the IA5STRING is the IA5String built-in type .
When a named bit is larger than the size of a BIT STRING, the compiler issues an error and stops. This flag instructs the compiler to issue a warning instead.
Instructs the ASN.1 compiler to accept ASN.1 names that contain the underscore character ("_") after the initial character. The -allow UnderscoresInAsn1Names option is enabled by the default -relaxedMode option.
M DEFINITIONS ::= BEGIN Some_Type ::=INTEGER END
Instructs the ASN.1 compiler to not report a type-value mismatch when the type of the referenced value differs from the required type only by the position of the extension marker within the fields of a SET, SEQUENCE, or CHOICE type.
We stand with Ukraine
M DEFINITIONS ::= BEGIN
Choice1 ::= [0] CHOICE
{
f1 INTEGER,
f2 REAL,
f3 BOOLEAN
}
Choice2 ::= [1] CHOICE
{
f1 INTEGER,
f2 REAL,
... ,
f3 BOOLEAN
}
choice1 Choice1 ::= f3:FALSE
choice21 Choice2 ::= choice1
END
Instructs the ASN.1 compiler to not report a type-value mismatch when the type of the referenced value differs from the required type only by the tags of the fields of a SET, SEQUENCE, or CHOICE type, including automatic tags.
M DEFINITIONS ::= BEGIN
Choice1 ::= [0] CHOICE
{
f1 [0] INTEGER,
f2 [1] REAL,
f3 [2] BOOLEAN
}
Choice2 ::= [1] CHOICE
{
f1 [2] INTEGER,
f2 [1] REAL,
f3 [0] BOOLEAN
}
choice1 Choice1 ::= f3:FALSE
choice21 Choice2 ::= choice1
END
Instructs the ASN.1/Java compiler to continue the current compilation if a content error occurs in the value notation of restricted character strings (for example, NumericString, PrintableString, and VisibleString), OBJECT IDENTIFIER types.
The following value notation causes the ASN.1 compiler to exit with an error message:
myPhoneNumber NumericString ::= "(800) 555-1212 EXT-6"
myObjectID OBJECT IDENTIFIER ::= {0 26}
According to the ASN.1 standard, the NumericString type allows numbers 0 through 9 and whitespace. However, the OBJECT IDENTIFIER type does not allow a value greater than 39 for its second node.
When the -allow BadValues option is specified, the compiler does not truncate the values of the following types:
To instruct the ASN.1 compiler to treat errors as warnings, use the -ignoreError compiler option.
If a type-value mismatch is present in value assignments of ENUMERATED, SET, SEQUENCE, or CHOICE types, the -allow BadValues option also instructs the ASN.1 compiler to issue the A1007W warning message instead of the A1006E error message.
For ENUMERATED types, the option allows names from one ENUMERATED type to be used in the value of a different ENUMERATED type, as shown in the following example:
Enum1 ::= ENUMERATED {blue(0), red(1)}
Enum2 ::= ENUMERATED {green(3)}
var Enum1 ::= green
For SET, SEQUENCE, and CHOICE types, the option allows a difference in the tags of the fields and in the position of the extension marker.
By default,the -allow BadValues option is disabled.
Instructs the ASN.1 compiler to process type and value assignments found outside input modules.
If the -assignments option is specified, the behavior of the ASN.1 compiler for the following ASN.1 specification:
I ::= INTEGER
B ::= BOOLEAN
is the same as for the specification:
NoModuleName DEFINITIONS AUTOMATIC TAGS ::=
BEGIN
I ::= INTEGER
B ::= BOOLEAN
END
Allows open types to be automatically encoded/decoded even when runtime constraint checking is disabled, which results in a faster and more efficient use of system resources.
Open types can be regarded as messages within messages. They are decoded by decoding the outer message in one pass, then decoding the inner message in a second pass. Encoding is the opposite, first encoding the inner message in one pass, then encoding the outer message in a second pass.
Open types are usually defined as component relation constraints. Difficulty arises when constraint checking is disabled because component relation constraint checking is disabled as well, and so is automatic decoding and encoding. To enable automatic encoding/decoding, use the enableAutomaticEncoding() method.
When you use the -constraints option (runtime constraint checking is enabled) -autoEncDec has no effect on runtime performance.
Use the -noAutoEncDec option to save runtime space. However, by omitting code used by the automatic encoding/decoding feature, -noAutoEncDec overrides the runtime enabling of automatic encoding/decoding. In this case, since enableAutomaticEncoding() would have no effect, the application must be prepared to manually encode and decode open types.
Instructs the compiler to generate additional Java code that implements parsing of ASN.1 value notation data into Java objects that represent values defined by value notation.
The -avn option is disabled.
The -avn option requires the -toed option.
Specifies the encoding rules available at runtime:
When you specify the -json, -xer, -cxer, or -exer option, -debug is also enabled. Also, the header file is identical to the one that is generated without these options.
These options have the following precedence: (1) -ber, (2) -per, (3) -cper, (4) -der, (5) -uper, (6) -cuper, (7) -xer, (8) -cxer, (9) -cer, (10) -exer, (11) -oer, (12) -coer, (13) -json. For example, if you specify -der -per -xer, the PER encoding rules are used by default, but you can switch to DER and XER at runtime.
The specific encoding rules available at runtime when one of these command-line options is specified vary according to the encoder/decoder library in use. This is summarized in the following table:
| -ber | -per | -der | -json | -uper | -xer | -cxer | -cer | -exer | -oer | -coer | -cper | -cuper | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SOED | BER | PER UPER |
DER BER |
JSON | UPER PER |
XER | XER CXER |
CER BER |
E-XER | OER | COER OER |
CPER CUPER PER UPER |
CUPER CPER UPER PER |
| TOED | BER | PER | DER BER |
JSON | UPER | XER | CXER | N/A | E-XER | OER | COER | CPER | CUPER | LED | BER | PER UPER |
DER BER |
JSON | UPER PER |
XER | XER CXER |
N/A | E-XER | OER | OER COER |
CPER CUPER PER UPER |
CUPER CPER UPER PER |
To use multiple sets of encoding rules, add one of the following lines of code to create another Coder object:
BERCoder berCoder = getBERCoder(); CERCoder cerCoder = getCERCoder(); COERCoder coerCoder = getCOERCoder(); CXERCoder cxerCoder = getCXERCoder(); DERCoder derCoder = getDERCoder(); EXERCoder exerCoder = getEXERCoder(); JSONCoder jsonCoder = getJSONCoder(); OERCoder oerCoder = getOERCoder(); PERAlignedCoder perCoder = getPERAlignedCoder(); PERUnalignedCoder uperCoder = getPERUnalignedCoder(); CPERAlignedCoder cperCoder = getCPERAlignedCoder(); CPERUnalignedCoder cuperCoder = getCPERUnalignedCoder(); XERCoder xerCoder = getXERCoder();
The JSON encoding rules are supported in the SOED runtime in version 7.0 and later.
Instructs the ASN.1 compiler to take files and options from File as if they were found at the command line. This option is useful when you have many input files or options specified.
To compile input.asn using the command-line options included in the tenLinesOfOptions.opt text file, issue the following command:
asn1pjav input.asn -commandFile tenLinesOfOptions.opt
Command files may contain comments. The characters "--" specify the beginning of a comment. They can be placed anywhere on the line. The comment continues until a subsequent "--" is reached or until the line ends.
Instructs the compiler to generate a compact version of Time-Optimized Decoder code for fields marked with the OSS.NODECODE directive. Note that when a field marked with the OSS.NODECODE directive is present in the input encoding, an error is reported if the compact version of the decoder is used. However, the error is not reported for open type fields and extension additions because the decoder easily skips these fields.
The -compactNoDecode option is disabled.
The -compactNoDecode option cannot be used with the -soed option and imposes the following restriction when using the OSS.NODECODE directive: the directive must be applied either to all fields of an extension group or to none of the fields of an extension group.
Instructs the compiler to generate files compatible with previous versions of the OSS ASN.1 compiler.
NOTE: OSS does not guarantee compatibility between different versions of the ASN.1 Tools released more than 10 years apart.
This option takes a single operand or flag, and can be specified more than once. For example:
asn1 foo.asn -compat JavaSharing -compat oldinnerclassreference
For more information about arguments that can be specified with the -compat option, see Backward Compatibility.
The -constraints option instructs the compiler to generate information in the Java files for runtime constraint checking.
The -noConstraints option disables generation of information in the Java files for runtime constraint checking. The size of the generated code is smaller and can be executed faster.
If the -constraints option is specified or implied, you can disable runtime constraint checking by calling the disableEncoderConstraints()method.
Enables access to the API that implements the conversion of Java objects to CSV format.
When the -csv option is specified, the compiler adds an extra getCSVTool() method to the generated ASN1Project class. This method provides access to the CSVTool utility, which can convert Java objects to CSV format.
When the following ASN.1 syntax in baseball.asn is compiled with the -csv option:
BBCard ::= SEQUENCE {
name IA5String (SIZE (1..60)),
team IA5String (SIZE (1..60)),
age INTEGER (1..100),
position IA5String (SIZE (1..60)),
handedness ENUMERATED
{left-handed(0), right-handed(1), ambidextrous(2)},
batting-average REAL
}
this ASN1Project class is generated:
public class Baseball extends ASN1Project {
...
public static CSVTool getCSVTool()
{
return createCSVTool(c_project);
}
}
The -csv command line option is ignored when it is specified along with the -lean or -toed command line options. A warning message is issued stating that -csv is not compatible with -lean or -toed.
Enables or suppresses generation of debugging information.
When the -debug option is specified, run-time diagnostic messages are more legible (note that there is an impact on size).
When the -noDebug option is specified, you can preserve run-time memory size by limiting the information on run-time diagnostic messages (note tha there is an impact on legibility).
When the -xer, -cxer, or -exer option is specified, -noDebug is ignored.
The -decodeOnly | -encodeOnly option is reserved for future use with the -toed option and currently has no effect.
Instructs the ASN.1 compiler to generate additional warning messages for protocol designers writing ASN.1 specifications. By default, no additional warnings are issued.
Additional warning messages are issued if:
MYCLASS ::= CLASS {
&data INTEGER OPTIONAL,
&Type
} WITH SYNTAX { &data &Type }
the following warning message is issued:
A0587W: A Setting for OPTIONAL field ' &data' is defined not inside an OptionalGroup in the DefinedSyntax.
Generates multiple Data Type Definitions (DTD) files, one for each PDU.
By default, the .dtd file is generated in the directory of the corresponding ASN.1 module package and it is called ClassName.dtd. For the baseball example, the generated DTD is located in the baseball/bcas directory and it is called BBCard.dtd .
The -dtd option (and the OSS.DTD directive) is available only for the XER Encoding Rules. Also, -dtd has no effect when the -noOutput or -syntaxOnly option is used.
Instructs the ASN.1 compiler to enable partial decoding, in addition to standard decoding. Encoding is not affected.
Partial decoding is only supported by the TOED runtime. That is, -enablePartialDecode cannot be used together with the -soed option.
The -enablePartialDecode option is supported by the BER, DER, PER, UPER, CPER, CUPER, OER, and COER encoding rules.
By default, the -enablePartialDecode option is disabled.
Instructs the compiler to redirect all ASN.1 compiler messages to an error file. This is useful on platforms where you cannot redirect stdout and stderr to a file.
If an error is detected at the command line before you specify the -errorFile option, the message is written to stdout. To write all command-line error messages to the error file, specify first the -errorFile option.
asn1pjav -err myerrs.err foo.asn
When errorFileName does not have an extension, it receives the .err extension (or "e" on the Tandem NonStop OS). When it has the .asn extension, it is replaced by .err; otherwise, the errorFileName keeps the extension specified by you.
When the compiler is invoked again, existing error files with the same name are overwritten.
Instructs the ASN.1 compiler to generate a .gen file that captures all directives from the ASN.1 input file as well as directives for names produced by the compiler (_setof1, for example).
The optional operand genDirFileName specifies the name of the .gen file. If the file name is not specified, the ASN.1 compiler generates one from the last ASN.1 input file specified at the command line and replaces .asn with .gen.
By default, the -genDirectives option is disabled.
Displays a summary of all valid command-line options.
By entering asn1pjav -help you can obtain a summary of valid command-line options:
OSS ASN.1 Compiler for Java Version 8.7
Copyright (C) 2023 OSS Nokalva, Inc. All rights reserved.
Compiler parameters: (.D. indicates default)
<input> <...input> . one or more ASN.1 input files
-1990 ... all modules conform to 1990 ASN.1 syntax
-2021 .D. all modules conform to 2021 ASN.1 syntax
-allow badcase ... enable badcases for backward compatibility
-allowbadvalues ... allow generation of bad values
-assignments ... process type and value assignments defined outside
ASN.1 modules
-autoencdec .D. generate metadata for automatic decoding of open types
-avn ... generate output for ASN.1 value notation parser
-ber .D. generate output file for BER encoder/decoder
-cer ... generate output file for BER & CER encoder/decoder
-coer ... generate output file for Canonical OER encoder/decoder
-commandfile <file> ... read command line from 'file'
-compactNoDecode
... generate compact time-optimized decoder for fields
marked by NODECODE directive
-compat feature ... disable new features for backward compatibility
-constraints .D. check constraints at runtime
-cper ... generate output file for Canonical Aligned PER encoder/decoder
-csv ... generate output for CSV printer
-cuper ... generate output file for Canonical Unaligned PER encoder/decoder
-cxer ... generate output file for Canonical XER encoder/decoder
-debug [0..2] .D. issue detailed trace data and error messages. When
used together with -toed, the numeric argument
specifies the debug level.
-decodeonly ... generate only decoder methods
-der ... generate output file for BER & DER encoder/decoder
-designerWarnings .. issue additional warnings for protocol designers
-dtd ... generate document type definition file for each PDU
-enablePartialDecode
... generate time-optimized full and partial decoders
-encodeonly ... generate only encoder methods
-errorfile file ... write all messages to 'file' instead of stdout/stderr
-exer ... generate output file for EXTENDED XER encoder/decoder
-gendir <genfile>... generate list of directives into <genfile>
-helperAPI ... generate specific helper API's selected via a keyword:
'opentype' - helper API's for constrained opentypes
'pdudecoder' - helper API's for PDU decoding
-ignoreError msg# .. ignore a specific error (issue a warning instead)
-ignoreIncompleteItems
... ignore incomplete ASN.1 definitions of types and values
-ignoreRedefinedAssignments
... ignore redefined ASN.1 definitions of types and values
-ignoresuppress ... ignore the SUPPRESS directive (display all messages)
-indexinfoobjectsets ... generate extra methods to index information
object sets for faster automatic decoding
-informatory ... allow informatory messages
-javamodule name ... generate the JPMS module
-jer ... alias to -json
-jiaapi ... generate JIAAPI support classes
-json ... generate output file for JSON encoder/decoder
-keepnames ... generate directives for keeping names
-lean ... generate reduced typeinfo for JLED encoder/decoder
-limitbigenums num# ... helps to avoid 64K limit for big enums
-limitcons num# ... limits number of arguments in a constructor
-limitmethodsize lines# ... split generated methods to avoid 64K
method size limit
-list <listfile> ... generate an ASN.1 combined listing into 'listfile'
-messageFormat <format>
... display error messages in <format>:
'oss', 'emacs' or 'msvc'
-mod <listfile> ... generate single ASN.1 module listings into 'listfile'
-noautoencdec ... do not generate metadata for automatic decoding of
open types
-noconstraints ... do not check constraints at runtime
-nodebug ... do not issue detailed trace data and error messages
to slightly improve CPU performance
-noHelperAPI ... do not generate specific helper API's selected via a keyword:
'opentype' - helper API's for constrained opentypes
'pdudecoder' - helper API's for PDU decoding
-noinformatory ... suppress informatory messages
-nolist .D. do not generate an ASN.1 combined listing
-nomod .D. do not generate single ASN.1 module listings
-nooutput ... do not generate output files, same as syntaxonly.
-noparamtypesuperclass .D. do not create a class for shareable parameterized
types
-nopdusforopen ... do not generate PDUs for info objects with -noconstraints
-nopedantic .D. rigorously check only the root module(s)
-norelaxedMode ... automatically select command-line options that
result in strict compiler behavior
-norelaySafe .D. do not retain unrecognized extension additions at runtime
-notest .D. do not test encoding/decoding of all ASN.1 values
-nouniquepdu ... do not check that pdu id's are unique
-nouserconstraintpdus .D. do not generate Java classes for types specified in user constraints
-nouserconstraints D do not check user constraints (even for -constraint)
-novaluerefs ... do not generate Java values for all valuereferences
-noverbose .D. do not display compilation progress messages
-nowarning ... suppress warning messages
-oer ... generate output file for OER encoder/decoder
-output name ... use name for ASN.1/Java package
-paramtypesuperclass ... create a class for shareable parameterized types
-partialDecodeOnly
... generate time-optimized partial decoder only
-path path ... generate package at specified location
-pdusforopentypes... ignore NOPDU directive for opentypes
-pedantic ... rigorously check all modules
-per ... generate output file for Aligned PER encoder/decoder
-prefix id ... prefix variables with unique id
-relaxedMode .D. automatically select command-line options that
result in relaxed compiler behavior, for example,
-allowBadValue, -noWarning, etc.
-relaySafe ... retain unrecognized extension additions at runtime
-reservedWords <reserved_words>
... treat words specified in the parameter and separated
by commas as reserved words in the generated files
that should be always mangled
-root ... treat all modules as root modules
-sampleCode <pdus|values>
... generate a sample code to initialize, encode, decode
and traverse values of PDU types defined in the input
ASN.1 syntax
-soed ... generate Java code compatible with SOED runtime
-splitbigenums num# ... helps to avoid 64K limit for big enums
-splitsamplecode <depth#> ... split sample value creation methods
to avoid 64K method size limit
-splittypeinfo num# ... set limit for the number of fields in SET/SEQ/CHOICE
to split static initializers of typeinfo avoid 64K
method size limit
-splitvalues ... split static value initializers into methods to avoid
64K method size limit
-suppress msg# ... suppress a specific message
-syntax ... perform syntax checking only
-test ... generate a program to encode/decode ASN.1 values
-toed .D. generate Java code compatible with TOED runtime
-uniquepdu .D. check that pdu id's are unique
-uper ... generate output file for Unaligned PER encoder/decoder
-userconstraintpdus ... generate Java classes for types specified in user constraints
-userconstraints ... check user constraints (even for -noconstraints)
-valuerefs .D. generate Java values for all valuereferences
-verbose ... display compilation progress messages
-warning ... allow warning messages
-xer ... generate output file for Basic XER encoder/decoder
-xsl ... generate default stylesheet for each PDU
You can obtain a synopsis of the command-line syntax by entering asn1pjav with no arguments:
OSS ASN.1 Compiler for Java Version 8.7 Copyright (C) 2023 OSS Nokalva, Inc. All rights reserved. asn1pjav <infile(s)> [-suppress msg#] [-verbose | -noverbose] [-ber] [-allowbadvalues ] [-warning | -nowarning] [-der] [-errorfile file ] [-soed | -lean | -toed] [-json] [-ignoresuppress ] [-ignoreIncompleteItems] [-per] [-uper] [-paramtypesuperclass |-noparamtypesuperclass] [-xer] [-cxer] [-commandfile file] [-mod <listfile> | -nom] [-cer] [-exer] [-assignments ] [-list <listfile> | -nol] [-dtd] [-xsl ] [-allow badcase ] [-messageFormat <format>] [-oer] [-coer] [-javamodule name ] [-output name | -nooutput] [-cper][-cuper] [-test | -notest] [-pedantic | -nopedantic] [-root] [-compat feature ] [-uniquepdu | -nouniquepdu] [-syntax] [-designerWarnings] [-relaySafe | -norelaySafe] [-keepnames] [-gendir <genfile>] [-splitsamplecode <depth#>] [-path path] [-splittypeinfo n#] [-limitmethodsize <lines#>] [-prefix id] [-splitbigenums #n] [-autoencdec | -noautoencdec] [-splitvalues] [-limitbigenums #n] [-informatory | -noinformatory] [-limitcons n#] [-ignoreError msg#] [-constraints | -noconstraints] [-jiaapi][-csv] [-debug | -nodebug] [-valuerefs | -novaluerefs] [-1990 | -2021] [-pdusforopentypes] [-relaxedMode | -norelaxedMode] [-ignoreRedefinedAssignments ] [-sampleCode | -noSampleCode ] [-userconstraints | -nouserconstraints] [-reservedWords <reservd_words>] [-helperAPI <api> | -noHelperAPI <api>] [-indexinfoobjectsets] [-userconstraintpdus | -nouserconstraintpdus] [-enablePartialDecode] [-partialDecodeOnly] [-compactNoDecode] [-avn] enter "asn1pjav -help" for more information
Command-line help is not displayed when input files are specified.
Enables or disables the generation of optional helper APIs. A parameter is required that can be a single keyword or a comma-separated list of keywords. Using a list of keywords is the same as specifying multiple single-keyword options. The keywords are not case-sensitive and can be specified in any order. The keywords specify the types 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.
If the -helperAPI opentype command-line option is specified and an open type field is constrained by a component relation constraint, the compiler will generate an extra class that represents the field's type. The extra class provides an application developer with methods that simplify handling of the constrained open type values.
The -helperAPI pdudecoder option instructs the compiler to generate optimal PDU and PDU_ID classes that are used to auto-detect and decode PDUs from bits on the wire when the PDU's type is not known ahead of time.
PDU auto-detection is available only for the encoding rules that use "tags" to identify an encoded value's type. Currently the option works with BER, DER, CER, XER, CXER, E-XER, and JSON/ER. PDU auto-detection is not available for PER, UPER, OER, or COER.
The PDU and PDU_ID classes are inner classes of an ASN.1/Java project class.
The -helperAPI <param> and -noHelperAPI <param> options are available in version 7.0 and later.
Instructs the ASN.1 compiler to treat certain errors as warnings.
You can use -ignoreError option to generate a code file without correcting your ASN.1 specification. Note that the values generated in the code file are not valid according to the ASN.1 standard.
The following message numbers can be ignored: 49, 76, 77, 305, 319, 811, 1078, 1130, 1162, 1207 and 1211.
By default, all compiler error messages are generated.
Instructs the ASN.1 compiler to treat certain errors related to undefined ASN.1 types and values as warnings, and to ignore incomplete ASN.1 definitions that directly or indirectly reference undefined ASN.1 types and values.
You can use the -ignoreIncompleteItems option to generate Java classes without correcting your ASN.1 specification, when undefined and incomplete ASN.1 items are not used by the application.
To see which incomplete items were ignored by the compiler, use the -verbose option.
In the following example, A references type B, which is not defined:
M DEFINITIONS ::= BEGIN
A ::= SEQUENCE {
a1 A1,
a2 A2,
b B1
}
A1 ::= INTEGER
A2 ::= BOOLEAN
B ::= REAL
END
Without -ignoreIncompleteItems, the following messages are issued:
"test.asn", line 7 (M): A0256W: 'B1' is referenced, but is not defined. "test.asn", line 7 (M): A0052E: 'B1' is not defined. C0043I: 1 error message, 1 warning message and 0 informatory messages issued.
With -ignoreIncompleteItems and -verbose, the following messages are issued:
"test.asn", line 7 (M): A0256W: 'B1' is referenced, but is not defined. "test.asn", line 4 (M): C1215W: The definition of the type identified by the absolute reference 'M.A' is incomplete and will be ignored. C0285I: Global checking abstract syntax. C0504I: Generating JAVA files. C0043I: 0 error messages, 2 warning messages and 5 informatory messages issued.
The compiler generates the .java files only for complete ASN.1 types:
a/m/M.java a/m/A1.java a/m/A2.java a/m/B.java
By default, the -ignoreIncompleteItems option is disabled.
Instructs the ASN.1 compiler to ignore all duplicate definitions within the same ASN.1 module, and to issue warnings instead of errors.
The -relaxedMode option implies the -ignoreRedefinedAssignments option.
The type reference Type is defined twice within the same ASN.1 module:
M DEFINITIONS ::= BEGIN Type ::= INTEGER Type ::= INTEGER END
Without -ignoreRedefinedAssignments, the following messages are issued:
"test.asn", line 5 (M): A0146E: Type 'Type' is illegally redefined.
Type ::= INTEGER
^
C0043I: 1 error message, 0 warning messages and 0 informatory messages issued.
With -ignoreRedefinedAssignments, the following messages are issued:
"test.asn", line 5 (M): A1270W: 'Type' has already been defined on line 3. Its redefinition is being ignored. C0043I: 0 error messages, 1 warning message and 0 informatory messages issued.
Instructs the compiler to ignore the OSS.SUPPRESS directive in an ASN.1 module definition.
By default, all messages identified by the OSS.SUPPRESS directive are suppressed.
Allows you to control which algorithm is used to implement the lookup of information object sets. Information object sets are used during automatic decoding of open types.
The -indexInfoObjectSets option instructs the compiler to generate additional methods in every Java class. The methods represent the information object sets of a particular information object class.
By default, -indexInfoObjectSets is not invoked and a linear search of an information object in an information object set takes place each time an open type defined with a component relation constraint is automatically decoded.
MyModule DEFINITIONS ::= BEGIN
MY-CLASS ::= CLASS {
&id ProcedureID UNIQUE,
&Type
}
MyInfoObjectSet MY-CLASS ::= {
{&id 1, &Type INTEGER} |
{&id 2, &Type UTF8String}
}
END
The following asn1pjav command-line is used: asn1pjav index myprotocol.asn.
Here is the generated code:
public class MY_CLASS_OSET extends IndexedInfoObjectSet {
...
// Methods to index the information object set
public static IndexProcedure getIndexProcedure();
public static void setIndexProcedure(IndexProcedure procedure);
public boolean indexById(Index index);
public boolean indexByType(Index index); }
Note that the generated class inherits from the IndexedInfoObjectSet class (to provide a more compact and readable view, the bodies of the methods listed above are not shown). The class is an extension of the InfoObjectSet class and includes additional code to support indexing.
The first two methods generated above are defined to facilitate automatic indexing of information object sets of this class:
public static IndexProcedure getIndexProcedure(); public static void setIndexProcedure(IndexProcedure procedure);
To activate automatic indexing, create (and instantiate) a class that implements the IndexProcedure interface and pass the instance of this class to setIndexProcedure(). After setIndexProcedure() is called, your IndexProcedure is applied to every information object set of the MY_CLASS_OSET class as soon as it is instantiated:
MY_CLASS_OSET oSet = new MY_CLASS_OSET(new MY_CLASS[] {...}, ...);
You can use the methods generated in this example to index individual information object sets at any moment after they are created:
public boolean indexById(Index index); public boolean indexByType(Index index);
To index an individual information object set, create the class that implements the Index interface and pass the instance of this class into the indexByXXX() method. The method returns boolean to indicate if the method has successfully indexed the information object set.
If, for example, the information object set contains two information objects with duplicate values of the index column, and you have implemented the Index interface to not support duplicate values in the index column, indexing may fail.
When you use the -indexInfoObjectSets compiler option, no additional work in your application is required. Linear searching takes place for each information object set. However, we recommend that you use the -indexInfoObjectSets compiler option with the Index or DefaultIndex interface.
Informs the compiler whether it should generate informatory messages.
The -noInformatoryMessages option is implied when the default -relaxedMode or the -noWarningMessages option is specified.
When -noRelaxedMode or -warningMessages is specified, the -informatoryMessages option is implied.
NOTE: The order in which -informatoryMessages | -noInformatoryMessages, -warningMessages | -noWarningMessages, and -relaxedMode | -noRelaxedMode appear on the command line is important. The rightmost option takes precedence.
Instructs the compiler to generate a Java 9 module.
The moduleName optional parameter specifies the name of the Java 9 module inserted in the module declaration that is generated in the module-info.java file. When moduleName is not used, the name of the output package (-output) is considered the module name.
MyProtocol DEFINITIONS ::= BEGIN
protocolID OBJECT IDENTIFIER ::= {iso standard 1 22 333}
bufferSize INTEGER ::= 1024
Data ::= SEQUENCE {
name PrintableString,
id INTEGER,
married BOOLEAN
}
END
By default, the ASN.1 compiler does not create a Java 9 module.
When the compiler is invoked using the asn1pjav -path src example.asn command, the following .java files are generated:
src/example/ // the project package src/example/Example.java // the project class src/example/myprotocol/ // a package for 'myprotocol' ASN.1 module src/example/myprotocol/MyProtocol.java // a class for 'myprotocol' ASN.1 module src/example/myprotocol/Data.java // an ASN.1 typereference class
When invoked using the asn1pjav -path src -javamodule com.acme.example example.asn command, the ASN.1 compiler for Java generates the following output .java files:
src/com.acme.example/example/ // the project package src/com.acme.example/example/Example.java // the project class src/com.acme.example/example/myprotocol/ // a package for 'myprotocol' ASN.1 module src/com.acme.example/example/myprotocol/MyProtocol.java // a class for 'myprotocol' ASN.1 module src/com.acme.example/example/myprotocol/Data.java // an ASN.1 typereference class src/com.acme.example/module-info.java // Java 9 module declaration
The module-info.java file contains the following statements:
module com.acme.example {
exports example;
exports example.myprotocol;
requires transitive com.oss.soed;
}
The module-info.java file defines the Java 9 module, com.acme.example, and specifies that all generated Java packages are visible to other Java modules and that the generated code requires the OSS Java SOED runtime library.
Using the Java 9 javac compiler, you can compile a Java module without explicitly specifying individual .java files. So, the example.bat/.sh helper script is not generated in src/com.acme.example/example/ when you specify the -javaModule option because it is no longer needed. You can compile the generated Java classes using the following command:
javac -d build -p build:"$OSS_ASN1_JAVA"/mlib --module-source-path src -m com.acme.example (UNIX) or javac -d build -p build;"%OSS_ASN1_JAVA%"/mlib --module-source-path src -m com.acme.example (Windows)
The OSS_ASN1_JAVA environment variable points to the directory where the OSS ASN.1 Tools for Java is installed.
The Java Interpretive ASN.1 API (JIAAPI) is a collection of Java classes included with the ASN.1 Tools for Java. The Java IAAPI provides access to ASN.1 types, subtypes and value notations through an easy-to-use interface. This allows applications to create and encode data using ASN.1 without any knowledge of the data structure (for example, the number of components and their types). It also allows messages (PDUs) to be decoded, and the components of the messages to be accessed based on their data types.
When the -jiaapi option is specified, the compiler generates the following additional classes:
The -jiaapi option is helpful when using the JIAAPI; however, it is optional. You can also construct your own classes to extend the JIA Project class.
The following ASN.1 syntax file, tst.asn is compiled with the -jiaapi option:
ModA DEFINITIONS ::= BEGIN
A ::= INTEGER
a A ::= 1234
END
ModB DEFINITIONS ::= BEGIN
B ::= SEQUENCE { a ModA.A }
b B ::= { a ModA.a }
END
The following JIA project class, JIATst, is generated:
public class JIATst {
private static JIA_Project jia_project = new JIA_Project (
new JIA_DefinedTypes(
new JIA_DefinedType[] {
new JIA_DefinedType("B", "tst.modb.B")
}
),
new JIA_Modules(
new JIA_Module[] {
tst.moda.JIAModA.jia_module,
tst.modb.JIAModB.jia_module
}
)
);
}
Two JIA module classes, JIAModA and JIAModB, are also generated:
public class JIAModA {
public static JIA_Module jia_module = new JIA_Module(
"ModA",
JIA_Module.MODE_TAGGING_EXPLICIT,
false,
new JIA_DefinedTypes(
new JIA_DefinedType[] {
new JIA_DefinedType("A", "jiaapi.moda.A")
}
),
new JIA_ValueReferences(
new JIA_ValueReference[] {
new JIA_ValueReference("a", ModA.a)
}
)
);
}
public class JIAModB {
public static JIA_Module jia_module = new JIA_Module(
"ModB",
JIA_Module.MODE_TAGGING_EXPLICIT,
false,
new JIA_DefinedTypes(
new JIA_DefinedType[] {
new JIA_DefinedType("B", "jiaapi.modb.B")
}
),
new JIA_ValueReferences(
new JIA_ValueReference[] {
new JIA_ValueReference("b", ModB.b)
}
)
);
}
The -jiaapi command line option is ignored when it is specified along with the -lean command line option. A warning message is issued stating that -jiaapi is not compatible with -lean.
Generates a .gen file that contains directives which isolate the generated files when the input changes.
The -keepNames option is disabled.
The ASN.1 compiler can generate different names for a given type each time the ASN.1 file is compiled, which requires further changes in your code. To avoid this, use the -keepNames option. When the ASN.1 file needs to be recompiled, the .gen file is considered as the first input file at the command line, with the files and command-line options previously specified. Even when the input contains changes, the compiler generates the same names.
| Initial ASN.1 input | Modified input |
|---|---|
Rec ::= SEQUENCE {name Name, age Age}
|
Rec ::= SEQUENCE {name Name, ageAtMarriage Age}}
|
The -keepNames option insulates your program from the element-order change.
When the -keepNames option is specified, and -genDirectives is not specified, the compiler treats the input as if the -genDirectives option without the optional -genDirFilename parameter was specified. In this case, the compiler creates the .gen file with a name obtained by changing the suffix of the last file on the command line to .gen. The .gen file includes all directives from the ASN.1 input stream and directives for each name that can change in a subsequent run of the ASN.1 compiler for Java.
| ASN.1 input | Generated code (with -keepNames) |
|---|---|
Module DEFINITIONS ::= BEGIN
Type ::= INTEGER {one(1), two(2), five(5)}
S ::= SEQUENCE {
flagColor ENUMERATED {red, white, blue}
}
END
|
Directives artificially generated for the names to be kept: --<OSS.TYPENAME Module.Type "Type">-- --<ASN1.Nickname Module.Type.one one>-- --<ASN1.Nickname Module.Type.two two>-- --<ASN1.Nickname Module.Type.five five>-- --<OSS.TYPENAME Module.S "S">-- --<ASN1.Nickname Module.S.flagColor.red red>-- --<ASN1.Nickname Module.S.flagColor.white white>-- --<ASN1.Nickname Module.S.flagColor.blue blue>-- |
Instructs the ASN.1 compiler to generate Java files compatible with the Lean Encoder/Decoder (LED).
When the -lean option is specified, the compiler prints condensed type information (metadata), which saves JVM memory space. This is useful when an application does not require the full function provided by the standard runtime. Condensed metadata means omitting the following:
Further space optimization is available by using the lean runtime in the osslean.jar file.
When -lean is specified, the OSS ASN.1 Java compiler issues warning messages if the input ASN.1 specification contains types or directives that are not supported by the lean runtime. The following types are not supported: REAL, EMBEDDED PDV, EXTERNAL, CHARACTER STRING, and UniversalString.
If the UNBOUNDED and UNIVERSALSTRING directives are used with the UTF8String type, the compiler issues warning messages because the only representation for the UTF8String type is BMPSTRING.
The generated Java classes can be used with either the full or the lean runtime libraries. It is not mandatory to use the osslean.jar file at runtime when the -lean option is specified.
The -lean option is disabled.
Use this option when the amount of code needed to initialize named static final class instances that represent ENUMERATED or INTEGER types with named numbers exceeds the 64K limit. The <nnn> number argument is mandatory. When -limitBigEnums is specified and the number of enumerators or named numbers exceeds the <nnn> limit, the compiler does not generate any constants representing known enumerators or named numbers.
In the following example, the application code retrieves enumerators using the valueOf(long) method:
public final class ITIScodes extends Enumerated {
...
public static final class Value {
public static final long stopped_traffic = 257;
public static final long stop_and_go_traffic = 258;
public static final long slow_traffic = 259;
...
}
...
public static ITIScodes valueOf(long value)
{
...
}
...
}
ITIScodes stopped_traffic =
ITIScodes.valueOf(ITIScodes.Value.stopped_traffic);
If an ASN.1 schema contains SET, SEQUENCE types, or Information Object classes with a very large number of elements, the constructor generated for these types might exceed the limit for the number of arguments imposed by many JVMs. This can result in a runtime application failure with a ClassFormatError exception thrown by the JVM with the following message:
Too many arguments in signature.
To avoid ClassFormatErrors, the compiler will not generate a constructor if the number of arguments exceeds the value (the default value is 200) specified by the -limitCons option.
The -limitCons option requires a parameter, nnn, that specifies the maximum number of arguments allowed in the constructor. For example, by specifying -limitcons 10 as a command-line argument, the compiler will not generate constructors with more than ten arguments. Types that contain ten or fewer components will have constructors with arguments generated as usual.
Instructs the compiler to restructure the generated code so that the size of each method should contain <number> code lines. The number parameter indicates the number of lines of generated source code (one line of code corresponds to one Java statement). The minimum value of <number> is 100.The -limitMethodSize option is especially useful when the size of the generated ASN.1/Java TOED methods exceeds the 64K limit imposed by certain JVMs, in which case the compiler might throw the ClassFormatError exception.
BigSet ::= [APPLICATION 3] IMPLICIT SET {
attr001 [1] IMPLICIT IA5String OPTIONAL,
attr002 [2] IMPLICIT IA5String OPTIONAL,
. . . . .
attr99 [99] IMPLICIT IA5String OPTIONAL,
attr100 [100] IMPLICIT IA5String OPTIONAL
}
| Without -limitMethodSize | With -ber and -limitMethodSize 100 |
|---|---|
public int encodeValue(...)
{
encodeValue1(...);
encodeValue2(...);
...
encode value100();
...
}
|
private int encodeValue(...)
{
// Encode fields attribute1 ... attribute10
...
}
private int encodeValue1(...)
{
// Encode fields attribute11 ... attribute20
...
}
. . .
|
Specifies whether the compiler should generate an ASN.1 composite listing of root modules, containing all macro instances and parameterized items expanded, and all external references resolved.
The listingFileName is the name of the output listing file. If you don't specify it, the default name is the last command-line input filename, with the .lst extension.
If no error conditions are detected in the input, the listing file contains valid ASN.1 that can be used as input by any ASN.1 compiler.
Controls the format of the error, warning, or informatory messages issued by the ASN.1 compiler for further parsing by a compatible text editor. This helps you automatically find the location in the input file for which the message is issued.
Three format schemes are available:
By default, the oss message format scheme is used.
Specifies whether the compiler should generate a module listing file that contains information from multiple ASN.1 modules.
The -listingFilename optional operand specifies the output listing file name. When the operand is absent, the output listing file name will be the last command-line input file name, with the .lst suffix appended.
By default, the -noModListingFile option is implied.
The module listing file will have all occurrences of macro definitions and INSTANCE OF expanded. However, parameterized items are not expanded.
This option is mostly used in diagnosing the compiler.
Specifies whether output files should be generated.
The outputPackage optional parameter specifies the directory in which the output files are generated and the name of the output file.
When outputPackage is not used, the prefix of the last .asn input file is considered the output filename.
MyProtocol DEFINITIONS ::= BEGIN
protocolID OBJECT IDENTIFIER ::= {iso standard 1 22 333}
bufferSize INTEGER ::= 1024
Data ::= SEQUENCE {
name PrintableString,
id INTEGER,
married BOOLEAN
}
END
By default, the output package name is example. When the ASN.1 compiler for Java is invoked with the command asn1pjav example.asn, the following .java files are generated:
example/ // the project package example/Example.java // the project class example/myprotocol/ // a module package example/myprotocol/MyProtocol.java // a module class example/myprotocol/Data.java // a ASN.1 typereference class
The Example.java file contains the following statement:
package example;
The MyProtocol.java and Data.java files contain the following statement:
package example.myprotocol;
When invoked with asn1pjav example.asn o com.acme.example, the ASN.1 compiler for Java generates the following output .java files:
com/acme/example/ // the project package com/acme/example/Example.java // the project class com/acme/example/myprotocol/ // a module package com/acme/example/myprotocol/MyProtocol.java // a module class com/acme/example/myprotocol/Data.java // a ASN.1 typereference class
The Example.java file contains the following statement:
package com.acme.example;
The MyProtocol.java and Data.java files contain the following statement:
package com.acme.example.myprotocol.
Note that if the last package name consists of a single uppercase letter followed by all lowercase letters, conflicting names are generated for the package and the ASN1Project class. For example, -output com.oss.Baseball would generate a class called Baseball which extends ASN1Project and resides in the com.oss.Baseball package. This would cause a javac compiler error, as well as a warning from the OSS compiler:
C0591W: Java package name 'Baseball' is the same as project class name 'Baseball'. Consider altering the package name in the output option to contain all lowercase letters or additional uppercase letters, i.e. 'BASEBALL'.
Certain parameterized assignments contain an INTEGER or a SEQUENCE type with parameterized constraints on the right side of an assignment. The instantiation of this type of parameterized assignments is a constrained type.
ParamType{parameters} ::= ActualType (parameterized constraint)
Instance1 ::= ParamType{actual parameters1}
Instance2 ::= ParamType{actual parameters2}
Instance1 and Instance2 are of the same type but have different constraints.
By default, the generated classes for the Instance1 and Instance2 parameterized types inherit from a universal class that corresponds to the type on the right side of the parameterized assignment of ParamType. For example:
class Instance1 extends ActualType { ...
class Instance2 extends ActualType { ...
When the -paramTypeSuperClass option is specified, an extra class is generated for ParamType and the Instance1 and Instance2 classes inherit from the new class.
class ParamType extends ActualType { ...
class Instance1 extends ParamType { ...
class Instance2 extends ParamType { ...
This is similar to inserting an auxiliary class in the middle of the inheritance hierarchy of the generated classes:
Effect of the -paramTypeSuperClass on the hierarchy of the generated classes
Also, if a parameterized type instance is used for a component of a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF type, then the generated Java class that corresponds to the outermost structured type references the ParamType class generated for the parameterized assignment.
AString {INTEGER:maxSize} ::= VisibleString (SIZE(0..maxSize))
A ::= AString { 80 }
B ::= AString { 100 }
C ::= SET {
a AString { 255 }
}
The following Java classes are generated when the -paramTypeSuperClass option is specified:
public class AString extends VisibleString { ... }
public class A extends AString { ... }
public class B extends AString { ... }
public class C extends Set {
...
public C(Astring a) { ... }
public AString getA() { ... }
public void setA(Astring a) { ... }
...
}
NOTE: The -paramTypeSuperClass option has an effect only if the parameter has a governor. In the following example, UseParam does not inherit from Param even if -paramTypeSuperClass is specified:
Param {Type} ::= SEQUENCE {a Type, b Type}
UseParam ::= Param {INTEGER}
In the following example, -paramTypeSuperClass causes UseParam to inherit from Param.
Param {INTEGER:maxsize} ::= PrintableString (SIZE(maxsize))
UseParam ::= Param {20}
If directives are applied to the base parameterized type or instances of a parameterized type, the following rules apply:
Instructs the compiler to replace standard decoding with partial decoding. In this case, no standard decoding functions are generated.
Partial decoding is only supported by the TOED runtime. That is, -partialDecodeOnly cannot be used together with the -soed option.
The -partialDecodeOnly option is supported by the BER, DER, PER, UPER, CPER, CUPER, OER, and COER encoding rules.
By default, the -partialDecodeOnly option is disabled.
Specifies the target output directory where the files are generated.
By default, the output file names are assigned relative to the current working directory. This can be changed by specifying the -path option and providing a directory that already exist. When the package subdirectories do not exist, the compiler creates them within the target output directory. Note that the listing file and the file that captures directives from the ASN.1 input syntax are also placed in the target output directory.
For the following command:
asn1pjav example -path com/acme
where example.asn is:
Module DEFINITIONS ::= A ::= INTEGER END
The compiler generates the following Java files in the com/acme directory:
com/acme/example/ // the project package com/acme/example/Example.java // the project class com/acme/example/module/ // a module package com/acme/example/module/Module.java // a module class com/acme/example/module/A.java // a ASN.1 typereference class
The Example.java file contains the following statement:
package example;
The Module.java and A.java files contain the following statement:
package example.module;
Instructs the compiler to treat open types created by the ASN1.DeferDecoding or the OSS.ENCODABLE directive as PDUs, even when the OSS.NOPDU directive is specified.
The -noPdusForOpenTypes option instructs the compiler to ignore open types created by the ASN1.DeferDecoding or the OSS.ENCODABLE directive. This option causes the ASN.1 compiler to issue the following error message:
C0923E: Implementation limit exceeded; too many fields in module for ASN.1 schemas with a large number of PDU types.
By default, the -pdusForOpenTypes and -noPdusForOpenTypes options are disabled, and only unreferenced types may become PDUs.
The -noPdusForOpenTypes option is ignored if the -noConstraints option is not specified.
The -autoEncDec option overrides -noPdusForOpenTypes.
Instructs the ASN.1 compiler to thoroughly check the input file syntax.
If a type is not defined and it is neither directly nor indirectly referenced by the root modules, the compiler does not consider it an error.
The -pedantic option implies the -syntaxOnly option, therefore no .java file is generated.
Specifies the prefix for the global generated names in your Java program file. The -prefix option is useful in multiple input ASN.1 syntaxes to avoid multiple declaration Java compiler errors resulting from conflicting names.
It is possible to prefix class names, package names, and public member variable names separately by specifying an optional selector that can be one of "package", "class", or "var". When the option is used without a selector the specified prefix is applied to all names eligible for prefixing, unless overridden by another -prefix option with a selector.
TEST DEFINITIONS ::= BEGIN
A ::= INTEGER {one(1)}
END
example/Example.java example/test/Test.java example/test/A.java public static int one;
example/Example.java example/my_test/My_Test.java example/my_test/My_A.java public static int My_one;
example/Example.java example/test/My_Test.java example/test/My_A.java public static int one;
example/Example.java example/My_test/My_Test.java example/My_test/My_A.java public static int my_one;
In this example, the prefix is added to module names, generated class names, and Java constants generated for named bits, named numbers, and enumerators.
Controls the automatic selection of command-line options.
By default, the -relaxedMode option is enabled by default.
When you specify -relaxedMode, the following options are automatically selected:
Note that certain warning messages are not suppressed when you use this option. To suppress all warnings, specify the -noWarningMessages option.
-noRelaxedMode implies the -warningMessages option.
To enable warnings or informatory messages when -relaxedMode is enabled, specify the -relaxedMode option, and then -warningMessages or -informatoryMessages.
To disable warnings or informatory messages when -noRelaxedMode is enabled, specify the -noRelaxedMode option, and then -noWarningMessages or -noInformatoryMessages.
Informs the ASN.1 compiler whether it should generate the instructions necessary for the decoder to preserve unknown extension additions for each extensible ASN.1 type. In this way, an application that needs to modify information in the extension root or in any recognized extensions, and then to re-encode, can do so without losing unknown extension additions. The encoder automatically reinserts into the encoding any unknown extension additions found while decoding.
By default, the -noRelaySafe option is implied.
When you specify the -relaySafe option, no additional changes in the code are required. Make sure you recompile the ASN.1 specification.
When you specify the -noRelaySafe option, the encoder/decoder silently ignores unknown extension addition values.
Defines keywords that are not automatically supported by the ASN.1 compiler.
By default, the -reservedWords option is disabled.
asn1pjav fname.xsd -reservedWords word1,word2,...
For example, ASN.1 type Enum is defined as follows:
Enum ::= ENUMERATED {send, assert}
The XSD/FWS compiler command-line:
asn1pjav a.asn
The generated Enum.java class contains:
public final class Enum extends Enumerated {
...
// Named list definitions.
public static final Enum send =
new Enum(0);
public static final Enum assert =
new Enum(1);
private final static Enum cNamedNumbers[] = {
send,
assert
};
...
}
The Enum class contains the identifier assert which might cause Java compiler warnings in certain versions:
m\Enum.java:48: warning: as of release 1.4, assert is a keyword, and may not be used as an identifier
public static final Enum assert =
^
To avoid these warnings, invoke the ASN.1 compiler as follows:
asn1pjav a.xsd -reserved assert
The generated Enum.java class contains:
public final class Enum extends Enumerated {
...
// Named list definitions.
public static final Enum send =
new Enum(0);
public static final Enum _assert =
new Enum(1);
private final static Enum cNamedNumbers[] = {
send,
_assert
};
...
}
To change the name of the Enum class, invoke the ASN.1 compiler as follows:
asn1pjav a.xsd -reserved assert,Enum
The generated Enum.java class contains:
public final class Enum_ extends Enumerated {
...
// Named list definitions.
public static final Enum_ send =
new Enum_(0);
public static final Enum_ _assert =
new Enum_(1);
private final static Enum_ cNamedNumbers[] = {
send,
_assert
};
...
}
Conflicts with Java reserved words
Instructs the ASN.1 compiler to treat all input modules as root modules.
By default, only the last module specified at the command line is treated as a root module.
When you use the -root option, all modules are thoroughly checked, and all unreferenced types in all modules are considered PDUs.
A Protocol Data Unit (PDU) is a protocol message that contains data defined by an ASN.1 type. PDUs can be encoded and decoded.
Instructs the compiler to generate sample code that shows you how to populate and use the generated Java-representations of PDU types defined in the input ASN.1 syntax.
The -noSampleCode option informs the compiler that it should not generate a sample application, even if the OSS.SampleCode directive is not specified in the ASN.1 input.
By default, -sampleCode | -noSampleCode option is disabled.
To generate sample code, use the following parameters:
If the parameter is absent, the compiler generates a sample application containing test code for each value reference in the ASN.1 input defined with a type that is a PDU, and for each value automatically created by the compiler for "true" PDU types.
When instructed to generate sample code, the ASN.1/Java compiler creates an additional samples subpackage directory inside the project directory. The sample code for a PDU Type that is defined inside a Module is placed into a project.samples.module.TypeSample Java class.
Sample classes are not intended to be instantiated and the sample code is static. A sample class contains the following methods:
To customize sample values (CHOICE, SEQUENCE OF, and SET OF) you can use -sampleCode with the OSS.SampleCode directive.
The -sampleCode option has no effect if the input ASN.1 syntax does not contain PDUs or when the -noOutput or -syntaxOnly option is present.
When -sampleCode is specified with the values parameter and the input ASN.1 syntax has no valuereferences for PDU types, the option is ignored.
The -sampleCode option is compatible with the -toed option in version 7.0 and later.
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 number argument is mandatory. The number of named items must be greater than the specified number argument, otherwise the option has no effect. The argument also specifies the size of the parts.
The -noSampleCode option informs the compiler that it should not generate a sample application, even if the OSS.SampleCode directive is not specified in the ASN.1 input.
The -splitBigEnums option is supported for the following types: ENUMERATED, INTEGERs with named numbers, and BIT STRINGs with named bits.
The ASN.1/Java compiler generates representations of ENUMERATED that define class constants (public static final) for each enumerator. Additionally, the class defines an array that aggregates all known enumerators of the type. The Java compiler (javac) generates the code required to initialize the members into the static initializer method.
When an ENUMERATED contains a large number of enumerators, the amount of code required to initialize the class constants and the array of enumerators could exceed the 64K size limit of the JVM method. A similar problem could occur for an INTEGER type that defines a large number of named numbers or when a BIT STRING defines a large number of named bits. Currently, the -soed compiler option generates correct Java code when the number of enumerators does not exceed 1600 (for -toed, the limit is 2200).
For example, if there are 2000 enumerators and the -splitBigEnums argument is 500, the static array initializer for 2000 members is split into four static _initMembers...() methods, each of which initializes 500 members of the array.
In the following example, the JVM 64K limit is exceeded:
ITIScodes ::= ENUMERATED {
-- Traffic Conditions
stopped-traffic (257),
stop-and-go-traffic (258),
slow-traffic (259),
heavy-traffic (260),
-- ... >2400 enumerators follow
}
The ENUMERATED in the above example uses a single initializer for the compiler-generated array of enumerators.
private final static ITIScodes cNamedNumbers[] = {
new ITIScodes(),
new ITIScodes(258),
new ITIScodes(259),
new ITIScodes(260),
... >2400 array members follow
}
When the -splitBigEnums 500 option is used, the cNamedNumbers[] array is initialized as follows:
private static void _initMembers0(ITIScodes[] members) {
members[0] = new ITIScodes();
members[1] = new ITIScodes(258);
members[2] = new ITIScodes(259);
members[3] = new ITIScodes(260);
... first 500 members follow
}
private static void _initMembers1(ITIScodes[] members) {
members[500] = new ITIScodes(4364);
... other 500 members follow
}
private static void _initMembers2(ITIScodes[] members) {
...
}
... other _initMembersN methods follow
private static ITIScodes[] _initMembers() {
ITIScodes[] members = new ITIScodes[2442];
_initMembers0(members);
_initMembers1(members);
_initMembers2(members);
_initMembers3(members);
_initMembers4(members);
return members;
}
private final static ITIScodes cNamedNumbers[] = _initMembers();
Instructs the compiler to generate auxiliary methods that provide initializations of PDU parts and are invoked from the createSampleValue() method, thus reducing the method size, to avoid the "code too large" error at Java compile time.
The ASN.1/Java -sampleCode option is used to generate sample Java code that illustrates API usage. The code is generated into project.samples.<module>.<type>.java classes, which include methods for initializing, printing and encoding/decoding sample values. The createSampleValue() method for types that have a huge number of components can be affected by the code too large error at Java compile time.
The -splitSampleCode option can be used only when the -sampleCode option or the SampleCode directive is specified.
The -splitSampleCode option can be followed by an optional number parameter that specifies the nesting level of the code split. By default, the number takes a value of 1, that is, only the top-level code is split.
The -splitSampleCode option affects only code that initializes values of SEQUENCE, SET, SEQUENCE OF, or SET OF ASN.1 types that also have components of the above types.
ASN.1
SampleType := SEQUENCE {
f1 TypeOfField1,
f2 TypeOfField2
}
TypeOfField1 ::= SEQUENCE {
f1 SEQUENCE {
f1 INTEGER
},
f2 INTEGER
}
TypeOfField2 ::= INTEGER
| Without -splitSampleCode | With -splitSampleCode used without a parameter | With -splitSampleCode 2 |
|---|---|---|
public static SampleType createSampleValue()
{
SampleType value = new SampleType();
value.setF1(new TypeOfField1());
{
TypeOfField1 f1_2 = value.getF1();
f1_2.setF1(new TypeOfField1.F1());
{
TypeOfField1.F1 f1_3 = f1_2.getF1();
f1_3.setF1(new com.oss.asn1.INTEGER(0));
}
f1_2.setF2(new com.oss.asn1.INTEGER(0));
}
value.setF2(new TypeOfField2(0));
return value;
}
|
public static SampleType createSampleValue()
{
SampleType value = new SampleType();
value.setF1(createSampleValue_f1());
value.setF2(new TypeOfField2(0));
return value;
}
public static TypeOfField1 createSampleValue_f1()
{
TypeOfField1 value = new TypeOfField1();
value.setF1(new TypeOfField1.F1());
{
TypeOfField1.F1 f1_3 = f1_2.getF1();
f1_3.setF1(new com.oss.asn1.INTEGER(0));
}
value.setF2(new com.oss.asn1.INTEGER(0));
return value;
}
|
public static SampleType createSampleValue()
{
SampleType value = new SampleType();
value.setF1(createSampleValue_f1());
value.setF2(new TypeOfField2(0));
return value;
}
public static TypeOfField1 createSampleValue_f1()
{
TypeOfField1 value = new TypeOfField1();
value.setF1(createSampleValue_f1_f1());
value.setF2(new com.oss.asn1.INTEGER(0));
return value;
}
public static TypeOfField1.F1 createSampleValue_f1_f1()
{
TypeOfField1.F1 value = new TypeOfField1.F1();
value.setF1(new com.oss.asn1.INTEGER(0));
return value;
}
|
Each type in an ASN.1 schema (for which a Java class is generated) contains generated metadata information. The metadata is a value called c_typeinfo that contains debugging, constraint, and tagging information. If a SEQUENCE, SET, CHOICE, or Information Object class with a large number of elements is present, c_typeinfo could exceed the 64K limit imposed the JVM, in which case the JVM throws a ClassFormatError exception with the following message:
Code of a method longer than 65535 bytes.
To avoid this error, the c_typeinfo definition is split into separate init_fieldnnn() methods which are used in the c_typeinfo initializer. This reduces the size of the JVM internal initialization method. This is supported for types where the number of elements exceeds the value (default: 200) specified by the -splitTtypeInfo option.
In the following example, the static variable that corresponds to c_typeinfo for a SEQUENCE with few elements is:
public static final TypeInfo c_typeinfo = new SequenceInfo( ... );
The number of elements is greater than nnn (default: 200), the TypeInfo initialization is split into separate methods for each field:
public static final TypeInfo c_typeinfo = new SequenceInfo(
...
init_field0(),
init_field1(),
...
init_fieldN()
);
private static SequenceFieldInfo init_field0() { ... }
private static SequenceFieldInfo init_field1() { ... }
...
private static SequenceFieldInfo init_fieldN() { ... }
This is supported for metadata of the following ASN.1 structured types: SEQUENCE, SET, and CHOICE, or for Information Object classes. The -splitTypeInfo option requires a parameter nnn, which specifies the maximum number of elements permitted before the TypeInfo is split. For example, if you specify -splittypeinfo 10 at the command line, the compiler splits TypeInfo if there are more than 10 elements in a SET, SEQUENCE, CHOICE, or CLASS.
Certain ASN.1 schemas may generate a large number of initialized static variables that correspond to ASN.1 value references and information object sets. Certain Java compilers combine these static initializations into one large internally defined method, therefore the size of the method might exceed the 64K method size limit imposed by JVMs, in which case the JVM may throw a ClassFormatError exception.
The -splitValues option instructs the ASN.1 Java compiler to generate variable initializers into separate private static init_XXXX() methods, which are used to assign a value to a static variable. This helps reduce the size of the JVM internal initialization method and helps you avoid ClassFormatError exception.
By default, the static variable that corresponds to an ASN.1 valuereference is:
public static final Type value_name = new Type ( ... );
With the -splitValues option, the compiler generates:
public static final Type value_name = init_value_name();
private static Type init_value_name() { return new Type( ...); }
This occurs for values of the following ASN.1 structured types: SEQUENCE, SET, CHOICE, SEQUENCE OF, SET OF and information object sets.
Instructs the compiler to suppress a specific warning or informatory message.
You can specify -suppress more than once at the command line.
messageNumber can be either the complete message identifier (A0210W ,for example) or the numeric part (210, for example).
Instructs the ASN.1 compiler to perform the syntax check only once on the ASN.1 input. This is useful if you don't need to generate Java files when debugging an abstract syntax.
By default, Java files are generated.
Instructs the ASN.1 compiler for Java to generate the Test.java file into the project package. The Test class contains the public static void main() method so the Test class can be run as a Java application. The purpose of the test application is to encode, decode, and print all value references in the ASN.1 input defined with a PDU type. This simplifies sample encoding generation and encoder/decoder testing (you don't need to write Java code).
The -noTest option does not generate the Test.java file described above.
The -noTest option is implied.
The Test application encodes or decodes values only if you incorporate value references into the ASN.1 syntax.
Only PDU type values are tested. By default, the compiler does not consider types referenced by other types as PDUs, except for types that have the PDU directive applied (ASN1.PDU or OSS.PDU).
If the test | -wtest option is implied and the ASN.1 syntax does not contain any value notation, that is, there are no predefined test cases, the compiler issues the C1261E error.
Instructs the ASN.1 compiler to generate Java code that is optimized either for speed or for size. Code optimized for speed is compatible with osstoed.jar, the time-optimized encoder/decoder library. Code optimized for size is compatible with oss.jar or osslean.jar, the space-optimized encoder/decoder libraries.
By default, the -toed option is implied.
The -toed and -soed options are mutually exclusive and the last one specified at the command line takes precedence.
Currently, the -ber, -der, -json, -oer, -coer, -per, -uper, -cper, -cuper, -xer, -cxer, and -constraints options are supported for -toed.
The following command-line options are ignored when specified with the -toed option:
When the -constraints option is specified with the -toed option, the compiler generates the validate() method, which enables runtime constraint checking. Currently, the following constraints are supported for TOED:
When the -constraints option is not specified, the validate() method is not generated.
Specifies whether Protocol Data Unit (PDU) tags should be unique.
The -uniquePDU option specifies that the tags for all PDUs must be unique. The -noUniquePDU option informs the compiler that PDUs can have identical tags.
By default, the compiler issues a warning message upon detecting duplicate PDU tags.
When the -uniquePDU option is specified and the compiler encounters a duplicate PDU tag, it generates an error message. If the -noUniquePDU option is enabled, no error or warning message is generated. When neither option is specified, the compiler issues only warning messages.
Note that in certain ASN.1 specifications (for example, the Presentation Layer Protocol (ISO/IEC 8823/ITU-T X.226)) PDUs don't have unique tags. In other ASN.1 specifications (for example, the Association Control Service Element (ACSE)) PDU tags are unique.
Specifies whether user-defined constraints should be generated into Java classes.
By default, the -noUserConstraints option is enabled.
When you specify the -userConstraints option with -noConstraints, information for user-defined constraints is generated into Java classes, and information for other constraints is excluded.
When you specify -noUserConstraints with -constraints, user-defined constraint information is excluded from the generated Java classes, and information for other constraints is included.
When you specify -userConstraints with an ASN.1 type definition that uses a user-defined constraint, as follows:
OddNumber ::= INTEGER (CONSTRAINED BY {-- Must be an odd number--})
Code is generated into the OddNumber Java class. To verify if the constraint is imposed on values of type OddNumber, the encoder/decoder calls the isValid() method of the OddNumber_fn class.
When you specify -userConstraints, you must write constraint checking methods for all user-defined constraints (unless the OSS.NoConstrain directive is specified to disable constraint checking for a particular type).
When you specify -noUserConstraints, you do not need to write methods to check user-defined constraints.
Instructs the compiler to treat types that occur as arguments in a CONSTRAINED BY constraint as top-level types, and ensures that the Java class that represents the type parameter of the user constraint is always generated.
By default, the -noUserConstraintPDUs option is enabled.
Due to limitations in the absoluteReference notation that is used in compiler directives to reference ASN.1 elements, it is not always possible to reference types that occur as type arguments in a user constraint. Therefore, we recommend that you do NOT use the -userConstraintPDUs option when the -keepNames and -genDirectives compiler options are also used.
In the following example, it is not possible to refer to the type argument of the user constraint using the absoluteReference syntax:
Data ::= SEQUENCE {
opaque OCTET STRING
}
Encrypted{T} ::= Data (WITH COMPONENTS{...,
opaque(CONSTRAINED BY {-- T is encrypted by some cipher -- T})})
Message ::= Encrypted{UserData}
Informs the compiler whether it should generate information about value references.
The -valueRefs option instructs the ASN.1 compiler for Java to generate public static variables for all value references from an input ASN.1 notation. The value references can then be accessed from anywhere in the user application.
The -noValueRefs option suppresses information about value references.
By default, the -valueRefs option is enabled.
If the -test option is specified, the -noValueRefs option has no effect.
Specifies whether ASN.1 compiler status messages should be issued.
The -verbose option instructs the ASN.1 compiler to issue status messages. The -noVerbose option instructs the ASN.1 compiler to suppress status messages.
By default, the -noVerbose option is enabled.
Specifies whether compiler warning and informatory messages should be generated.
By default, the -noWarningMessages option is implied via -relaxedMode. To suppress all warnings, specify the -noWarningMessages option.
The -warningMessages option implies the -informatoryMessages option. The -noWarningMessages option implies the -noInformatoryMessages option.
The order in which -warningMessages | -noWarningMessages and -relaxedMode | -noRelaxedMode options appear on the command line is important. The rightmost option takes precedence.
Generates Extensible Stylesheet Language (XSLs) files, one for each PDU.
If the -xer is not specified, the -xsl option and the OSS.Stylesheet directive have no effect. Also, when the -noOutput or -syntaxOnly option is used, the -xsl option has no effect.
By default, the XSL stylesheet file is generated in the directory of the corresponding ASN.1 module package and has the name ClassName.xsl. For the "baseball" example, the generated XSL stylesheet file is BBCard.xsl in the baseball/bcas directory.
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.