This section lists the compiler directives and provides a detailed description of their function. The compiler directives on this page are grouped into two categories:
The format of a standard directive is:
--<ASN1.nameOfDirective [absoluteReference] [directiveOperand(s)]>--
nameOfDirective can be one of the following:
absoluteReference is used for uniquely specifying one or more components in ASN.1.
The absolute reference notation is similar to the syntax used in many programming languages to access components within named structures and records. The outermost structure is listed first using its identifier followed by a period ("."). A component of the outermost structure can be listed next. If a component is placed within a nested structure, a period is added after the name of the containing structure, and the component is listed next.
There are four methods of specifying ASN.1 components:
For example, for the following ASN.1 definition:
We stand with Ukraine
MyMod DEFINITIONS ::= BEGIN
Comp1 ::= SET OF SEQUENCE {
a INTEGER,
b OCTET STRING OPTIONAL,
c CHOICE {
nest1 BOOLEAN,
nest2 BIT STRING
}
}
Comp2 ::= IA5String
END
The absolute reference for:
To access ASN.1 types located within CONSTRAINED BY clauses, specify the dollar sign ("$") followed by a number index indicating a particular CONSTRAINED BY. This number index can be optionally followed by a colon (":") and another number index or a component identifier that indicates a particular component within the CONSTRAINED BY braces. If the colon and the index or the identifier following it are left out, the first component within the CONSTRAINED BY is targeted by default.
Specifies the name of a Java class that is used to check a user-defined constraint.
The absoluteReference refers to a component within a module that has a user-defined constraint attached.
The className argument is the name of the constraint-checking class to be used. The class name can be a quoted or an unquoted string. Use a quoted string if the class name is a fully qualified (period-separated) class name. If the className argument is omitted, the ASN.1 compiler will issue an error message. The Java class specified with the className argument must implement the com.oss.asn1.ExternalChecker interface.
In the following example, the my.OddChecker.isValid(AbstractData odd) application class method is used to check if the OddInteger type is indeed odd. The custom class used to check the constraints must implement the com.oss.asn1.ExternalChecker interface; otherwise, a runtime error would occur. If the constraining class name is not provided, the name of the constraining class will default to OddInteger_fn.
--<ASN1.ConstraintFunction Module.OddInteger "my.OddChecker">--
Module DEFINITIONS ::= BEGIN
OddInteger ::= INTEGER (CONSTRAINED BY {-- odd --} )
END
This directive can be used only with types with a CONSTRAINED BY clause.
The ASN1.ConstraintFunction directive must be placed before the user-defined type it references. User-defined constraint-checking methods are generated only if the -userConstraints compiler option is enabled.
By default, the name of the constraining class is typereference_fn.
Does not allow the compiler to automatically decode a particular component within a CHOICE, SEQUENCE, or SET structure when its containing type is marked for decoding.
The type referred to by the absolute reference will result in extra methods generated by the ASN.1 Java compiler, which enables access to the still-encoded portion of the deferred component and allows encoding/decoding of the deferred component.
| ASN.1 | Java |
|---|---|
--<ASN1.DeferDecoding Module.Type.setComponent>--
Module DEFINITIONS ::= BEGIN
Type ::= SET {
setComponent INTEGER,
b BOOLEAN
}
END
|
public class Type extends Set {
public Type(){...}
public Type(INTEGER setComponent, BOOLEAN b) {...}
public Type(long setComponent, boolean b) {...}
public INTEGER getSetComponent(){...}
public byte[] getEncodedSetComponent(){...}
public void setSetComponent(long setComponent){...}
public void setSetComponent(INTEGER setComponent){...}
public void decodeSetComponent(Coder coder){...}
public void encodeSetComponent(Coder coder){...}
...
}
|
The methods shown above in bold are generated only when the DeferDecoding directive is set.
The ASN1.DeferDecoding directive is supported only by the SOED runtime for BER, DER, and CER. Do not use it with any other encoding rules.
By default, all components of CHOICE, SET, or SEQUENCE types are decoded with their containing type.
Sets a special representation for INTEGERs whose size is not limited by the long Java integer type. By default, INTEGER types are represented by the com.oss.asn1.INTEGER class (it uses the long Java type, which is sufficient for representing 64-bit numbers). When either directive is used, the corresponding INTEGER types are represented by the com.oss.asn1.HugeInteger class.
When specified globally, absoluteReference refers to INTEGER types represented using the HugeInteger directive. The HugeInteger representation consists of a structure that contains a pointer to a CHARACTER STRING and a length field. When specified locally, the directives take no operands.
Using a local directive:
| ASN.1 | Java |
|---|---|
HugeInt DEFINITIONS ::= BEGIN
A ::= INTEGER --<HUGE>--
END
|
public class A extends HugeInteger {
...
}
|
Using a global directive:
| ASN.1 | Java |
|---|---|
--<ASN1.HugeInteger LengthModule.LengthData.lengthOfSolarSystem>--
LengthModule DEFINITIONS ::= BEGIN
LengthData ::= SEQUENCE {
lengthOfSolarSystem INTEGER,
units ENUMERATED{mm(0), cm(1), m(2), km(3), lightyears(4)}
DEFAULT mm
}
END
|
public class LengthData extends Sequence {
...
/**
* Construct with components.
*/
public LengthData(HugeInteger lengthOfSolarSystem, Units units)
{
setLengthOfSolarSystem(lengthOfSolarSystem);
setUnits(units);
}
...
// Methods for field "lengthOfSolarSystem"
public HugeInteger getLengthOfSolarSystem()
{
return (HugeInteger)mComponents[0];
}
public void setLengthOfSolarSystem(HugeInteger lengthOfSolarSystem)
{
mComponents[0] = lengthOfSolarSystem;
}
...
}
|
Provides an alias to a name from an ASN.1 module to be used in the application program. By default, the name used in the generated data structures is derived from the input ASN.1 syntax.
The absolute reference specifies the name of a module, type reference, value reference, object class reference, object reference, object set reference, identifier or field name, element of a SET or SEQUENCE, anonymous component of a SET or SEQUENCE, or an identifier in a named number list.
The nickname parameter should follow the naming rules of the target programming language.
In the following notation, the MTN nickname is used for the MyTypeName type, which is an element of MySequence within MyModule.
--<ASN1.Nickname MyModule.MySequence.MyTypeName MTN>--
The following example illustrates how to name types and identifiers:
| ASN.1 | Java |
|---|---|
--<ASN1.Nickname Module.UserData Monkey>--
--<ASN1.Nickname Module.UserData.* Gorilla>--
--<ASN1.Nickname Module.UserData.*.1 Gibbon>--
--<ASN1.Nickname Module.UserData.*.fvalue Mandrill>--
Module DEFINITIONS ::= BEGIN
UserData ::= SET OF SEQUENCE {
key INTEGER,
fvalue OCTET STRING OPTIONAL
}
END
|
public class Monkey extends SetOf {
...
public static class Gorilla extends Sequence {
...
/**
* Construct with components.
*/
public Gorilla(long Gibbon, OctetString Mandrill)
{
setGibbon(Gibbon);
setMandrill(Mandrill);
}
...
}
...
}
|
The above ASN.1 example is equivalent to:
Module DEFINITIONS ::= BEGIN
UserData ::= SET --<TYPENAME "Monkey">-- OF SEQUENCE {
key INTEGER --<FIELDNAME "Gibbon">--,
value OCTET STRING --<FIELDNAME "Mandrill">-- OPTIONAL
} --<TYPENAME "Gorilla">--
END
Note that "*" refers to the SEQUENCE type, and 1 refers to the first element in the SEQUENCE (the key). In ASN.1:1990, you can omit identifiers for elements of a SEQUENCE, SET, or CHOICE, therefore you can use the number notation to give a name to every component of these constructs. Note that identifiers are mandatory in ASN.1:2021.
The following example shows how to name an item in a named number list:
| ASN.1 | Java |
|---|---|
--<ASN1.Nickname Module.E.enum1 " new_enum1">--
--<ASN1.Nickname Module.B.bit1 " new_bit1">--
--<ASN1.Nickname Module.I.int1 " new_int1">--
Module DEFINITIONS ::= BEGIN
E ::= ENUMERATED {enum1(1), enum2(2)}
B ::= BIT STRING {bit1(4), bit2(8)}
I ::= INTEGER {int1(10), int2(8)}
END
|
public class E extends Enumerated {
...
// Named list definitions.
public static final E new_enum1 = new E(1);
...
}
public class B extends BitString {
...
// Named list definitions.
public static final int new_bit1 = 4;
...
}
public class I extends INTEGER {
...
// Named list definitions.
public static final I new_int1 = new I(10);
...
}
|
Instructs the compiler to treat one or more ASN.1 types as Protocol Data Units (PDUs).
The types following the directive are operands that specify which ASN.1 types should be treated as PDUs. Note that these types should be specified using the absolute reference notation.
By default, unreferenced types (user defined types that are not referenced by any other type) are considered PDUs by the compiler, and they can be encoded and decoded as complete units.
In the following example, MyType is treated as a PDU, even if it is referenced in another type definition. Note that the types in the directive must be specified using the absolute reference notation.
--<ASN1.PDU Module.Type>--
Module DEFINITIONS ::= BEGIN
TypeRef ::= Type
Type ::= SET { b BOOLEAN }
END
Type will be treated as a PDU, even though it is referenced in another type definition.
Enables you to select the representation (binary, decimal, or mixed) to be used for ASN.1 values of type REAL. This directive can be applied to particular REAL types, or can specify a default for all REAL types. By default, the REAL type is represented by the com.oss.asn1.Real class or compiler-generated classes which extend the com.oss.asn1.Real class.
The realKind operand can be: binary, decimal, or mixed, and it specifies how the REAL type should be represented in the generated .java files.
A list of affected types can be specified after the realKind operand using the absolute reference notation. If no type references are specified, the ASN1.RealRepresentation directive sets the default representation for REAL types locally, on the module-level, or globally, according to its location.
| ASN.1 | Java |
|---|---|
--<ASN1.RealRepresentation mixed Module.Type.a1.b2>--
Module DEFINITIONS ::= BEGIN
MyType ::= SEQUENCE {
a1 SET { b1 INTEGER, b2 REAL},
a2 REAL
}
END
|
// Methods for field "b2" public MixedReal getB2() public void setB2(MixedReal b2); // Methods for field "a2" public double getA2(); public void setA2(double a2); |
In the above example, the com.oss.asn1.MixedReal class is used to represent field b2 of field a1 of type Type, while field a2 of the type Type is represented by the com.oss.asn1.Real class.
For a global effect, the ASN1.RealRepresentation directive must be used with no type references and placed before the first module in the ASN.1 input.
Instructs the ASN.1 compiler to ignore certain ASN.1 types or components. The compiler does not generate code for these types. This is useful when you want to omit certain parts of an ASN.1 specification without modifying the original ASN.1 source.
absoluteReference can refer to: defined types, defined values, members of CHOICE types (excluding the last component specified), components that are marked OPTIONAL in a SEQUENCE or SET type, components that have a DEFAULT value in a SEQUENCE or SET type, information object classes, information objects that are not included in information object sets, information object sets.
The ASN1.Remove directive informs the compiler that an ASN.1 item should be treated as if it was not included in the ASN.1 source text, in other words, no associated code is generated in the .java files for this type for use by the application. However, removal of components leads to encodings that are perfectly compatible with counterpart applications that do not use the ASN1.Remove directive. By default, all parts of the ASN.1 input are included in the compiler-generated files.
In the following example, after compiling the syntax, an empty class structure S with no component accessor or mutator methods is generated in the .java file:
| ASN.1 | Java |
|---|---|
--<ASN1.Remove Mod.Int>--
--<ASN1.Remove Mod.S.a>--
--<ASN1.Remove Mod.i>--
Mod DEFINITIONS ::= BEGIN
S ::= SET { a SET OF SET OF SEQUENCE {
b Int
} OPTIONAL
}
Int ::= INTEGER
i Int ::= 10
END
|
public class S extends Set {
/**
* The default constructor.
*/
public S()
{
}
...
}
|
Also, no static final member variable is created in the Mod.java module class to represent the value i.
--<ASN1.Remove Mod.bit, Mod.Int>--
--<ASN1.Remove Mod.Set.a.b.c.d.*.e>--
Mod DEFINITIONS ::= BEGIN
Int ::= INTEGER
A ::= SEQUENCE {a Int OPTIONAL, b BIT STRING}
a A ::= { a 1, b bit}
bit BIT STRING ::= '0'B
C ::= CHOICE { a Int }
Set ::= SET {
a SET {
b SET {
c SET {
d SET OF SET {
e INTEGER OPTIONAL
}
}
}
}
}
s Set ::= { a { b { c { d { {e 3}, {e 4}, {e 5} } } } } }
END
The .rmv file will contain the following Remove directives for types, values, components that reference items marked for removal:
When an ASN.1 item is marked for removal, any references to the item must also be removed (by using the ASN1.Remove directive). If errors related to missing references occur and the -genDirectives or the -keepNames command-line option is specified, the OSS ASN.1 compiler automatically generates the ASN1.Remove directives in a file with an .rmv extension (this file will have the same prefix as the .gen file).
The generated .rmv file can be passed at the command-line (before any compiler options) to let the compiler automatically remove the types that are causing problems.
Under special circumstances, the ASN1.Remove directives cannot be generated into the .rmv file. In such a case, you should successively call the ASN.1 compiler several times (correcting the syntax) until the ASN.1 notation compiles correctly.
The listing file generated with the -listingFile command-line option omits removed items entirely. To get a full listing with removed items included, use the -modListingFile command-line option.
Standard directives applied to or found inside ASN.1 items marked for removal have no effect.
The ASN1.Remove directive applied to the fields of a parameterized type results in removing those fields from each instance of the parameterized type, and therefore we do not recommend it.
Removing fields from a type that is referenced in the COMPONENTS OF type notation results in removing those fields from each type specified with the COMPONENTS OF type notation.
The ASN1.ValueInFile directive specifies that values can be huge, and may require special handling at runtime. Currently, huge values are supported only with oss.jar, the space-optimized encoder/decoder runtime library (SOED).
Certain applications need to process huge data. The following values can become huge:
X.509 applications might encounter huge CRLs (SEQUENCE OF or SET OF). Applications that employ cryptographic signing may need to work with huge binary strings that represent the data to be signed. To avoid out-of-memory crashes, you can use the ValueInFile directive to indicate which components of a value can become huge. The runtime provides special handling for these components. That is, it no longer assumes that the value is stored in memory but instead resides in the external storage, such as a disk file or a TCP/IP socket.
Special processing of huge data means extra expense and poorer performance. Using the ASN1.ValueInFile, OSS.OBJHANDLE, and NOCOPY directives, you can explicitly control which data requires special handling. The OBJHANDLE and NOCOPY directives are aliases for ValueInFile and are provided to maintain compatibility with other OSS ASN.1 compilers (for languages other than Java).
The absoluteReference refers to the ASN.1 types specified in the following table:
| ASN.1 type | Representing class | Effect of the directive |
|---|---|---|
|
BIT STRING OCTET STRING |
HugeBitString HugeOctetString |
The contents are represented as ByteStorage rather than as byte[] array. |
|
BMPString GeneralString GraphicString IA5String ObjectDescriptor NumericString PrintableString TeletexString UTF8String VideotexString VisibleString |
HugeBMPString HugeGeneralString HugeGraphicString HugeIA5String HugeNumericString HugeObjectDescriptor HugePrintableString HugeTeletexString HugeUTF8String16 HugeVideotexString HugeVisibleString |
The contents are represented as CharStorage rather than as String. |
|
open type component with the ASN1.DeferDecoding directive applied |
HugeOpenType HugeDeferredComponent |
The encoded component is represented as ByteStorage rather than as byte[] array. |
|
SET OF SEQUENCE OF |
HugeSetOf HugeSequenceOf |
The elements are represented as ObjectStorage rather than as an array. |
|
extensible CHOICE SEQUENCE or SET in relaySafe mode |
HugeRelaySafeChoice HugeRelaySafeSequence HugeRelaySafeSet |
Unknown extensions are internally stored as ByteStorage rather than as byte[] array. |
--<ASN1.ValueInFile Test.HugeBinaryData>--
Test DEFINITIONS ::= BEGIN
HugeBinaryData ::= OCTET STRING
END
| When ASN1.ValueInFile is specified: | When ASN1.ValueInFile is not specified: |
|---|---|
public class HugeBinaryData extends HugeOctetString {
...
}
|
public class HugeBinaryData extends OctetString {
...
}
|
There are local forms of NOCOPY and OBJHANDLE, but not of ASN1.ValueInFile. The following three examples are equivalent:
--<ASN1.ValueInFile Test1.HugeBinaryData>--
Test1 DEFINITIONS ::= BEGIN
HugeBinaryData ::= OCTET STRING
END
Test2 DEFINITIONS ::= BEGIN
HugeBinaryData ::= OCTET STRING --<OSS.OBJHANDLE>--
END
Test3 DEFINITIONS ::= BEGIN
HugeBinaryData ::= OCTET STRING --<OSS.NOCOPY>--
END
Directives are not limited to ASN.1 type references, but may also apply to individual components of a SEQUENCE or SET.
--<ASN1.ValueInFile Test.Signed.data>--
Test DEFINITIONS ::= BEGIN
Signed ::= SEQUENCE {
signature BIT STRING,
data OCTET STRING
}
END
|
Test DEFINITIONS ::= BEGIN
Signed ::= SEQUENCE {
signature BIT STRING,
data OCTET STRING --<OBJHANDLE>--
}
END
|
When the OSS ASN.1/Java compiler maps input ASN.1 definitions to Java classes, it chooses special representative classes for types that have the ValueInFile (or NOCOPY, OBJHANDLE) directive. These representations are quite different from default representations (as the HugeInteger class differs from the INTEGER), therefore type compatibility and API compatibility with default representations are not maintained. For example, HugeSequenceOf does not inherit from AbstractContainer and does not provide all the methods available for SequenceOf.
For information on Java classes that handle huge values, see the OSS ASN.1/Java Universal Classes section (classes typically begin with the word Huge, for example, HugeOctetString).
For information on using the Storage interface to work with huge values, refer to the Storage Interface section.
Enables you to select from the input ASN.1 schema a subset of types that can be used in your application. In other words, the ASN1.WorkingSet directive enables you to specify, using one directive, all PDUs (the types of the messages to encode and decode). Values, information objects, etc. defined in the working set are also represented in the compiler generated code.
The ASN1.WorkingSet directive replaces the default compiler behavior of assigning PDUs for non-referenced types. You can access certain parts of the ASN.1 specification that are not included in the working set by referencing them from the parts in the working set.
WSName is a working set name required for consistency between the ASN.1/C product and the ASN.1/C++ and ASN.1/Java products; otherwise it is ignored.
absoluteReference refers to a module name, type reference, value reference, object class reference, object reference, or object set reference. If absoluteReference is a module name, this directive has the same effect as the OSS.ROOT directive.
By default, the ASN.1 compiler chooses a working set by examining the type of compiler directives that are present.
In the following example, Type1, Type2 and Type4 are directly available to the application as PDUs. Type3 is not available as a PDU.
--<ASN1.WorkingSet WSName Module2, Module3.Type4>--
Module2 DEFINITIONS ::= BEGIN
Type1 ::= SET { typeComponent INTEGER, b BOOLEAN
}
Type2 ::= INTEGER
END
Module3 DEFINITIONS ::= BEGIN
Type3 ::= SET { aComponent INTEGER, b BOOLEAN }
Type4 ::= IA5String
END
You can extend a set by adding more than one module. For example, both module1 and module14 are included in commonSet:
--<ASN1.WorkingSet commonSet module1>-- --<ASN1.WorkingSet commonSet module14>--
The ASN1.WorkingSet directive does not affect pairs of cross referencing types. In the following example, when using a working set, neither Foo nor Bar will become a PDU:
Foo ::= SEQUENCE OF Bar
Bar ::= SEQUENCE {a INTEGER, b Foo}
A component of a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF cannot be added to a working set by itself.
By default, the ASN.1 compiler computes the working set by considering four types of directives, in the following order of precedence:
Based on the presence or absence of these directives in the input, the ASN.1 compiler assumes one of the following four modes of operation:
The following table illustrates how the above four modes are used by the ASN.1 compiler (x = present, blank = absent):
| Directive Type | Types of Directives Present in Input | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| OSS.ROOT | x | x | x | x | x | x | x | ||||||||
| Other OSS.* directive | x | x | x | x | x | x | x | ||||||||
| ASN1.WorkingSet | x | x | x | x | x | x | x | x | |||||||
| Other ASN1.* directive | x | x | x | x | x | x | x | ||||||||
| ASN.1 Compiler Mode | dws | rd | rd | rd | r | r | ws | ws | ws | ws | ws | ws | ws | ws | ws |
OSS directives can be placed in the ASN.1 schema files where spaces or tabs are allowed (locally, at the module-level, and globally). When used globally, they must be specified before the first module definition. To capture these directives in a .gen file, use the -genDirectives command-line option.
Enables you to specify the year of the ASN.1 standard used in a particular ASN.1 module. This directive is useful for applications that use several versions of ASN.1 source.
By default, before detecting a particular type of notation, the compiler uses neutral mode. After the compiler detects notation particular to a version, it switches out of neutral mode and enforces conformance to that standard.
When specified globally, the OSS.ASN1VER directive can take an absolute reference which can be a name of an ASN.1 module or some component within a module that should be treated being part of the ASN.1:version syntax. version can take on the values: 1990, 1993, 1994, 1997, 2002, 2008, 2015, and 2021. If specified globally without an absolute reference, the OSS.ASN1VER directive sets the default version of the entire ASN.1 input.
When specified locally, the OSS.ASN1VER directive does not take an absolute reference and only affects the type next to which it is placed.
The following example shows how to allow unnamed elements to be used in a SEQUENCE:
--<OSS.ASN1VER Module.NoNames 1990>--
Module DEFINITIONS ::= BEGIN
NoNames ::= SEQUENCE {
BOOLEAN,
BOOLEAN,
INTEGER
}
END
Enables representation of ASN.1 UTF8String types in Java via the com.oss.asn1.AbstractString16 class which can contain two byte characters (Unicode). This is the default representation for the ASN.1 BMPString type.
absoluteReference refers to an item in the ASN.1 syntax that is declared as a UTF8String. When used without arguments, this directive can only operate as a local directive.
When specified globally, the OSS.BMPSTRING directive should take an absolute reference specifying a UTF8String type which is intended for the desired representation. When specified locally, this directive does not take any arguments and only affects the type next to which it is placed.
In the following example, TwoByteGlobal is set to the BMPString representation by a global OSS-prefixed directive specified with an absolute reference. TwoByteLocal is set to the BMPString representation through the use of a local directive. Default has no OSS.BMPSTRING directives applied to it, but it uses the same representation because it is the default representation. Compiler-generated Java classes for the above ASN.1 types extend the com.oss.asn1.UTF8String16 class.
| ASN.1 | Java |
|---|---|
--<OSS.BMPSTRING Module.TwoByteGlobal>-- Module DEFINITIONS ::= BEGIN Default ::= UTF8String TwoByteLocal ::= UTF8String --<BMPSTRING>-- TwoByteGlobal ::= UTF8String END |
public class Default extends UTF8String16 {
...
}
public class TwoByteLocal extends UTF8String16 {
...
}
public class TwoByteGlobal extends UTF8String16 {
...
}
|
With the BMPSTRING and UNIVERSALSTRING representations, character data will be automatically converted to the UTF-8 format before encoding and converted from UTF-8 format after decoding.
No attempt is made at runtime to ensure that the Java value contains a valid UTF-8 encoded character string. The string octets are passed to the encoder unmodified as the user places them. Also, unmodified data octets are used to fill the Java value when decoding. It is the user's responsibility to provide valid UTF-8 data before calling the encoder and to interpret the UTF-8 data received from the decoder.
Associates a field of a SEQUENCE or SET type, an alternative of a CHOICE type, or an element of a SEQUENCE OF or SET OF type with your callback function. This directive is useful when using partial decoding.
When specified globally (either in an ASN.1 file before the module definition or in a separate directives file), the OSS.DataCallback directive takes an absoluteReference to a field.
FunctionName is used to construct names of the user-defined callback methods. There are two callback methods per directive: beginFunctionName() and endFunctionName().
When specified locally, the OSS.DataCallback directive must be placed next to the field definition, as in the following example:
age INTEGER(1..100) --<DataCallback "FunctionName">--,
It is possible for a named type to appear more than once in a PDU. When an OSS.DataCallback directive is applied to such a field, the decoder will call the same callback function for each occurrence. The callback, however, cannot differentiate a call for one field from a call for the other since they are both associated with the same function. To discern the difference, consider the OSS.InfoCallback directive.
Specify representations for the ASN.1 REAL type.
When the OSS.DECIMAL directive is used, the type is represented by the com.oss.asn1.DecimalReal class, which stores a REAL value as a character string of the form "[ ]nnnnn.nnnnn[E[ |+]nnnnn]".
When the OSS.MIXED directive is used, the type is represented by the com.oss.asn1.MixedReal class, which can store the REAL value both as a double and as a character string.
The following ASN.1 notation shows the various ways of determining the representation of the REAL type:
| ASN.1 | Java |
|---|---|
Module DEFINITIONS ::= BEGIN
Decimal ::= REAL (WITH COMPONENTS {..., base (10) } )
Binary ::= REAL (WITH COMPONENTS {..., base (2) } )
BinaryAlso ::= REAL
Mixed ::= REAL --<MIXED>--
END
|
public class Decimal extends DecimalReal {...
public class Binary extends Real { ...
public class BinaryAlso extends Real { ...
public class Mixed extends MixedReal { ...
|
Note that global directives will override the default representation of a base constraint. However, such a global directive does not take precedence over the local directives.
By default, the REAL type is represented by the com.oss.asn1.Real class, which stores REAL values as double unless the base component of ASN.1 REAL is constrained to be 10. In the latter case, com.oss.asn1.DecimalReal is used.
When specified globally, these directives can take an absolute reference specifying which component of the ASN.1 syntax is intended for the desired representation. If specified globally without an absolute reference, the OSS.DECIMAL and OSS.MIXED directives determine the default representation for all REAL types within their scope.
When specified locally, these directives do not take any arguments and only affect the type next to which they are placed.
double is provided as the default representation. The ASN.1 standard implies that values encoded in base 10 must be represented in a format suitable for base 10 and values encoded in base 2 must be represented in a format suitable for base 2. This is done to avoid losing precision in conversions to and from their floating point representation. To ensure that no precision is lost, you can constrain the type REAL to base 2 or base 10. To ensure that the Java representation can encode and decode without conversion, you can use the MIXED directive.
Instructs the compiler to generate a Document Type Definition (DTD) for the specified ASN.1 types in the input definitions. The optional absolute reference refers to any ASN.1 type reference in the input ASN.1 syntax for which you wish to have a separate XML DTD generated. OptionalNewName is an optional argument that allows you to specify a filename for the DTD file which will be generated.
When the absoluteReference is missing, it is assumed that DTDs are produced for all PDUs in the input ASN.1 syntax. When the OSS.DTD directive is used globally, its behavior is identical to the -dtd ASN.1 compiler option.
The directive has two forms:
Each form specifies that a DTD file is produced for:
If filename is omitted, then the DTD file name defaults to the typename, with the .dtd suffix appended.
If filename is present, it can be an absolute filename or a relative filename. If the filename is absolute (for example, starts with a slash '/' on a Unix system) then all directories in its pathname should exist. Other filenames are relative to the type's module package directory and all subdirectories in the relative pathnames will be created as needed.
Note: Do not specify the same file name in more than one directive, otherwise the file will be overwritten and its contents will be unpredictable.
The first directive instructs the compiler to generate a DTD for a particular type that is identified by the absoluteReference, and can optionally specify the name for the .dtd.
The optional filename parameter in the directive can take the following forms:
By default, no DTDs are produced by the ASN.1 compiler.
NOTE: Unless -xer is specified, the -dtd option and the OSS.DTD directive have no effect.
Enables you to provide your own encoding for a particular component of a type. This directive should be used with the DeferDecoding directive. A new method (in addition to the methods generated by the DeferDecoding directive) is generated in the Java class of the ENCODABLE component as:
setEncodedXXX()
where XXX is replaced by the name of the field. Note that using the ENCODABLE directive without the DeferDecoding directive will not cause the additional method to be generated.
Be aware that this method can create incorrect encodings which are difficult to trace.
| ASN.1 | Java |
|---|---|
--<ASN1.DeferDecoding Module.SetType.s>--
--<OSS.ENCODABLE Module.SetType.s>--
Module DEFINITIONS ::= BEGIN
SetType ::= SET {
s SEQUENCE {
a INTEGER OPTIONAL,
b BOOLEAN
} ,
p PrintableString
}
END
|
public void setEncodedS(byte[] encoded); |
The OSS.FIELDNAME directive specifies the field name that should be generated into the .java file where the compiler would have generated a name derived from the ASN.1 identifier of the corresponding SET, SEQUENCE, or CHOICE component.
The OSS.TYPENAME directive specifies a name for a user-defined type that should be generated into the .java file where the compiler would have generated a name derived from the ASN.1 input.
When specified globally, these directives have an absolute reference that refers to the ASN.1 component that is renamed in the generated file, and a new name either with or without double quotation marks. When specified locally, there is no absolute reference, but a new name (in double quotation marks) must be provided. In both cases, newname must be a valid Java name.
By default, names are derived from the ASN.1 definition.
| ASN.1 | Java |
|---|---|
--<OSS.TYPENAME Module.RenamedStr "asciiStr">--
Module DEFINITIONS ::= BEGIN
RenamedStruct ::= [4] SEQUENCE {
lunchPrepared BOOLEAN --<FIELDNAME "lunchReady">--,
cost REAL
}
DefaultNameStr ::= [5] IA5String
RenamedStr ::= [6] IA5String
END
|
public class RenamedStruct extends Sequence {
...
// Methods for field "lunchReady"
public boolean getLunchReady()
{
return ((BOOLEAN)mComponents[0]).booleanValue();
}
public void setLunchReady(boolean lunchReady)
{
((BOOLEAN)mComponents[0]).setValue(lunchReady);
}
}
public class DefaultNameStr extends IA5String {
}
public class asciiStr extends IA5String {
}
|
Make sure the names you specify conform to the Java language conventions. For example, the asciiStr class name in the above example is specified to start with a lowercase letter, which is not encouraged in Java.
The effect of the directives is absolute; the ASN.1 compiler for Java will not try to change them, even if they are invalid. If the specified name conflicts with another one that was derived from an ASN.1 identifier or type reference, the compiler for Java will modify the derived name.
Specifies a name for a class that checks user-defined constraints. By default, the name of the Java class that the encoder/decoder will call before encoding and after decoding a user-constrained value is derived from the name of the type reference or identifier with which the constraint is associated. For example:
Y ::= INTEGER (CONSTRAINED BY { -- Must be a power of 2 -- })
The default constraint-checking class name is Y_fn.
When specified globally, the OSS.FUNCNAME directive takes an absolute reference to a type that has a user-defined constraint. FunctionName is the name to be used for the constraint-checking class. Note that when using OSS.FUNCNAME globally, it must be specified before the type to which it applies.
When specified locally, the OSS.FUNCNAME directive does not take an absolute reference and affects only the type in whose user-defined constraint it is placed.
| ASN.1 | Java |
|---|---|
--<OSS.FUNCNAME Module.DataCard.c "checkForPowerOf2">--
Module DEFINITIONS ::= BEGIN
DataCard ::= SEQUENCE {
a BOOLEAN,
b BOOLEAN,
c INTEGER (CONSTRAINED BY { -- Must be a power of 2 --})
}
END
|
public class DataCard extends Sequence {
...
}
|
The user will provide the CheckForThePowerOf2 class that will be used to check user-constraint, imposed on field c:
public class CheckForPowerOf2 implements ExternalChecker {
...
public boolean isValid(AbstractData value)
throws UserValidateFailedException
{
INTEGER number = (INTEGER)value;
long n = number.longValue();
int nbits = 0;
if (n < 0)
n = --n;
while (n != 0) {
if ((n & 1) != 0)
++nbits;
if (nbits > 1)
throw new UserValidateFailedException
("Not a power of 2");
n >>= 1;
}
return true;
}
NOTE: User-defined constraint-checking functions are only generated if the -userConstraints compiler option is specified.
Specifies the name of one or more configuration files that you can add to the ASN.1 input. This is useful when defining different sets of compiler directives that can be included or excluded, depending on the application.
In the following example, directives from file1.cfg and file2.cgf are inserted at the location of the OSS.INCLUDES directive:
--<OSS.INCLUDES "file1.cfg", "file2.cfg" >--
Sample1 DEFINITIONS EXPLICIT TAGS ::= BEGIN
Name1 ::= INTEGER
Name2 ::= BOOLEAN
END
The OSS.INCLUDES directive can be specified only globally and must have at least one configuration filename as an operand. The configuration file must contain global directives.
Directives obtained by specifying the OSS.INCLUDES directive can be used only in a single ASN.1 module definition and override any conflicting directives in the asn1dflt file.
The Java source file will not mention the OSS.INCLUDES directive, but it will be generated as if the directives in the configuration files were declared at the instance of the OSS.INCLUDES directive.
By default, no configuration files are inserted into the ASN.1 input.
Used when an OSS.DataCallback directive is applied to a type that occurs in multiple locations in a message.
For the following definition
M DEFINITIONS AUTOMATIC TAGS ::= BEGIN
PackageInfo ::= SEQUENCE {
from Address,
to Address,
posted DATE
}
Address ::= SEQUENCE {
zipcode INTEGER( 0..99999 ),
addressline VisibleString( SIZE (1..64) )
}
END
a directive such as
--<OSS.DataCallback M.Address.zipcode "ZipCode">--
would cause the beginZipCode() and endZipCode() methods to be called for both PackageInfo.from.zipcode and PackageInfo.to.zipcode, but the methods would not be able to differentiate the two fields. Use OSS.InfoCallback to solve the problem. By employing
--<OSS.InfoCallback M.PackageInfo.from "fromAddress">--
you instruct the compiler to use the beginfromAddress() and endfromAddress() callback methods. The beginfromAddress() method is invoked before partial decoding of the from field begins and the endfromAddress() method is invoked after its decoding is finished.
Identifies types or components for which constraint checking should be disabled. The directive disables all constraint checking for the type, including checking of the default permitted alphabet for CHARACTER STRING types. For ENUMERATED types, it disables the subtype constraints, but it does not disable checking for valid enumerators.
When the -constraint option is not specified, all constraints for type S are disabled. When the -userConstraints option is specified, constraint checking of user-constraints is enabled.
--<OSS.NoConstrain Module.S>--
Module DEFINITIONS ::= BEGIN
S ::= INTEGER (1..10 | 300) (CONSTRAINED BY { })
END
In the following example, PrintableString abc is passed at run time and constraint violation errors are not issued. Although the OSS.NoConstrain directive is not explicitly applied to the ShortABCs type, constraint checking for this type is disabled because the type is composed of types marked with OSS.NoConstrain.
--<OSS.NoConstrain Mod.ABConly>--
--<OSS.NoConstrain Mod.ShortString>--
--<OSS.PDU>--
Mod DEFINITIONS ::= BEGIN
ABConly ::= PrintableString (FROM ("A" | "B" | "C"))
abc ABConly ::= "The wrong string"
ShortString ::= PrintableString (SIZE(1 | 3 ))
shStr ShortString ::= "The long string"
ShortABCs ::= PrintableString (ABConly INTERSECTION ShortString)
shABC ShortABCs ::= "ABCDD"
END
In the following example, although the -constraint option is specified, the automatic encoding and decoding is not performed at run time:
--<OSS.NoConstrain ContConstr.O>-- ContConstr DEFINITIONS::= BEGIN O ::= OCTET STRING (CONTAINING INTEGER) END
The OSS.NoConstrain directive cannot be specified locally. Also, it has no effect if -constraint is explicitly specified, except when it is applied to a BIT STRING or OCTET STRING type constrained by contents constraint. In this case, it disables automatic encoding and decoding of the contained type.
If the -userConstraints option is used with the OSS.NoConstrain directive, all constraints except for user-constraints are disabled for the specified type or field.
By default, constraint checking is enabled.
Informs the ASN.1 compiler to treat items marked with the ASN.1 DEFAULT keyword as items marked with the OPTIONAL keyword.
When specified globally, the absoluteReference operand refers to an ASN.1 type marked as DEFAULT. When specified globally without an operand, the OSS.NODEFAULTVALUE directive affects all types marked as DEFAULT.
When specified locally, the OSS.NODEFAULTVALUE directive takes no operands and affects only the type next to which it is placed.
--<OSS.NODEFAULTVALUE Module.DataCard.a>--
Module DEFINITIONS ::= BEGIN
DataCard ::= SEQUENCE {
a [0] BOOLEAN DEFAULT TRUE,
b [1] BOOLEAN DEFAULT TRUE,
c [2] BOOLEAN
}
END
Instructs the compiler to not generate decoder or encoder routines for the operand of the directive when using the Time-Optimized Encoder/Decoder.
The OSS.NOENCODE and OSS.NODECODE compiler directives reduce the amount of generated code. The directives can be applied either to a named PDU type or to a SEQUENCE or SET field or a CHOICE alternative, as follows:
NOTE: Unless the directive satisfies the conditions mentioned in the third case, the CXER encoder ignores the OSS.NOENCODE directive applied to DEFAULT extensions because default fields are always encoded by CXER.
The following restriction applies to the compact version: the OSS.NODECODE directive must be applied either to all fields of an extension group or to none of the fields of an extension group.
By default, when the -toed option is specified, the compiler generates both encoder and decoder routines.
When you use the Space-Optimized Encoder and Decoder, the OSS.NOENCODE and OSS.NODECODE directives have no effect.
Allows the compiler to represent OBJECT IDENTIFIER types as structures of a given size. The Java representation of OBJECT IDENTIFIER types is not limited to any particular size, therefore this directive will have no effect on the code generated for OBJECT IDENTIFIER types, but it will be possible to create values of a size specified in the directive.
By default, all Java class definitions that correspond to a single ASN.1 module are generated into the <project_name>.<module_name> package. For example, if the project name is project, the Java files generated for the ASN.1 module Module have the following first statement:
package project.module;
The .java files are placed into the module subdirectory of the project directory. You can use the OSS.PACKAGE directive to specify a different output package name for the module. This directive has the following format:
--<OSS.PACKAGE absoluteReference "package_name">--
absoluteReference refers to an ASN.1 module to which the directive is applied.
package_name is the name of a Java package that contains the Java class definitions generated for absoluteReference.
The following PACKAGE directive changes the default package name for the module Module to foo.bar.module.
--<OSS.PACKAGE Module "foo.bar.module">--
The .java files that the compiler generates for the definitions within Module contain the following package statement:
package foo.bar.module;
The .java files are placed into the module subdirectory within the bar subdirectory within the foo directory. The location of the top-level directory is determined by the -path command-line parameter that specifies the default current working directory.
Instructs the compiler to send or receive ASN.1 types as protocol data units.
When specified globally, the OSS.PDU | OSS.NOPDU directive can take an absolute reference that specifies which component of the ASN.1 syntax is intended. If specified globally without an absolute reference, the OSS.PDU | OSS.NOPDU directive sets a default for all types within their scope.
When specified locally, these directives do not take any arguments and only affect the type next to which they are placed.
| ASN.1 | Java |
|---|---|
--<OSS.PDU Module.NameString>--
Module DEFINITIONS ::= BEGIN
MiddleAgeClubCard ::= SEQUENCE {
name NameString,
phoneNumber PhoneString,
age AgeInt
}
NameString ::= IA5String (SIZE (40))
PhoneString ::= NumericString (SIZE (15)) --<PDU>--
AgeInt ::= INTEGER (45..54)
END
|
MiddleAgeClubCard NameString PhoneString |
Note that AgeInt is not a PDU, because it is referenced in the SEQUENCE MiddleAgeClub and does not have a PDU directive applied.
The OSS.PDU and ASN1.PDU directives can be applied to types included in root modules. To treat all input modules as root modules, either specify the -root compiler option or include the global OSS.ROOT directive in your ASN.1 specification.
Identifies ASN.1 modules that are used as root modules. In a root module, all unreferenced types are considered PDUs. In addition, the scope of non-root modules is to supply external references to root modules. By default, the last ASN.1 input file specified at the command line contains the root module.
--<OSS.ROOT DirectorySystemProtocol{joint-iso-ccitt ds(5) modules(1) dsp(12)}>--
The OSS.ROOT directive can only be used globally and can take one or more operands. The operand can be a module reference (moduleName) or a module reference followed by a built-in objectIdentifier value. If no operands are provided, all input modules are considered root modules.
Instructs the compiler whether to generate a sample application containing sample code for PDU types and value references identified by it.
The directive accepts two types of syntax; the first allows you to select those PDU types and value references that should be included in the sample code when generating the sample application. The second allows you to control how the compiler creates sample values for some ASN.1 types.
The pdus or values parameters are only accepted when the directive is specified globally and applied to an ASN.1 module or to all ASN.1 input (the absolute reference is absent).
When the OSS.SampleCode directive is applied to all ASN.1 input, it has the same effect as the -sampleCode command-line option with the same parameter.
parameter is mandatory, and can be either count:number ( number is a non-negative integer) or selection.
When parameter is set to count: number, the directive specifies the default number of items to be used by the compiler when it automatically creates values for SEQUENCE OF or SET OF types for use in the sample code. If OSS.SampleCode has an unspecified count parameter for a specific SEQUENCE OF or SET OF type, then the compiler uses 1 as the default number of SEQUENCE OF or SET OF items.
When parameter is set to selection, the directive refers to a CHOICE alternative. If OSS.SampleCode has an unspecified selection parameter for a specific CHOICE type, then the compiler selects the first CHOICE alternative by default. If there are several such directives assigned to different alternatives of the same CHOICE type, then the compiler creates as many sample values as needed to cover all selected alternatives.
The compiler generates sample code for all values, except for those defined in Module2:
--<OSS.ROOT>-- --<OSS.SampleCode values>-- --<OSS.NoSampleCode Module2>-- Module1 DEFINITIONS ::= BEGIN A ::= OCTET STRING value1 A ::= '00'H END Module2 DEFINITIONS ::= BEGIN B ::= INTEGER value2 B ::= 1 END
The following example shows how to customize generation of sample values:
--<OSS.SampleCode pdus Module>--
--<OSS.SampleCode selection Module.S.b>--
Module DEFINITIONS ::= BEGIN
S ::= CHOICE {
a IA5String,
b SEQUENCE --<SampleCode count:3>-- OF INTEGER
}
END
The compiler creates the sample application containing test code for the following value:
samplevalue1-S S ::= b : {
0,
0,
0
}
Compared to the -sampleCode command-line option, the OSS.SampleCode directive provides more control over the sample code that is created.
You can use the OSS.SampleCode directive more than once in the ASN.1 input.
The OSS.NoSampleCode directive can be used to exclude PDUs or values from sample applications.
Applying OSS.SampleCode results in the same sample code as when using the -sampleCode command-line option.
The -sampleCode | -noSampleCode options overrides the OSS.SampleCode | OSS.NoSampleCode directive.
Instructs the ASN.1 compiler to generate a separate XML stylesheet with your filename for any particular PDU. This directive gives you more control over the default XML stylesheets generated by the ASN.1 compiler.
The absolute reference refers to any ASN.1 type reference in the input ASN.1 syntax for which a separate XML Stylesheet is generated. OptionalNewName is an optional argument that allows you to specify a new full pathname for the XSL that will be generated.
When absoluteReference is not specified, a stylesheet is generated for every PDU in the input syntax.
The OSS.Stylesheet has two forms:
Each form of the directive specifies that an XSL file is generated for:
If filename is omitted, then the XSL file name defaults to the type name, with the .xsl suffix appended.
If filename is present, it can be absolute or relative. If filename is absolute (for example, it starts with a slash ("/") on a Unix system) then all directories in its pathname should exist. Other (non-absolute) filenames are relative to the type's module package directory, and all subdirectories in the relative pathnames will be created as needed.
NOTE: Do not specify the same filename in several directives, because the file will be overwritten and its contents will be unpredictable.
The optional filename parameter in the directive can take the following forms:
The OSS.Stylesheet directive and the -xsl option have no effect if the -xer option is not specified.
The compiler does not print specific informatory and warning messages when this directive is used. OSS.SUPPRESS is especially useful when compiling abstract syntaxes that contain specifications that are not fully compliant with the ASN.1 standard.
By default, informatory and warning messages suppressed when -noRelaxedMode is turned on.
The OSS.SUPPRESS directive can be used only globally and takes one or more operands (messageID) specifying which message needs to be suppressed. This messageID can be either the full message identifier or just the numeric part of the message number.
Message A0178W indicates that the first digit of a number in a module definition should be non-zero.
--<OSS.SUPPRESS A0178W>--
Sample DEFINITIONS ::= BEGIN
Age ::= INTEGER
legalAge Age ::= 021
END
Note that the OSS.SUPPRESS directive does not affect the Java-representation. Its only effect is that the following warning message is not generated for the above syntax:
A0178W: The first digit should not be zero unless the number is a single digit.
legalAge Age ::= 021
Specifies the representation of CHARACTER STRING, BIT STRING, and OCTET STRING types.
Except for UTF8String, UNBOUNDED is the default representation in Java and therefore this directive has no effect unless it is used to override a global directive. For UTF8String where the default is the BMPSTRING representation (Unicode), UNBOUNDED has the effect of forcing representation with one byte per character rather than with the default of two bytes per character. Using the table below as an example, you will notice that the UNBOUNDED directive only affects the representation of UTF8String.
| Types | Default class representation | UNBOUNDED representation |
|---|---|---|
PrintableString |
PrintableString | PrintableString |
UTF8String |
UTF8String16 | UTF8String |
UTF8String --<NOCOPY>-- |
HugeUTF8String16 | HugeUTF8String |
BIT STRING |
BitString | BitString |
OCTET STRING |
OctetString | OctetString |
SEQUENCE OF |
SequenceOf | SequenceOf |
SET OF |
SetOf | SetOf |
Instructs the compiler to represent a UTF8String type as a com.oss.asn1.UTF8String32 class that stores a string value as an array of four-byte characters (UCS-4), which is the same representation as the one for the UniversalString type. By default, the UTF8String is represented with the com.oss.asn1.UTF8String16 class that stores a UTF8String value as a regular Java string.
When specified globally, the OSS.UNIVERSALSTRING directive takes an absolute reference that refers to certain UTF8String in the ASN.1 syntax. When specified locally, this directive takes no operands and only affects the type next to which it is placed.
| ASN.1 | Java |
|---|---|
--<OSS.UNIVERSALSTRING Module.FourByteGlobal>-- Module DEFINITIONS ::= BEGIN TwoByteDefault ::= [1] UTF8String TwoByteLocal ::= [2] UTF8String --<BMPSTRING>-- FourByteGlobal ::= [3] UTF8String FourByteLocal ::= [4] UTF8String --<UNIVERSALSTRING>-- END |
public class TwoByteDefault extends UTF8String16 { ...
public class TwoByteLocal extends UTF8String16 { ...
public class FourByteGlobal extends UTF8String32 { ...
public class FourByteLocal extends UTF8String32 { ...
|
Allows you to use user-defined Java classes instead of compiler-generated or predefined universal classes that would have otherwise been used by default. User-defined classes must extend the compiler-generated classes or predefined universal classes they are replacing.
The absoluteReference refers to an ASN.1 type to which the directive is applied. The type can be an ASN.1 type reference or a component of a structured type. If it is a type reference, absoluteReference has the form: Module.Type. If the type is a component type, absoluteReference has the form: Module.Type.field.
classname is the name of the user-defined Java class.
The fully qualified name of the user-defined class depends on the presence of an optional dot (".") and an optional packagename. If packagename and the dot (".") are omitted, the user-defined class is placed into the same package as the corresponding compiler-generated or universal class. If the name starts with a dot ("."), the user-defined class is placed into a package under the project package and has a fully qualified name, projectname.packagename.classname. If the dot (".") is not present, the user-defined class can be placed in any package outside the project package.
If the OSS.UserClass directive is applied to a type for which the compiler generates a Java class, the compiler-generated class is declared abstract.
--<OSS.UserClass Module.Type "UserClass">--
Module DEFINITIONS ::= BEGIN
Type ::= INTEGER
OtherType ::= Type
END
For the above notation, the ASN.1 compiler-generates class Type is abstract. You need to provide the user-defined class UserClass which extends Type in the package project.module. Compiler-generated classes that extend Type will continue extending Type and not UserClass.
package project.module;
public abstract class Type extends INTEGER { ... }
public class OtherType extends Type { ... }
The compiler references the specified user-defined class wherever it would otherwise reference the compiler-generated or universal class.
--<OSS.UserClass Tortoise.Length "Turtle.Size">--
Tortoise DEFINITIONS ::= BEGIN
Length ::= INTEGER
Description ::= SEQUENCE {
a Length
}
value Description ::= { a 123 }
END
For the above notation, the compiler will replace references to Length with references to Size. You need to provide the user-defined class Size which extends Length in the package Turtle.
package project.tortoise;
abstract public class Length extends INTEGER { ... }
public class Description extends Sequence {
public Description(Turtle.Size a) { ... }
public Turtle.Size getA() { ... }
public void setA(Turtle.Size a) { ... }
...
}
public static Description value= new Description(new turtle.Size(123));
The OSS.UserClass directive cannot be applied to the ENUMERATED type because the classes which the compiler generates for ENUMERATED must not be extended.
The OSS.UserClass directive should be used with caution. Make sure you do not override a non-final method defined in the compiler-generated or universal class with a user-defined class. This could cause errors at runtime.
The user-defined class should provide the same set of constructors as its base class. Failing to do so could cause Java compile-time errors. The user-defined class should not declare its default constructor as private, otherwise the runtime decode() method would fail due to an inability to create UserClass objects.
Make sure you do not omit packagename when applying the UserClass directive to an instance of an ASN.1 built-in type. If a starting dot (".") or a packagename is not present, and the directive is applied to an ASN.1 built-in type, the user-defined class should be placed into the com.oss.asn1 package; however, this is not recommended, as it can cause name conflicts.
To override the method used to print values of the ASN.1 type to which this directive applies, the user-defined class should implement the Printable interface.
Specifies whether each ASN.1 value references a corresponding Java-initialized variable, and must be generated in the Java module class file. The presence or absence of the initialized variables in the compiler output is globally controlled by the -valueRefs | -noValueRefs command-line option while the directives apply to individual value references. By default, the compiler uses -valueRefs, therefore value references are generated. To suppress the -valueRefs command-line option for individual values, use the OSS.NOVALUE directive.
When specified globally, these directives can take an absolute reference to any ASN.1 user-defined type that is specified in a value reference. When specified globally without arguments, these directives set a default for all value references within their scope.
When specified locally, the OSS.VALUE | OSS.NOVALUE directives does not take any arguments and affects only the value reference next to which they are placed.
The following ASN.1 notation demonstrates the local and global use of the OSS.VALUE and OSS.NOVALUE directives (note that the local OSS.VALUE directive overrides the global OSS.NOVALUE directive):
| ASN.1 | Java |
|---|---|
--<OSS.NOVALUE Module.IdInt>--
Module DEFINITIONS ::= BEGIN
ASCIIStr ::= IA5String
name ASCIIStr ::= "John"
age INTEGER --<NOVALUE>-- ::= 57
IdInt ::= INTEGER
idNumAbsent IdInt --<VALUE>--::= 767543
idNumPresent IdInt ::= 354876
END
|
public abstract class Module extends ASN1Module {
// Value references
public static final ASCIIStr name = new ASCIIStr("John");
public static final idInt idNumAbsent = new IdInt(767543);
}
|
Note that the age value is absent due to a local --<NOVALUE>--. The idNumAbsent is present because the local --<VALUE>-- overrides the global --<OSS.NOVALUE>-- directive.
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.