ASN1C
ASN.1 Compiler
Version 6.4
Java User’s Guide
Objective Systems, Inc. — February 2011
The software described in this document is furnished under a license agreement and may be used only in accordance
with the terms of this agreement.
Copyright Notice
Copyright ©1997–2011 Objective Systems, Inc. All rights reserved.
This document may be distributed in any form, electronic or otherwise, provided that it is distributed in its entirety and
that the copyright and this notice are included.
Author’s Contact Information
Comments, suggestions, and inquiries regarding ASN1C may be submitted via electronic mail to info@obj-sys.com.
Table of Contents
Overview of ASN1C for Java ...................................................................................................... 1
Using the Compiler ...................................................................................................................... 3
Running ASN1C ................................................................................................................... 3
ASN1C Java Command Line Options ................................................................................. 3
Using the GUI Wizard to Run ASN1C ............................................................................... 9
Using Projects ............................................................................................................. 10
Common Code Generation Options ........................................................................... 12
XSD Options ............................................................................................................... 16
Java Code Generation Options ................................................................................ 16
Compilation ................................................................................................................. 17
Compiler Configuration File .............................................................................................. 18
Compiler Error Reporting ................................................................................................... 22
Generated Java Source Code Overview ..................................................................................... 25
General Form of a Generated Java Source File ................................................................. 25
Package Specification ......................................................................................................... 26
Class Declaration ................................................................................................................ 27
Tag Constant ....................................................................................................................... 27
Public Member Variables ................................................................................................... 27
Constructors ........................................................................................................................ 28
Decode Method ................................................................................................................... 28
Encode Method ................................................................................................................... 29
Other Methods .................................................................................................................... 30
Inner Classes ....................................................................................................................... 30
ASN.1 Type to Java Class Mappings ........................................................................................ 33
BOOLEAN .......................................................................................................................... 33
INTEGER ............................................................................................................................ 33
Large Integer Support ................................................................................................. 34
BIT STRING ...................................................................................................................... 35
Named Bits .............................................................................................................. 36
OCTET STRING ................................................................................................................ 36
Character String Types ....................................................................................................... 37
ENUMERATED ................................................................................................................. 38
NULL .................................................................................................................................. 39
OBJECT IDENTIFIER ....................................................................................................... 40
RELATIVE-OID ................................................................................................................. 40
REAL .................................................................................................................................. 41
SEQUENCE ........................................................................................................................ 42
Creation of Temporary Types .................................................................................. 44
OPTIONAL keyword ............................................................................................... 45
DEFAULT keyword ................................................................................................ 45
Extension Elements .................................................................................................. 46
XSD Type Mapping ................................................................................. 46
iii
ASN1C
SET ........................................................................................................................... 46
SEQUENCE OF ................................................................................................................. 47
Generation of Temporary Types for SEQUENCE OF Elements ............................. 48
SEQUENCE OF Type Elements in Other Constructed Types ................................. 48
SET OF ............................................................................................................................... 49
CHOICE .............................................................................................................................. 49
Creation of Temporary Types .................................................................................. 51
Populating Generated Choice Structures for Encoding ............................................ 51
Accessing the Choice Element Value after Decoding ............................................. 52
Open Type .......................................................................................................................... 52
External Type ..................................................................................................................... 54
EmbeddedPDV Type .......................................................................................................... 54
Parameterized Types ........................................................................................................... 55
Value Specifications ........................................................................................................... 56
INTEGER Value Specification ................................................................................ 57
BOOLEAN Value Specification .............................................................................. 58
Binary String Value Specification ........................................................................... 58
Hexadecimal String Value Specification ................................................................. 58
Character String Value Specification ....................................................................... 58
Object Identifier Value Specification ...................................................................... 59
ENUMERATED Value Specification ...................................................................... 59
REAL Value Specification ...................................................................................... 59
SEQUENCE Value Specification ............................................................................ 60
SET Value Specification .......................................................................................... 60
SEQUENCE OF Value Specification ...................................................................... 60
SET OF Value Specification ................................................................................... 61
CHOICE Value Specification .................................................................................. 61
Generated BER/DER/CER Encode Methods ............................................................................. 63
Memory-buffer Based Definite Length Encoders .............................................................. 63
Generated Java Method Format and Calling Parameters ......................................... 64
Populating Generated Variables for Encoding ......................................................... 64
Procedure for Calling Java BER Encode Methods .................................................. 65
Reuse of Java Encoding Objects ............................................................................. 67
Stream-Oriented Indefinite Length Encode Methods ......................................................... 68
Generated Java Method Format and Calling Parameters ......................................... 68
Procedure for Calling Java BER Stream-Oriented Encode Methods ....................... 69
Generated BER/DER/CER Decode Methods ............................................................................. 71
Generated Java Method Format and Calling Parameters ................................................... 71
Procedure for Calling Java BER Decode Methods ............................................................ 72
Reuse of Java Decoding Objects ........................................................................................ 73
Generated PER Encode Methods ............................................................................................... 75
Generated Java Method Format and Calling Parameters ................................................... 75
Procedure for Calling Java PER Encode Methods ............................................................. 76
Reuse of Java Encoding Objects ........................................................................................ 78
Generated PER Decode Methods ............................................................................................... 79
iv
ASN1C
Generated Java Method Format and Calling Parameters ................................................... 79
Procedure for Calling Java PER Decode Methods ............................................................. 80
Reuse of Java Decoding Objects ........................................................................................ 81
Generated XER / XML Encode Methods .................................................................................. 83
Generated Java Method Format and Calling Parameters ................................................... 83
Procedure for Calling Java XER Encode Methods ............................................................ 84
Generated XER / XML Decode Methods .................................................................................. 89
Generated MDER Encode Methods ........................................................................................... 93
Generated Method Format and Calling Parameters .......................................................... 93
Populating Generated Variables for Encoding ................................................................. 94
Procedure for Calling MDER Encode Methods .............................................................. 94
Reuse of Java Encoding Objects ..................................................................................... 95
Generated MDER Decode Methods ........................................................................................... 97
Generated Method Format and Calling Parameters ........................................................... 97
Procedure for Calling Java MDER Decode Methods ........................................................ 97
Reuse of Java Decoding Objects ........................................................................................ 98
Table Constraint Processing ..................................................................................................... 101
CLASS specification ........................................................................................................ 101
Data Member Generation ....................................................................................... 101
Method and Constructor Generation ...................................................................... 102
ABSTRACT-SYNTAX .......................................................................................... 104
TYPE-IDENTIFIER ............................................................................................... 104
Information Object ............................................................................................................ 104
Information Object Set ..................................................................................................... 106
Generated Information Object Table Structure ................................................................ 107
Simple Form Code Generation .............................................................................. 108
Table Form Code Generation ................................................................................ 109
Additional Code Generated for the -tables Option ................................................ 110
Populating OpenType Variables for Encoding ................................................................. 112
Decoding Types with Table Constraints .......................................................................... 114
Generated Print Methods .......................................................................................................... 115
Generated Java Method Format and Calling Parameters ............................................... 115
Generated Compare Methods ................................................................................................... 117
Generated Sample Programs .................................................................................................... 119
Generated Build Script ............................................................................................................. 121
Event Handler Interface ............................................................................................................ 123
How It Works ................................................................................................................... 123
How to Use It ................................................................................................................... 124
Example 1: A Formatted Print Handler ................................................................. 125
Example 2: An XML Converter Class ................................................................... 127
IMPORT/EXPORT of Types ................................................................................................... 131
Compact Code Generation ....................................................................................................... 133
ROSE and SNMP Macro Support ............................................................................................ 135
ROSE OPERATION and ERROR ................................................................................... 135
SNMP OBJECT-TYPE ..................................................................................................... 138
v
ASN1C
Java Micro Edition Support ..................................................................................................... 141
vi
Overview of ASN1C for Java
The ASN1C code generation tool translates an Abstract Syntax Notation 1 (ASN.1) or XML
Schema Definitions (XSD) source file into computer language source files that allow typed data
to be encoded/decoded. This release of ASN1C includes options to generate code in the following
languages: C, C++, C# or Java. This manual discusses the Java code generation capabilities. The
following manuals discuss the other language code generation capabilities:
• ASN1C C/C++ Compiler User's Manual : C/C++ code generation
• ASN1C C# Compiler User's Manual : C# code generation
Each module or namespace that is encountered in an ASN.1 or XSD source file results in the
generation of a series of Java source files. A separate Java file is generated for each production
(type or global element) in the source file. Additional files are generated for compiler-generated
productions and to hold value specification constants.
There is also a set of classes that form the run-time component of the Java package. These classes
provide the primitive component building blocks that are assembled by the compiler to encode/decode complex structures. They also provide support for managing message buffers that hold the
encoded message components.
ASN1C works with the version of ASN.1 specified in ITU-T international standards X.680 through
X.683. It generates code for encoding/decoding data in accordance with the following encoding
rules:
• Basic Encoding Rules (BER), Distinguished Encoding Rules (DER), and Canonical Encoding
Rules (CER) as published in the ITU-T X.690 standard.
• Packed Encoding Rules (PER) as published in the ITU-T X.691 standard.
• XML Encoding Rules (XER) as published in the ITU-T X.693 standard.
• XML Schema to ASN.1 translation as published in the ITU-T X.694 standard.
The compiler is capable of parsing all ASN.1 syntax as defined in the standards. It is capable
of parsing advanced syntax including Information Object Specifications as defined in the ITU-T
X.681 standard as well as Parameterized Types as defined in ITU-T X.683.
Note that XER support does not include support for the EXTENDED-XER syntax. This is accomplished through direct compilation of XSD files. An internal translation of XSD to ASN.1 based
on the rules in the X.694 standard is done within the compiler and the resulting ASN.1 syntax is
compiled into Java classes.
This release of the compiler contains a special compiler option (-asnstd x208) that is backward
compatible with deprecated features from the older X.208 and X.209 standards. These include the
1
ANY data type and unnamed fields in SEQUENCE, SET, and CHOICE types. This version can
also parse type syntax from common macro definitions such as ROSE and SNMP.
2
Using the Compiler
Running ASN1C
The ASN1C compiler distribution contains command-line compiler executables as well as a graphical user interface (GUI) wizard that can aid in the specification of compiler options. Please refer
to the ASN1C C/C++ Compiler User's Manual for instructions on how to run the compiler. The
remaining sections describe options and configuration items specific to the Java version.
ASN1C Java Command Line Options
The following table shows a summary of the command line options that have meaning when Java
code generation is selected:
Option
Argument
Description
-asnstd
x680
x208
mixed
This option instructs the compiler to parse ASN.1 syntax
conforming to the specified
standard. x680 (the default)
refers to modern ASN.1 as
specified in the ITU-T X.680X.690 series of standards. x208
refers to the now deprecated X.208 and X.209 standards.
This syntax allowed the ANY
construct as well as unnamed
fields in SEQUENCE, SET,
and CHOICE constructs. This
option also allows for parsing and generation of code
for ROSE OPERATION and
ERROR macros and SNMP
OBJECT-TYPE macros. The
mixed option is used to specify
a source file that contains modules with both X.208 and X.680
based syntax.
-ber
None
This option instructs the compiler to generate functions that
implement the Basic Encoding
Rules (BER) as specified in the
ASN.1 standards.
3
ASN1C Java Command Line Options
Option
Argument
Description
-cer
None
This option instructs the compiler to generate functions that
implement the Canonical Encoding Rules (CER) as specified in the ASN.1 standards.
-cldc
None
This option instructs the compiler to generate Java Micro
Edition Connected Limited Device Configuration (CLDC) 1.1
compatible code. See the chapter Java Micro Edition Support
for more information.
-compact
None
This option instructs the compiler to generate more compact
code at the expense of some
constraint and error checking.
This is an optimization option
that should be used after an application is thoroughly tested.
-compare
None
This option is used to generate a
comparison method (Equals) in
the generated classes.
-compat
Generate code compatible with
an older version of the compiler. The compiler will attempt
to generate code more closely
aligned with the given previous
release of the compiler.
is specified
as x.x (for example, -compat
5.2)
-config
4
This option is used to specify the name of a file containing configuration information
for the source file being parsed.
A full discussion of the contents
of a configuration file is provided in the Compiler Configuration File section.
ASN1C Java Command Line Options
Option
Argument
Description
-depends
None
This option instructs the compiler to generate a full set of Java source files that contain only the productions in the main
file being compiled and items
those productions depend on
from IMPORT files.
-der
None
This option instructs the compiler to generate functions that
implement the Distinguished
Encoding Rules (DER) as specified in the ASN.1 standards.
-dirs
None
This is a Java option that causes
a subdirectory to be created to
hold each of the generated Java
source files for each module in
an ASN.1 source file.
-events
None
Generate extra code to invoke
user defined event and error
handler callback methods (see
the Event Handlers section).
-genant
None
Generate a build script
(build.xml) that is compatible
with the Ant toolchain.
-genbuild
None
This option is used to generate a
build script for compiling generated classes.
-genPrint
-print
None
This option specifies that print
methods should be generated.
Print functions are debug functions that allow the contents of
generated type variables to be
written to stdout.
-getset
None
This option is used to generate
protected member variables and
get/set methods for accessing
the variables. By default, member variables are declared to be
public and they are accessed directly by application code.
5
ASN1C Java Command Line Options
Option
Argument
Description
-I
This option is used to specify a
directory that the compiler will
search for ASN.1 source files
for IMPORT items. Multiple –I
qualifiers can be used to specify
multiple directories to search
-java4
None
Generate Java source code compatible with the Java runtime
environment version 1.4.x. By
default, code is generated that
is compatible with versions 1.5
and higher.
-lax
None
This option instructs the compiler to not generate code to
check constraints. When used in
conjunction with the –compact
option, it produces the smallest
code base for a given ASN.1
specification
-list
None
Generate listing. This will
dump the source code to the
standard output device as it is
parsed. This can be useful for
finding parse errors.
-nodecode
None
This option suppresses the generation of decode functions.
-noencode
None
This option suppresses the generation of encode functions.
-noIndefLen
None
This option instructs the compiler to omit indefinite length
tests in generated decode functions. These tests result in the
generation of a large amount
of code. If you know that your
application only uses definite
length encoding, this option can
result in a much smaller code
base size.
-noOpenExt
None
This option instructs the compiler to not add an open extension element in constructs
6
ASN1C Java Command Line Options
Option
Argument
Description
that contain extensibility markers. The purpose of the element
is to collect any unknown items
in a message. If an application
does not care about these unknown items, it can use this option to reduce the size of the
generated code.
-o
This option is used to specify
the name of a directory to which
all of the generated files will be
written.
-pdu
Designate given type name to
be a Protocol Definition Unit
(PDU) type. By default, PDU
types are determined to be types
that are not referenced by any
other types within a module.
This option allows that behavior
to be overridden.
The * wildcard character may
be specified for
to indicate that all productions
within an ASN.1 module should
be treated as PDU types.
-per
None
This option instructs the compiler to generate functions that
implement the Packed Encoding Rules (PER) as specified in
the ASN.1 standards.
-pkgname
This is a Java option that allows the entire Java package
name to be changed. Instead
of the module name, the full
name specified using this option
will be used. This option cannot be used in conjunction with
–pkgpfx option.
-pkgpfx
This is a Java option for adding
a prefix in front of the assigned
Java package name. By default,
7
ASN1C Java Command Line Options
Option
Argument
Description
the Java package name is set to
the module name. If the package is embedded within a hierarchy, this option can be used
to set the other directory names
that must be added to allow Java to find the .class files.
-reader
None
This option is used to generate
a sample reader program to decode data.
-shortnames
None
This option is used to change
the names generated by compiler for embedded types in constructed types. This option is required to handle the limit on
the size of filenames in certain situations. With this option,
the generated code filenames
would be shorter than without
this option.
-stream
None
This option instructs the compiler to generate stream-based
encoders/decoders instead of
memory buffer based. This
makes it possible to encode directly to or decode directly from
a source or sink such as a file
or socket. In the case of BER,
it will also cause forward encoders to be generated, which
will use indefinite lengths for all
constructed elements in a message.
-tables
None
This option is used to generate
additional code for the handling
of table constraints as defined in
the X.682 standard.
-uniquenames
None
This option instructs the compiler to automatically generate
unique names to resolve name
collisions in the generated code.
Name collisions can occur, for
8
Using the GUI Wizard to Run ASN1C
Option
Argument
Description
example, if two modules are being compiled that contain a production with the same name.
A un ique name is generated by prepending the module
name to one of the productions
to form a name of the form
_.
Note that name collisions can
also be manually resolved by
using the typePrefix, enumPrefix, and valuePrefix configuration items (see the Compiler
Configuration File section for
more details)
-warnings
None
Output information on compiler
generated warnings.
-writer
None
This option is used to generate
a sample writer program to encode data.
-xer
None
This option instructs the compiler to generate functions that
implement the XML Encoding
Rules (XER) as specified in the
ASN.1 standards.
-xml
None
This option instructs the compiler to generate functions that
implement the XML Encoding Rules (XML) as specified
in the World-Wide Consortium
(W3C). Related XML Schema
can be produced by using the xsd command line option.
Using the GUI Wizard to Run ASN1C
ASN1C includes a graphical user interface (GUI) wizard that can be used as an alternative to the
command-line version. It is a cross-platform GUI and has been ported to Windows and several
UNIXes. The GUI makes it possible to specify ASN.1 files and configuration files via file navigation windows, to set command line options by checking boxes, and to get online help on specific
options.
9
Using Projects
The Windows installation program should have installed an ‘ASN1C Compiler’ option on your
computer desktop and an ‘ASN1C’ option on the start menu. The wizard can be launched using
either of these items. The UNIX version should be installed in ASN1C_INSTALL_DIR/bin; no desktop shortcuts are created, so it will be necessary to create one or to run the wizard from the command-line.
The Java GUI differs little from the C/C++ GUI; screenshots may include references to C or C++
directories, but the common code options are identical.
Using Projects
The wizard is navigated by means of Next and Back buttons. Following is the initial window:
The status window will display the version of the software you have installed as well as report any
errors upon startup that occur, such as a missing license file.
The Project Wizard will allow you to save your compilation options and file settings into a project
file and retrieve them later. If you wish to make a new project, click the icon next to Create a
New Project:
10
Using Projects
Previously saved projects may be recalled by clicking the icon next to Open an Existing Project:
The project format has changed in ASN1C 6.3 to help accommodate the transition to Qt 4.5.
Changes to the interface necessitated changes to the underlying project file format. Projects made
with previous versions may be loaded with version 6.3, but new projects are incompatible with
previous versions. Additional metadata are stored in the project file to help with version tracking.
Files may be added to a project in the following window:
11
Common Code Generation Options
In this window, the ASN.1 file or files to be compiled are selected. This is done by clicking the Add
button on the right hand side of the top windows pane. A file selection box will appear allowing
you to select the ASN.1 or XSD files to be compiled. Files can be removed from the pane by
highlighting the entry and clicking the Remove button.
ASN.1 specifications and XML Schema Documents must not be compiled in the same project.
Once an ".asn" file has been added, no ".xsd" files may be added.
Include directories are selected in a similar manner in the middle pane. These are directories the
compiler will search for import files. By default, the compiler looks for files in the current working
directory with the name of the module being imported and extension ".asn" or ".xsd". Additional
directories can be searched for these files by adding them here.
User-defined configuration files are specified in the third pane. These allow further control of the
compilation process. They are optional and are only needed if the default compilation process is to
be altered (for example, if a type prefix is to be added to a generated type name). See the Compiler
Configuration File section for details on defining these files.
Common Code Generation Options
Code generation options common to all language types are specified in the following tabbed window:
12
Common Code Generation Options
Language options, pictured above, encompass not only the output language choice, but also input
specification type, encoding rules, and code compatibility options.
Certain options will be inactive (greyed out) depending on the file type selected. For example, if an
XSD file is selected, the option Generate ASN.1 file based on X.694 will be active and the option
Generate equivalent XML schema (XSD) file will be inactive.
Checking Generate code for all dependent imported type definitions will cause the compiler to
search and generate code for modules specified in the IMPORTS statement of an ASN.1 specification.
Basic encoding rules are selected by default. Only one of BER, DER, and CER can be checked at
any time. XML and XER are also mutually exclusive options.
Generated function options are shown in the following tab:
13
Common Code Generation Options
The options in this tab control which functions are generated and what modifications are made to
those functions.
By default, encoding and decoding functions are generated by the compiler. If the target application does not require encoding or decoding capabilities (for example, if it is only intended to read
messages and does not need to write them), unchecking the corresponding checkbox will reduce
the amount of code generated.
Check Stream to modify generated encode and decode functions to use streams instead of memory
buffers. This allows encoding and decoding to a source or sink such as a file or socket. Streambased encoding and decoding cannot be combined with buffer-based.
As an aid to debugging, Print functions may also be generated. Three different different types exist:
print to stdout, print to string, and print to stream. These allow the contents of generated types to
be printed to the standard output, a string, or a stream (such as a file or socket).
Constraint checking may be relaxed or tightened depending on selected options. Constraints may be
ignored completely by checking Do not generate constraint checks. To tighten constraints, check
Enable strict constraint checks. ASN1C supports decoding and encoding values described by table
constraints; checking Generate code to handle table constraints will enable this behavior. This
option is a legacy option for C and C++ code generation: generating table constraints in unions is
the preferred method (see the following section).
14
Common Code Generation Options
To reduce the code footprint, several other options may be selected: Generate compact code, Do
not generate indefinite length processing code, Do not generate code to save/restore unknown
extensions, and Do not generate types for items embedded in information objects may all be used
to reduce the amount of generated code. Generate compact code cannot be used in conjunction
with Generate compatible code. If XML validation is not needed, check Do not generate XML
namespaces for ASN.1 modules. This will result in a smaller codebase as well as smaller output
XML data. Check Generate short form of type names if generated type names are too long for the
target language.
The following tab provides options for generating utility functions and applications:
The Sample Program Generation frame allows you to generate boilerplate reader and writer applications as well as randomized test data for populating a sample encoded message. The items in
the Protocol Data Units frame may be used in conjunction to select the appropriate PDU data type
to be used in the sample programs.
The Debugging and Event Handlers frame contains options that generate code for adding trace
diagnostics and event handling hooks into generated code. It is possible to generate a type parser
by generating only an event handler and no data types for the decoded messages. This grants a
great deal of flexibility in handling input data at the expense of generating pre-defined functions
for most common encoding and decoding tasks. Users of embedded systems may find this useful as
it will shrink the output considerably while allowing them fine control over decoding procedures.
15
XSD Options
The Other Options frame contains miscellaneous modifications to code output, including type
name resolution (avoiding duplicate names), date stamp removal (useful when generated code will
be stored in source control), and a line item for including any new command-line features not yet
represented in the GUI.
XSD Options
If the Generate equivalent XML schema (XSD) file option was checked in the Common Code Generation Options screen, the following window will be presented for modifying the contents of the
generated XSD:
These options are described in Running ASN1C from the command-line.
Java Code Generation Options
For information about code generation options for languages other than Java, please refer to the
appropriate language manual or the online documentation.
The following window contains the Java-specific code-generation options:
16
Compilation
The options in this window allow users to change the way the generated code is organized, what
files are generated to assist compiling the generated code, and to set parameters for the generated
code.
Changing the code organization can be particularly helpful for using generated code with IDEs like
Netbeans or Eclipse. IDEs typically impose a directory structure for projects, so ASN1C can try
to organize code to conform to such a hierarchy.
There are several different tools available for building Java files; ASN1C provides a few basic
generated files to help simplify the build process. A list of generated files can be provided for use
with command-line tools like make; Ant and shell scripts may also be generated.
Code may also be generated that is compatible with Java 1.4; get and set methods may also be
generated for users desiring Bean-style encapsulation.
These options are detailed further in the Running ASN1C from the Command Line section.
Compilation
When all options have been specified, the final screen may be used to execute the compilation
command:
17
Compiler Configuration File
Included in the window are the compiler command, an option to save the project, and the output
from compilation. Selected options are reflected in the command line.
It is also possible to generate a printed listing of the input specifications. Warnings encountered
during compilation will also be printed if the appropriate check box is marked.
Click Finish to terminate the program. The wizard will ask whether or not to save any changes
made, whether a new project has been created or not.
Compiler Configuration File
In addition to command line options, a configuration file can be used to specify compiler options.
These options can be applied not only globally but also to specific modules and productions.
A simple form of the Extended Markup Language (XML) is used to format items in the file. This
language was chosen because it is fairly well known and provides a natural interface for representing hierarchical data such as the structure of ASN.1 modules and productions. The use of an
external configuration file was chosen over embedding directives within the ASN.1 source itself
due to the fact that ASN.1 source versions tend to change frequently. An external configuration
file can be reused with a new version of an ASN.1 module, but internal directives would have to
be reapplied to the new version of the ASN.1 code.
18
Compiler Configuration File
At the outer level of the markup is the tag pair. Within this tag pair,
the specification of global items and modules can be made. Global items are applied to all items
in all modules. An example would be the qualifier. A storage class such as dynamic
can be specified and applied to all productions in all modules. This will cause dynamic storage
(pointers) to be used to any embedded structures within all of the generated code to reduce memory
consumption demands.
The specification of a module is done using the tag pair. This tag pair can
only be nested within the top-level section. The module is identified by using the
required tag pair or by specifying the name as an attribute (for example, ). Other attributes specified within the section apply only to that
module and not to other modules specified within the specification. A complete list of all module
attributes is provided in the table at the end of this section.
The specification of an individual production is done using the tag
pair. This tag pair can only be nested within a section. The production is identified by
using the required tag pair or by specifying the name as an attribute (for example,
). Other attributes within the production section apply only to the
referenced production and nothing else. A complete list of attributes that can be applied to individual productions is provided in the table at the end of this section.
When an attribute is specified in more than one section, the most specific application is always
used. For example, assume a qualifier is used within a module specification to specify
a prefix for all generated types in the module and another one is used to specify a prefix for a single
production. The production with the type prefix will be generated with the type prefix assigned to
it and all other generated types will contain the type prefix assigned at the module level.
Values in the different sections can be specified in one of the following ways:
1. Using the value form. This assigns the given value to the given name. For
example, the following would be used to specify the name of the "H323-MESSAGES" module
in a module section:
H323-MESSAGES
2. Flag variables that turn some attribute on or off would be specified using a single
entry. For example, to specify a given production is a PDU, the following would be specified
in a production section:
3. An attribute list can be associated with some items. This is normally used as a shorthand form
for specifying lists of names. For example, to specify a list of type names to be included in the
generated code for a particular module, the following would be used:
The following are some examples of configuration specifications
19
Compiler Configuration File
dynamic
This specification indicates dynamic storage should be used in all places where its use would result
in significant memory usage savings within all modules in the specified source file.
H323-MESSAGES
h225.asn
H225
...
This specification applies to module 'H323-MESSAGES' in the source file being processed. For
IMPORT statements involving this module, it indicates that the source file 'h225.asn' should be
searched for specifications. It also indicates that when C or C++ types are generated, they should be
prefixed with the 'H225'. This can help prevent name clashes if one or more modules are involved
and they contain productions with common names.
The following tables specify the list of attributes that can be applied at all of the different levels:
global, module, and individual production:
Global Level
There are no attributes that are specific to Java that can be specified at the global level.
Module Level
These attributes can be applied at the module level by including them within a section:
Name
Values
Description
module name
This attribute identifies the
module to which this section applies. It is required.
specified as an attribute list
types and/or values to be included in the generated code. By
default, the compiler generates
code for all types and values
within a specification. This allows the user to reduce the size
of the generated code base by
selecting only a subset of the
types/values in a specification
for compilation.
Note that if a type or value is included that has dependent types
or values (for example, the el20
Compiler Configuration File
Name
Values
Description
ement types in a SEQUENCE,
SET, or CHOICE), all of the dependent types will be automatically included as well.
ASN.1 module name(s) speci- This form of the include direcfied as an attribute list.
tive tells the compiler to only include types and/or values in the
generated code that are imported by the given module(s).
specified as an attribute list
types and/or values to be excluded in the generated code.
By default, the compiler generates code for all types and values within a specification. This
is generally not as useful as in
include directive because most
types in a specification are referenced by other types. If an attempt is made to exclude a type
or value referenced by another
item, the directive will be ignored.
source file name
Indicates the given module
is contained within the given ASN.1 source file. This is
used on IMPORTs to instruct
the compiler where to look for
imported definitions. This replaces the module.txt file used
in previous versions of the compiler to accomplish this function.
Java package name
Name of the Java package associated with this module. This
will cause a Java import statement to be generated for the
module if this name is not the
same as that of the package being compiled.
Production Level
21
Compiler Error Reporting
These attributes can be applied at the production level by including them within a
section:
Name
Values
Description
module name
This attribute identifies the
module to which this section applies. It is required.
n/a
This is a flag variable (an 'empty element' in XML terminology) that specifies that this production will be used to store an
integer larger than the Java long
type (64 bits). A Java BigInteger class will be used to hold the
value.
This qualifier can be applied to
either an integer or constructed
type. If constructed, all integer
elements within the constructed
type are flagged as big integers.
Java List Class
This instructs the compiler to
use a different class than the
default LinkedList; it would be
possible, for example, to use
java.util.ArrayList.
Compiler Error Reporting
Errors that can occur when generating source code from an ASN.1 source specification take two
forms: syntax errors and semantics errors.
Syntax errors are errors in the ASN.1 source specification itself. These occur when the rules specified in the ASN.1 grammar are not followed. ASN1C will flag these types of errors with the error
message 'Syntax Error' and abort compilation on the source file. The offending line number will
be provided. The user can re-run the compilation with the '-l' flag specified to see the lines listed
as they are parsed. This can be quite helpful in tracking down a syntax error.
The most common types of syntax errors are as follows:
• Invalid case on identifiers: module name must begin with an uppercase letter, productions (types)
must begin with an uppercase letter, and element names within constructors (SEQUENCE, SET,
CHOICE) must begin with lowercase letters.
22
Compiler Error Reporting
• Elements within constructors not properly delimited with commas: either a comma is omitted at
the end of an element declaration, or an extra comma is added at the end of an element declaration
before the closing brace.
• Invalid special characters: only letters, numbers, and the hyphen (-) character are allowed. Programmers tend to like to use the underscore character (_) in identifiers. This is not allowed in
ASN.1. Conversely, C or C# does not allow hyphens in identifiers. To get around this problem,
ASN1C converts all hyphens in an ASN.1 specification to underscore characters in the generated code.
Semantics errors occur on the compiler back-end as the code is being generated. In this case, parsing
was successful, but the compiler does not know how to generate the code. These errors are flagged
by embedding error messages directly in the generated code. The error messages always begin with
an identifier with the prefix '%ASN-',. A search can be done for this string in order to find the
locations of the errors. A single error message is output to stderr after compilation on the unit is
complete to indicate error conditions exist.
23
24
Generated Java Source Code Overview
A separate Java source file with extension '.java' is generated for each production encountered
within an ASN.1 source file. Every ASN.1 type is mapped to a Java class. This is true even at the
lowest levels – types such as BOOLEAN, INTEGER, and NULL all have wrapper classes.
General Form of a Generated Java
Source File
The following items may be present in a generated java file:
• Package specification
• Import statements
• Class declaration
• A tag constant object declaration
• Public member variables
• Constructors
• Public decode() method
• Public encode() method
• Other methods
• Inner SAX Handler class (XER or XML only)
Additional specialized items may be present as well depending on the base type of the target production. These specialized items are discussed in the sections on ASN.1 to Java mappings for the
various ASN.1 types.
A complete generated Java source file for the 'EmployeeNumber' production within the production
within the ASN.1 sample file 'employee.asn' can be found on the following page. The ASN.1 production from which this file was generated is as follows:
EmployeeNumber ::= [APPLICATION 2] IMPLICIT INTEGER
The generated code is as follows:
package sample_ber.Employee;
import com.objsys.asn1j.runtime.*;
import java.io.*;
import java.util.*;
25
Package Specification
public class EmployeeNumber extends Asn1Integer {
public final static Asn1Tag TAG =
new Asn1Tag (Asn1Tag.APPL, Asn1Tag.PRIM, 2);
public EmployeeNumber() {
super();
}
public EmployeeNumber (int value_) {
super (value_);
}
pubilc void decode
(Asn1BerDecodeBuffer buffer, boolean explicit, int implicitLength)
throws Asn1Exception, java.io.IOException
{
final int llen = (explicit) ?
matchTag (buffer, TAG) : implicitLength;
super.decode (buffer, false, llen);
if (explicit && llen == Asn1Status.INDEFLEN) {
matchTag (buffer, Asn1Tag.EOC);
}
}
public int encode (Asn1BerEncodeBuffer buffer, boolean explicit)
throws Asn1Exception
{
int aal = super.encode (buffer, false);
if (explicit) {
aal += buffer.encodeTagAndLength (TAG, aal);
}
return (aal);
}
}
Package Specification
The package specification is the first item in the file and is declared using the 'package' keyword.
By default, this is set to the name of the ASN.1 module that is being compiled. However, this
can be modified by using the –pkgpfx and – pkgname command line options. The –pkgpfx option
adds the specified prefix before the module name. For example, if an ASN.1 module named 'Employee' is being compiled and '-pkgpfx test.' is specified on the command line, the package name
in the generated source files would be 'test.Employee'. The –pkgname switch takes this a step further. It allows specification of the full package name. In the sample specification above, '-pkgpfx
sample_ber.' was specified on the compiler command line.
Standard import statements are added for the ASN1C Java run-time classes and Java utility classes.
Import statements may also be added for items imported from other ASN.1 modules if they don't
exist within the package being generated.
26
Class Declaration
Class Declaration
Next comes the class declaration. It is of the following form:
public class extends
is the name of the production in the ASN.1 source file. is a class from
which the type is derived. This can either be a standard run-time or compiler-generated class. In
our example, the EmployeeNumber is an INTEGER, so we can directly extend the Asn1Integer
run-time base class. If we had a declaration such as the following:
EmployeeSSNumber ::= [APPLICATION 22] EmployeeNumber
Our EmployeeSSNumber class would be derived from the compiler-generated EmployeeNumber
class as follows:
public class EmployeeSSNumber extends EmployeeNumber
Note: the preceding example is not true if –compact is specified. In that case, all intermediate
classes would be removed so EmployeeSSNumber would extend Asn1Integer as in the first case.
Tag Constant
The next item in the generated source file is a tag constant. This is only generated if the production
is tagged. The runtime class Asn1Tag is used for this constant. This class contains methods for
operating on ASN.1 tag values. In the sample above, the [APPLICATION 2] tag that is present in
the ASN.1 production definition is represented by the generated tag constant.
Public Member Variables
The next section of the file would be public member variables. In our example above, no member
variables are present. This is because INTEGER is a primitive type, so the member variable in
which the integer value is stored can be found in the Asn1Integer base class from which this class
is derived. This is true for all primitive types – the value will be contained within the run-time
base class.
Constructed types will contain public member variables to represent the elements that make up the
type. For example, the following SEQUENCE production:
Name ::= [APPLICATION 1] IMPLICIT SEQUENCE {
givenNameIA5String,
initial IA5String,
familyNameIA5String
}
will result in the following public member variables being added to the generated class:
public Asn1IA5String givenName;
public Asn1IA5String initial;
27
Constructors
public Asn1IA5String familyName;
Note that the member variables are public. They were declared this way to make access easier.
A trade-off existed between ease-of-use and secure encapsulation. The ease-of-use approach was
chosen because it was felt that the repeated use of get/set methods within deeply nested structures
would be too clumsy and bulky in most applications. Therefore, the variables were made public
to make the encapsulated values easier to set and retrieve. Consistency checks have been added
in some methods to make sure values of the correct types are specified for these elements. These
checks are discussed in the sections on the specific constructed types.
This behavior can be overridden by using the -getset command-line option. This will cause the
member variables to be declared as protected variables and accessor/mutator methods (i.e. get/set)
methods added to access the variables.
Constructors
Constructors are generated to allow an object to be initialized in a number of different ways. All
productions have a default constructor with no parameters. This creates an empty object that can
be populated at a later time. Constructors are also created that take a parameter of the base type
value to allow direct population upon creation of an object. In our example code, two constructors
were generated:
public EmployeeNumber () {
super();
}
public EmployeeNumber (int value_) {
super (value_);
}
More complex constructed ASN.1 types such as a SEQUENCE would have a constructor that
would have an argument for each defined element. A CHOICE on the other hand would have a
unique constructor for each of the possible choice items. See the sections on specific ASN.1 types
to find out exactly what constructors are generated for a given type.
Decode Method
The generated decode method for BER/DER has the following general form:
public void decode (Asn1BerDecodeBuffer buffer,
boolean explicit, int implicitLength);
Users of the C and C++ version of the product might recognize this form. It is very similar to the
C function prototype. A reference to an Asn1BerDecodeBuffer object is passed that specifies the
message being decoded. This is similar to the context variable in the C version of the product.
The explicit and implicitLength arguments should be of no concern to the average user. The explicit
argument should be set to true and the implicitLength argument set to zero. These arguments are
28
Encode Method
only used in internal calls generated by the compiler when implicit tagging is used. In this case,
the decoder will at times only be concerned with decoding the contents of a field and not the tag
information. At the outer levels, it will always be necessary to decode a tag and length.
The Java decode method reports errors by throwing exceptions. This is a change from the C/C++
version that returned a status value. The method signature includes the following throws clause:
throws Asn1Exception, java.io.IOException
The Asn1Exception class is the base class for all exceptions defined for ASN1C. A complete list
of these exceptions can be found in the ASN1C Exceptions section.
For PER, the signature is similar:
public void decode (Asn1PerDecodeBuffer buffer);
In this case, the explicit and implicitLength arguments are not required since PER has no tagging.
The only required argument is a reference to a decode buffer object.
For XER or XML, two overloaded decode methods are generated:
public void decode (XMLReader reader, String xmlURI);
public void decode (XMLReader reader, InputStream byteStream);
These take as arguments an XML reader object reference and a reference to an input source object.
The XML reader object is a standard class within an XML parser that reads and parses an XML
document. The input source can either be a URI (this can be a local filename) or an in-memory
byte stream.
Encode Method
The generated encode method for BER/DER has the following general form:
public int encode (Asn1BerEncodeBuffer buffer, boolean explicit);
The Asn1BerEncodeBuffer argument specifies the buffer into which the message will be encoded.
The explicit argument is primarily for use by the compiler for generating internal calls to handle
implicitly tagged elements in constructed types. Users should always set this argument to true.
The encode method returns the length of the encoded component. Unlike the C /C++ version, this
return value does no double as a status value as well. Any errors that occur in the encode process
are reported by throwing an ASN1C exception. A complete list of these exceptions can be found
in the ASN1C Exceptions section.
The general form of a PER encode method is as follows:
public void encode (Asn1PerEncodeBuffer buffer);
In this case, the explicit argument is not required since PER has no tagging. The only required
argument is a reference to an encode buffer object. Also note that the return value is void instead
29
Other Methods
of int. No intermediate lengths are returned during the encoding of a PER message. Any errors that
occur are reported as an exception; hence there I no need for a return value.
The general form of an XER or XML encode method is as follows:
public void encode (Asn1XerEncoder buffer, String elemName);
In this case, the buffer reference is to an XER encoder object and an element name argument is
added. The Asn1XerEncoder reference is to an interface that allows either a message buffer or
output stream object to be passed into the method. In the case of XML, this object reference would
be to an Asn1XmlEncoder interface.
The element name is the name of the element that is to bracket the XML encoded value (i.e.
value).
The method return type is void because errors are reported through the exception mechanism.
Other Methods
Other generated methods include the following:
get/set - Public get/set methods are generated for each element within a
container type (SEQUENCE, SET, CHOICE) if the -getset command-line switch is specified.
print() - A public print() method. This is only generated if the –print option is specified. This provides a formatted printout of the contents of the object. The output can be directed to a PrintStream
object.
getElemName() - A public getElemName method (CHOICE only). This method retrieves the
name of an element within a CHOICE construct give its assigned identifier value.
set_ - Public set_ methods (CHOICE only). These are generated for each
element in a CHOICE construct to allow the CHOICE value to be set. Note that this method is not
generated if -getset is specified. In this case, the standard set method is used to set the choice option.
Inner Classes
The generation of code for XER or XML may cause the following inner class definition to be
generated:
public class SaxHandler extends Asn1XerSaxHandler {
Asn1XerSaxHandler mElemSaxHandler;
StringBuffer mCurrElemValue;
SaxHandler() {
}
30
Inner Classes
public void startElement (String namespaceURI, String localName,
String qName, Attributes atts)
throws SAXException
{
}
public void characters (char[] ch, int start, int length)
throws SAXException
{
}
public void endElement (String namespaceURI,
String localName, String qName)
throws SAXException
{
}
}
This is an implementation of a standard SAX content handler class. As the XML parser software
parses messages, the methods within this class are invoked with the parsed content. The startElement method is invoked after a start element tag () is parsed. The characters method is invoked one or more times to pass the content between tags into the application. The endElement
method is invoked when an end element tag () is encountered.
The ASN1C compiler generates custom code for each ASN.1 type within a given specification to
parse the XML contents and fill in the generated Java objects.
31
32
ASN.1 Type to Java Class Mappings
The following sections discuss the specific mappings of ASN.1 and XSD types to Java classes.
BOOLEAN
The ASN.1 BOOLEAN type is converted to a Java class that extends the Asn1Boolean run-time
class. This base class encapsulates the following public member variable:
public boolean value;
This is where the Boolean value to be encoded is stored. It also contains the result of a decode
operation. Since it is public, it can be accessed directly to get or set the value. The generated
constructors can also be used to set the value.
The following shows the basic mapping from ASN.1 type to Java class definition:
ASN.1 Production
::= BOOLEAN
XSD Type
Generated Java class
public class extends Asn1Boolean {
public ()
{
super();
}
public (boolean value_)
{
super (value_);
}
}
This definition assumes a simple assignment of the form " ::= BOOLEAN" (i.e., no tagging
or subtypes have been added to the BOOLEAN declaration). In this case, no specific encode or
decode methods are generated – calls to these methods pass through to the generic calls defined in
the base class. This is true of all other primitive type declarations as well unless otherwise noted.
INTEGER
The ASN.1 INTEGER type is converted to a Java class that extends the Asn1Integer run-time class.
This base class encapsulates the following public member variable:
public long value;
33
Large Integer Support
This is where the integer value to be encoded is stored. It also contains the result of a decode
operation. Since it is public, it can be accessed directly to get or set the value. The generated
constructors can also be used to set the value.
The following shows the basic mapping from ASN.1 type to Java class definition:
ASN.1 Production
::= INTEGER
XSD Types
,
,
,
,
,
,
,
,
,
,
, ,
Generated Java class:
public class extends Asn1Integer {
public () {
super();
}
public (long value_) {
super (value_);
}
}
This shows the class generated for a simple INTEGER assignment. If a tagged or constrained type
is specified, specific encode and decode methods will be generated as well.
Large Integer Support
The maximum size for a Java long integer type is 64 bits. ASN.1 has no such limitation on integer
sizes and some applications (security key values for example) demand larger sizes. In order to
accommodate these types of applications, the ASN1C compiler allows an integer to be declared
a "big integer" via a configuration file variable (the setting is used to do this –
see the section describing the configuration file for full details). When the compiler detects this
setting, it will declare the integer class to be derived from the Asn1BigInteger class instead of the
Asn1Integer class. The Asn1BigInteger class encapsulates an object of the Java BigInteger class.
This provides full support for working with integers of arbitrary lengths.
For example, the following INTEGER type might be declared in the ASN.1 source file:
SecurityKeyType ::= [APPLICATION 2] INTEGER
Then, in a configuration file used with the ASN.1 definition above, the following declaration can
be made:
SecurityKeyType
34
BIT STRING